Metatile Bridge

Metatile Bridge

A small NES 2×2 metatile compiler with round-trip checks.

Turn a tile grid into deterministic C and ca65 tables, then check that every tile index and palette selector comes back intact.

Metatile Bridge is an experimental, offline Python command-line tool for developers who want an inspectable conversion step in their build process. It accepts a documented JSON format, an uncompressed 32×30 nametable, or a limited NEXXT text-session canvas. It exports C arrays, ca65 byte tables, a documented binary, and reconstruction/check reports.

What you get

• Palette-aware 2×2 deduplication with stable first-seen IDs.
• A decoder and verifier that compare against your original source.
• Source code, tests, synthetic examples, and format documentation.
• A one-command demo: python3 demo.py.
• A single-screen assembly RAM-expansion example, checked with ca65/ld65 and 6502 CPU emulation.
• No accounts, telemetry, or network calls. The core tool uses only Python's standard library.

Free, with an optional contribution

The complete download is free. If you find it useful, the suggested contribution is $5 USD. Paying does not unlock extra features, priority support, or promised updates.

MIT licensed. Copyright (c) 2026 Old Key Interactive. You can use, modify, and redistribute the software under the included license, including commercially, while retaining its copyright and permission notice. The software license does not clear rights in your input assets. See LICENSE and NOTICES.md in the download.

Before you download

This is a source-code tool, not a visual editor or one-click NES game maker. You need Python 3.10+ and a command line. Linux with Python 3.12 was tested; Windows and macOS were not. The optional assembly/runtime checks need external cc65 tools and py65; nothing auto-installs them.

NSS import is canvas-only. It does not import CHR graphics, color values, collision data, existing editor metatile IDs, sprites, or session state. There is a maximum of 256 unique tile-and-palette metatiles. The importer was checked against NEXXT 3.8 source and distribution samples, not a running editor workflow or every session format. This is not affiliated with NEXXT.

You still need to integrate the data into your game. The assembly example writes a RAM buffer: it is not a PPU upload routine or vblank-safe code. No full NES emulator, PPU, or hardware validation is claimed. C output compiled with cc65, but the C probe was not linked or run as a game.

What was checked

The v0.3.1 release passed 53 automated tests, real ca65 assembly, a cc65 header compile, 36 assembled CPU/RAM screen cases, and 96 additional adversarial runtime checks. Import/export stress tests and provenance reports are included. This is not a human security audit or a hardware certification.

NEXXT and nexxtporter already provide free editing/export workflows. This tool's narrower purpose is deterministic 2×2 conversion and explicit reconstruction checks; you may not need it if your current workflow already does that well. Storage savings depend on your data and are not guaranteed.

Development, documentation, and the geometric listing graphics were AI-assisted. The gallery shows a workflow diagram and a rendering of actual demo output, not a graphical editor or running game.

Start here

Unzip the download, open a terminal in its folder, and run:

python3 demo.py

Then read README.md, INTEROPERABILITY.md, and RUNTIME-WORKFLOW.md for the exact input contract and integration limits. The included software is provided as-is under the MIT license.