Spatial API

Control 2.5D front/behind ordering for LibGDX actors and Tiled layers with Pixscape Spatial.

In a 2.5D or isometric LibGDX scene, Spatial helps Pixscape decide what appears in front of or behind something else.

The normal gameplay model has three parts:

1. Enable Spatial for a scene layer.
2. Give actors an altitude and height.
3. Give Tiled cells an altitude and height.

Enable Spatial on a layer

SpatialAPI spatial = api.spatial();

api.spatial().setLayerEnabled(2, true);
boolean enabled = api.spatial().isLayerEnabled(2);

The number is the visual/exported scene layer index. Spatial ordering only applies to layers that participate in Spatial; Studio display names are not Runtime layer identity.

setLayerEnabled(...) updates every Runtime layer matching that layer index.

Give an actor a Spatial volume

EntityRef player = api.entities().requireTag("player");

player.spatial()
        .enable()
        .setVolume(0f, 32f);

• Altitude is where the Spatial volume starts vertically.
• Height is how tall the volume is.

You can inspect or change them separately with altitude(), height(), setAltitude(...), and setHeight(...). disable() removes the actor’s vertical Spatial volume. Negative height values are clamped to zero.

Check effective participation

enable() establishes the actor’s vertical volume, but does not by itself guarantee effective Spatial ordering.

if (player.spatial().participatesInRenderOrder()) {
    // The actor currently participates in Spatial ordering.
}

The actor must be renderable on a Spatial-enabled actor layer, have a positive height, and have a valid Spatial actor footprint.

In Runtime 0.1.9, the footprint comes from the physics shape explicitly authored as the actor’s Spatial footprint. An ordinary circle fixture is not selected automatically. Author the footprint through the normal Studio physics/Spatial workflow; Pixscape combines it with the actor’s altitude and height. See Physics and Collisions for Runtime physics access.

Give a Tiled layer default volumes

Get the Tiled layer by its exported layer index:

TiledLayerRef walls = api.tiled().requireLayerIndex(4);

walls.spatial()
        .setEnabled(true)
        .setDefaultVolume(0f, 48f);

The default altitude and height apply to tiles on that layer unless a cell has its own override.

float defaultAltitude = walls.spatial().defaultAltitude();
float defaultHeight = walls.spatial().defaultHeight();
boolean spatialEnabled = walls.spatial().enabled();

Override one tile

walls.spatial().setTileVolume(12, 4, 0f, 96f);

float altitude = walls.spatial().tileAltitude(12, 4);
float height = walls.spatial().tileHeight(12, 4);

A cell override replaces the layer default for that tile. tileAltitude(...) and tileHeight(...) return the effective values, including the default when there is no override.

Use hasTileOverride(...) to check for an explicit value. Clear it to return the cell to the layer default:

walls.spatial().clearTileOverride(12, 4);

Negative tiled height values are also clamped to zero.

Spatial and normal render order

renderOrder() controls an entity’s normal scene layer and local z-index. Spatial ordering adds 2.5D front/behind relationships for participating actors, Tiled cells, and Spatial Blocks; it does not replace normal layer placement.

Spatial Blocks authored in Studio contribute to the scene’s 2.5D ordering automatically. The high-level Spatial API focuses on gameplay controls; advanced Spatial authoring and query APIs are separate from this normal guide. See Spatial V3 for 2.5D depth for the visual authoring workflow.