rpgmaker-mz-mcp 1.0.0

package/dist/validation/eventCommands.js

@@ -0,0 +1,273 @@
+const expectLength = (n) => (params) => params.length === n ? null : `expected ${n} parameter(s), got ${params.length}`;
+const expectAtLeast = (n) => (params) => params.length >= n ? null : `expected at least ${n} parameter(s), got ${params.length}`;
+/**
+ * Curated table of core RPG Maker MZ event command codes. Not exhaustive — it
+ * covers the commands this server is most likely to read or write, plus enough
+ * of the common set that an unrecognized code is a meaningful signal. Codes not
+ * listed here produce a soft "unrecognized" warning rather than an error, since
+ * plugins are free to introduce their own.
+ */
+export const KNOWN_COMMANDS = {
+    0: { name: 'End of list' },
+    // Messages
+    101: {
+        name: 'Show Text (setup)',
+        check: (p) => p.length === 4 || p.length === 5
+            ? null
+            : `Show Text expects 4 or 5 parameters, got ${p.length}`,
+    },
+    102: { name: 'Show Choices', check: expectAtLeast(2) },
+    103: { name: 'Input Number', check: expectLength(2) },
+    104: { name: 'Select Item', check: expectLength(2) },
+    105: { name: 'Show Scrolling Text', check: expectAtLeast(1) },
+    108: { name: 'Comment', check: expectAtLeast(1) },
+    // Flow control
+    111: { name: 'Conditional Branch', check: expectAtLeast(1) },
+    112: { name: 'Loop' },
+    113: { name: 'Break Loop' },
+    115: { name: 'Exit Event Processing' },
+    117: { name: 'Common Event', check: expectLength(1) },
+    118: { name: 'Label', check: expectLength(1) },
+    119: { name: 'Jump to Label', check: expectLength(1) },
+    // Game progression
+    121: { name: 'Control Switches', check: expectLength(3) },
+    122: { name: 'Control Variables', check: expectAtLeast(4) },
+    123: { name: 'Control Self Switch', check: expectLength(2) },
+    124: { name: 'Control Timer', check: expectAtLeast(1) },
+    125: { name: 'Change Gold', check: expectLength(3) },
+    126: { name: 'Change Items', check: expectLength(4) },
+    127: { name: 'Change Weapons', check: expectLength(5) },
+    128: { name: 'Change Armors', check: expectLength(5) },
+    129: { name: 'Change Party Member', check: expectLength(3) },
+    // System settings (name-only; params not inspected)
+    132: { name: 'Change Battle BGM' },
+    133: { name: 'Change Victory ME' },
+    134: { name: 'Change Save Access' },
+    135: { name: 'Change Menu Access' },
+    136: { name: 'Change Encounter Disable' },
+    137: { name: 'Change Formation Access' },
+    138: { name: 'Change Window Color' },
+    139: { name: 'Change Defeat ME' },
+    140: { name: 'Change Vehicle BGM' },
+    // Movement / character
+    201: { name: 'Transfer Player', check: expectLength(6) },
+    202: { name: 'Set Vehicle Location' },
+    203: { name: 'Set Event Location' },
+    204: { name: 'Scroll Map' },
+    205: { name: 'Set Movement Route', check: expectAtLeast(2) },
+    206: { name: 'Get on/off Vehicle' },
+    211: { name: 'Change Transparency' },
+    212: { name: 'Show Animation', check: expectLength(3) },
+    213: { name: 'Show Balloon Icon', check: expectLength(3) },
+    214: { name: 'Erase Event' },
+    216: { name: 'Change Player Followers' },
+    217: { name: 'Gather Followers' },
+    // Screen / audio / timing
+    221: { name: 'Fadeout Screen', check: expectLength(0) },
+    222: { name: 'Fadein Screen', check: expectLength(0) },
+    223: { name: 'Tint Screen', check: expectLength(3) },
+    224: { name: 'Flash Screen', check: expectLength(3) },
+    225: { name: 'Shake Screen', check: expectLength(4) },
+    230: { name: 'Wait', check: expectLength(1) },
+    231: { name: 'Show Picture', check: expectLength(10) },
+    232: { name: 'Move Picture' },
+    233: { name: 'Rotate Picture' },
+    234: { name: 'Tint Picture' },
+    235: { name: 'Erase Picture', check: expectLength(1) },
+    236: { name: 'Set Weather Effect' },
+    241: { name: 'Play BGM', check: expectLength(1) },
+    242: { name: 'Fadeout BGM' },
+    243: { name: 'Save BGM' },
+    244: { name: 'Replay BGM' },
+    245: { name: 'Play BGS', check: expectLength(1) },
+    246: { name: 'Fadeout BGS' },
+    249: { name: 'Play ME', check: expectLength(1) },
+    250: { name: 'Play SE', check: expectLength(1) },
+    251: { name: 'Stop SE' },
+    261: { name: 'Play Movie' },
+    // Map / scene settings
+    281: { name: 'Change Map Name Display' },
+    282: { name: 'Change Tileset' },
+    283: { name: 'Change Battle Background' },
+    284: { name: 'Change Parallax' },
+    285: { name: 'Get Location Info' },
+    // Actor / party
+    301: { name: 'Battle Processing', check: expectLength(4) },
+    302: { name: 'Shop Processing', check: expectLength(5) },
+    303: { name: 'Name Input Processing', check: expectLength(2) },
+    311: { name: 'Change HP', check: expectLength(6) },
+    312: { name: 'Change MP', check: expectLength(5) },
+    313: { name: 'Change State', check: expectLength(4) },
+    314: { name: 'Recover All', check: expectLength(2) },
+    315: { name: 'Change EXP', check: expectLength(6) },
+    316: { name: 'Change Level', check: expectLength(6) },
+    // Actor attributes (name-only; params not inspected)
+    317: { name: 'Change Parameter' },
+    318: { name: 'Change Skill' },
+    319: { name: 'Change Equipment' },
+    320: { name: 'Change Name' },
+    321: { name: 'Change Class' },
+    322: { name: 'Change Actor Images' },
+    323: { name: 'Change Vehicle Image' },
+    324: { name: 'Change Nickname' },
+    325: { name: 'Change Profile' },
+    // Enemy (in-battle; name-only)
+    331: { name: 'Change Enemy HP' },
+    332: { name: 'Change Enemy MP' },
+    333: { name: 'Change Enemy TP' },
+    334: { name: 'Change Enemy State' },
+    335: { name: 'Enemy Recover All' },
+    336: { name: 'Enemy Appear' },
+    337: { name: 'Enemy Transform' },
+    338: { name: 'Show Battle Animation' },
+    339: { name: 'Force Action' },
+    340: { name: 'Abort Battle' },
+    // Scene control (all parameterless)
+    351: { name: 'Open Menu Screen', check: expectLength(0) },
+    352: { name: 'Open Save Screen', check: expectLength(0) },
+    353: { name: 'Game Over', check: expectLength(0) },
+    354: { name: 'Return to Title Screen', check: expectLength(0) },
+    // Advanced
+    355: { name: 'Script', check: expectAtLeast(1) },
+    356: { name: 'Plugin Command (MV)', check: expectAtLeast(1) },
+    357: { name: 'Plugin Command (MZ)', check: expectAtLeast(4) },
+    // Continuation codes (data rows for the setup command above them)
+    401: { name: 'Show Text line', check: expectLength(1) },
+    402: { name: 'When [choice]', check: expectLength(2) },
+    403: { name: 'When Cancel' },
+    404: { name: 'End Choices' },
+    405: { name: 'Scrolling Text line', check: expectLength(1) },
+    408: { name: 'Comment line', check: expectAtLeast(1) },
+    505: { name: 'Move Route step', check: expectLength(1) },
+    605: { name: 'Shop goods', check: expectLength(4) },
+    411: { name: 'Else' },
+    412: { name: 'End Conditional Branch' },
+    413: { name: 'Repeat Above' },
+    655: { name: 'Script line', check: expectAtLeast(1) },
+};
+/** Validate a single event command. */
+export function validateCommand(command, path) {
+    const warnings = [];
+    if (typeof command?.code !== 'number') {
+        warnings.push({ path, message: 'command is missing a numeric `code`', severity: 'error' });
+        return warnings;
+    }
+    if (!Array.isArray(command.parameters)) {
+        warnings.push({
+            path,
+            code: command.code,
+            message: '`parameters` is not an array',
+            severity: 'error',
+        });
+        return warnings;
+    }
+    const spec = KNOWN_COMMANDS[command.code];
+    if (!spec) {
+        // Advisory: KNOWN_COMMANDS is curated, not exhaustive, and plugins are free
+        // to introduce their own codes — blocking here would fail valid writes.
+        warnings.push({
+            path,
+            code: command.code,
+            message: `unrecognized command code ${command.code} (may be a plugin command)`,
+            severity: 'warning',
+        });
+        return warnings;
+    }
+    const problem = spec.check?.(command.parameters);
+    if (problem) {
+        warnings.push({
+            path,
+            code: command.code,
+            message: `${spec.name}: ${problem}`,
+            severity: 'error',
+        });
+    }
+    return warnings;
+}
+/** Message-window line budget in characters (default 816px window, 26px font). */
+const TEXT_LINE_LIMIT = 55;
+/** Same budget when a face graphic is shown — the face eats a third of the window. */
+const TEXT_LINE_LIMIT_WITH_FACE = 38;
+/** Display width of a message line: escape codes (\C[3], \N[1], \G, \\, …) cost nothing. */
+function visibleTextLength(line) {
+    return line.replace(/\\[A-Z]+\[[^\]]*\]/gi, '').replace(/\\./g, '').length;
+}
+/**
+ * Warn (never block) on Show Text lines (401) too wide for the message window —
+ * RPG Maker MZ does **not** word-wrap, an over-long line is silently cut off at
+ * the window edge. Face-aware: a 101 setup with a face image shrinks the budget
+ * for the 401 lines that follow it. Exported so the read-only text builders can
+ * surface the same warning at build time (on fragments without a terminator).
+ */
+export function textLineWidthWarnings(list, path) {
+    const warnings = [];
+    let faceShown = false;
+    list.forEach((command, i) => {
+        if (!command || !Array.isArray(command.parameters))
+            return;
+        if (command.code === 101) {
+            faceShown = typeof command.parameters[0] === 'string' && command.parameters[0] !== '';
+        }
+        else if (command.code === 401 && typeof command.parameters[0] === 'string') {
+            const limit = faceShown ? TEXT_LINE_LIMIT_WITH_FACE : TEXT_LINE_LIMIT;
+            const length = visibleTextLength(command.parameters[0]);
+            if (length > limit) {
+                warnings.push({
+                    path: `${path} / command ${i}`,
+                    code: 401,
+                    // Advisory: the line budget is an estimate (fonts and window widths are
+                    // configurable), and an over-long line still runs.
+                    severity: 'warning',
+                    message: `Show Text line is ${length} visible chars but the message window fits ~${limit}${faceShown ? ' with a face shown' : ''} — MZ does not word-wrap, the end will be cut off; split it into shorter 401 lines`,
+                });
+            }
+        }
+    });
+    return warnings;
+}
+/**
+ * Validate an event command list (an event page's `list`). Checks that it is a
+ * proper array terminated by the code-0 end marker, then validates each command.
+ */
+export function validateCommandList(list, path) {
+    const warnings = [];
+    if (!Array.isArray(list)) {
+        warnings.push({ path, message: 'command list is not an array', severity: 'error' });
+        return warnings;
+    }
+    if (list.length === 0 || list[list.length - 1]?.code !== 0) {
+        warnings.push({
+            path,
+            message: 'command list should end with an end-of-list command (code 0)',
+            severity: 'error',
+        });
+    }
+    list.forEach((command, i) => {
+        warnings.push(...validateCommand(command, `${path} / command ${i}`));
+    });
+    warnings.push(...textLineWidthWarnings(list, path));
+    return warnings;
+}
+/** Validate every page of an event. */
+export function validateEvent(event, path = `event ${event?.id}`) {
+    const warnings = [];
+    if (!event || !Array.isArray(event.pages)) {
+        warnings.push({ path, message: 'event has no `pages` array', severity: 'error' });
+        return { ok: warnings.length === 0, warnings };
+    }
+    event.pages.forEach((page, i) => {
+        warnings.push(...validateCommandList(page?.list, `${path} / page ${i}`));
+    });
+    return { ok: warnings.length === 0, warnings };
+}
+/** Validate every (non-null) event in a map's `events` array. */
+export function validateEvents(events) {
+    const warnings = [];
+    events.forEach((event) => {
+        if (event) {
+            warnings.push(...validateEvent(event).warnings);
+        }
+    });
+    return { ok: warnings.length === 0, warnings };
+}
+//# sourceMappingURL=eventCommands.js.map

package/dist/validation/eventCommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventCommands.js","sourceRoot":"","sources":["../../src/validation/eventCommands.ts"],"names":[],"mappings":"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"}

package/dist/validation/gate.d.ts

@@ -0,0 +1,56 @@
+import { ValidationWarning } from './eventCommands.js';
+/**
+ * Throw-by-default write gating.
+ *
+ * Validation used to be warn-by-default everywhere: a tool wrote the file, then
+ * validated what it had written and returned the findings. A malformed event
+ * therefore **landed on disk**, and the warning was easy for an LLM client to
+ * skim past — the caller had to notice the problem and undo it. Now a
+ * structural finding (`severity: 'error'` — see {@link ValidationWarning})
+ * aborts the write *before* it happens, and the caller must opt back in with
+ * `force: true`.
+ *
+ * The two tiers matter: only findings that are almost always bugs block. A
+ * finding that is legitimately possible (an unrecognized command code may be a
+ * plugin command, an over-long text line still runs) stays advisory and is
+ * reported exactly as before, so this can't manufacture false failures.
+ */
+/**
+ * A hook run with the fully-built value immediately **before** it is committed.
+ * Throwing aborts the write — nothing reaches disk, and in dry-run nothing is
+ * reported as `wouldChange`, so a preview of a bad write fails the same way the
+ * real write would.
+ */
+export type PreCommit<T> = (value: T) => void | Promise<void>;
+/** The findings that refuse a write: structural problems, not advice. */
+export declare function blockingWarnings(warnings: ValidationWarning[]): ValidationWarning[];
+/**
+ * Refuse a write whose result is structurally malformed, unless the caller has
+ * explicitly forced it. The message lists every blocking finding (an LLM caller
+ * usually wants to fix them all in one go) and names the escape hatch.
+ */
+export declare function assertWritable(warnings: ValidationWarning[], force: boolean | undefined, subject: string): void;
+/**
+ * Build a {@link PreCommit} hook that validates the would-be result, refuses the
+ * write when anything blocks, and keeps the findings for the tool's response.
+ *
+ * The returned `warnings` array is filled in when the hook runs (i.e. once the
+ * mutating function has built its result), so a handler reads it *after* the
+ * call:
+ *
+ * ```ts
+ * const gate = writeGate<MapEvent>(args.force, `event on map ${mapId}`, (event) =>
+ *   validateEvent(event).warnings,
+ * );
+ * const event = await createMapEvent(projectPath, mapId, data, gate.precommit);
+ * return gate.respond({ event });
+ * ```
+ */
+export declare function writeGate<T>(force: boolean | undefined, subject: string, compute: (value: T) => ValidationWarning[] | Promise<ValidationWarning[]>): {
+    precommit: PreCommit<T>;
+    warnings: ValidationWarning[];
+    respond: <R extends object>(result: R) => R & {
+        warnings?: ValidationWarning[];
+    };
+};
+//# sourceMappingURL=gate.d.ts.map

package/dist/validation/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/validation/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAEnF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,KAAK,EAAE,OAAO,GAAG,SAAS,EAC1B,OAAO,EAAE,MAAM,GACd,IAAI,CAYN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,KAAK,EAAE,OAAO,GAAG,SAAS,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,iBAAiB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,GACxE;IACD,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACxB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC;CAClF,CAaA"}

package/dist/validation/gate.js

@@ -0,0 +1,50 @@
+/** The findings that refuse a write: structural problems, not advice. */
+export function blockingWarnings(warnings) {
+    return warnings.filter((warning) => warning.severity === 'error');
+}
+/**
+ * Refuse a write whose result is structurally malformed, unless the caller has
+ * explicitly forced it. The message lists every blocking finding (an LLM caller
+ * usually wants to fix them all in one go) and names the escape hatch.
+ */
+export function assertWritable(warnings, force, subject) {
+    if (force)
+        return;
+    const blocking = blockingWarnings(warnings);
+    if (blocking.length === 0)
+        return;
+    const detail = blocking.map((w) => `  - ${w.path}: ${w.message}`).join('\n');
+    throw new Error(`Refusing to write ${subject}: the result would be structurally invalid, so nothing was written.\n` +
+        `${detail}\n` +
+        `Fix the problem(s) above, or pass force: true to write anyway.`);
+}
+/**
+ * Build a {@link PreCommit} hook that validates the would-be result, refuses the
+ * write when anything blocks, and keeps the findings for the tool's response.
+ *
+ * The returned `warnings` array is filled in when the hook runs (i.e. once the
+ * mutating function has built its result), so a handler reads it *after* the
+ * call:
+ *
+ * ```ts
+ * const gate = writeGate<MapEvent>(args.force, `event on map ${mapId}`, (event) =>
+ *   validateEvent(event).warnings,
+ * );
+ * const event = await createMapEvent(projectPath, mapId, data, gate.precommit);
+ * return gate.respond({ event });
+ * ```
+ */
+export function writeGate(force, subject, compute) {
+    const warnings = [];
+    return {
+        warnings,
+        precommit: async (value) => {
+            warnings.push(...(await compute(value)));
+            assertWritable(warnings, force, subject);
+        },
+        // Advisory findings still ride along on a successful write; a clean write
+        // keeps the tidy no-`warnings` response shape it has always had.
+        respond: (result) => (warnings.length > 0 ? { ...result, warnings } : result),
+    };
+}
+//# sourceMappingURL=gate.js.map

package/dist/validation/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/validation/gate.ts"],"names":[],"mappings":"AA2BA,yEAAyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,QAA6B;IAC5D,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,QAA6B,EAC7B,KAA0B,EAC1B,OAAe;IAEf,IAAI,KAAK;QAAE,OAAO;IAElB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAElC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,IAAI,KAAK,CACb,qBAAqB,OAAO,uEAAuE;QACjG,GAAG,MAAM,IAAI;QACb,gEAAgE,CACnE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CACvB,KAA0B,EAC1B,OAAe,EACf,OAAyE;IAMzE,MAAM,QAAQ,GAAwB,EAAE,CAAC;IAEzC,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,KAAK,EAAE,KAAQ,EAAE,EAAE;YAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzC,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,0EAA0E;QAC1E,iEAAiE;QACjE,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;KAC9E,CAAC;AACJ,CAAC"}

package/dist/validation/moveCommands.d.ts

@@ -0,0 +1,31 @@
+import { MoveCommand } from '../utils/types.js';
+import { ValidationWarning } from './eventCommands.js';
+/**
+ * Specification for a known RPG Maker MZ move-route command. `params` is the
+ * exact number of parameters the command expects (default 0 for the many
+ * parameterless move commands). Mirrors the CommandSpec shape in
+ * `eventCommands.ts`, but move commands are a separate, smaller code table.
+ */
+interface MoveCommandSpec {
+    name: string;
+    params?: number;
+}
+/**
+ * The RPG Maker MZ move-route command table (Game_Character `ROUTE_*` constants).
+ * A move route's `list` uses these codes — a different, self-contained table from
+ * the event-command codes in `eventCommands.ts`. Codes not listed here produce a
+ * soft "unrecognized" warning (warn-by-default), since plugins can add their own.
+ */
+export declare const KNOWN_MOVE_COMMANDS: Record<number, MoveCommandSpec>;
+/** Validate a single move-route command. */
+export declare function validateMoveCommand(command: MoveCommand, path: string): ValidationWarning[];
+/**
+ * Validate a move route (the object command 205 carries, or an event page's
+ * autonomous `moveRoute`). Checks that `list` is an array terminated by the
+ * Route-End marker (code 0), then validates each move command. Never throws —
+ * findings are returned and classified by `severity`; it's the mutating tools
+ * that decide to refuse a write (see `validation/gate.ts`).
+ */
+export declare function validateMoveRoute(route: unknown, path?: string): ValidationWarning[];
+export {};
+//# sourceMappingURL=moveCommands.d.ts.map

package/dist/validation/moveCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moveCommands.d.ts","sourceRoot":"","sources":["../../src/validation/moveCommands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAa,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAmD/D,CAAC;AAEF,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAyC3F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAe,GAAG,iBAAiB,EAAE,CAsB1F"}

package/dist/validation/moveCommands.js

@@ -0,0 +1,123 @@
+/**
+ * The RPG Maker MZ move-route command table (Game_Character `ROUTE_*` constants).
+ * A move route's `list` uses these codes — a different, self-contained table from
+ * the event-command codes in `eventCommands.ts`. Codes not listed here produce a
+ * soft "unrecognized" warning (warn-by-default), since plugins can add their own.
+ */
+export const KNOWN_MOVE_COMMANDS = {
+    0: { name: 'Route End' },
+    // Directional movement
+    1: { name: 'Move Down' },
+    2: { name: 'Move Left' },
+    3: { name: 'Move Right' },
+    4: { name: 'Move Up' },
+    5: { name: 'Move Lower Left' },
+    6: { name: 'Move Lower Right' },
+    7: { name: 'Move Upper Left' },
+    8: { name: 'Move Upper Right' },
+    9: { name: 'Move at Random' },
+    10: { name: 'Move toward Player' },
+    11: { name: 'Move away from Player' },
+    12: { name: '1 Step Forward' },
+    13: { name: '1 Step Backward' },
+    14: { name: 'Jump', params: 2 },
+    15: { name: 'Wait', params: 1 },
+    // Turning
+    16: { name: 'Turn Down' },
+    17: { name: 'Turn Left' },
+    18: { name: 'Turn Right' },
+    19: { name: 'Turn Up' },
+    20: { name: 'Turn 90° Right' },
+    21: { name: 'Turn 90° Left' },
+    22: { name: 'Turn 180°' },
+    23: { name: 'Turn 90° Right or Left' },
+    24: { name: 'Turn at Random' },
+    25: { name: 'Turn toward Player' },
+    26: { name: 'Turn away from Player' },
+    // Switches / movement attributes
+    27: { name: 'Switch ON', params: 1 },
+    28: { name: 'Switch OFF', params: 1 },
+    29: { name: 'Change Speed', params: 1 },
+    30: { name: 'Change Frequency', params: 1 },
+    31: { name: 'Walking Animation ON' },
+    32: { name: 'Walking Animation OFF' },
+    33: { name: 'Stepping Animation ON' },
+    34: { name: 'Stepping Animation OFF' },
+    35: { name: 'Direction Fix ON' },
+    36: { name: 'Direction Fix OFF' },
+    37: { name: 'Through ON' },
+    38: { name: 'Through OFF' },
+    39: { name: 'Transparent ON' },
+    40: { name: 'Transparent OFF' },
+    // Appearance / audio / script
+    41: { name: 'Change Image', params: 2 },
+    42: { name: 'Change Opacity', params: 1 },
+    43: { name: 'Change Blend Mode', params: 1 },
+    44: { name: 'Play SE', params: 1 },
+    45: { name: 'Script', params: 1 },
+};
+/** Validate a single move-route command. */
+export function validateMoveCommand(command, path) {
+    const warnings = [];
+    if (typeof command?.code !== 'number') {
+        warnings.push({ path, message: 'move command is missing a numeric `code`', severity: 'error' });
+        return warnings;
+    }
+    if (!Array.isArray(command.parameters)) {
+        warnings.push({
+            path,
+            code: command.code,
+            message: '`parameters` is not an array',
+            severity: 'error',
+        });
+        return warnings;
+    }
+    const spec = KNOWN_MOVE_COMMANDS[command.code];
+    if (!spec) {
+        // Advisory, for the same reason as an unrecognized event command code.
+        warnings.push({
+            path,
+            code: command.code,
+            message: `unrecognized move command code ${command.code} (may be a plugin move command)`,
+            severity: 'warning',
+        });
+        return warnings;
+    }
+    const expected = spec.params ?? 0;
+    if (command.parameters.length !== expected) {
+        warnings.push({
+            path,
+            code: command.code,
+            message: `${spec.name}: expected ${expected} parameter(s), got ${command.parameters.length}`,
+            severity: 'error',
+        });
+    }
+    return warnings;
+}
+/**
+ * Validate a move route (the object command 205 carries, or an event page's
+ * autonomous `moveRoute`). Checks that `list` is an array terminated by the
+ * Route-End marker (code 0), then validates each move command. Never throws —
+ * findings are returned and classified by `severity`; it's the mutating tools
+ * that decide to refuse a write (see `validation/gate.ts`).
+ */
+export function validateMoveRoute(route, path = 'move route') {
+    const warnings = [];
+    if (!route || typeof route !== 'object' || !Array.isArray(route.list)) {
+        warnings.push({ path, message: 'move route has no `list` array', severity: 'error' });
+        return warnings;
+    }
+    const list = route.list;
+    if (list.length === 0 || list[list.length - 1]?.code !== 0) {
+        warnings.push({
+            path,
+            message: 'move route should end with a Route-End command (code 0)',
+            severity: 'error',
+        });
+    }
+    list.forEach((command, i) => {
+        warnings.push(...validateMoveCommand(command, `${path} / command ${i}`));
+    });
+    return warnings;
+}
+//# sourceMappingURL=moveCommands.js.map

package/dist/validation/moveCommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moveCommands.js","sourceRoot":"","sources":["../../src/validation/moveCommands.ts"],"names":[],"mappings":"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"}