Layers#

Depth bands, sorting, coordinate spaces, parallax, and lighting.

A layer occupies one of sixteen depth bands. Entities sort inside their band and never against another band. Higher layer numbers draw nearer, so a HUD on layer 8 covers a world on layer 1.

tecs.gfx.layers.configure(1, {sort = "topdown", parallax = 0.4})
tecs.gfx.layers.configure(8, {
    sort = "z",
    screenSpace = true,
    unlit = true,
    overlay = true,
})

world:spawn(
    tecs.ecs.Transform2D(16, 16, 0, 8, 0, 96, 24),
    tecs.gfx.Tint(1.0, 1.0, 1.0, 1.0),
    tecs.gfx.Renderable2D
)

The fourth Transform2D argument selects the layer.

Sort modes#

"topdown" sorts by Y with Z for height. "z" ignores position. "isometric" combines X, Y, and Z for a diamond grid. Equal depths retain instance order.

setExtents(maxZ, maxY) defines the authored extents that each sort maps into its band. Values past an extent clamp to its edge. They still draw, but clamped entities no longer sort against one another. Reduce an extent if nearby depths collapse together in the target depth format.

Coordinate spaces#

World coordinates form the default. screenSpace uses target pixels and ignores the camera. virtualCoords stretches one virtualWidth by virtualHeight coordinate system to the target. ignoreZoom follows camera position while preserving drawn size. parallax scales camera movement.

One layer cannot combine screenSpace and virtualCoords. Virtual coordinates preserve the authored coordinate system but do not letterbox or preserve square pixels.

unlit bypasses scene lighting for UI, debug overlays, and other content that must retain its own color.

Put a HUD on a high screen-space, unlit overlay layer. overlay selects the forward lane even for opaque content. The layer still orders the HUD internally.

configure replaces the complete layer configuration. Any omitted option returns to its default.