TMX Package Preflight

Catch broken or non-portable TMX/TSX references before build and distribution.

TMX Package Preflight is a small, read-only command-line gate for existing Tiled TMX/TSX XML projects. Point it at a project folder and receive a clear PASS, BLOCKED, or ERROR result before a bad reference reaches another machine, a case-sensitive build environment, or a release package.

It runs locally. It does not require Tiled, an account, a backend, a network connection, telemetry, or runtime AI.

The current version is 0.2.0-rc1 and the project status is In development. Its supported contract is intentionally frozen and documented below.

What it checks

• referenced files that are missing;
• path case that differs from the name stored on disk;
• references that escape the authorized project root;
• cycles between referenced TMX/TSX documents;
• symlinked or unreadable paths that the checker will not follow;
• invalid TMX/TSX XML inputs.

The scanner follows tileset source, image source, object template, and file-property references in TMX and TSX XML documents.

One-command project check

Choose the ZIP for your Linux architecture, extract it, then run:

./tmx-preflight scan --root /path/to/project --all

The packaged positive fixture is available immediately:

./tmx-preflight scan --root fixtures/pass --all

Optional evidence outputs:

./tmx-preflight scan --root /path/to/project --all \
  --json report.json \
  --transcript run.txt \
  --png run.png

Exit code 0 means PASS, 1 means BLOCKED, and 2 means invalid input, configuration, or execution. This makes the same check usable by a person or a CI step.

Included

• static Linux executable for amd64 or arm64;
• positive and blocked TMX/TSX fixtures;
• quick-start README;
• buyer license and third-party notices;
• deterministic terminal, JSON, transcript, and 1280×720 PNG outputs.

No activation or online service is required. The buyer license permits use in commercial and non-commercial projects and CI systems under the buyer's control. The software itself may not be redistributed.

Deliberately narrow scope

This release checks TMX and TSX XML reference portability and integrity. It does not support TMJ/TSJ, edit files, repair references, validate GIDs or geometry, integrate with an engine, test performance or security, playtest a project, or guarantee build success or marketplace approval.

Only the listed Linux builds are included. Both packaged architectures were executed automatically against positive and blocked fixtures on a Linux kernel; that does not guarantee every distribution or environment.

Frequently asked questions

Does this replace Tiled?

No. It reads references in existing TMX/TSX XML projects. It is not an editor, exporter, renderer, or replacement for Tiled.

Does it modify or repair my project?

No. The scan is read-only. Findings identify the source, reference, resolved path and, for case mismatches, a suggested spelling; you decide what to change.

Must Tiled be installed?

No. The checker reads XML directly and does not launch or depend on Tiled.

Which formats and systems are supported?

TMX and TSX XML documents on Linux amd64 and arm64. JSON variants TMJ and TSJ, Windows, and macOS builds are not included in this release.

Can I use it in CI?

Yes. Use --all, read exit codes 0, 1, and 2, and optionally save the canonical JSON report. The software may run on machines and CI systems under the buyer's control, subject to LICENSE.txt.

Are my maps uploaded?

No. The executable has no network, account, backend, telemetry, or runtime AI. It reads the authorized local project root and writes only optional outputs you request.

Does PASS guarantee that my game builds or runs?

No. PASS means no blocking reference condition was found within this tool's documented TMX/TSX scope. It does not test an engine, gameplay, security, performance, marketplace rules, or every possible project defect.

Support

For support, use the comments section on this itch.io project page. Include the product version, command, exit code, and JSON report when possible; do not post private project files or credentials.

Independence and disclosure

TMX Package Preflight is an independent utility for TMX/TSX projects. It is not affiliated with or endorsed by the Tiled project or its maintainer.

Product development and listing materials were AI-assisted and human-directed. The shipped runtime contains no AI.