A visual node-graph editor for creating RPG Maker MZ character interactions without coding. Design complex dialogue trees, choice menus, and branching logic visually, then export directly to RPG Maker event commands.
Part of MZ DevKit — a suite of visual tools for RPG Maker MZ:
mz-plugin-studio(plugins) ·mz-interaction-builder(dialogue trees) ·mz-scene-builder(timelines / cutscenes)
- Visual Node Graph - Drag-and-drop interface using React Flow
- 7 Node Types - Start, Choice Menu, Action, Condition, End, Group, Comment
- Unlimited Choices - Menu nodes support any number of choices
- Hide/Disable Conditions - Conditionally show or gray out choices
- Loop Support - Connect back to earlier nodes for repeating menus
- Variable Presets - Built-in presets for Relationship and Time systems
- Direct Export - Export to RPG Maker map events with one click
- Undo/Redo - Full history support with Ctrl+Z/Ctrl+Y
- Copy/Paste - Duplicate nodes with Ctrl+C/Ctrl+V
- Multi-Select - Drag rectangle selection, bulk delete, bulk copy/paste
- Validation - Real-time warnings for unconnected nodes and dead ends
- Auto-Save - Automatically saves every 30 seconds when file path exists
- Help System - Press F1 or ? for keyboard shortcuts and node reference
- Dialogue Preview - F5 to test dialogue flow with typewriter text, choices, and variable inspection
- Coverage Overlay - See which nodes have been visited during preview testing
- Templates - Save node selections as reusable templates, drag to instantiate
- Toast Notifications - Visual feedback for save, copy, and template actions
- Dark Theme - Blue-tinted palette with Inter/JetBrains Mono fonts, smooth animations
- Accessibility - Respects OS reduced-motion preference
- Search - Ctrl+F to find nodes by label or content
- Path Highlighting - Alt+Click a node to trace upstream/downstream connections
- Bookmarks - Pin important nodes for quick navigation
- Breadcrumb Trail - Shows shortest path from Start to selected node
- Zoom Controls - Fit All, Fit Selection, Fit to Start hotkeys
- Context Menu - Right-click canvas to quickly add nodes
- Auto-Layout - Dagre-powered automatic graph layout (LR/TB)
- Alignment Tools - Align and distribute selected nodes
- Snap Guides - Visual alignment guides when dragging nodes
- Quick-Add Hotkeys - Press 1-7 to create nodes at viewport center
- Mute Nodes - Skip nodes during export without deleting them (M hotkey)
- Edge Reconnection - Drag edge endpoints to rewire connections
cd tools/mz-interaction-builder
# Install dependencies (use --no-bin-links on WSL)
npm install --no-bin-links
# Run in development mode
npm run dev
# Build for production
npm run build
- Add Nodes - Drag nodes from the left palette onto the canvas
- Connect Nodes - Drag from output handles (right) to input handles (left)
- Edit Properties - Click a node to edit its properties in the right panel
- Save - Use Ctrl+S or the toolbar button to save your work
| Node | Color | Purpose |
|---|---|---|
| Start | Green | Entry point - every interaction needs one |
| Choice Menu | Purple | Display choices to the player |
| Action | Blue | Execute scripts, set variables, call events |
| Condition | Amber | Branch based on switches, variables, or scripts |
| End | Red | Exit the interaction |
| Group | Blue | Visual container for organizing nodes |
| Comment | Amber | Annotation note (not exported) |
- Add unlimited choices with the + button
- Use up/down arrows to reorder choices
- Set cancel behavior (Disallow, Branch, Last Choice)
- Configure window background and position
- Hide Condition - Choice doesn't appear when condition is true
- Disable Condition - Choice is grayed out when condition is true
- Conditions support Switches, Variables, and Script expressions
- When project is loaded, switch/variable dropdowns populate automatically
Supports multiple action types:
- Script - Execute JavaScript code
- Set Variable - Change a game variable
- Set Switch - Toggle a game switch
- Common Event - Call a common event
- Show Text - Display a text message
- Plugin Command - Call a plugin command
Branch on:
- Switch - Check if ON or OFF
- Variable - Compare with operators (=, !=, >, <, >=, <=)
- Script - Evaluate JavaScript that returns true/false
The toolbar includes a validation button that checks your graph for common issues before exporting:
Click "Copy to Clipboard" in the Export modal to copy the generated RPG Maker commands. Paste into your event's command list.
- Click the Export button in the toolbar
- Select your RPG Maker MZ project folder
- Choose the target Map, Event, and Page
- Click "Export to Map"
- Reload the map in RPG Maker to see changes
When choices have Hide or Disable conditions, the export uses a dynamic menu system:
- Hidden choices are excluded from the menu when their condition is true
- Disabled choices appear grayed out (
\C[8]color code) when their condition is true - Uses
$gameMessage.setChoices()for dynamic menu generation - Note: Variable 99 is used as temporary storage for choice routing
Interactions are saved as .mzinteraction JSON files:
{
"version": "1.0.0",
"name": "My Interaction",
"description": "",
"nodes": [...],
"edges": [...],
"variables": [...],
"bookmarks": [...]
}| Shortcut | Action |
|---|---|
| Ctrl+N | New file |
| Ctrl+O | Open file |
| Ctrl+S | Save file |
| Ctrl+Z | Undo |
| Ctrl+Y / Ctrl+Shift+Z | Redo |
| Ctrl+C | Copy selected nodes |
| Ctrl+V | Paste nodes |
| Delete / Backspace | Delete selected nodes or edges |
| Ctrl+F | Search nodes |
| Ctrl+0 | Zoom to fit all nodes |
| Ctrl+1 | Zoom to fit selection |
| Home | Zoom to Start node |
| B | Toggle bookmark on selected node |
| M | Mute/unmute selected node |
| Alt+Click | Highlight upstream path |
| Shift+Alt+Click | Highlight downstream path |
| Escape | Clear highlights |
| Ctrl+Shift+L | Auto-layout graph |
| Ctrl+G | Toggle snap-to-grid |
| Alt+L/C/R/T/M/B | Align selected nodes |
| 1-7 | Quick-add node (Start, Menu, Action, Condition, End, Group, Comment) |
| Right-Click | Context menu to add nodes |
| F5 | Toggle dialogue preview |
| Space (in preview) | Step to next node |
| 1-9 (in preview) | Pick choice by number |
| R (in preview) | Restart preview |
| F1 / ? | Show help |
| Scroll Wheel | Zoom in/out |
| Click + Drag | Pan canvas (or rectangle select) |
| Click Edge | Select edge (for deletion) |
| Drag Edge Endpoint | Reconnect to different handle |
Built-in presets for common game systems:
Relationship System
- Get/Add Affection
- Get/Add Corruption
- Get/Check Stage
Time System
- Time Slot, Energy, Day, Weekday
- Action Points, In School flag
The export generates standard RPG Maker MZ event commands:
| Node Type | Event Codes |
|---|---|
| Choice Menu | 102 (Show Choices), 402 (When [Choice]), 404 (End) |
| Condition | 111 (Conditional Branch), 411 (Else), 412 (End) |
| Action: Script | 355/655 (Script) |
| Action: Switch | 121 (Control Switches) |
| Action: Variable | 122 (Control Variables) |
| Action: Common Event | 117 (Common Event) |
| Action: Show Text | 101/401 (Show Text) |
Loops are handled with Labels (118) and Jump to Label (119).
This application follows Electron security best practices:
- Sandboxed renderer —
sandbox: true,contextIsolation: true,nodeIntegration: false - IPC validation — File operations restricted to
.mzinteractionfiles; project paths validated before acceptance - Content Security Policy — Restricts script, style, connect, object, and frame sources
- Navigation blocking —
will-navigatehandler prevents renderer from loading external pages - Protocol allowlist —
shell.openExternallimited tohttps:andhttp:URLs - Script sandbox — Preview script evaluation shadows
window,document,fetch, and other globals to prevent access to the IPC bridge - Error boundaries — Global React error boundary prevents white-screen crashes with recovery UI
- Framework: Electron 40 + Vite 7
- UI: React 19 + TypeScript 5
- Node Graph: React Flow (@xyflow/react 12)
- State: Zustand 5
- Layout: Dagre (auto-layout engine)
- Styling: Tailwind CSS 3
- Animation: Framer Motion 12
src/
├── main/ # Electron main process
│ └── ipc/ # File, dialog, project handlers
├── preload/ # IPC bridge
└── renderer/
└── src/
├── components/
│ ├── properties/ # Per-node-type property editors
│ └── ... # Canvas, SearchPanel, BookmarkPanel, PropertiesPanel, etc.
├── edges/ # InteractionEdge (custom color-coded edge component)
├── nodes/ # BaseNode + 7 node types
├── hooks/ # useCanvasKeyboard, useCanvasLayout, useDebouncedSync, etc.
├── stores/ # Zustand: Document, History, UI, Project, Template, Preview
├── lib/
│ ├── export/ # RPG Maker command generation
│ ├── preview/ # Dialogue preview engine + sandboxed script eval
│ ├── presets/ # Variable presets
│ ├── animations.ts # Centralized animation constants (Framer Motion)
│ ├── nodeColors.ts # Centralized node accent colors
│ ├── nodeFactory.ts # Node creation helpers
│ ├── edgeUtils.ts # Edge type/color logic
│ ├── validateDocument.ts # Pure validation function
│ ├── graphTraversal.ts # BFS upstream/downstream/shortest path
│ ├── searchNodes.ts # Node text extraction and search
│ └── __tests__/ # Unit tests
├── styles/ # globals.css with CSS variables
└── types/ # TypeScript interfaces
npm test # 181 tests across 14 files
npm run test:coverage # Coverage reportTested modules include graph traversal, node search, alignment/layout, export (muted paths), document validation, preview engine, script sandbox, debounced sync, templates, and UI components.
# Type checking
npm run typecheck
# Linting
npm run lint
# Format code
npm run format
# Build for Windows
npm run build:win
# Build for macOS
npm run build:mac
# Build for Linux
npm run build:linuxMIT
"RPG Maker" is a trademark of Gotcha Gotcha Games Inc. This project is not affiliated with or endorsed by Gotcha Gotcha Games.