Skip to content

Layers: Add recursive property #32619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wrangelvid wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

Layers: Add recursive property #32619

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions examples/jsm/renderers/CSS2DRenderer.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ class CSS2DRenderer {

}

function renderObject( object, scene, camera ) {
function renderObject( object, scene, camera, inheritedLayers = null ) {

if ( object.visible === false ) {

Expand All @@ -221,12 +221,23 @@ class CSS2DRenderer {

}

const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
const layerVisible = effectiveLayers.test( camera.layers );

if ( layerVisible === false && effectiveLayers.recursive === true ) {

hideObject( object );

return;

}

if ( object.isCSS2DObject ) {

_vector.setFromMatrixPosition( object.matrixWorld );
_vector.applyMatrix4( _viewProjectionMatrix );

const visible = ( _vector.z >= - 1 && _vector.z <= 1 ) && ( object.layers.test( camera.layers ) === true );
const visible = ( _vector.z >= - 1 && _vector.z <= 1 ) && layerVisible;

const element = object.element;
element.style.display = visible === true ? '' : 'none';
Expand Down Expand Up @@ -255,9 +266,11 @@ class CSS2DRenderer {

}

const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;

for ( let i = 0, l = object.children.length; i < l; i ++ ) {

renderObject( object.children[ i ], scene, camera );
renderObject( object.children[ i ], scene, camera, childInheritedLayers );

}

Expand Down
19 changes: 16 additions & 3 deletions examples/jsm/renderers/CSS3DRenderer.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ class CSS3DRenderer {

}

function renderObject( object, scene, camera, cameraCSSMatrix ) {
function renderObject( object, scene, camera, cameraCSSMatrix, inheritedLayers = null ) {

if ( object.visible === false ) {

Expand All @@ -369,9 +369,20 @@ class CSS3DRenderer {

}

const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
const layerVisible = effectiveLayers.test( camera.layers );

if ( layerVisible === false && effectiveLayers.recursive === true ) {

hideObject( object );

return;

}

if ( object.isCSS3DObject ) {

const visible = ( object.layers.test( camera.layers ) === true );
const visible = layerVisible;

const element = object.element;
element.style.display = visible === true ? '' : 'none';
Expand Down Expand Up @@ -431,9 +442,11 @@ class CSS3DRenderer {

}

const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;

for ( let i = 0, l = object.children.length; i < l; i ++ ) {

renderObject( object.children[ i ], scene, camera, cameraCSSMatrix );
renderObject( object.children[ i ], scene, camera, cameraCSSMatrix, childInheritedLayers );

}

Expand Down
11 changes: 11 additions & 0 deletions src/core/Layers.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,17 @@ class Layers {
*/
this.mask = 1 | 0;

/**
* When set to `true`, this object's layer mask is propagated to all
* descendants during rendering and raycasting traversal. If the layer
* test fails, the entire subtree is skipped. If it passes, children
* inherit this object's layers instead of using their own.
*
* @type {boolean}
* @default false
*/
this.recursive = false;

}

/**
Expand Down
31 changes: 31 additions & 0 deletions src/core/Object3D.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1080,6 +1080,37 @@ class Object3D extends EventDispatcher {

}

/**
* Like {@link Object3D#traverseVisible}, but the callback will only be executed
* for visible 3D objects that pass the layer test. Descendants of invisible
* 3D objects and objects with recursive layers that fail the test are not traversed.
*
* Note: Modifying the scene graph inside the callback is discouraged.
*
* @param {Layers} cameraLayers - The camera layers to test against.
* @param {Function} callback - A callback function that allows to process the current 3D object.
*/
traverseVisibleWithLayers( cameraLayers, callback, inheritedLayers = null ) {

if ( this.visible === false ) return;

const effectiveLayers = inheritedLayers !== null ? inheritedLayers : this.layers;
const layerVisible = effectiveLayers.test( cameraLayers );

if ( ! layerVisible && effectiveLayers.recursive ) return;

if ( layerVisible ) callback( this );

const childInheritedLayers = this.layers.recursive ? this.layers : inheritedLayers;
Copy link

@diffray-bot diffray-bot Dec 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 HIGH - Incorrect layer inheritance - using object.layers instead of effectiveLayers
Agent: Delegated (architecture, bugs, documentation, performance)

Category: bug

Description:
When an object has recursive=true, children should inherit the effectiveLayers (which may have been inherited from an ancestor), not object.layers. The code checks object.layers.recursive instead of effectiveLayers.recursive, causing children to inherit the wrong layer mask when their parent inherited layers from an ancestor with recursive=true.

Suggestion:
Change line 1104 from 'const childInheritedLayers = this.layers.recursive ? this.layers : inheritedLayers;' to 'const childInheritedLayers = effectiveLayers.recursive ? effectiveLayers : inheritedLayers;'

Confidence: 85%
Review ID: 18426889-7dd5-4a37-bc33-d2c4c0357982
Rate it 👍 or 👎 to improve future reviews | Powered by diffray


for ( let i = 0, l = this.children.length; i < l; i ++ ) {

this.children[ i ].traverseVisibleWithLayers( cameraLayers, callback, childInheritedLayers );

}

}

Comment on lines +1083 to +1113
Copy link

@diffray-bot diffray-bot Dec 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 HIGH - New traverseVisibleWithLayers method lacks test coverage
Agent: testing

Category: quality

Description:
A new public method traverseVisibleWithLayers() was added to Object3D with parameters (cameraLayers, callback, inheritedLayers = null) but there are no corresponding unit tests. The existing traverse/traverseVisible/traverseAncestors tests follow a pattern in Object3D.tests.js but the new method combining layer visibility testing with inheritance logic has zero test coverage.

Suggestion:
Add comprehensive test case to test/unit/src/core/Object3D.tests.js following the existing pattern, testing: (1) Basic traversal with matching camera layers, (2) Traversal when child layers don't match camera layers, (3) Recursive layer inheritance - when parent has recursive=true and child has different layers, (4) Handling of inheritedLayers parameter (5) Edge case where recursive=true but test fails, (6) Multiple levels of nesting with mixed recursive values

Confidence: 92%
Rule: test_new_parameter_coverage
Review ID: 18426889-7dd5-4a37-bc33-d2c4c0357982
Rate it 👍 or 👎 to improve future reviews | Powered by diffray

/**
* Like {@link Object3D#traverse}, but the callback will only be executed for all ancestors.
*
Expand Down
13 changes: 10 additions & 3 deletions src/core/Raycaster.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,11 +233,16 @@ function ascSort( a, b ) {

}

function intersect( object, raycaster, intersects, recursive ) {
function intersect( object, raycaster, intersects, recursive, inheritedLayers = null ) {

const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
const visible = effectiveLayers.test( raycaster.layers );

if ( visible === false && effectiveLayers.recursive === true ) return;

let propagate = true;

if ( object.layers.test( raycaster.layers ) ) {
if ( visible ) {

const result = object.raycast( raycaster, intersects );

Expand All @@ -247,11 +252,13 @@ function intersect( object, raycaster, intersects, recursive ) {

if ( propagate === true && recursive === true ) {

const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;
Copy link

@diffray-bot diffray-bot Dec 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 HIGH - Incorrect layer inheritance in raycasting - using object.layers instead of effectiveLayers
Agent: Delegated (architecture, bugs, documentation, performance)

Category: bug

Description:
When an object has recursive=true, children should inherit the effectiveLayers (which may have been inherited from an ancestor), not object.layers. The code checks object.layers.recursive instead of effectiveLayers.recursive, causing incorrect raycasting behavior with inherited layers.

Suggestion:
Change line 255 from 'const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;' to 'const childInheritedLayers = effectiveLayers.recursive === true ? effectiveLayers : inheritedLayers;'

Confidence: 85%
Review ID: 18426889-7dd5-4a37-bc33-d2c4c0357982
Rate it 👍 or 👎 to improve future reviews | Powered by diffray


const children = object.children;

for ( let i = 0, l = children.length; i < l; i ++ ) {

intersect( children[ i ], raycaster, intersects, true );
intersect( children[ i ], raycaster, intersects, true, childInheritedLayers );

}

Expand Down
33 changes: 19 additions & 14 deletions src/renderers/WebGLRenderer.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1373,9 +1373,9 @@ class WebGLRenderer {

// gather lights from both the target scene and the new object that will be added to the scene.

targetScene.traverseVisible( function ( object ) {
targetScene.traverseVisibleWithLayers( camera.layers, function ( object ) {

if ( object.isLight && object.layers.test( camera.layers ) ) {
if ( object.isLight ) {

currentRenderState.pushLight( object );

Expand All @@ -1391,9 +1391,9 @@ class WebGLRenderer {

if ( scene !== targetScene ) {

scene.traverseVisible( function ( object ) {
scene.traverseVisibleWithLayers( camera.layers, function ( object ) {

if ( object.isLight && object.layers.test( camera.layers ) ) {
if ( object.isLight ) {

currentRenderState.pushLight( object );

Expand Down Expand Up @@ -1797,11 +1797,14 @@ class WebGLRenderer {

};

function projectObject( object, camera, groupOrder, sortObjects ) {
function projectObject( object, camera, groupOrder, sortObjects, inheritedLayers = null ) {

if ( object.visible === false ) return;

const visible = object.layers.test( camera.layers );
const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
const visible = effectiveLayers.test( camera.layers );

if ( visible === false && effectiveLayers.recursive === true ) return;

if ( visible ) {

Expand Down Expand Up @@ -1839,7 +1842,7 @@ class WebGLRenderer {

if ( material.visible ) {

currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null );
currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null, effectiveLayers );

}

Expand Down Expand Up @@ -1883,15 +1886,15 @@ class WebGLRenderer {

if ( groupMaterial && groupMaterial.visible ) {

currentRenderList.push( object, geometry, groupMaterial, groupOrder, _vector4.z, group );
currentRenderList.push( object, geometry, groupMaterial, groupOrder, _vector4.z, group, effectiveLayers );

}

}

} else if ( material.visible ) {

currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null );
currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null, effectiveLayers );

}

Expand All @@ -1901,11 +1904,13 @@ class WebGLRenderer {

}

const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;

const children = object.children;

for ( let i = 0, l = children.length; i < l; i ++ ) {

projectObject( children[ i ], camera, groupOrder, sortObjects );
projectObject( children[ i ], camera, groupOrder, sortObjects, childInheritedLayers );

}

Expand Down Expand Up @@ -2020,9 +2025,9 @@ class WebGLRenderer {

const renderItem = transmissiveObjects[ i ];

const { object, geometry, material, group } = renderItem;
const { object, geometry, material, group, effectiveLayers } = renderItem;

if ( material.side === DoubleSide && object.layers.test( camera.layers ) ) {
if ( material.side === DoubleSide && effectiveLayers.test( camera.layers ) ) {

const currentSide = material.side;

Expand Down Expand Up @@ -2067,7 +2072,7 @@ class WebGLRenderer {

const renderItem = renderList[ i ];

const { object, geometry, group } = renderItem;
const { object, geometry, group, effectiveLayers } = renderItem;
let material = renderItem.material;

if ( material.allowOverride === true && overrideMaterial !== null ) {
Expand All @@ -2076,7 +2081,7 @@ class WebGLRenderer {

}

if ( object.layers.test( camera.layers ) ) {
if ( effectiveLayers.test( camera.layers ) ) {

renderObject( object, scene, camera, geometry, material, group );

Expand Down
16 changes: 10 additions & 6 deletions src/renderers/common/RenderList.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ class RenderList {
* @param {ClippingContext} clippingContext - The current clipping context.
* @return {Object} The render item.
*/
getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext ) {
getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers ) {

let renderItem = this.renderItems[ this.renderItemsIndex ];

Expand All @@ -240,7 +240,8 @@ class RenderList {
renderOrder: object.renderOrder,
z: z,
group: group,
clippingContext: clippingContext
clippingContext: clippingContext,
effectiveLayers: effectiveLayers
};

this.renderItems[ this.renderItemsIndex ] = renderItem;
Expand All @@ -256,6 +257,7 @@ class RenderList {
renderItem.z = z;
renderItem.group = group;
renderItem.clippingContext = clippingContext;
renderItem.effectiveLayers = effectiveLayers;

}

Expand All @@ -276,10 +278,11 @@ class RenderList {
* @param {number} z - Th 3D object's depth value (z value in clip space).
* @param {?number} group - {?Object} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`.
* @param {ClippingContext} clippingContext - The current clipping context.
* @param {Layers} effectiveLayers - The effective layers for layer visibility testing.
*/
push( object, geometry, material, groupOrder, z, group, clippingContext ) {
push( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers ) {

const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext );
const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers );

if ( object.occlusionTest === true ) this.occlusionQueryCount ++;

Expand Down Expand Up @@ -310,10 +313,11 @@ class RenderList {
* @param {number} z - Th 3D object's depth value (z value in clip space).
* @param {?number} group - {?Object} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`.
* @param {ClippingContext} clippingContext - The current clipping context.
* @param {Layers} effectiveLayers - The effective layers for layer visibility testing.
*/
unshift( object, geometry, material, groupOrder, z, group, clippingContext ) {
unshift( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers ) {

const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext );
const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers );

if ( material.transparent === true || material.transmission > 0 ||
( material.transmissionNode && material.transmissionNode.isNode ) ||
Expand Down
9 changes: 9 additions & 0 deletions src/renderers/common/RenderObject.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,15 @@ class RenderObject {
*/
this.group = null;

/**
* The effective layers for layer visibility testing.
* This accounts for recursive layer inheritance from ancestors.
*
* @type {?Layers}
* @default null
*/
this.effectiveLayers = null;

/**
* An array holding the vertex buffers which can
* be buffer attributes but also interleaved buffers.
Expand Down
Loading