rpgmaker-mz-mcp 1.0.0

package/dist/tools/classTools.d.ts

@@ -0,0 +1,85 @@
+import { GameClass, Learning, Skill } from '../utils/types.js';
+import { ToolDefinition } from '../registry.js';
+import { ValidationWarning } from '../validation/eventCommands.js';
+/** Human-readable labels for the 8 base parameters, indexed 0-7. */
+export declare const PARAM_NAMES: readonly ["maxHP", "maxMP", "atk", "def", "mat", "mdf", "agi", "luk"];
+/**
+ * Build the 8×(maxLevel+1) parameter matrix for a new class: one linear curve per
+ * param. Index 0 mirrors the level-1 value (the engine never reads level 0).
+ */
+export declare function defaultClassParams(maxLevel?: number): number[][];
+/**
+ * A blank class mirroring what the RPG Maker MZ editor writes for a freshly-created
+ * class: the default EXP curve, no traits or learnings, and a default linear param
+ * curve. Pure so the template shape can be unit-tested. Field order mirrors the
+ * editor's on-disk shape.
+ */
+export declare function defaultClass(maxLevel?: number): Omit<GameClass, 'id'>;
+/** Get all classes from the project (`data/Classes.json`). */
+export declare function getClasses(projectPath: string): Promise<(GameClass | null)[]>;
+/** The caller-supplied class shape accepted by both `create_class` and `batch_create`. */
+export type ClassInput = {
+    name: string;
+    maxLevel?: number;
+} & Partial<Omit<GameClass, 'id' | 'name'>>;
+/**
+ * Build one new class record against the current array — the shared per-record
+ * source of truth for both `create_class` and `batch_create`. Pure: `maxLevel`
+ * sizes the generated param curves via {@link defaultClass}, then the caller's
+ * defined fields merge over it with the computed id last so it always wins.
+ */
+export declare function buildClassRecord(existing: (GameClass | null)[], input: ClassInput): GameClass;
+/**
+ * Create a new class. Only `name` is required; any omitted field falls back to the
+ * editor's new-class default (see {@link defaultClass}). Allocates the next unused
+ * id (max existing + 1) and writes through the commit choke point.
+ */
+export declare function createClass(projectPath: string, options: ClassInput): Promise<GameClass>;
+/** Update an existing class's properties (shallow merge; id re-pinned). */
+export declare function updateClass(projectPath: string, classId: number, updates: Partial<GameClass>): Promise<GameClass>;
+/**
+ * Add a "learn skill at level" entry to a class — the first-class replacement for
+ * the hack of attaching skills directly to an actor via an Add-Skill trait. The
+ * `skillId` is validated to reference an existing skill (throws otherwise) and the
+ * resulting `learnings` list is kept sorted by level.
+ */
+export declare function addClassLearning(projectPath: string, classId: number, skillId: number, level: number, note?: string): Promise<GameClass>;
+/**
+ * Replace one of a class's 8 parameter growth curves. `paramId` is 0-7
+ * ([maxHP, maxMP, atk, def, mat, mdf, agi, luk]) and `values` must match the
+ * existing curve's length (so the matrix stays rectangular / same max level).
+ */
+export declare function setClassParamCurve(projectPath: string, classId: number, paramId: number, values: number[]): Promise<GameClass>;
+/**
+ * A compact response view of a class for mutation tools. The on-disk record keeps
+ * its full 8×(maxLevel+1) `params` matrix, but echoing 800+ numbers back on every
+ * edit (e.g. adding one skill learning) is pure token waste — so the tool response
+ * replaces `params` with `maxLevel` plus a per-param first/last-level preview. A
+ * caller that needs the whole curve can still `get_database('classes')`.
+ */
+export declare function summarizeClass(c: GameClass): {
+    maxLevel: number;
+    paramCurves: {
+        param: "def" | "maxHP" | "maxMP" | "atk" | "mat" | "mdf" | "agi" | "luk";
+        atLevel1: number;
+        atMaxLevel: number;
+    }[];
+    id: number;
+    name: string;
+    expParams: number[];
+    learnings: Learning[];
+    traits: import("../utils/types.js").Trait[];
+    note: string;
+};
+/**
+ * Warn (never throw) when a class learns skills whose skill type is not covered by
+ * an Add Skill Type trait ({ code: 41, dataId: stypeId }). Learnings only *teach*
+ * the skill — without the trait the skill-type command never appears in battle or
+ * the menu, so the actor silently "has no skills" even though the learnings are
+ * correct. One aggregated warning per uncovered stypeId. Skills with stypeId 0
+ * (no type) and learnings pointing at unknown skills are skipped (the latter is
+ * add_class_learning's throw, not this check's job). Pure so it's unit-testable.
+ */
+export declare function skillTypeTraitWarnings(gameClass: GameClass, skills: (Skill | null)[]): ValidationWarning[];
+export declare const classToolDefinitions: ToolDefinition[];
+//# sourceMappingURL=classTools.d.ts.map

package/dist/tools/classTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classTools.d.ts","sourceRoot":"","sources":["../../src/tools/classTools.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,oEAAoE;AACpE,eAAO,MAAM,WAAW,uEAAwE,CAAC;AAoBjG;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,EAAE,EAAE,CAQnF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,GAAE,MAA0B,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CASxF;AAED,8DAA8D;AAC9D,wBAAsB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,EAAE,CAAC,CAEnF;AAeD,0FAA0F;AAC1F,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CACpE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC,CAC/B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,CAAC,SAAS,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,GAAG,SAAS,CAQ7F;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAM9F;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,GAC1B,OAAO,CAAC,SAAS,CAAC,CAKpB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,IAAI,SAAK,GACR,OAAO,CAAC,SAAS,CAAC,CAcpB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,SAAS,CAAC,CAmBpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS;;;;;;;;;;;;;EAS1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,GACvB,iBAAiB,EAAE,CAmBrB;AAmBD,eAAO,MAAM,oBAAoB,EAAE,cAAc,EAmGhD,CAAC"}

package/dist/tools/classTools.js

@@ -0,0 +1,279 @@
+import { z } from 'zod';
+import { readJsonFile, getDataPath } from '../utils/fileHandler.js';
+import { commitChange } from '../utils/commit.js';
+import { definedOnly } from '../utils/records.js';
+/** Human-readable labels for the 8 base parameters, indexed 0-7. */
+export const PARAM_NAMES = ['maxHP', 'maxMP', 'atk', 'def', 'mat', 'mdf', 'agi', 'luk'];
+/**
+ * Per-param [level-1 base, growth-per-level] for the default new-class curve.
+ * RPG Maker MZ's sample curves are effectively linear, so a fresh class gets a
+ * clean linear growth the user can then reshape with `set_class_param_curve`.
+ */
+const DEFAULT_PARAM_CURVE = [
+    [500, 50], // maxHP
+    [50, 8], // maxMP
+    [15, 2], // atk
+    [15, 2], // def
+    [15, 2], // mat
+    [15, 2], // mdf
+    [15, 2], // agi
+    [15, 2], // luk
+];
+const DEFAULT_MAX_LEVEL = 99;
+/**
+ * Build the 8×(maxLevel+1) parameter matrix for a new class: one linear curve per
+ * param. Index 0 mirrors the level-1 value (the engine never reads level 0).
+ */
+export function defaultClassParams(maxLevel = DEFAULT_MAX_LEVEL) {
+    return DEFAULT_PARAM_CURVE.map(([base, growth]) => {
+        const row = [];
+        for (let level = 0; level <= maxLevel; level++) {
+            row.push(base + growth * Math.max(level - 1, 0));
+        }
+        return row;
+    });
+}
+/**
+ * A blank class mirroring what the RPG Maker MZ editor writes for a freshly-created
+ * class: the default EXP curve, no traits or learnings, and a default linear param
+ * curve. Pure so the template shape can be unit-tested. Field order mirrors the
+ * editor's on-disk shape.
+ */
+export function defaultClass(maxLevel = DEFAULT_MAX_LEVEL) {
+    return {
+        name: '',
+        expParams: [30, 20, 30, 30],
+        traits: [],
+        learnings: [],
+        note: '',
+        params: defaultClassParams(maxLevel),
+    };
+}
+/** Get all classes from the project (`data/Classes.json`). */
+export async function getClasses(projectPath) {
+    return await readJsonFile(getDataPath(projectPath, 'Classes.json'));
+}
+/** Load a class by id or throw a "not found" error. Returns [classes, index]. */
+async function findClassIndex(projectPath, classId) {
+    const classes = await getClasses(projectPath);
+    const index = classes.findIndex((c) => c && c.id === classId);
+    if (index === -1) {
+        throw new Error(`Class with ID ${classId} not found`);
+    }
+    return [classes, index];
+}
+/**
+ * Build one new class record against the current array — the shared per-record
+ * source of truth for both `create_class` and `batch_create`. Pure: `maxLevel`
+ * sizes the generated param curves via {@link defaultClass}, then the caller's
+ * defined fields merge over it with the computed id last so it always wins.
+ */
+export function buildClassRecord(existing, input) {
+    const { maxLevel, ...overrides } = input;
+    const maxId = existing.reduce((max, c) => (c && c.id > max ? c.id : max), 0);
+    return {
+        ...defaultClass(maxLevel),
+        ...definedOnly(overrides),
+        id: maxId + 1,
+    };
+}
+/**
+ * Create a new class. Only `name` is required; any omitted field falls back to the
+ * editor's new-class default (see {@link defaultClass}). Allocates the next unused
+ * id (max existing + 1) and writes through the commit choke point.
+ */
+export async function createClass(projectPath, options) {
+    const classes = await getClasses(projectPath);
+    const gameClass = buildClassRecord(classes, options);
+    classes.push(gameClass);
+    await commitChange(getDataPath(projectPath, 'Classes.json'), classes);
+    return gameClass;
+}
+/** Update an existing class's properties (shallow merge; id re-pinned). */
+export async function updateClass(projectPath, classId, updates) {
+    const [classes, index] = await findClassIndex(projectPath, classId);
+    classes[index] = { ...classes[index], ...updates, id: classId };
+    await commitChange(getDataPath(projectPath, 'Classes.json'), classes);
+    return classes[index];
+}
+/**
+ * Add a "learn skill at level" entry to a class — the first-class replacement for
+ * the hack of attaching skills directly to an actor via an Add-Skill trait. The
+ * `skillId` is validated to reference an existing skill (throws otherwise) and the
+ * resulting `learnings` list is kept sorted by level.
+ */
+export async function addClassLearning(projectPath, classId, skillId, level, note = '') {
+    const skills = await readJsonFile(getDataPath(projectPath, 'Skills.json'));
+    if (!skills.some((s) => s && s.id === skillId)) {
+        throw new Error(`Learning references skillId ${skillId}, which does not exist`);
+    }
+    const [classes, index] = await findClassIndex(projectPath, classId);
+    const gameClass = classes[index];
+    const learning = { level, note, skillId };
+    const learnings = [...(gameClass.learnings ?? []), learning].sort((a, b) => a.level - b.level);
+    classes[index] = { ...gameClass, learnings };
+    await commitChange(getDataPath(projectPath, 'Classes.json'), classes);
+    return classes[index];
+}
+/**
+ * Replace one of a class's 8 parameter growth curves. `paramId` is 0-7
+ * ([maxHP, maxMP, atk, def, mat, mdf, agi, luk]) and `values` must match the
+ * existing curve's length (so the matrix stays rectangular / same max level).
+ */
+export async function setClassParamCurve(projectPath, classId, paramId, values) {
+    if (paramId < 0 || paramId > 7) {
+        throw new Error(`paramId must be 0-7 (got ${paramId})`);
+    }
+    const [classes, index] = await findClassIndex(projectPath, classId);
+    const gameClass = classes[index];
+    const expectedLength = gameClass.params[paramId]?.length ?? values.length;
+    if (values.length !== expectedLength) {
+        throw new Error(`Param curve for ${PARAM_NAMES[paramId]} must have ${expectedLength} entries (got ${values.length})`);
+    }
+    const params = gameClass.params.map((row, i) => (i === paramId ? values : row));
+    classes[index] = { ...gameClass, params };
+    await commitChange(getDataPath(projectPath, 'Classes.json'), classes);
+    return classes[index];
+}
+/**
+ * A compact response view of a class for mutation tools. The on-disk record keeps
+ * its full 8×(maxLevel+1) `params` matrix, but echoing 800+ numbers back on every
+ * edit (e.g. adding one skill learning) is pure token waste — so the tool response
+ * replaces `params` with `maxLevel` plus a per-param first/last-level preview. A
+ * caller that needs the whole curve can still `get_database('classes')`.
+ */
+export function summarizeClass(c) {
+    const { params, ...rest } = c;
+    const maxLevel = (params?.[0]?.length ?? 1) - 1;
+    const paramCurves = params?.map((row, i) => ({
+        param: PARAM_NAMES[i],
+        atLevel1: row[1],
+        atMaxLevel: row[maxLevel],
+    }));
+    return { ...rest, maxLevel, paramCurves };
+}
+/**
+ * Warn (never throw) when a class learns skills whose skill type is not covered by
+ * an Add Skill Type trait ({ code: 41, dataId: stypeId }). Learnings only *teach*
+ * the skill — without the trait the skill-type command never appears in battle or
+ * the menu, so the actor silently "has no skills" even though the learnings are
+ * correct. One aggregated warning per uncovered stypeId. Skills with stypeId 0
+ * (no type) and learnings pointing at unknown skills are skipped (the latter is
+ * add_class_learning's throw, not this check's job). Pure so it's unit-testable.
+ */
+export function skillTypeTraitWarnings(gameClass, skills) {
+    const covered = new Set((gameClass.traits ?? []).filter((t) => t.code === 41).map((t) => t.dataId));
+    const missing = new Map();
+    for (const learning of gameClass.learnings ?? []) {
+        const skill = skills.find((s) => s && s.id === learning.skillId);
+        if (!skill || !skill.stypeId || covered.has(skill.stypeId))
+            continue;
+        const names = missing.get(skill.stypeId) ?? [];
+        names.push(skill.name || `#${skill.id}`);
+        missing.set(skill.stypeId, names);
+    }
+    return [...missing].map(([stypeId, names]) => ({
+        path: 'learnings',
+        message: `class "${gameClass.name}" learns ${names.join(', ')} (skill type ${stypeId}) but has no ` +
+            `Add Skill Type trait { code: 41, dataId: ${stypeId}, value: 1 } — without it the ` +
+            `skill-type command never appears, so actors can never use these skills`,
+    }));
+}
+/**
+ * Attach warn-by-default skill-type coverage to a class-write response (on the
+ * compact summary the handlers return). Fails soft when Skills.json is missing
+ * (nothing to check against — e.g. a bare fixture).
+ */
+async function withSkillTypeWarnings(projectPath, gameClass) {
+    const summary = summarizeClass(gameClass);
+    let skills;
+    try {
+        skills = await readJsonFile(getDataPath(projectPath, 'Skills.json'));
+    }
+    catch {
+        return summary;
+    }
+    const warnings = skillTypeTraitWarnings(gameClass, skills);
+    return warnings.length > 0 ? { ...summary, warnings } : summary;
+}
+export const classToolDefinitions = [
+    {
+        name: 'create_class',
+        mutates: true,
+        description: "Create a new character class in data/Classes.json. Only `name` is required; omitted fields use the editor's new-class defaults (EXP curve [30,20,30,30], no traits/learnings, a linear param curve to maxLevel). Allocates and returns the next unused class id. NOTE: a class with no Hit Rate trait (xparam id 0: trait { code: 22, dataId: 0, value: 0.95 }) makes its actors always miss physical actions — pass one in `traits` for a combat-ready class. Likewise every learned skill's stypeId needs an Add Skill Type trait ({ code: 41, dataId: stypeId, value: 1 }) or the skill-type command never appears (warned, never blocked).",
+        inputSchema: {
+            name: z.string().describe('Class name shown in the database'),
+            maxLevel: z
+                .number()
+                .int()
+                .optional()
+                .describe('Highest level the param curve covers (default 99); sizes the params matrix'),
+            expParams: z
+                .array(z.number())
+                .length(4)
+                .optional()
+                .describe('EXP curve: [basis, extra, accelerationA, accelerationB]'),
+            params: z
+                .array(z.array(z.number()))
+                .optional()
+                .describe('8 param growth curves, each maxLevel+1 long: [maxHP,maxMP,atk,def,mat,mdf,agi,luk]'),
+            learnings: z
+                .array(z.unknown())
+                .optional()
+                .describe('Learned-skill entries { level, skillId, note }'),
+            traits: z.array(z.unknown()).optional().describe('Trait objects { code, dataId, value }'),
+            note: z.string().optional().describe('Note field'),
+        },
+        handler: async (ctx, args) => {
+            const { dryRun: _dryRun, name, ...rest } = args;
+            return withSkillTypeWarnings(ctx.projectPath, await createClass(ctx.projectPath, { name, ...rest }));
+        },
+    },
+    {
+        name: 'update_class',
+        mutates: true,
+        description: "Update a class's properties (shallow merge into the existing record). Use for name, expParams, traits, or to replace the whole learnings/params arrays; for targeted edits prefer add_class_learning / set_class_param_curve. Warns when a learned skill's stypeId has no Add Skill Type trait ({ code: 41 }).",
+        inputSchema: {
+            classId: z.number().int().positive().describe('The ID of the class to update'),
+            updates: z
+                .record(z.string(), z.unknown())
+                .describe('Object containing class properties to update'),
+        },
+        handler: async (ctx, args) => withSkillTypeWarnings(ctx.projectPath, await updateClass(ctx.projectPath, args.classId, args.updates)),
+    },
+    {
+        name: 'add_class_learning',
+        mutates: true,
+        description: 'Add a "learn skill at level" entry to a class (replaces the hack of attaching skills to an actor via an Add-Skill trait). Validates the skillId exists and keeps the learnings sorted by level. Warns (never blocks) when the skill\'s stypeId is not covered by an Add Skill Type trait ({ code: 41, dataId: stypeId, value: 1 }) on the class — without it the skill-type command never appears and actors cannot use the skill.',
+        inputSchema: {
+            classId: z.number().int().positive().describe('The ID of the class to add the learning to'),
+            skillId: z
+                .number()
+                .int()
+                .positive()
+                .describe('The skill learned (must exist in data/Skills.json)'),
+            level: z.number().int().describe('Level at which the skill is learned'),
+            note: z.string().optional().describe('Optional note for the learning entry'),
+        },
+        handler: async (ctx, args) => withSkillTypeWarnings(ctx.projectPath, await addClassLearning(ctx.projectPath, args.classId, args.skillId, args.level, args.note)),
+    },
+    {
+        name: 'set_class_param_curve',
+        mutates: true,
+        description: "Replace one of a class's 8 parameter growth curves. paramId is 0-7 ([maxHP,maxMP,atk,def,mat,mdf,agi,luk]); values must match the existing curve length (same max level).",
+        inputSchema: {
+            classId: z.number().int().positive().describe('The ID of the class to edit'),
+            paramId: z
+                .number()
+                .int()
+                .min(0)
+                .max(7)
+                .describe('Which param: 0 maxHP,1 maxMP,2 atk,3 def,4 mat,5 mdf,6 agi,7 luk'),
+            values: z
+                .array(z.number())
+                .describe('New curve, indexed by level; must match the existing curve length'),
+        },
+        handler: async (ctx, args) => summarizeClass(await setClassParamCurve(ctx.projectPath, args.classId, args.paramId, args.values)),
+    },
+];
+//# sourceMappingURL=classTools.js.map

package/dist/tools/classTools.js.map

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

package/dist/tools/commonEventTools.d.ts

@@ -0,0 +1,32 @@
+import { CommonEvent, EventCommand } from '../utils/types.js';
+import { ToolDefinition } from '../registry.js';
+import { PreCommit } from '../validation/gate.js';
+/**
+ * A blank common event mirroring what the RPG Maker MZ editor writes for a fresh
+ * slot: no trigger (call-only), switch 1, and an empty (just the code-0 end
+ * marker) command list. Pure so the template shape can be unit-tested. Field
+ * order mirrors the editor's on-disk shape.
+ */
+export declare function defaultCommonEvent(): Omit<CommonEvent, 'id'>;
+/** Get all common events from the project (`data/CommonEvents.json`). */
+export declare function getCommonEvents(projectPath: string): Promise<(CommonEvent | null)[]>;
+/**
+ * Create a new common event. Only `name` is required; any omitted field falls
+ * back to the editor's new-slot default (see {@link defaultCommonEvent}).
+ * Allocates the next unused id (max existing + 1) and writes through the commit
+ * choke point.
+ */
+export declare function createCommonEvent(projectPath: string, overrides: {
+    name: string;
+} & Partial<Omit<CommonEvent, 'id' | 'name'>>, precommit?: PreCommit<CommonEvent>): Promise<CommonEvent>;
+/** Update an existing common event's properties (shallow merge; id re-pinned). */
+export declare function updateCommonEvent(projectPath: string, commonEventId: number, updates: Partial<CommonEvent>, precommit?: PreCommit<CommonEvent>): Promise<CommonEvent>;
+/**
+ * Build a "Common Event" event command (code 117) that calls the given common
+ * event — the helper for wiring shared logic into a map/battle event page via
+ * `add_event_command`. Validates that the referenced common event exists (throws
+ * otherwise, mirroring create_map's parent check).
+ */
+export declare function callCommonEvent(projectPath: string, commonEventId: number, indent?: number): Promise<EventCommand>;
+export declare const commonEventToolDefinitions: ToolDefinition[];
+//# sourceMappingURL=commonEventTools.d.ts.map

package/dist/tools/commonEventTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commonEventTools.d.ts","sourceRoot":"","sources":["../../src/tools/commonEventTools.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,SAAS,EAAa,MAAM,uBAAuB,CAAC;AAK7D;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAO5D;AAgBD,yEAAyE;AACzE,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,CAAC,CAE1F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC,EACvE,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,WAAW,CAAC,CAiBtB;AAED,kFAAkF;AAClF,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,EAC7B,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,WAAW,CAAC,CAatB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,MAAM,SAAI,GACT,OAAO,CAAC,YAAY,CAAC,CAMvB;AAED,eAAO,MAAM,0BAA0B,EAAE,cAAc,EAkFtD,CAAC"}

package/dist/tools/commonEventTools.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { readJsonFile, getDataPath } from '../utils/fileHandler.js';
+import { commitChange } from '../utils/commit.js';
+import { definedOnly } from '../utils/records.js';
+import { validateCommandList } from '../validation/eventCommands.js';
+import { writeGate } from '../validation/gate.js';
+/** Command code for "Common Event" (call a common event from an event page). */
+const CALL_COMMON_EVENT_CODE = 117;
+/**
+ * A blank common event mirroring what the RPG Maker MZ editor writes for a fresh
+ * slot: no trigger (call-only), switch 1, and an empty (just the code-0 end
+ * marker) command list. Pure so the template shape can be unit-tested. Field
+ * order mirrors the editor's on-disk shape.
+ */
+export function defaultCommonEvent() {
+    return {
+        list: [{ code: 0, indent: 0, parameters: [] }],
+        name: '',
+        switchId: 1,
+        trigger: 0,
+    };
+}
+/**
+ * The pre-commit gate the common-event-writing tools install. A common event's
+ * `list` reuses the event-command format, so the same command validator applies
+ * — and a structurally invalid list is refused before the write rather than
+ * saved and warned about.
+ */
+function commonEventWriteGate(force) {
+    return writeGate(force, 'common event', (commonEvent) => validateCommandList(commonEvent.list, `common event ${commonEvent.id}`));
+}
+/** Get all common events from the project (`data/CommonEvents.json`). */
+export async function getCommonEvents(projectPath) {
+    return await readJsonFile(getDataPath(projectPath, 'CommonEvents.json'));
+}
+/**
+ * Create a new common event. Only `name` is required; any omitted field falls
+ * back to the editor's new-slot default (see {@link defaultCommonEvent}).
+ * Allocates the next unused id (max existing + 1) and writes through the commit
+ * choke point.
+ */
+export async function createCommonEvent(projectPath, overrides, precommit) {
+    const commonEvents = await getCommonEvents(projectPath);
+    const maxId = commonEvents.reduce((max, ce) => (ce && ce.id > max ? ce.id : max), 0);
+    // Template first, caller's defined fields next, computed id last so it always wins.
+    const commonEvent = {
+        ...defaultCommonEvent(),
+        ...definedOnly(overrides),
+        id: maxId + 1,
+    };
+    commonEvents.push(commonEvent);
+    await precommit?.(commonEvent);
+    await commitChange(getDataPath(projectPath, 'CommonEvents.json'), commonEvents);
+    return commonEvent;
+}
+/** Update an existing common event's properties (shallow merge; id re-pinned). */
+export async function updateCommonEvent(projectPath, commonEventId, updates, precommit) {
+    const commonEvents = await getCommonEvents(projectPath);
+    const index = commonEvents.findIndex((ce) => ce && ce.id === commonEventId);
+    if (index === -1) {
+        throw new Error(`Common event with ID ${commonEventId} not found`);
+    }
+    commonEvents[index] = { ...commonEvents[index], ...updates, id: commonEventId };
+    await precommit?.(commonEvents[index]);
+    await commitChange(getDataPath(projectPath, 'CommonEvents.json'), commonEvents);
+    return commonEvents[index];
+}
+/**
+ * Build a "Common Event" event command (code 117) that calls the given common
+ * event — the helper for wiring shared logic into a map/battle event page via
+ * `add_event_command`. Validates that the referenced common event exists (throws
+ * otherwise, mirroring create_map's parent check).
+ */
+export async function callCommonEvent(projectPath, commonEventId, indent = 0) {
+    const commonEvents = await getCommonEvents(projectPath);
+    if (!commonEvents.some((ce) => ce && ce.id === commonEventId)) {
+        throw new Error(`Common event with ID ${commonEventId} does not exist`);
+    }
+    return { code: CALL_COMMON_EVENT_CODE, indent, parameters: [commonEventId] };
+}
+export const commonEventToolDefinitions = [
+    {
+        name: 'create_common_event',
+        mutates: true,
+        forceable: true,
+        description: "Create a new common event (reusable event-command list) in data/CommonEvents.json. Only `name` is required; omitted fields use the editor's new-slot defaults (empty command list, trigger 0 = call-only, switchId 1). Allocates and returns the next unused id. A structurally invalid command list refuses the write (nothing is saved) — pass force: true to override.",
+        inputSchema: {
+            name: z.string().describe('Common event name shown in the database'),
+            trigger: z
+                .number()
+                .int()
+                .optional()
+                .describe('How it runs on its own: 0 None (call-only), 1 Autorun, 2 Parallel'),
+            switchId: z
+                .number()
+                .int()
+                .optional()
+                .describe('Switch that gates an Autorun/Parallel trigger (ignored when trigger is 0)'),
+            list: z
+                .array(z.unknown())
+                .optional()
+                .describe('Event-command list { code, indent, parameters }; must end with code 0'),
+        },
+        handler: async (ctx, args) => {
+            // dryRun/force are dispatcher arguments, not common-event fields — strip
+            // them so they can't leak into the record via the spread below.
+            const { dryRun: _dryRun, force, ...overrides } = args;
+            const gate = commonEventWriteGate(force);
+            const commonEvent = await createCommonEvent(ctx.projectPath, overrides, gate.precommit);
+            return gate.respond({ commonEvent });
+        },
+    },
+    {
+        name: 'update_common_event',
+        mutates: true,
+        forceable: true,
+        description: "Update a common event's properties (shallow merge into the existing record). Use for name, trigger, switchId, or to replace the whole command list. A structurally invalid command list refuses the write (nothing is saved) — pass force: true to override.",
+        inputSchema: {
+            commonEventId: z.number().int().positive().describe('The ID of the common event to update'),
+            updates: z
+                .record(z.string(), z.unknown())
+                .describe('Object containing common event properties to update (name, trigger, switchId, list)'),
+        },
+        handler: async (ctx, args) => {
+            const gate = commonEventWriteGate(args.force);
+            const commonEvent = await updateCommonEvent(ctx.projectPath, args.commonEventId, args.updates, gate.precommit);
+            return gate.respond({ commonEvent });
+        },
+    },
+    {
+        name: 'call_common_event',
+        description: 'Build a "Common Event" event command (code 117) that calls the given common event, for insertion into an event page via insert_event_commands. Validates the common event exists. Read-only: returns `{ command }` (matching the build_* tools, so it composes into a thenBranch/commands array); writes nothing.',
+        inputSchema: {
+            commonEventId: z
+                .number()
+                .int()
+                .positive()
+                .describe('The ID of the common event to call (must exist)'),
+            indent: z
+                .number()
+                .int()
+                .optional()
+                .describe('Indentation level in the target list (default 0)'),
+        },
+        handler: async (ctx, args) => ({
+            command: await callCommonEvent(ctx.projectPath, args.commonEventId, args.indent),
+        }),
+    },
+];
+//# sourceMappingURL=commonEventTools.js.map

package/dist/tools/commonEventTools.js.map

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

package/dist/tools/eventCommandTools.d.ts

@@ -0,0 +1,37 @@
+import { EventCommand } from '../utils/types.js';
+import { ToolDefinition } from '../registry.js';
+import { ValidationWarning } from '../validation/eventCommands.js';
+/** The three homes an EventCommand list can have in an MZ project. */
+export type CommandListTarget = 'map_event' | 'common_event' | 'troop_page';
+export interface InsertEventCommandsOptions {
+    mapId?: number;
+    eventId?: number;
+    commonEventId?: number;
+    troopId?: number;
+    pageIndex?: number;
+    commands: EventCommand[];
+    position?: number;
+    force?: boolean;
+}
+export interface InsertEventCommandsResult {
+    target: CommandListTarget;
+    id: number;
+    list: EventCommand[];
+    warnings?: ValidationWarning[];
+}
+/**
+ * Insert a pre-built command sequence into any of the three command lists an MZ
+ * project has — a map event page, a common event body, or a troop battle-event
+ * page — the mutating companion to the read-only builders below. This is how a
+ * Show Text / Show Choices / Conditional Branch block built by the builders
+ * actually lands in the game.
+ *
+ * All three lists share the EventCommand format, so there is one splice path:
+ * resolve the list, splice before its code-0 end marker (or at `position`),
+ * gate, commit. The resulting list is validated **before** the commit — a
+ * structurally invalid result is refused and nothing is written (unless
+ * `opts.force`).
+ */
+export declare function insertEventCommands(projectPath: string, target: CommandListTarget, opts: InsertEventCommandsOptions): Promise<InsertEventCommandsResult>;
+export declare const eventCommandToolDefinitions: ToolDefinition[];
+//# sourceMappingURL=eventCommandTools.d.ts.map

package/dist/tools/eventCommandTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventCommandTools.d.ts","sourceRoot":"","sources":["../../src/tools/eventCommandTools.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,iBAAiB,EAClB,MAAM,gCAAgC,CAAC;AA0FxC,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,cAAc,GAAG,YAAY,CAAC;AAE5E,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAuGD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,yBAAyB,CAAC,CAMpC;AAqKD,eAAO,MAAM,2BAA2B,EAAE,cAAc,EAypBvD,CAAC"}