Import Tiled maps and tilesets (.tmx / .tsx)

Import supported Tiled TMX maps and TSX tilesets into Pixscape Studio and export them as Pixscape scene data for LibGDX.

Pixscape Studio Free 0.2.2 imports a supported Tiled .tmx map as a new Pixscape scene. It can also import a supported standalone .tsx tileset through the regular asset importer.

The source files are not runtime dependencies. Studio converts their maps, layers, images, tilesets and animations into native Pixscape project data, which Pixscape Runtime loads in the LibGDX game. See Tiled Maps for gameplay access to exported layers and cells.

Import a TMX map

1. Open or create a Pixscape project.
2. Choose File > Import > Tiled map (.tmx)....
3. Select the .tmx file.
4. Review the preflight summary and every diagnostic.
5. Confirm or change the scene name.
6. Click Import.

The importer creates and opens a new scene. It does not add the map to the current scene, reimport a previous map or keep the project synchronized with Tiled.

Preflight runs before project data is changed. A blocking diagnostic prevents import; a warning identifies data that will be adapted or ignored. If materialization fails after preflight, the transaction is rollback-aware so the previous project and scene can be restored instead of retaining a partial import.

Compatibility matrix

Image paths in .tmx and external .tsx files are resolved relative to the file that declares them. Keep the referenced images beside the source files at the expected relative paths when importing.

For direct .tsx import and manual PNG tileset profiles, see Import assets.

Tileset profiles and alignment

Imported tilesets retain the tile dimensions, margin and spacing declared by Tiled. Studio also exports a tileset profile used to place the rendered image relative to its logical cell.

After import, check tall walls, props and tiles whose image dimensions differ from the map cell. If the visual anchor needs adjustment, review the tileset profile fields described in Import assets: cell size, projection, anchor and X/Y offset. This is especially important before authoring Spatial V3 walls.

Tile animations

For animations declared on a supported single-image tileset, Studio preserves the declared frame order and each frame duration. The imported definition is available to Studio’s tiled-animation workflow and is included when the project is exported for Pixscape Runtime.

An empty animation, a frame outside the tileset range or a non-positive frame duration is a blocking error. Tile animations on image-collection tilesets are not part of the supported animation scope in 0.2.2.

See Tiled animations in Studio and Tiled animations in the Runtime for editing and playback details.

Map size reporting

The preflight summary reports map dimensions, tile-layer count, non-empty tile count and Required tiled cells. Required cells are calculated from each tile layer’s complete area, not only painted cells, so large sparse layers still carry their full cell cost. No fixed numeric maximum is stated here because the inspected 0.2.2 import source does not define one.

Diagnostics

Typical blocking diagnostics include:

• a missing or unsupported tileset or image-layer image;
• an invalid GID or animation frame;
• an unsupported map orientation, encoding or compression;
• an infinite map or non-zero tile offset;
• a tileset whose single-image tile dimensions do not match the map cell;
• invalid or non-positive map and tile dimensions.

Warnings cover non-imported object layers, ignored custom properties and unsupported image-layer attributes. Read them before continuing: the scene can import successfully while intentionally omitting that data.

Migrating existing projects to Studio 0.2.2

Compatibility warning: Tiled-map and Spatial data created by older Studio releases are not backward-compatible with the 0.2.2 data model. There is no automatic V2-to-V3 migration or compatibility fallback.

1. Make a backup copy of the project directory before opening it in 0.2.2.
2. If the scene came from Tiled, import its source .tmx again. This creates a new scene.
3. If no source map exists, recreate the affected tiled layers and Spatial walls rather than expecting old data to be upgraded.
4. Verify tileset anchors and offsets, animated tiles, transformed tiles and image layers.
5. Recreate and test Spatial structures and generated collision fixtures.
6. Save only after the new scene behaves correctly in Preview.

See Spatial V3 for 2.5D depth for the new wall-authoring workflow and Runtime setup for loading exported scenes.

Troubleshooting

The import command is unavailable

Open or create a project first. TMX import needs an active project and scene.

A tileset image is missing

Restore the relative path referenced by the .tmx or .tsx file. External TSX paths are resolved from the TSX file.

An invalid GID is reported

The layer or animation refers to a tile ID outside its declared tileset range. Correct the source map in Tiled and import it again.

The map imports, but some data is absent

Review the warnings. Object layers, custom properties and some image-layer attributes are intentionally not materialized in 0.2.2.

The imported tiles do not align visually

Check the tileset profile, especially cell size, anchor and offset. The render size remains the source image’s native size.