LayerDef

Defined in: renderer/src/LayerDef.ts:42

Declarative layer definition attached to a Scene subclass via readonly layers = [...]. The renderer augments Scene in core (via scene-augmentation.ts) so this field is typed without core depending on renderer.

A layer’s space controls whether cameras transform it:

• "world" (default) — cameras auto-bind the layer (unless spawned with autoBind: false), so it scrolls/zooms with the world.
• "screen" — cameras skip the layer on auto-bind, so it stays fixed to the viewport. Use for HUD, menus, dialogs, or any UI you want anchored to the screen.

UI plugins auto-provision a screen-space "ui" layer when no layer is explicitly declared, so a single new UISurface(...) keeps working with zero layer wiring.

Properties

isRenderGroup?

optional isRenderGroup?: boolean

Defined in: renderer/src/LayerDef.ts:106

Promote the layer’s container to a Pixi v8 render group boundary so its children render as a separate pass with their own uniform scope. Default: false.

Why this exists: when a filter is applied to anything inside a render group, Pixi composes the filter’s uWorldTransformMatrix from the active render group’s transform and leaves it on the global uniform stack until the group ends. Sibling render passes that read globalUniforms directly — notably @pixi/tilemap’s TilemapPipe.execute (which pulls _activeUniforms.at(-1)) — pick up that polluted matrix and visibly drift.

Set isRenderGroup: true on layers that contain filtered content AND on any sibling layer whose contents must stay unaffected (e.g. a canopy tilemap above filtered entities). Both layers then sit inside their own uniform scope, and the filter’s transform stays scoped to its source.

---

name

name: string

Defined in: renderer/src/LayerDef.ts:54

Unique layer name within a scene. "default" is special — every scene’s render tree auto-creates a layer called "default" at order 0, and any sprite/text/graphics with no explicit layer renders there. Declaring { name: "default", order: 0, sort, space, isRenderGroup } configures that pre-created layer (e.g. { name: "default", order: 0, sort: ySort } to depth-sort the layer your entities are already on). order is required, but the value declared for "default" is ignored — "default" is the order-0 layer by definition. Use any other name to add a separate custom layer.

---

order

order: number

Defined in: renderer/src/LayerDef.ts:56

Draw order within the scene. Lower values render first (behind higher values).

---

sort?

optional sort?: LayerSortFn

Defined in: renderer/src/LayerDef.ts:88

Depth-key function applied to the layer’s children. When set, DisplaySystem writes child.zIndex = sort(child) for every child each frame, and flips container.sortableChildren = true so Pixi’s render pipeline orders the layer by zIndex. Default: unset (insertion order).

Use ySort for the classic top-down depth rule, or ySortBy(getOffset) to anchor each sprite’s sort key at a per-entity Y offset (Godot’s y_sort_origin pattern — matches a sprite’s apparent “footprint” instead of its top-left).

Game code that manually writes child.zIndex on individual sprites doesn’t need sort — Pixi already sorts them once sortableChildren is on. sort is for the common case where the key is a function of the sprite’s current state (position, depth offset, etc.) and needs to be recomputed each frame.

---

space?

optional space?: LayerSpace

Defined in: renderer/src/LayerDef.ts:69

Coordinate space the layer lives in. Default: "world".

• "world": included in a camera’s auto-bindings, so it scrolls and zooms with the camera. Use for gameplay layers (background, entities, foreground), parallax, and diegetic UI that should follow an entity. Naming the layer in a camera’s bindings changes how it follows, not whether it does, unless the camera sets autoBind: false.
• "screen": excluded from auto-bindings; stays fixed to the viewport. Use for HUD, menus, dialogs, and other screen-anchored UI. Cameras can still opt in explicitly by naming the layer in their bindings.