| name | rpg-maker-format-research |
| description | Investigate RPG Maker MZ project-file structure and behavior using authoritative sources, user-owned observations, explicit uncertainty, and safe experiments without importing proprietary material. |
| license | MPL-2.0 |
| compatibility | opencode |
| metadata | {"audience":"maintainers","workflow":"format-research"} |
RPG Maker MZ format research
Use an evidence-first workflow. The goal is not merely to make a parser accept one file; it is to establish a defensible format contract while preserving data that Tilewright does not yet understand.
Evidence hierarchy
Use evidence in this order:
- official documentation or an explicit vendor contract;
- direct observation of files generated by a user-owned RPG Maker MZ project;
- controlled before/after experiments in which one editor action changes one concept;
- inspectable runtime behavior relevant to project data;
- multiple independent community implementations or plugin-author reports;
- a single community claim, treated as a lead rather than proof.
Never paste proprietary application code or assets into the repository. Summarize behavior and record source locations instead.
Maintained version scope
Maintainer-led Tilewright research targets RPG Maker MZ 1.10.0 and newer under
docs/decisions/0002-rpg-maker-mz-version-floor.md. Investigate and label one
named version at a time; do not generalize an observation automatically to later
versions. Treat pre-1.10.0 research as contributor-led scope that needs its own
evidence, legal fixtures or generated test data, regression tests, and explicit
compatibility review.
Local experiment sandbox
Authorized user-owned projects under .local-research/sources/ are immutable
research inputs. Inspect them directly, but perform any write or execution in a
collision-resistant, per-session copy under .local-research/workspaces/.
Create the directory only if it does not exist and record an ownership manifest
with the session ID, coordinator, creation time, canonical source, provenance,
purpose, and copy method before experimenting.
Within the assigned workspace, agents may modify or delete files and run project
scripts, plugins, binaries, runtimes, and generated games when needed. Treat all
executable material as untrusted. A working directory is not containment: use a
host sandbox that confines writes, network, and credentials, or obtain explicit
user acceptance of unsandboxed risk for the named experiment. Do not follow or
create escaping symlinks.
Raw inputs and generated outputs stay ignored. Never force-add them or reproduce
them in tracked source, fixtures, documentation, patches, logs, screenshots, or
commit messages. Commit only derived observations, non-identifying provenance,
safe procedures, and independently legal synthetic fixtures.
Bounded workflow
- State the exact question and the behavior that depends on it.
- Search existing docs, ADRs, tests, and fixtures before external research.
- Build an evidence ledger with columns: claim, evidence, classification, confidence, and unresolved alternatives.
- Separate syntax from semantics. Knowing a JSON field's type does not prove its meaning or invariants.
- Identify unknown-field, ordering, identifier, encoding, and cross-file-reference risks.
- Resolve the canonical primary research root and atomically create and record
an owned local experiment workspace when direct observation requires mutation
or execution.
- Run the smallest controlled experiment needed to resolve each important
unknown, changing one concept at a time.
- Recommend a library contract only for behavior supported by the evidence.
Implementation implications
When evidence is incomplete:
- parse losslessly where practical;
- preserve unknown fields and values;
- avoid normalizing ordering or identifiers without proof;
- expose uncertainty through raw/extension data rather than dropping it;
- refuse unsafe writes when round-trip preservation cannot be guaranteed.
Output
Return:
- question and scope;
- evidence ledger;
- established facts;
- inferences and confidence;
- unresolved unknowns;
- safe API/fixture implications;
- next experiment.
