Optionaloptions: RenderLayerOptionsWhether this object has been destroyed. If true, the object should no longer be used. After an object is destroyed, all of its functionality is disabled and references are removed.
Container#destroy For destroying objects
ReadonlyparentThe display object container that contains this display object. This represents the parent-child relationship in the display tree.
// Basic parent access
const parent = sprite.parent;
// Walk up the tree
let current = sprite;
while (current.parent) {
console.log('Level up:', current.parent.constructor.name);
current = current.parent;
}
Readonly AdvancedparentThe RenderLayer this container belongs to, if any. If it belongs to a RenderLayer, it will be rendered from the RenderLayer's position in the scene.
ReadonlyrenderThe list of objects that this layer is responsible for rendering. Objects in this list maintain their original parent in the scene graph but are rendered as part of this layer.
const layer = new RenderLayer();
const sprite = new Sprite(texture);
// Add sprite to scene graph for transforms
container.addChild(sprite);
// Add to layer for render order control
layer.attach(sprite);
console.log(layer.renderLayerChildren.length); // 1
// Access objects in the layer
layer.renderLayerChildren.forEach(child => {
console.log('Layer child:', child);
});
// Check if object is in layer
const isInLayer = layer.renderLayerChildren.includes(sprite);
// Clear all objects from layer
layer.detachAll();
console.log(layer.renderLayerChildren.length); // 0
If set to true, the container will sort its children by zIndex value
when the next render is called, or manually if sortChildren() is called.
This actually changes the order of elements in the array of children, so it will affect the rendering order.
Also be aware of that this may not work nicely with the addChildAt() function,
as the zIndex sorting may cause the child to automatically sorted to another position.
Function used to sort layer children if sortableChildren is true
Adds one or more Containers to this render layer. The Containers will be rendered as part of this layer while maintaining their original parent in the scene graph.
If the Container already belongs to a layer, it will be removed from the old layer before being added to this one.
The Container(s) to add to this layer. Can be any Container or array of Containers.
The first child that was added, for method chaining
const layer = new RenderLayer();
const container = new Container();
const sprite1 = new Sprite(texture1);
const sprite2 = new Sprite(texture2);
// Add sprites to scene graph for transforms
container.addChild(sprite1, sprite2);
// Add sprites to layer for render order control
layer.attach(sprite1, sprite2);
// Add single sprite with type checking
const typedSprite = layer.attach<Sprite>(new Sprite(texture3));
typedSprite.tint = 'red';
// Automatically removes from previous layer if needed
const otherLayer = new RenderLayer();
otherLayer.attach(sprite1); // Removes from previous layer
Removes one or more Containers from this render layer. The Containers will maintain their original parent in the scene graph but will no longer be rendered as part of this layer.
The Container(s) to remove from this layer
The first child that was removed, for method chaining
const layer = new RenderLayer();
const container = new Container();
const sprite1 = new Sprite(texture1);
const sprite2 = new Sprite(texture2);
// Add sprites to scene graph and layer
container.addChild(sprite1, sprite2);
layer.attach(sprite1, sprite2);
// Remove single sprite from layer
layer.detach(sprite1);
// sprite1 is still child of container but not rendered in layer
// Remove multiple sprites at once
const otherLayer = new RenderLayer();
otherLayer.attach(sprite3, sprite4);
otherLayer.detach(sprite3, sprite4);
// Type-safe detachment
const typedSprite = layer.detach<Sprite>(spriteInLayer);
typedSprite.texture = newTexture; // TypeScript knows this is a Sprite
Removes all objects from this render layer. Objects will maintain their original parent in the scene graph but will no longer be rendered as part of this layer.
The RenderLayer instance for method chaining
const layer = new RenderLayer();
const container = new Container();
// Add multiple sprites to scene graph and layer
const sprites = [
new Sprite(texture1),
new Sprite(texture2),
new Sprite(texture3)
];
container.addChild(...sprites); // Add to scene graph
layer.attach(...sprites); // Add to render layer
// Later, remove all sprites from layer at once
layer.detachAll();
console.log(layer.renderLayerChildren.length); // 0
console.log(container.children.length); // 3 (still in scene graph)
AdvancedComputes an approximate global bounding box for the container and its children. This method is optimized for speed by using axis-aligned bounding boxes (AABBs), and uses the last render results from when it updated the transforms. This function does not update them. which may result in slightly larger bounds but never smaller than the actual bounds.
for accurate (but less performant) results use container.getGlobalBounds
OptionalfactorRenderLayers: booleanA flag indicating whether to consider render layers in the calculation.
Optionalbounds: BoundsThe output bounds object to store the result. If not provided, a new one is created.
The computed bounds.
Sort the layer's children using the defined sort function. This method allows manual sorting of layer children and is automatically called during rendering if sortableChildren is true.
The RenderLayer instance for method chaining
const layer = new RenderLayer();
// Add multiple sprites at different depths
const sprite1 = new Sprite(texture);
const sprite2 = new Sprite(texture);
const sprite3 = new Sprite(texture);
sprite1.zIndex = 3;
sprite2.zIndex = 1;
sprite3.zIndex = 2;
layer.attach(sprite1, sprite2, sprite3);
// Manual sorting with default zIndex sort
layer.sortRenderLayerChildren();
// Order is now: sprite2 (1), sprite3 (2), sprite1 (3)
// Custom sort by y position
layer.sortFunction = (a, b) => a.y - b.y;
layer.sortRenderLayerChildren();
// Automatic sorting
layer.sortableChildren = true; // Will sort each render
The RenderLayer API provides a way to control the rendering order of objects independently of their logical parent-child relationships in the scene graph. This allows developers to decouple how objects are transformed (via their logical parent) from how they are rendered on the screen.
Key Concepts
RenderLayers Control Rendering Order:
Logical Parenting Remains Unchanged:
Explicit Control:
API Details
1. Creating a RenderLayer
A RenderLayer is a lightweight object responsible for controlling render order. It has no children or transformations of its own but can be inserted anywhere in the scene graph to define its render position.
2. Adding Objects to a Layer
Use renderLayer.add to assign an object to a layer. This overrides the object's default render order defined by its logical parent.
3. Removing Objects from a Layer
To stop an object from being rendered in the layer, use remove.
When an object is removed from its logical parent (removeChild), it is automatically removed from the layer.
4. Re-Adding Objects to Layers
If an object is re-added to a logical parent, it does not automatically reassign itself to the layer. Developers must explicitly reassign it.
5. Layer Position in Scene Graph
A layer's position in the scene graph determines its render priority relative to other layers and objects. Layers can be inserted anywhere in the scene graph.
This is a new API and therefore considered experimental at this stage. While the core is pretty robust, there are still a few tricky issues we need to tackle. However, even with the known issues below, we believe this API is incredibly useful!
Known issues: