msw-behaviourtree skill for Claude Code: build MapleStory Worlds behavior trees

• Runs a Node script that catalogs your custom node IDs and properties

  Runs scripts/build-spec.cjs, which scans .codeblock files whose paired .mlua extends ActionNode, DecoratorNode or CompositeNode and writes .behaviourDocs/bt-spec.md. Rebuild it after node or property changes or a CoreVersion bump.

  Try: “Build the BT spec for this project, then create a Patrol behaviour tree.”

  Runs code · Step 0: build bt-spec.md

• Confirms name, save path, tree shape, custom nodes and Blackboard variables

  Claude asks (via AskUserQuestion) when anything is unclear. If a custom node you name is not in bt-spec.md, it stops and asks instead of inventing a UUID.

  Read · Step 1: collect input

• Generates one file ID and one ID per node

  Runs a one-line node command that prints crypto.randomUUID() for the file and each node.

  Runs code · Step 2: mint UUIDs

• Maps each node to its definitionId and btNodeType

  Built-in composites use their own name, custom nodes use the value from bt-spec.md. Types are 0 for action, 1 for composite and 2 for decorator.

  Read · Step 3: resolve definitionId

• Builds the Blackboard and each node's nodeProperties

  Copies type strings verbatim from bt-spec.md, resolves property types from the paired .mlua file, and points *Key properties at Blackboard variable names.

  Read · Steps 4 and 4.5: Blackboard and properties

• Builds the graph under strict parent and child rules

  One start node, composites own multiple children, decorators wrap exactly one child and chain when they apply to the same action, and actions are leaves.

  Write · Step 5: assemble nodes

• Lays the tree out downward with float coordinates

  The RootNode anchor stays at 0,0, the start node sits at y -200 or lower, and decorators carry no position.

  Write · Step 6: nodePosition

• Writes the file, then runs a checklist and a JSON parse check

  The checklist covers IDs, parent and child consistency, version strings and no empty arrays. It parses the result with a short node command.

  Runs code · Step 7: write and validate

• Changes an existing .behaviourtree file without breaking IDs

  Reads the whole file first, keeps the wrapper UUID, updates parent and child lists together, re-runs Step 0 if node definitions may have changed, and re-runs the checklist.

  Write · Edit workflow

Watch out for

• The plugin writes AGENTS.md and CLAUDE.md in your project

  On session start, inject-agents-md.cjs copies the plugin's AGENTS.md into the project root, replacing it when the content differs, and adds an @AGENTS.md import to CLAUDE.md (creating the file if missing). Back up an existing AGENTS.md first. github.com

• The plugin runs 9 hook scripts on 6 events

  hooks.json registers 9 hook scripts on 6 events. SessionStart: mlua-session-start.cjs starts the mlua LSP daemon in the background when it finds a RootDesk folder, and inject-agents-md.cjs (next item). UserPromptSubmit: skill-router-reminder.cjs adds the same fixed routing reminder to every prompt. PreToolUse: skill-read-guard.cjs refuses Bash reads such as cat, head or grep on the plugin's skill .md files, and structured-file-guard.cjs refuses reads, edits and shell commands on .model and .ui files. PostToolUse on Edit, Write and MultiEdit: mlua-diagnose-post-tool-use.cjs runs the mlua checker on edited .mlua files and returns a block decision with the errors when it finds any, and a second hook calls the msw-maker-mcp tool maker_refresh_workspace. PostToolUse on Read and Skill, and the InstructionsLoaded event: skill-log.cjs logs skill reads to .mswai/logs/skill.log. PostToolUse on every tool: mcp-log.cjs (below). SessionEnd: mlua-session-end.cjs stops the LSP daemon. Use the skills CLI route in the install box if you do not want hooks. github.com

• The plugin runs a downloaded package with npx -y

  The mlua checks start a background daemon at session start and run again after each .mlua edit. resolve-cmd.cjs looks first for a local copy (env override, the workspace .mswai/runtime folder, the ai-cli vendored copy, mlua-lsp on PATH). If none is found and npx exists, it runs npx -y @maplestoryworlds/mlua-lsp@1.1.4, which downloads that package from the npm registry. github.com

• The plugin logs every MCP call to .mswai/logs

  mcp-log.cjs runs after every tool call and, for MCP tools from any server, appends one line to .mswai/logs/mcp.log in your project with the tool name, the full arguments and the full response (cut only if MCP_LOG_MAX_OUTPUT_BYTES is set). lsp.log and skill.log are written to the same folder. Our advice: add .mswai/ to .gitignore, because the log can hold anything your MCP servers return. github.com

• The plugin blocks direct reads of .model and .ui files

  structured-file-guard.cjs refuses Read, Edit, Write and shell commands on .model and .ui files and tells Claude to use the builders. Setting MSW_STRUCTURED_FILE_GUARD_DISABLE=1 turns it off. skill-read-guard.cjs also refuses Bash reads such as cat or grep on the plugin's skill .md files (MSW_SKILL_READ_GUARD_DISABLE=1 turns it off). github.com