rpg-maker-format-research

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:

1. official documentation or an explicit vendor contract;
2. direct observation of files generated by a user-owned RPG Maker MZ project;
3. controlled before/after experiments in which one editor action changes one concept;
4. inspectable runtime behavior relevant to project data;
5. multiple independent community implementations or plugin-author reports;
6. 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

1. State the exact question and the behavior that depends on it.
2. Search existing docs, ADRs, tests, and fixtures before external research.
3. Build an evidence ledger with columns: claim, evidence, classification, confidence, and unresolved alternatives.
4. Separate syntax from semantics. Knowing a JSON field's type does not prove its meaning or invariants.
5. Identify unknown-field, ordering, identifier, encoding, and cross-file-reference risks.
6. Resolve the canonical primary research root and atomically create and record an owned local experiment workspace when direct observation requires mutation or execution.
7. Run the smallest controlled experiment needed to resolve each important unknown, changing one concept at a time.
8. 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.