Skip to content

feat: add experimental tileset catalog #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jasoncavinder merged 3 commits into from
Aug 10, 2026
Merged

feat: add experimental tileset catalog #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2762523
feat: add experimental tileset catalog
jasoncavinder Aug 9, 2026
6e064f2
docs: accept ADR 0012
jasoncavinder Aug 9, 2026
eece11a
Merge dev and fix Windows tileset path test
jasoncavinder Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 15 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,12 @@ not a current support claim.
> Tilewright is experimental. It can inventory and load selected project JSON
> into bounded, read-only raw snapshots, then project map IDs, names, display
> order, and parent relationships into a typed catalog. It can also summarize
> one catalog-selected map's basic metadata and opaque event count, and selected
> project-level system settings. A further bounded projection lists map-scoped
> event IDs, names, coordinates, and opaque page counts. Its first contextual
> validator checks only the stored player start. It does not yet provide broader
> semantic understanding, project validity, or modification. Do not rely on it
> for valuable workflows.
> one catalog-selected map's basic metadata and opaque event count, selected
> project-level system settings, tileset IDs and editor-facing names, and
> map-scoped event IDs, names, coordinates, and opaque page counts. Its first
> contextual validator checks only the stored player start. It does not yet
> provide broader semantic understanding, project validity, or modification.
> Do not rely on it for valuable workflows.

## What Tilewright aims to provide

Expand Down Expand Up @@ -58,8 +58,8 @@ for the distinction between planned and supported behavior.

| Package | Role | Current state |
| --- | --- | --- |
| [`tilewright`](crates/tilewright/README.md) | Format-aware domain library and primary public API | Experimental discovery, inventory, strict lossless JSON syntax, raw snapshot loading, typed map and event catalogs, selected-map and system summaries, and player-start validation |
| [`tilewright-cli`](crates/tilewright-cli/README.md) | Human- and script-facing adapter; installs the `tilewright` executable | Experimental discovery, inventory, raw snapshot, typed map/event projections, player-start validation, and JSON inspection adapter |
| [`tilewright`](crates/tilewright/README.md) | Format-aware domain library and primary public API | Experimental discovery, inventory, strict lossless JSON syntax, raw snapshot loading, typed map, tileset, and event catalogs, selected-map and system summaries, and player-start validation |
| [`tilewright-cli`](crates/tilewright-cli/README.md) | Human- and script-facing adapter; installs the `tilewright` executable | Experimental discovery, inventory, raw snapshot, typed map/tileset/event projections, player-start validation, and JSON inspection adapter |
| [`tilewright-mcp`](crates/tilewright-mcp/README.md) | Thin MCP adapter over the library | Scaffold |

The dependency direction is inward:
Expand Down Expand Up @@ -115,6 +115,7 @@ cargo run -p tilewright-cli -- discover path/to/project --format json
cargo run -p tilewright-cli -- inventory path/to/project
cargo run -p tilewright-cli -- snapshot path/to/project
cargo run -p tilewright-cli -- maps path/to/project
cargo run -p tilewright-cli -- tilesets path/to/project
cargo run -p tilewright-cli -- map path/to/project 1
cargo run -p tilewright-cli -- events path/to/project 1
cargo run -p tilewright-cli -- system path/to/project
Expand All @@ -133,6 +134,7 @@ tilewright discover path/to/project --format json
tilewright inventory path/to/project
tilewright snapshot path/to/project
tilewright maps path/to/project
tilewright tilesets path/to/project
tilewright map path/to/project 1
tilewright events path/to/project 1
tilewright system path/to/project
Expand All @@ -146,9 +148,11 @@ for update and uninstall details.

The CLI currently exposes experimental candidate discovery, project inventory,
bounded raw snapshot loading, typed map-catalog inspection, selected-map
summaries, selected-map event catalogs, selected system-setting summaries,
bounded player-start validation, and strict lossless JSON syntax inspection.
The event command leaves page bodies and commands opaque. The validation
summaries, tileset identity/name catalogs, selected-map event catalogs,
selected system-setting summaries, bounded player-start validation, and strict
lossless JSON syntax inspection. The tileset command leaves modes, images,
flags, and notes opaque; the event command leaves page bodies and commands
opaque. The validation
command covers only the stored player start; it does not establish general
project validity or editor compatibility. No command establishes MZ-version
compatibility, round-trip behavior, or write support. Contributors should use
Expand Down
35 changes: 24 additions & 11 deletions crates/tilewright-cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,13 @@
## Status

This crate is experimental. It provides help and version output plus read-only
`discover`, `inventory`, `snapshot`, `maps`, `map`, `events`, `system`,
`validate`, and `inspect-json`
commands over the core library's experimental RPG Maker MZ
candidate-discovery, capability-relative project inventory, raw snapshot
loader, typed map catalog, selected-map summary and event catalog, system
summary, player-start validation, and strict lossless JSON syntax APIs. It does
not provide general project understanding, project validity, editor
compatibility, or modification.
`discover`, `inventory`, `snapshot`, `maps`, `tilesets`, `map`, `events`,
`system`, `validate`, and `inspect-json` commands over the core library's
experimental RPG Maker MZ candidate-discovery, capability-relative project
inventory, raw snapshot loader, typed map, tileset, and selected-map event
catalogs, selected-map and system summaries, player-start validation, and
strict lossless JSON syntax APIs. It does not provide general project
understanding, project validity, editor compatibility, or modification.

## Install from a checkout

Expand Down Expand Up @@ -66,6 +65,10 @@ cargo run -p tilewright-cli -- snapshot path/to/project --format json
cargo run -p tilewright-cli -- maps path/to/project
cargo run -p tilewright-cli -- maps path/to/project --format json

# List tileset IDs and editor-facing names.
cargo run -p tilewright-cli -- tilesets path/to/project
cargo run -p tilewright-cli -- tilesets path/to/project --format json

# Summarize one catalog-selected map.
cargo run -p tilewright-cli -- map path/to/project 1
cargo run -p tilewright-cli -- map path/to/project 1 --format json
Expand Down Expand Up @@ -128,6 +131,16 @@ available on `maps`. The command does not interpret map contents or events,
validate editor compatibility, provide stable project-wide resource identities,
or establish mutation, round-trip, and write support.

The `tilesets` command loads the same bounded snapshot and reports positive
tileset IDs and decoded editor-facing names in ID order. Missing, unavailable,
or structurally ambiguous `data/Tilesets.json` prevents projection and exits
with code 1. Unrelated snapshot diagnostics remain separate.

The command does not emit or interpret modes, image names, tile flags, notes, or
unknown fields. It does not validate map references, assets, tile behavior,
editor compatibility, mutation, round trips, or writes. The snapshot
resource-limit options are available on `tilesets`.

The `map` command loads the same bounded snapshot and delegates selection and
projection to the core library. It requires a coherent map catalog and matching
positive ID, then reports the catalog and display names, exact evidenced
Expand Down Expand Up @@ -188,9 +201,9 @@ a non-UTF-8 path.

Note: While descendant symlink entries are reported without traversal, the
initial `open_ambient_dir` acquisition used by `inventory`, `snapshot`, `maps`,
`map`, `events`, `system`, and `validate` may resolve root or ancestor symlinks
and does not prove root identity. The `inspect-json` command explicitly opens
the provided path and makes no project-containment claim.
`tilesets`, `map`, `events`, `system`, and `validate` may resolve root or
ancestor symlinks and does not prove root identity. The `inspect-json` command
explicitly opens the provided path and makes no project-containment claim.

## Responsibilities

Expand Down
Loading