Spatial API

Control Universal Layer actor participation, entity volumes, and independent Tiled Map Spatial Depth.

Spatial helps a 2.5D or isometric scene decide whether an actor appears in front of or behind map geometry. Runtime exposes three related controls with separate responsibilities.

Universal Layer Spatial participation

api.spatial() enables or disables Spatial actor participation for normal Universal Layers:

api.spatial().setLayerEnabled(layerIndex, true);

boolean enabled =
        api.spatial().isLayerEnabled(layerIndex);

The value is the exported visual Layer index. setLayerEnabled(...) updates every Runtime Layer matching that index. These are normal Universal Layers with optional Spatial actor participation.

Entity Spatial volume

Use entity.spatial() to configure an actor’s vertical volume:

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

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

Altitude is the bottom of the volume; height is its vertical extent. Use altitude(), height(), setAltitude(...), and setHeight(...) for individual values. disable() removes the entity’s Spatial height component, and negative finite heights are clamped to zero.

enable() establishes authored volume state, but effective participation also requires:

• Spatial actor participation on the owning Universal Layer
• a positive height
• a valid authored Spatial footprint
• an otherwise renderable entity

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

The footprint comes from the Physics shape authored as the entity’s Spatial footprint. See Physics and Collisions for Runtime Physics access.

Tiled Map Spatial Depth

A Tiled Map has independent Spatial Depth state through TiledMapRef.spatial():

TiledMapRef walls =
        api.tiled().requireStableId(wallsMapStableId);

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

The default altitude and height apply to cells without an explicit override:

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

Override one cell when it needs a different volume:

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

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

tileAltitude(...) and tileHeight(...) return effective values, including the Map default when no override exists. Use hasTileOverride(...) to distinguish an explicit value, and clearTileOverride(...) to restore the Map default. Negative finite heights are clamped to zero.

Independent controls

Universal Layer Spatial participation controls eligible actors and entities owned by that Layer. Tiled Map Spatial Depth controls that Map and its cells. Neither enables or mirrors the other: a Layer can contain a spatially enabled Map without participating as a Spatial actor Layer, and a Spatial actor Layer can contain a Map whose Spatial Depth is disabled.

Spatial and normal render order

renderOrder() controls normal Universal Layer placement and local z-index. Spatial adds 2.5D relationships for participating actors, Map cells, and Spatial Blocks; it does not replace normal placement.

Spatial Blocks authored in Studio contribute to ordering automatically. The high-level API does not expose block authoring. See Spatial V3 for 2.5D depth for the visual authoring workflow.