Spatial V3 for 2.5D depth

Author 2.5D isometric depth and connected Spatial structures visually, with optional generated collisions for LibGDX scenes.

In an isometric game, actors must move consistently in front of and behind walls, buildings and other structures. Pixscape Spatial provides this 2.5D depth authoring visually in Studio.

Spatial V3 gives a 2D isometric scene coherent ordering around walls, fences, cliffs and buildings. You author rectangular wall footprints on tiled layers; Studio connects compatible walls into structures and compiles their exterior geometry for runtime depth decisions.

Spatial V3 is not a 3D renderer. Tiles remain fixed in layer order. Dynamic actors with Spatial enabled are the elements repositioned relative to the compiled structures.

What Spatial V3 solves

A multi-tile building is treated as one connected structure instead of a collection of unrelated depth blocks. Its compiled exterior faces give a dynamic actor a consistent front/behind relationship at corners, junctions, intersections and enclosed rooms. Optional generated fixtures keep the collision footprint synchronized with the same authored walls.

Spatial layers and Tiled Spatial Depth

A scene can contain only one dedicated Spatial actor layer. This is the common layer for dynamic actors that participate in Spatial 2.5D ordering. Studio offers the Spatial layer type only when scene Physics is enabled; after the scene has its Spatial actor layer, another one cannot be created.

A Tiled layer with Spatial Depth owns the authored Spatial structures in its environment. Multiple relevant Tiled layers may each enable Spatial Depth and contain their own walls or volumes. A Spatial actor layer and a Tiled layer with Spatial Depth therefore have related but different roles.

Prepare a tiled layer

1. Select the Tiled layer that contains the visible structure.
2. Enable Spatial Depth in Properties.
3. Set Default Altitude and Default Height for new walls.
4. In the Items tree, expand the layer and select Spatial volumes.

Ground-only layers normally do not need Spatial walls. Enable the feature on layers whose visible structures actors must pass in front of and behind.

Create a Spatial structure

1. Select the relevant Tiled layer.
2. Enable Spatial Depth for that layer.
3. In Items, select Spatial volumes.
4. Drag a rectangle across the occupied tile cells.
5. Release the pointer.
6. Studio creates the Spatial wall when the selection is valid.
7. Select the created wall and adjust its footprint or properties as needed.

A valid selection resolves to a filled rectangle of occupied tiles. Empty outer rows or columns are trimmed, while an internal hole or non-rectangular footprint is rejected. Run Preview and move a configured actor around every side of a new wall to verify its ordering.

Connected structures

Each wall has its own rectangular footprint and a structure ID. Walls that intersect through one or more cells are connected automatically when their shared properties are compatible. This supports straight walls, corners, T and cross junctions, U shapes, closed rooms, thick intersections and larger building outlines.

When a new wall joins existing structures, Studio merges them into one structure. Connected walls share structure altitude and height; an incompatible connection is rejected atomically rather than leaving a partial merge. Duplicate walls and walls fully contained inside another wall are also invalid.

Footprints and ordering

Select a wall to open SPATIAL WALL properties. Use X, Y, Width and Depth, or drag its canvas handles, to align the footprint with the visible base of the artwork. Structure altitude and Structure height apply to the complete connected structure.

New connected walls inherit the structure’s canonical alignment and thickness where applicable. Moving or resizing an existing wall is constrained when necessary to preserve its junctions. A locked handle usually means the requested edit would disconnect or invalidate the structure.

For predictable ordering, place the footprint on the part of the art that touches the ground, not around the full transparent image. Tileset Cell, Anchor and Offset settings can affect this alignment; review Import assets and tilesets before fine-tuning walls.

Enable Spatial on actors

Remember that a scene has one dedicated Spatial actor layer. To make an actor participate:

1. Create or select the scene’s Spatial layer. Scene Physics must be enabled before this layer type is available.
2. Place the actor on that Spatial layer.
3. Select the actor.
4. Enable Spatial Actor in Properties.
5. Adjust Altitude and Height when needed.

Actor Spatial footprint

A Spatial actor uses one explicitly designated circular physics footprint for 2.5D ordering. When you enable Spatial Actor on an eligible entity, Studio can create a default footprint automatically from the actor’s visual bounds if one has not already been authored. Use the normal physics tools to adjust it when the default does not match the actor.

The circle should match the part of the actor that touches the ground. A footprint that is too large or badly offset can make the actor change its front/behind relationship too early or too late. Conflicting multiple designated Spatial footprints are invalid.

Altitude and Height

Altitude is where the actor’s Spatial volume begins vertically. Height is that volume’s vertical extent. Spatial uses both values when deciding whether actor and structure volumes overlap vertically, and Height must remain positive for the actor to participate effectively.

Altitude and Height do not yet provide complete vertical 2.5D physics gameplay such as jumping over obstacles, floor-based collision filtering, or full multi-level collision behavior.

Preview the scene and move the actor through each doorway, corner and junction to verify the compiled ordering.

Collisions

Enable Use for physics collision on a Spatial wall to create a managed static polygon fixture from its base footprint. Studio regenerates the fixture when the wall changes and removes it when collision is disabled.

The generated fixture’s shape and offset are read-only because Spatial geometry owns them. You can still edit sensor, material and collision-filter properties. Deleting the generated fixture disables Use for physics collision in the same undoable operation, keeping wall and physics state synchronized.

Occlusion flags and current limits

The wall properties also expose Actor occluder, Light occluder, Shadow caster and Particle occluder. Actor ordering is implemented. The light, shadow and particle consumers are not implemented yet, so those flags do not currently add the corresponding rendering effects.

Other boundaries in 0.2.2:

• authored walls are rectangular, although connected structures can form complex outlines;
• all walls in one structure share altitude and height;
• wall creation needs a filled rectangular selection over occupied tiles;
• tiles themselves are not dynamically reordered by Spatial V3;
• invalid duplicate, containment, thickness or junction edits are rejected;
• old Spatial V2 data has no compatibility fallback or automatic migration.

Migrating Spatial data to Studio 0.2.2

Compatibility warning: Spatial V3 deliberately replaces the previous data model. Back up the project directory, then recreate affected tiled data and Spatial walls in Studio Free 0.2.2. If the scene originated in Tiled, the safest path is to import the TMX again as a new scene and author new structures there.

Do not rely on opening and saving an old scene to upgrade its Spatial volumes. After recreation, verify:

• tileset alignment and wall footprints;
• structure joins, shared altitude and height;
• actor ordering at every exterior face and opening;
• generated fixtures, sensors and collision filters;
• undo/redo for creation, editing, merging and fixture deletion;
• Preview behavior before replacing the old scene.

Troubleshooting

Dragging does not create a wall

Confirm that Spatial volumes is selected, the Tiled layer has Spatial Depth enabled, and the selection is a valid filled rectangle over occupied tiles.

A connecting wall is rejected

Check structure altitude, height, thickness and alignment. The wall cannot create an incompatible junction, duplicate or full containment.

Spatial Actor cannot be enabled

Confirm that the actor is a supported sprite or Animation entity on the scene’s Spatial layer, its visual bounds are valid, and its Spatial footprint state is valid.

An actor never changes depth

Confirm that the actor is on the Spatial actor layer, Spatial Actor is enabled, Height is positive, and the designated Spatial footprint is valid.

An actor switches sides at the wrong position

Adjust the designated circular footprint so it matches the actor’s ground contact area, then check the wall footprint against the visible base of the tileset art.

The collision shape cannot be resized

That is expected for a generated fixture. Edit the Spatial wall footprint; Studio will regenerate the fixture.

An older scene is rejected or behaves differently

Do not save it as an attempted in-place upgrade. Restore the backup, then reimport or recreate its tiled and Spatial data with 0.2.2 and verify the new scene in Preview.

For gameplay control of actor and tile altitude, height, and layer participation, see the Spatial API. For loading exported scene data in a game, continue with Runtime setup.