rpgmaker-event-writing

Writing events

An event has pages; each page has conditions, an image, a trigger and a list of commands {code, indent, parameters}. Every list ends with {code: 0, indent: 0, parameters: []}. The full table is in the resource rpgmaker://reference/event-commands and the tool event_command_reference.

Fast paths

• Dialogue: add_dialogue {mapId, eventId, lines, faceName?, position?} builds the 101/401 commands and starts a new message box every 4 lines (the window shows 4 lines).
• Common patterns (preferred): create_event_from_template {mapId, x, y, template, ...} builds a finished chest, locked door, inn, shop, save point or NPC in one write; it refuses an occupied tile unless allowStack is true. Events are invisible until you give them an image.
• Branching conversations (preferred): build_dialogue_tree {tree, mapId?, eventId?} compiles nested say / choices / if / set-switch / set-variable / transfer nodes into correctly indented commands. Call it without mapId/eventId (or with dryRun) to preview first. Use these two before hand-writing add_event_command lists; the hand-built indent and terminator bookkeeping is where most event bugs come from.
• Cutscenes and game flow (same tool): build_dialogue_tree also has presentation nodes - wait, fade (out/in), tint, flash, shake, weather, playAudio, fadeAudio, showPicture, erasePicture, animation, balloon, moveRoute - and game-flow nodes - battle (with onWin / onEscape / onLose), shop, callCommon, label / jump, exit, comment, gold, item, party, learnSkill, recoverAll, nameInput, plugin, scene. Example: [{"fade":"out"},{"battle":{"troopId":3,"canLose":true,"onWin":[{"gold":200}],"onLose":[{"scene":"gameOver"}]}},{"fade":"in"}]. onEscape needs canEscape: true and onLose needs canLose: true. Preview with dryRun, and play important cutscenes: the command layouts come from knowledge of the MV engine, not engine source.
• Move routes: {moveRoute: {target: "player" | "this" | eventId, steps: [...], repeat?, skippable?, wait?}}. A step is up, down, left, right, turnUp (and the other turns), throughOn/throughOff, {wait: n}, {jump: {x, y}}, {switchOn: id} and so on. The route is written as one 205 command plus a 505 row per step, so never insert commands between those rows by hand. Repeat/wait rule: a route with repeat: true never finishes, so the event cannot wait for it - wait then defaults to false and an explicit wait: true is rejected. A one-shot route waits by default, so the next command runs after it ends.
• Anything else: add_event_command with a commands array; it inserts before the terminator, or at index.
• New NPC: create_event {mapId, name, x, y} then add_dialogue. Give it a sprite by passing a page with image: {characterName, characterIndex, direction, pattern: 1} (look at an existing event with get_event for the full page shape).