diff --git a/README.md b/README.md index 61d0b27..45d3e4a 100644 --- a/README.md +++ b/README.md @@ -150,7 +150,6 @@ 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, tileset identity/name catalogs, selected system-setting summaries, summaries, tileset identity/name catalogs, selected-map event catalogs, selected system-setting summaries, bounded player-start and map-to-tileset validation, and strict lossless JSON syntax inspection. The tileset command diff --git a/docs/capability-roadmap.md b/docs/capability-roadmap.md index f1180c1..bd933b6 100644 --- a/docs/capability-roadmap.md +++ b/docs/capability-roadmap.md @@ -183,8 +183,12 @@ The bounded `System.json` orientation summary is accepted in [ADR 0009](decisions/0009-experimental-system-summary.md) and implemented experimentally. It projects only the seven accepted string and nonnegative integer fields, retains raw bytes and unknown settings in the snapshot, and -does not validate map references or coordinate bounds. Neither acceptance nor -implementation makes the capability Supported. +does not validate map references or coordinate bounds. A controlled MZ 1.10.0 +save preserved negative player-start coordinates, exposing a known gap in that +unsigned contract. Proposed +[ADR 0014](decisions/0014-signed-player-start-coordinates.md) defines the +correction. Neither acceptance nor implementation makes the capability +Supported. A bounded tileset identity/name catalog is implemented experimentally under accepted [ADR 0012](decisions/0012-experimental-tileset-catalog.md). It leaves @@ -218,8 +222,9 @@ decision. **Current status: Experimental first slice.** The player-start contract accepted in [ADR 0010](decisions/0010-experimental-player-start-validation.md) composes the system summary, coherent map catalog, and selected-map dimensions. It -reports only the evidenced zero triplet, an unevidenced mixed-zero state, a -missing positive catalog record, and coordinates outside the map rectangle. +reports only the evidenced zero triplet, a distinct zero-map/mixed-coordinate +state, a missing positive catalog record, and coordinates outside the map +rectangle. Structural projection failures remain errors. A finding-free result is not a general project-validity or compatibility claim, and the general severity and diagnostic model remains open. @@ -332,10 +337,13 @@ Differential verification matched all 196 catalog records and all 196 selected-map summaries in the local four-project MZ 1.10.0 evidence corpus. It also matched all 28 field comparisons and all four output envelopes for the system summary. Controlled MZ 1.10.0 experiments also establish same-map start -relocation and editor recognition/preservation of the exact zero triplet as -`None`. Independent differential verification also matched the bounded tileset -and event projections and the map-to-tileset validation relationship against -the four-project corpus. The next evidence steps are controlled tileset name, -mode, and map-assignment experiments plus event creation, movement, renaming, -page lifecycle, and deletion. Tile behavior, event page bodies, and commands -remain later separate slices. +relocation, Delete-generated zero-triplet serialization, and preservation of +mixed-zero, exact-boundary, dangling-map, negative-coordinate, and upper +out-of-bounds states. The negative case returns the system and player-start +contracts to the contract stage under proposed ADR 0014. Independent +differential verification also matched the bounded tileset and event +projections and the map-to-tileset validation relationship against the +four-project corpus. A controlled tileset rename changed only the name field; +the next editor evidence steps are tileset mode and map assignment plus event +creation, movement, renaming, page lifecycle, and deletion. Tile behavior, +event page bodies, and commands remain later separate slices. diff --git a/docs/compatibility.md b/docs/compatibility.md index 4992830..eb4dec7 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -42,8 +42,8 @@ not use “supported” to mean only that one file happened to parse. | RPG Maker MZ typed tileset catalog | Experimental | Projects exact `data/Tilesets.json` into positive catalog-scoped IDs and decoded editor-facing names in ID order while retaining exact bytes and every unprojected field. It accepts null holes and refuses ambiguous required structure or ID/index mismatches. Aggregate evidence covers 24 records and 196 resolving map references across four MZ 1.10.0 projects, and an independent differential audit matched all 72 bounded comparisons. Modes, image slots, flags, notes, map-reference validation, assets, tile behavior, lifecycle operations, malformed-input editor behavior, mutation, persistence, and later versions remain unknown or unimplemented, so the capability remains Experimental. | | RPG Maker MZ selected-map summary | Experimental | Requires a coherent typed map catalog and matching catalog-scoped ID, then projects one evidenced three-digit map document into its exact path, catalog and display names, positive dimensions, positive tileset ID scalar, and count of opaque event objects. Unknown fields and exact bytes remain in the raw snapshot. The operation refuses ambiguous required structure and does not interpret tile data or event bodies, validate tileset references or editor compatibility, support IDs above 999, mutate, serialize, or persist data. Direct shape evidence covers 196 map documents from four MZ 1.10.0 projects, and an independent differential audit matched every bounded summary field across the corpus. Later versions and malformed-input editor behavior remain unknown, so the capability remains Experimental. | | RPG Maker MZ selected-map event catalog | Experimental | Requires a coherent map catalog, matching catalog-scoped ID, and evidenced three-digit map document, then projects map-scoped positive event IDs, decoded names, nonnegative coordinates, and opaque page counts in ID order. Coordinates outside the map dimensions are contextual findings, not editor-rejection claims. Exact bytes, notes, page bodies, commands, and unknown fields remain in the raw snapshot. Aggregate evidence covers 1,555 events and 1,576 pages across 196 MZ 1.10.0 map documents, and an independent differential audit matched all 10,323 bounded comparisons. Page semantics, commands, mutation, persistence, malformed-input editor behavior, and later versions remain unknown or unimplemented, so the capability remains Experimental. | -| RPG Maker MZ system summary | Experimental | Projects exact `data/System.json` from an existing snapshot into its exact path, decoded game title, currency unit, and locale, plus nonnegative editor-map and player-start map/X/Y scalars. Unknown settings and exact bytes remain in the raw snapshot. The operation refuses ambiguous required structure and does not interpret other system settings, validate map references or coordinate bounds, compare titles across files, mutate, serialize, or persist data. Aggregate shape evidence covers four MZ 1.10.0 projects, and an independent differential audit matched all 28 field comparisons and all four output envelopes across that corpus. Later versions and malformed-input editor behavior remain unknown, so the capability remains Experimental. | -| RPG Maker MZ player-start validation | Experimental | Composes the system summary, coherent map catalog, and selected-map dimensions over one existing snapshot. It reports the observed exact zero triplet as an unset player start, treats a zero map ID with nonzero coordinates as unevidenced, reports a missing positive catalog record, and checks `x < width` and `y < height`. Structural projection failures remain operation errors. Findings do not imply general project validity or editor rejection, and a finding-free report does not establish compatibility, passability, runtime success, mutation safety, or write support. Direct editor evidence covers one controlled MZ 1.10.0 relocation and recognition/preservation of the prepared zero triplet. An independent differential audit matched all 36 bounded comparisons across four MZ 1.10.0 projects, whose observed states were all finding-free. Delete-generated serialization, mixed-zero behavior, malformed-reference editor behavior, negative-category corpus coverage, and later versions remain unknown. | +| RPG Maker MZ system summary | Experimental | Projects exact `data/System.json` from an existing snapshot into its exact path, decoded game title, currency unit, and locale, plus nonnegative editor-map and player-start map/X/Y scalars. Unknown settings and exact bytes remain in the raw snapshot. The current unsigned-coordinate contract rejects an MZ 1.10.0 saved negative-coordinate state; proposed ADR 0014 defines a correction but is not implemented. Aggregate shape evidence covers four projects, an independent differential audit matched all 28 field comparisons and four output envelopes, and controlled saves cover deletion, mixed zero, exact bounds, dangling map IDs, negative coordinates, and upper out-of-bounds coordinates. The operation remains Experimental and does not establish general editor validity, runtime behavior, mutation, persistence, or later-version compatibility. | +| RPG Maker MZ player-start validation | Experimental | Composes the system summary, coherent map catalog, and selected-map dimensions over one existing snapshot. It reports the exact zero triplet as an unset player start, a zero map ID with nonzero coordinates as a distinct ambiguous state, a missing positive catalog record, and coordinates outside the map rectangle. Structural projection failures remain operation errors. MZ 1.10.0 generated the zero triplet through Delete and saved prepared mixed-zero, exact-boundary, dangling-map, negative-coordinate, and upper-out-of-bounds states. The current unsigned system projection prevents validation of the observed negative case; proposed ADR 0014 defines a correction. Findings do not imply general project validity, editor rejection, passability, runtime success, mutation safety, write support, or later-version behavior. | | RPG Maker MZ map-to-tileset reference validation | Experimental | Composes coherent map and tileset catalogs with every selected-map summary and deterministically reports positive map tileset IDs that have no catalog record. Structural prerequisite failures remain operation errors. A finding-free report does not establish project validity, editor acceptance, asset existence, tile behavior, runtime success, compatibility, mutation safety, or write support. Aggregate evidence covers 196 resolving references across four MZ 1.10.0 projects, and an independent differential audit matched all 220 bounded comparisons. Malformed-reference editor behavior and later versions remain unknown. | | General project validation | Not implemented | Only bounded experimental player-start and map-to-tileset relationships are implemented; no general validity, severity, compatibility, repair, or write-time validation contract exists. | | Lossless project round trips | Not implemented | The immutable syntax representation has an exact accepted-input no-op contract, but no project round-trip, typed edit, or supported mutation exists. | diff --git a/docs/decisions/0014-signed-player-start-coordinates.md b/docs/decisions/0014-signed-player-start-coordinates.md new file mode 100644 index 0000000..2271f64 --- /dev/null +++ b/docs/decisions/0014-signed-player-start-coordinates.md @@ -0,0 +1,112 @@ +# ADR 0014: Signed Player-Start Coordinates + +- **Status:** Proposed +- **Date:** 2026-08-09 +- **Supersedes in part:** + [ADR 0009](0009-experimental-system-summary.md) and + [ADR 0010](0010-experimental-player-start-validation.md) + +## Context + +ADR 0009 selected `u32` for all four projected map-position scalars because the +initial four-project corpus contained only nonnegative values. The resulting +system summary therefore rejects a negative `startX` or `startY` before the +player-start validator can report its relationship to the selected map. + +A controlled RPG Maker MZ 1.10.0 tolerance matrix has now contradicted that +assumption. In an owned disposable project, the editor saved prepared +`startX = -1` and `startY = -1` values without normalizing them. The same matrix +also preserved exact upper in-bounds coordinates, upper out-of-bounds +coordinates, a dangling positive start-map ID, and a zero map ID with nonzero +coordinates. These observations establish persistence tolerance in that +version, not editor validity or runtime success. + +The stored coordinate domain must therefore be representable independently +from coordinate validation. Map IDs remain nonnegative in all available +evidence and retain their existing zero and positive-reference behavior. + +## Decision + +If accepted, the experimental system-summary and player-start contracts will +change as follows: + +1. `editMapId` and `startMapId` remain stored `u32` scalars. Their zero, + dangling, and catalog-reference semantics remain separate validation + questions. +2. `startX` and `startY` become stored `i64` scalars in `SystemSummary`, + `PlayerStartValidation`, and their associated findings. The `i64` boundary + is an explicit Tilewright representation limit, not a claimed MZ limit. +3. Coordinate projection accepts strict base-ten JSON integer lexemes in the + inclusive `i64` range. It continues to refuse fractional, exponent-form, + or out-of-range coordinates through the existing typed unsupported-integer + error. Map ID projection retains its unsigned-decimal `u32` policy. +4. The exact `startMapId = 0`, `startX = 0`, `startY = 0` triplet continues to + produce `MissingPlayerStart`. +5. A zero map ID with either nonzero signed coordinate continues to produce + `ZeroMapIdWithCoordinates`, but documentation and human output describe it + as an editor-preserved ambiguous state rather than an unobserved state. +6. For a positive catalog-selected map, a negative coordinate or a coordinate + greater than or equal to the corresponding positive dimension produces the + existing `OutOfBounds` finding. This remains a contextual geometric finding, + not an editor-rejection claim. +7. The core operations remain pure and read-only. Exact source bytes, unknown + properties, and every unprojected setting remain untouched in the snapshot. +8. Because successful `system --format json` and `validate --format json` + reports can newly contain negative coordinate values, the CLI output schema + version advances from 1 to 2. The other command shapes remain unchanged, + but the current executable-wide schema number advances consistently. + +## Rationale + +Signed storage reflects observed project data without conflating tolerance with +validity. Keeping map IDs unsigned avoids expanding an unrelated domain. An +`i64` bound is wide, directly serializable by the Rust and JSON adapters, and +keeps recoverable range failure explicit without exposing the provisional CST. + +Reusing `OutOfBounds` preserves the caller's real question: whether the stored +coordinate lies in the selected map's zero-origin rectangle. A separate +negative-coordinate category would encode a representation detail without +changing the relationship or available remediation. + +Advancing the JSON schema version makes the successful value-domain change +visible to script consumers. Tilewright is pre-1.0 and these APIs are +Experimental, but versioned output should still avoid silent contract changes. + +## Consequences + +- Tilewright can summarize and validate the newly observed negative-coordinate + state instead of failing structural projection. +- Public Rust coordinate accessors and finding fields change from `u32` to + `i64`; downstream experimental callers must update explicit types. +- Existing nonnegative reports retain the same values and finding categories. +- CLI consumers must accept schema version 2 before processing new reports. +- Values outside `i64`, exponent notation, and fractional forms remain refused + without implying that MZ rejects them. +- General project validity, runtime behavior, mutation, and persistence remain + outside the capability. + +## Alternatives Considered + +- **Keep `u32` and classify negative values as malformed:** Rejected because it + contradicts a directly observed MZ 1.10.0 saved state and prevents contextual + validation from running. +- **Use `i32`:** Rejected because no editor evidence establishes a 32-bit + coordinate limit; the narrower bound would add an unsupported assumption. +- **Expose the raw numeric lexeme:** Rejected because callers need a small + domain value and the raw document already preserves exact syntax. +- **Add a distinct negative-coordinate finding:** Rejected because negative and + upper-bound values violate the same evidenced rectangular relationship. +- **Keep CLI schema version 1:** Rejected because successful coordinate fields + change from a nonnegative to a signed value domain. +- **Interpret editor preservation as validity:** Rejected because Save tolerance + does not establish runtime behavior, passability, or editor intent. + +## Validation + +Implementation requires generated synthetic tests for `-1`, `i64::MIN`, +`i64::MAX`, both overflow directions, nonnegative regression cases, zero-map +mixed coordinates, negative and upper out-of-bounds findings, raw-byte +preservation, schema-version-2 human/JSON adapters, and typed structural errors. +The retained local controlled cases must be checked differentially without +copying project data into the repository. The complete Rust quality gate must +pass before merge. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index d4c2dbd..61b02cb 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -5,7 +5,9 @@ implementation context has changed. ## Proposed decisions -No decisions are currently proposed. +| ADR | Status | Summary | +| --- | --- | --- | +| [0014: Signed player-start coordinates](0014-signed-player-start-coordinates.md) | Proposed | Correct the experimental system and player-start projections to retain observed signed coordinates and report their map relationship contextually. | ## Accepted decisions diff --git a/docs/formats/rpg-maker-mz/player-start-validation.md b/docs/formats/rpg-maker-mz/player-start-validation.md index 4a5e232..50f59c2 100644 --- a/docs/formats/rpg-maker-mz/player-start-validation.md +++ b/docs/formats/rpg-maker-mz/player-start-validation.md @@ -10,13 +10,13 @@ Can Tilewright use the bounded system summary, map catalog, and selected-map summary to report useful player-start relationships without guessing editor acceptance rules or exposing a broad validation framework prematurely? -Direct observations cover one disposable copy of a user-created RPG Maker MZ -1.10.0 project on the recorded macOS environment. A separate read-only -differential audit covers four authorized MZ 1.10.0 projects. Official -documentation describes deletion and the runtime consequence of an unset -player start. Later versions, converted projects, malformed editor behavior, -vehicle starts, passability, event placement, and write behavior remain outside -this contract. +Direct observations cover multiple isolated disposable copies of a user-created +RPG Maker MZ 1.10.0 project on the recorded macOS environment. A separate +read-only differential audit covers four authorized MZ 1.10.0 projects. +Official documentation describes deletion and the runtime consequence of an +unset player start. Later versions, converted projects, runtime behavior for +prepared edge states, vehicle starts, passability, event placement, and write +behavior remain outside this contract. ## Evidence ledger @@ -25,10 +25,10 @@ this contract. | The player start can be moved by selecting a map position, and the editor shows the selected location. | `MZ-HELP-SYSTEM1-2026-08-07` | Documented | High for the editor concept | The help does not name serialized fields or numeric bounds. | | The player-start icon can be deleted, and the game cannot start without a player starting position. | `MZ-HELP-SYSTEM1-2026-08-07` | Documented | High for the documented editor and runtime behavior | The help does not specify serialized unset values. | | Moving the player start within the same map from displayed coordinate `(8, 6)` to `(2, 3)` changed `startX`, `startY`, and save bookkeeping, while `startMapId` remained fixed; reopening showed `(2, 3)`. | `MZ-1.10.0-PLAYER-START-RELOCATION-2026-08-09` | Observed | High for this controlled action and version | Cross-map relocation, boundary positions, and later versions remain unobserved. | -| MZ 1.10.0 presents the exact stored triplet `startMapId = 0`, `startX = 0`, `startY = 0` as `None`, preserves it across Save, and presents `None` again after reopen. | `MZ-1.10.0-PLAYER-START-ZERO-TRIPLET-2026-08-09` | Observed tolerance and preservation | High for recognizing and preserving the exact triplet | The triplet was prepared outside the editor because automation could not activate the main map canvas; this does not prove the Delete gesture emits it. | +| MZ 1.10.0 presents the exact stored triplet `startMapId = 0`, `startX = 0`, `startY = 0` as `None`, preserves it across Save, and emits that triplet after the editor's Delete gesture in a separate copy. | `MZ-1.10.0-PLAYER-START-ZERO-TRIPLET-2026-08-09` and `MZ-1.10.0-PLAYER-START-DELETE-2026-08-09` | Observed generation, tolerance, and preservation | High for these controlled actions and version | Runtime behavior and later versions remain unobserved. | | A positive `startMapId` absent from a coherent `MapInfos.json` catalog is an unresolved cross-file reference. | Existing typed contracts | Inferred | High as an internal relationship finding | Editor acceptance and repair behavior remain unknown. | -| A nonnegative coordinate at or beyond a selected map's positive width or height is outside that map's zero-origin rectangular index range. | Relocation observation plus typed map dimensions | Inferred | High as arithmetic contextual validation | Editor acceptance, clamping, passability, and runtime behavior remain unknown. | -| A zero map ID with nonzero coordinates has established set or unset semantics. | Incomplete mixed-zero experiment | Unknown | No conclusion | The Mac locked before the editor could open the prepared state. | +| A signed coordinate below zero or a nonnegative coordinate at or beyond a selected map's positive width or height is outside that map's zero-origin rectangular index range. | Relocation observation, typed map dimensions, and `MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09` | Inferred relationship over observed stored values | High as arithmetic contextual validation | Editor validity, passability, and runtime behavior remain unknown. | +| MZ 1.10.0 saved prepared mixed-zero, exact-boundary, dangling-map, negative-coordinate, and upper-out-of-bounds start states without normalizing the triplets. | `MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09` | Observed persistence tolerance | High for the five exact states and version | Persistence does not establish whether the states are semantically set, unset, valid, or runnable. | | Tilewright's merged player-start validator matches an independent reconstruction of the bounded relationship across the four-project MZ 1.10.0 corpus. | `MZ-1.10.0-PLAYER-START-DIFFERENTIAL-2026-08-09` | Observed implementation behavior | High for the exact implementation and corpus | All observed source states were finding-free; synthetic tests cover negative categories, while editor behavior for those states remains unknown. | ## Controlled editor observations @@ -70,6 +70,41 @@ this contract. - **Redistribution:** Only derived property names, equality results, controlled values, and editor presentation are retained. +### `MZ-1.10.0-PLAYER-START-DELETE-2026-08-09` + +- **Kind:** Controlled editor action. +- **Version/environment:** The same editor and platform in a fresh disposable + copy of the authorized Basic project. +- **Procedure:** Deleted the player-start marker through the editor, saved, + closed, and compared only derived property-level results with the immutable + baseline. +- **Observed:** Delete generated the exact `0, 0, 0` triplet already observed + as `None`. Only `startMapId`, `startX`, `startY`, and unrelated `versionId` + differed from the baseline. +- **Limits:** This does not establish runtime behavior, every deletion context, + or later-version serialization. +- **Redistribution:** Only controlled values, changed property names, and + equality results are retained. + +### `MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09` + +- **Kind:** Controlled malformed/tolerance matrix. +- **Version/environment:** The same editor and platform; five isolated copies + with a `17 x 13` selected map. +- **Procedure:** Prepared one triplet per closed-editor copy: mixed zero + `(0, 8, 6)`, exact upper in-bounds `(1, 16, 12)`, dangling positive map + `(999, 8, 6)`, negative coordinates `(1, -1, -1)`, and exact upper + out-of-bounds `(1, 17, 13)`. Opened and saved each project, then compared only + the selected scalars, decoded changed-property names, and root key equality. +- **Observed:** Every save retained its prepared triplet exactly. Only the + prepared field or fields and unrelated `versionId` differed from the + baseline; the decoded root property set remained fixed. The negative case + demonstrates that MZ 1.10.0 can save signed start coordinates. +- **Limits:** Save tolerance is not an editor-validity, UI-semantics, runtime, + passability, clamping, or numeric-range claim. No playtest was performed. +- **Redistribution:** Only controlled triplets, map dimensions, changed + property names, and equality results are retained. + ## Differential implementation audit ### `MZ-1.10.0-PLAYER-START-DIFFERENTIAL-2026-08-09` @@ -108,6 +143,13 @@ the existing system-summary, map-catalog, and selected-map projections. It: - checks a catalog-selected map using `x < width` and `y < height`; and - preserves all raw documents and unknown fields without filesystem I/O. +The current implementation cannot reach those relationship checks when a +coordinate is negative because the system summary still projects coordinates +as `u32`. Proposed +[ADR 0014](../../decisions/0014-signed-player-start-coordinates.md) corrects +that evidence conflict by using signed stored coordinates and applying the same +rectangular out-of-bounds relationship to negative values. + An unavailable structural projection is an operation error, not a contextual finding. Findings have no public severity and do not generally claim editor rejection. The missing-player-start message may state the documented @@ -128,12 +170,10 @@ RPG Maker MZ accepts or rejects the synthetic states. ## Remaining unknowns and next experiments -- Use the editor's Delete gesture on the player-start icon and compare the - generated state with the observed zero triplet. -- Complete the zero-map/nonzero-coordinate tolerance experiment after the host - is unlocked. -- Test exact coordinate boundaries and dangling positive map IDs in a - disposable copy before making editor-rejection claims. +- Establish UI presentation and runtime consequences for mixed-zero, dangling, + negative, and upper-out-of-bounds states before making validity claims. +- Test lower and upper values beyond the exact observed matrix only if a caller + capability needs broader numeric evidence. - Repeat the relocation and unset observations on another named MZ version at or above 1.10.0 before broadening compatibility scope. - Keep vehicle starts, passability, map transfer events, and broader diagnostic diff --git a/docs/formats/rpg-maker-mz/research-ledger.md b/docs/formats/rpg-maker-mz/research-ledger.md index 7d12ecf..1bdd30f 100644 --- a/docs/formats/rpg-maker-mz/research-ledger.md +++ b/docs/formats/rpg-maker-mz/research-ledger.md @@ -1744,10 +1744,27 @@ validity. The accepted architecture is recorded in retained. Only aggregate derived observations and the non-content-revealing procedure are recorded. +### Evidence record: `MZ-1.10.0-TILESET-NAME-2026-08-09` + +- **Kind:** Controlled editor rename. +- **Version/environment:** RPG Maker MZ 1.10.0 on arm64 macOS 26.6 build + 25G72; unique disposable copy of the authorized Basic project. +- **Procedure:** Renamed exactly one existing record through Database → + Tilesets, saved, closed, and compared only changed decoded property names, + identity/structure equality, and string lengths with the baseline. +- **Observed:** Only record 1's `name` changed within `Tilesets.json`. Its ID, + mode, note, image-name array, flag array, surrounding records, and array + length remained equal. The save changed only unrelated `versionId` in + `System.json`. +- **Limits:** One rename does not establish allowed text, normalization, + uniqueness, record lifecycle, mutation safety, or later-version behavior. +- **Redistribution:** No name, asset string, note, flag, path, raw excerpt, + digest, screenshot, or project-specific value is retained. + ### Next experiment -Change one tileset name, toggle one mode, and reassign one map in separate -disposable MZ 1.10.0 copies, saving and reopening after each action. +Toggle one tileset mode and reassign one map in separate disposable MZ 1.10.0 +copies, saving and reopening after each action. ## `mz-map-events-001`: What is the smallest useful map-event catalog? @@ -1865,7 +1882,9 @@ experiments are maintained in roles are documented by `MZ-HELP-SYSTEM1-2026-08-07` and the existing `MZ-SCRIPTREF-DB-1.0.0` record. Direct shape evidence is recorded as `MZ-1.10.0-SYSTEM-SUMMARY-SHAPE-AUDIT-2026-08-07`; implementation parity is -recorded as `MZ-1.10.0-SYSTEM-SUMMARY-DIFFERENTIAL-2026-08-07`. +recorded as `MZ-1.10.0-SYSTEM-SUMMARY-DIFFERENTIAL-2026-08-07`. Controlled +edge-state evidence is recorded by `MZ-1.10.0-PLAYER-START-DELETE-2026-08-09` +and `MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09`. ### Evidence record: `MZ-HELP-SYSTEM1-2026-08-07` @@ -1930,6 +1949,41 @@ recorded as `MZ-1.10.0-SYSTEM-SUMMARY-DIFFERENTIAL-2026-08-07`. `4/4` and `28/28` counts were emitted and retained. No project path, title, currency text, locale value, raw document, excerpt, or digest is retained. +### Evidence record: `MZ-1.10.0-PLAYER-START-DELETE-2026-08-09` + +- **Kind:** Controlled editor action. +- **Version/environment:** RPG Maker MZ 1.10.0 on arm64 macOS 26.6 build + 25G72; unique disposable copy of the authorized Basic project. +- **Procedure:** Deleted the player-start marker through the editor, saved, + closed, and compared only derived property-level results with the immutable + baseline. +- **Observed:** Delete generated exact `startMapId = 0`, `startX = 0`, and + `startY = 0`. Those properties and unrelated `versionId` were the only + decoded values that differed from the baseline. +- **Limits:** This does not establish runtime behavior, every deletion context, + or later-version serialization. +- **Redistribution:** Only controlled values, changed property names, and + equality results are retained. + +### Evidence record: `MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09` + +- **Kind:** Controlled malformed/tolerance matrix. +- **Version/environment:** The same editor and platform; five isolated copies + with a `17 x 13` selected map. +- **Procedure:** Prepared mixed-zero `(0, 8, 6)`, exact upper in-bounds + `(1, 16, 12)`, dangling positive map `(999, 8, 6)`, negative coordinates + `(1, -1, -1)`, and exact upper out-of-bounds `(1, 17, 13)` in separate + closed-editor copies. Opened and saved each project, then compared only the + selected scalars, decoded changed-property names, and root key equality. +- **Observed:** Every save retained its prepared triplet exactly. Only the + prepared scalar or scalars and unrelated `versionId` differed from baseline; + the root key set remained fixed. MZ therefore saved signed negative start + coordinates in the observed scope. +- **Limits:** Persistence tolerance is not evidence of editor validity, UI + meaning, runtime success, passability, clamping, or broader numeric limits. +- **Redistribution:** Only controlled triplets, map dimensions, changed + property names, and equality results are retained. + ### Implementation implications The implemented experimental projection decodes only the three selected strings @@ -1938,14 +1992,17 @@ raw lossless document. It refuses ambiguous required structure, avoids normalizing strings or treating map scalars as stable identifiers, and makes no validation, mutation, or editor-compatibility claim. The accepted architecture is recorded in -[ADR 0009](../../decisions/0009-experimental-system-summary.md). +[ADR 0009](../../decisions/0009-experimental-system-summary.md). The negative +coordinate observation contradicts the implemented unsigned-coordinate bound; +proposed [ADR 0014](../../decisions/0014-signed-player-start-coordinates.md) +defines the correction. ### Next experiment -Use the editor's Delete gesture on the player-start icon and compare the -generated state with the exact zero triplet that MZ 1.10.0 has now been observed -to recognize and preserve as `None`. Complete the prepared mixed-zero state -experiment before interpreting zero map IDs with nonzero coordinates. +Establish UI presentation and runtime consequences for the preserved +mixed-zero, dangling, negative, and upper-out-of-bounds states before assigning +validity semantics. Observe another named version at or above 1.10.0 before +broadening the coordinate contract. ## `mz-player-start-validation-001`: What player-start relationships can be validated? @@ -1966,7 +2023,9 @@ implications, and remaining experiments are maintained in Official behavior is recorded by `MZ-HELP-SYSTEM1-2026-08-07`. Controlled editor results are recorded by `MZ-1.10.0-PLAYER-START-RELOCATION-2026-08-09` and -`MZ-1.10.0-PLAYER-START-ZERO-TRIPLET-2026-08-09`. Implementation parity is +`MZ-1.10.0-PLAYER-START-ZERO-TRIPLET-2026-08-09`, with deletion and edge-state +tolerance recorded by `MZ-1.10.0-PLAYER-START-DELETE-2026-08-09` and +`MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09`. Implementation parity is recorded by `MZ-1.10.0-PLAYER-START-DIFFERENTIAL-2026-08-09`. ### Evidence record: `MZ-1.10.0-PLAYER-START-DIFFERENTIAL-2026-08-09` @@ -1994,19 +2053,22 @@ recorded by `MZ-1.10.0-PLAYER-START-DIFFERENTIAL-2026-08-09`. ### Implementation implications The implemented experimental operation composes existing owned projections. It -can report the observed zero triplet, an unevidenced zero-map/mixed-coordinate -state, a missing positive catalog record, and coordinates outside positive map -dimensions. Structural projection failures remain errors. Findings do not -claim general editor rejection, validity, compatibility, or write safety. The -accepted architecture is recorded in -[ADR 0010](../../decisions/0010-experimental-player-start-validation.md). +can report the observed zero triplet, a zero-map/mixed-coordinate state, a +missing positive catalog record, and nonnegative coordinates outside positive +map dimensions. Structural projection failures remain errors. It currently +cannot report the observed negative-coordinate state because the system summary +rejects it first. Findings do not claim general editor rejection, validity, +compatibility, or write safety. Accepted +[ADR 0010](../../decisions/0010-experimental-player-start-validation.md) defines +the original operation; proposed +[ADR 0014](../../decisions/0014-signed-player-start-coordinates.md) defines the +evidence-driven correction. ### Next experiment -Complete the editor Delete and mixed-zero experiments, then test exact map -coordinate boundaries and a dangling positive start-map ID in separate owned -copies. Repeat the bounded observations on another named version at or above -1.10.0 before broadening compatibility scope. +Establish UI presentation and runtime consequences for mixed-zero, dangling, +negative, and upper-out-of-bounds states. Repeat the bounded observations on +another named version at or above 1.10.0 before broadening compatibility scope. ## `mz-map-tileset-validation-001`: Which map-to-tileset references can be validated? diff --git a/docs/formats/rpg-maker-mz/system-summary.md b/docs/formats/rpg-maker-mz/system-summary.md index 5625424..21884f5 100644 --- a/docs/formats/rpg-maker-mz/system-summary.md +++ b/docs/formats/rpg-maker-mz/system-summary.md @@ -11,11 +11,11 @@ orientation without interpreting the complete database, validating references, or treating editor state as stable project identity? Direct observations cover four user-owned projects created by RPG Maker MZ -1.10.0 plus one controlled disposable-copy experiment on the recorded macOS -environment. Official documentation describes the roles of the selected -settings. Later versions, converted projects, malformed input, editor-generated -unset serialization, and plugin-defined extensions remain outside the -established scope. +1.10.0 plus controlled player-start experiments in disposable copies on the +recorded macOS environment. Official documentation describes the roles of the +selected settings. Later versions, converted projects, runtime behavior, +general malformed-input behavior, and plugin-defined extensions remain outside +the established scope. ## Evidence ledger @@ -24,7 +24,8 @@ established scope. | `System.json` stores system data including initial game settings. | `MZ-HELP-SYSTEM1-2026-08-07` and `MZ-SCRIPTREF-DB-1.0.0` | Documented | High for the official role and filename | Editor-requiredness and other-version behavior remain unknown. | | `gameTitle`, `currencyUnit`, and `locale` identify the game title, currency unit, and language setting. | Official System 1 help and script reference | Documented | High for the named roles | Allowed string contents, locale grammar, normalization, and editor validation are unknown. | | `editMapId` is the map being edited; `startMapId`, `startX`, and `startY` describe the player's initial position. | `MZ-SCRIPTREF-DB-1.0.0`; controlled map lifecycle and player-start records; official System 1 help | Documented and Observed | High for the field roles in the observed MZ 1.10.0 scope | Malformed references, numeric limits, and other versions remain unknown. | -| MZ 1.10.0 presents and preserves the exact `startMapId = 0`, `startX = 0`, `startY = 0` triplet as `None`. | `MZ-1.10.0-PLAYER-START-ZERO-TRIPLET-2026-08-09` | Observed tolerance and preservation | High for this exact prepared state | The editor's Delete gesture was not directly observed to generate the triplet, and mixed-zero behavior remains unknown. | +| MZ 1.10.0 presents and preserves the exact `startMapId = 0`, `startX = 0`, `startY = 0` triplet as `None`, and the editor's Delete gesture generated that triplet in a separate copy. | `MZ-1.10.0-PLAYER-START-ZERO-TRIPLET-2026-08-09` and `MZ-1.10.0-PLAYER-START-DELETE-2026-08-09` | Observed generation, tolerance, and preservation | High for these controlled actions and version | Runtime behavior and later versions remain unobserved. | +| MZ 1.10.0 saved prepared mixed-zero, exact-boundary, dangling-map, negative-coordinate, and upper-out-of-bounds player-start states without normalizing the three scalars. | `MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09` | Observed persistence tolerance | High for the five exact states and version | Save tolerance does not establish validity, runtime behavior, UI meaning, or broader numeric limits. | | All four audited documents have object roots and one shared set of 58 decoded top-level property names. | `MZ-1.10.0-SYSTEM-SUMMARY-SHAPE-AUDIT-2026-08-07` | Observed | High across the four fresh projects | Duplicate decoded properties were not established absent; converted, plugin-extended, and later-version shapes may differ. | | Every selected string field is present and string-valued; every selected numeric field is present and integer-valued. | Shape audit | Observed syntax | High across the four fresh projects | Requiredness and editor behavior for missing, duplicate, alternate-kind, or alternate numeric forms remain unknown. | | Observed edit and start map IDs are positive and resolve to map-catalog records; observed start coordinates are nonnegative and within the referenced map dimensions. | Shape and cross-file audit | Observed | High across all four projects | This is not evidence that the editor rejects zero, missing, dangling, or out-of-bounds values. | @@ -73,6 +74,45 @@ establish behavior for malformed or unavailable documents beyond synthetic tests, human-output presentation beyond adapter tests, editor acceptance, converted projects, later MZ versions, or broader system semantics. +## Controlled player-start tolerance observations + +### `MZ-1.10.0-PLAYER-START-DELETE-2026-08-09` + +- **Kind:** Controlled editor action. +- **Version/environment:** RPG Maker MZ 1.10.0 on arm64 macOS 26.6 build + 25G72; unique disposable copy of the authorized Basic project. +- **Procedure:** Deleted the player-start marker through the editor, saved, + closed, and inspected only derived property-level differences against the + immutable baseline. +- **Observed:** The saved triplet was exactly `startMapId = 0`, `startX = 0`, + and `startY = 0`. Those three properties and unrelated `versionId` were the + only decoded `System.json` values that differed from the baseline. +- **Limits:** This establishes one editor-generated unset representation, not + runtime behavior, other versions, or every deletion context. +- **Redistribution:** Only the controlled values, changed property names, and + equality results are retained. + +### `MZ-1.10.0-PLAYER-START-TOLERANCE-MATRIX-2026-08-09` + +- **Kind:** Controlled malformed/tolerance matrix. +- **Version/environment:** The same editor and platform; five separately copied + disposable projects with a `17 x 13` selected map. +- **Procedure:** With the editor closed, prepared one triplet per copy: mixed + zero `(0, 8, 6)`, exact upper in-bounds `(1, 16, 12)`, dangling positive map + `(999, 8, 6)`, negative coordinates `(1, -1, -1)`, and exact upper + out-of-bounds `(1, 17, 13)`. Opened and saved each project in MZ, then + compared only the selected scalars, decoded changed-property names, and root + key equality with its baseline. +- **Observed:** Every save retained the prepared triplet exactly. The changed + properties were limited to the prepared scalar or scalars plus unrelated + `versionId`; the decoded root property set remained fixed. In particular, + MZ saved signed negative `startX` and `startY` values. +- **Limits:** Persistence tolerance is not evidence of editor validity, intended + UI meaning, runtime success, passability, clamping rules, or numeric bounds + beyond these exact values. No playtest was performed. +- **Redistribution:** Only the controlled triplets, map dimensions, changed + property names, and equality results are retained. + ## Bounded typed contract The experimental slice accepts an existing `ProjectSnapshot` and reads only @@ -91,6 +131,14 @@ values because the summary reports stored values without contextual validation. The separate player-start validation recognizes only the directly observed zero triplet and does not change this projection contract. +This implemented unsigned-coordinate contract now has a known evidence gap: +it rejects the directly observed saved `-1, -1` coordinate state before +contextual validation can run. Proposed +[ADR 0014](../../decisions/0014-signed-player-start-coordinates.md) defines a +signed-coordinate correction. Until that proposal is accepted and implemented, +negative stored coordinates remain outside Tilewright's system-summary +capability even though MZ 1.10.0 was observed to preserve one such state. + Unknown properties and all exact source bytes remain in the untouched raw snapshot. The operation does not parse party members or other system settings, interpret `versionId`, require a map catalog, validate map references or @@ -116,11 +164,9 @@ that MZ accepts or rejects malformed projects. ## Remaining unknowns and next experiments -- Use the editor's Delete gesture on the player-start icon and compare the - generated values with the zero triplet already observed to be recognized and - preserved as `None`. -- Complete the mixed-zero experiment before interpreting a zero map ID with - nonzero coordinates. +- Establish the editor presentation and runtime consequences of mixed-zero, + dangling, negative, and upper-out-of-bounds states separately before assigning + validity semantics. - Change locale and currency independently before describing their accepted grammars or cross-file effects. - Determine whether `editMapId` zero or a dangling ID is an editor-produced or diff --git a/docs/formats/rpg-maker-mz/tileset-catalog.md b/docs/formats/rpg-maker-mz/tileset-catalog.md index c832880..6595de0 100644 --- a/docs/formats/rpg-maker-mz/tileset-catalog.md +++ b/docs/formats/rpg-maker-mz/tileset-catalog.md @@ -11,10 +11,11 @@ What is the smallest tileset projection that lets callers resolve the positive flags, image slots, modes, or notes? Direct observations cover 24 tileset records in four user-owned projects -created by RPG Maker MZ 1.10.0 and 196 map references. Official MZ help -separately documents tilesets, their editor-facing names, modes, images, tile -settings, and assignment to maps. Later versions, record lifecycle, malformed -input, and editor persistence remain unknown. +created by RPG Maker MZ 1.10.0, 196 map references, and one controlled rename in +a disposable copy. Official MZ help separately documents tilesets, their +editor-facing names, modes, images, tile settings, and assignment to maps. +Later versions, record lifecycle, malformed input, and persistence for fields +other than the controlled name remain unknown. ## Evidence ledger @@ -25,6 +26,7 @@ input, and editor persistence remain unknown. | Every observed record has exactly `flags`, `id`, `mode`, `name`, `note`, and `tilesetNames`; IDs are positive integers equal to array indexes and names are nonempty strings. | Shape audit | Observed | High across 24 records | Plugins or later versions may add fields; decoded duplicate keys were not established absent. | | Every audited map's positive `tilesetId` resolves to an ID/index-consistent record in its project's tileset array. | Shape audit and 196-map cross-file comparison | Observed; reference meaning Documented and Inferred | High in the audited scope | Missing-reference editor behavior and tileset changes remain unknown. | | Observed `mode` values are integers 0 or 1, `tilesetNames` has nine strings, and `flags` has 8,192 integers. | Shape audit | Observed syntax only | High in the audited scope | Numeric mode mapping, slot meaning, flag encoding, allowed lengths, and mutation rules remain unestablished. | +| Renaming one tileset in MZ 1.10.0 changed only that record's `name` within `Tilesets.json`; ID, mode, note, images, flags, and array structure remained fixed. | `MZ-1.10.0-TILESET-NAME-2026-08-09` | Observed controlled persistence | High for one rename and version | Allowed strings, normalization, duplicate names, record lifecycle, mutation APIs, and later versions remain unknown. | | Tilewright's tileset catalog matches an independent direct extraction of every bounded record and CLI-envelope field. | `MZ-1.10.0-TILESET-DIFFERENTIAL-2026-08-09` | Observed | High across all four projects and 24 records | This does not test editor mutation, malformed input, adjacent fields, or later versions. | ## Aggregate shape audit @@ -70,6 +72,27 @@ validation, mutation, persistence, or later-version behavior. No project path, tileset name, note, asset name, flag, raw document, excerpt, field value, report, hash, or per-project manifest was retained. +## Controlled name observation + +### `MZ-1.10.0-TILESET-NAME-2026-08-09` + +- **Kind:** Controlled editor rename. +- **Version/environment:** RPG Maker MZ 1.10.0 on arm64 macOS 26.6 build + 25G72; unique disposable copy of the authorized Basic project. +- **Procedure:** Renamed exactly one existing tileset through Database → + Tilesets, saved, closed, and compared only changed decoded property names, + record identity, structural equality, and string lengths with the immutable + baseline. +- **Observed:** Only record 1's decoded `name` changed within `Tilesets.json`. + Its ID, mode, note, image-name array, flag array, surrounding records, and + array length remained equal. The same editor save changed only unrelated + `versionId` in `System.json`. +- **Limits:** This establishes one name-field persistence action, not allowed + contents, normalization, uniqueness, mutation safety, record lifecycle, or + behavior in later versions. +- **Redistribution:** No name, asset string, note, flag, raw excerpt, path, + digest, screenshot, or project-specific value is retained. + ## Official documentation The official *Tileset Settings* help page describes tilesets as the tile-image @@ -116,8 +139,6 @@ that MZ accepts or rejects malformed states. ## Remaining unknowns and next experiments -- Change only one tileset name and confirm the exact persisted field after save - and reopen. - Toggle one tileset mode and establish the numeric mapping without inferring it from stock names. - Change one map's selected tileset and confirm the cross-file identifier diff --git a/docs/open-questions.md b/docs/open-questions.md index 9dd45f3..b89c8ea 100644 --- a/docs/open-questions.md +++ b/docs/open-questions.md @@ -61,6 +61,11 @@ unknown and plugin-defined content. The following details remain open: `MapEventId` scoped to one selected map, while ADR 0012 introduces a `TilesetId` scoped to one catalog. ADR 0009 deliberately retains system map fields as unvalidated `u32` scalars. +- What numeric representation should stored editor coordinates use as broader + versions and data areas are observed? Proposed + [ADR 0014](decisions/0014-signed-player-start-coordinates.md) selects `i64` + for the experimental player-start correction without claiming an editor + limit or settling a general coordinate type. - How should event-command parameter arrays be typed incrementally? - How should validation findings, severities, source locations, and related diagnostics be represented?