Msw Behaviourtree

MSW BehaviourTree

End-to-end authoring skill for MSW .behaviourtree files. Owns both the project-specific authoring spec (<ProjectRoot>/.behaviourDocs/bt-spec.md) and the tree generation itself. Fixed graph rules and skeletons live in this skill's references/; the per-project spec is (re)built by this skill's local scripts/build-spec.cjs.

---

🚦 Execution order (follow this sequence)

0. Build / refresh the project spec (bt-spec.md)

The spec is the source of truth for every project-specific data point: each custom action/decorator node's definitionId, btNodeType, visible propertyKey names, and the serialized Type.type strings stamped to this project's CoreVersion.

When to (re)build:

• First time working on BT in a project (no .behaviourDocs/bt-spec.md yet).
• After any change that affects BT node surface area:
• new / renamed / removed .codeblock whose paired .mlua extends ActionNode / DecoratorNode
• added / removed / renamed property lines in such a .mlua
• Environment/config CoreVersion bumped (the serialized type strings are version-tagged).
• The user says they recently added/changed a BT codeblock or a .mlua property — stale UUIDs / missing properties silently produce broken trees.
• The downstream validation (Step 7) flags a definitionId, propertyKey, or version mismatch.

How to run — invoke this skill's local script:

node "scripts/build-spec.cjs" --projectRoot "<MSW project root>"

If the current working directory is already the MSW project root, --projectRoot can be omitted. Requires Node.js on PATH (no other dependencies — pure stdlib fs/path).

Optional overrides (long flags, case-insensitive):

Example with overrides:

node "scripts/build-spec.cjs" --projectRoot "C:/path/to/project" --coreVersion 26.5.0.0

The script throws if Environment/config is absent and --coreVersion is not passed — there is no fallback default.

What the spec contains:

1. Project metadata — project root, CoreVersion, generated time, discovered node counts. 2. Built-in composite node names and their fixed definitionId / btNodeType. 3. Custom action nodes — Name, definitionId, btNodeType, visible property names. 4. Custom decorator nodes — same shape as action nodes. 5. Type map — mlua type to serialized MODNativeType.type plus Blackboard ObjectValue shape.

UUIDs come from real .codeblock files in the project — the spec never invents them. @HideFromInspector properties are filtered out automatically. Fixed authoring rules, file skeletons, and validation checklists live in this skill's references/ rather than in the generated spec.

After (re)building, read the freshly written <ProjectRoot>/.behaviourDocs/bt-spec.md and continue with the steps below. The compact spec intentionally lists only property names; when constructing nodeProperties, resolve each property's mlua type/default from the paired .mlua file, then use the type map in bt-spec.md §4 for propertyType.type.

Also read `references/skeleton-minimal.json` for the smallest valid tree, `references/skeleton-full.json` for a Composite+Decorator+Action+Blackboard example with all optional fields populated, `references/node-catalog.md` for fixed graph rules, and any existing .behaviourtree in the project (**/*.behaviourtree) to mirror conventions. Replace {CORE_VERSION} in the skeletons with the CoreVersion from bt-spec.md — both at the top level and inside every MOD.Core.* type string in Blackboard variables and nodeProperties.

1. Collect input from the user

Confirm via context, or ask via AskUserQuestion if anything is ambiguous:

Custom-node existence check (mandatory): every custom action/decorator name the user mentions must appear in bt-spec.md §2 / §3. If a referenced node is not in the spec, stop and ask the user — do not invent a UUID, do not assume a node exists by name, and do not skip rerunning Step 0.

2. Mint UUIDs

You need:

• One UUID for the file → goes into EntryKey and ContentProto.Json.id (both identical, both prefixed behaviourtree://).
• One UUID for each node in Nodes (nodeId).

node -e "console.log(require('node:crypto').randomUUID())"

Mint up front, write into a scratch table, then assemble. Don't reuse the file UUID as a nodeId.

3. Resolve every definitionId

Custom-node UUIDs come from bt-spec.md (which read them from real .codeblock files) — never any other source.

4. Build the Blackboard

For each variable, copy the Type.type string and ObjectValue shape verbatim from bt-spec.md §4. The version-tagged substring (Version=<CoreVersion>) must match exactly — a typo silently breaks deserialization.

Variables is an ordered array; each entry: { Name, Type: { "$type": "MODNativeType", type: "<from spec>" }, ObjectValue: <from spec> }. The ObjectValue does not include a $type discriminator (unlike Value in .model files).

For Component / ComponentRef, ComponentId is <entity-uuid>:<ComponentName> (engine component) or <entity-uuid>:<scriptCodeblockUuid>:<ScriptComponentName> (script component). Mirror an existing serialized example in the project.

Numeric ObjectValues use float literal form (3.0, not 3).

4.5 Resolve node property values

For each custom node that needs nodeProperties:

1. Confirm the propertyKey exists in bt-spec.md §2 / §3 for that node. 2. Find the paired .mlua by searching for script <NodeName> extends ActionNode or script <NodeName> extends DecoratorNode under the project. If multiple files match, prefer the one whose sibling .codeblock has the exact definitionId UUID from bt-spec.md; if still ambiguous, ask the user. 3. Read the visible property declarations in that .mlua, ignoring @HideFromInspector properties. This gives the mlua type and default value. 4. Include a nodeProperties entry only when the user provided a value, the behavior requires a non-default value, or a *Key property must point at a Blackboard variable. Omit optional properties that can safely use the .mlua default. 5. For *Key string properties, set propertyValue to the Blackboard variable name. Infer the variable by name and getter usage when obvious (MoveSpeedKey -> MoveSpeed, TargetEntityKey -> TargetEntity). If more than one Blackboard variable could match, ask. 6. For literal properties, use the user-provided value. If no value is provided and the .mlua default is meaningful, omit the property instead of serializing a guessed value. 7. If OnBehave checks a property for nil, empty string, or invalid enum and no value can be inferred, ask the user before writing the tree.

nodeProperties entry shape:

{
  "propertyKey": "<property name>",
  "propertyType": { "$type": "MODNativeType", "type": "<type from bt-spec.md §4>" },
  "propertyValue": <value>
}

5. Assemble Nodes

Hard graph constraints (validate before writing):

• RootNode is not a parent node. It must not have childNodes. It only stores startNodeId, and startNodeId points to exactly one node in Nodes.
• If the tree needs several top-level behaviors, use either one Composite as the single startNodeId, or one Decorator as the single startNodeId whose decoChildNodes wraps a Composite or another Decorator chain that eventually wraps a Composite. Put the multiple behaviors under that Composite's childNodes.
• Exactly one node in Nodes may have nodeParentId: "": the node referenced by RootNode.startNodeId. Do not create multiple root-level Action/Composite/Decorator nodes.
• Composite (btNodeType: 1) is the only node category that can own multiple children through childNodes.
• Decorator (btNodeType: 2) is only a wrapper/parent for exactly one Action, Composite, or Decorator node. It can also be the child of another Decorator, so Decorator-to-Decorator chains are valid. It must use singular decoChildNodes (a single nodeId string) for that one child, not childNodes; the wrapped child must also record the Decorator's id in its nodeParentId.
• Decorators applying to the same Action MUST be chained — never flattened as siblings. Each decorator owns exactly one downstream subtree. If two or more decorators are meant to gate/modify the same Action, build a single chain Composite → ADeco → BDeco → CDeco → Action where each decorator's decoChildNodes points to the next decorator (and finally the Action). Concretely: within one chain leading to a single Action, no two decorators may share the same `nodeParentId` — each decorator's parent is the previous decorator, and only the topmost decorator's parent is the Composite. Sibling decorators under one Composite are still valid when each wraps a different downstream subtree. ✅ Composite → ADeco → BDeco → CDeco → Action (chain — every decorator has a unique parent within the chain). ❌ Composite → [ADeco→Action, BDeco→Action, CDeco→Action] (Action duplicated to bypass chaining). ❌ Composite → [ADeco, BDeco, CDeco, Action] (decorators flattened — they don't wrap the Action and are effectively orphaned).
• Action (btNodeType: 0) is a leaf — never has children.

Node-write invariants:

• Every nodeId is unique within the file.
• nodeParentId of every non-root node points to a real nodeId that is a Composite or Decorator. It must never point to RootNode, because RootNode is not represented as a node in Nodes.
• If a node's parent is a Composite, that Composite must include the node id in childNodes.
• If a node's parent is a Decorator, that Decorator's decoChildNodes must equal that node's nodeId. This is valid even when both parent and child are Decorators.
• Composite childNodes ↔ child nodeParentId is bidirectionally consistent.
• Action nodes omit childNodes. Decorator nodes omit childNodes and use exactly one decoChildNodes (single string nodeId) instead.
• Never write `probability`. The editor strips this field on round-trip, and the supported composites (SequenceNode, SelectorNode, ParallelNode) do not consume per-child weights. Older generated trees in the project may still carry "probability": 1.0 on every node; treat that as legacy on read but do not write it on new nodes.
• Decorator nodes (`btNodeType: 2`) omit `nodePosition`. The editor positions a Decorator automatically relative to the child it wraps, and writes no nodePosition field for it on save. Only Composites and Actions carry nodePosition. The RootNode block also carries its own nodePosition (separate from the start node).
• Empty collection fields are omitted, not serialized as `[]`. A Composite with no children yet should omit childNodes entirely; a node with no overrides should omit nodeProperties entirely. Empty arrays are an editor-draft artifact — do not author them.
• Decorator child field is `decoChildNodes` (canonical — this is what the editor preserves on save; ChildNodeId is silently stripped on round-trip). It is a single string holding the wrapped child's nodeId (not an array). When reading legacy files you may still encounter ChildNodeId on hand-authored decorators; treat it as the same field. When writing, always emit decoChildNodes.
• RootNode.startNodeId references one of the nodeIds — an Action, Composite, or Decorator — and that node is the only node with nodeParentId: "".

*Key-suffix String properties carry the name of a Blackboard variable (resolved at runtime via BlackBoard:GetXxx). Non-Key properties carry the literal value.

6. nodePosition format

nodePosition is a JSON object with numeric x / y:

"nodePosition": { "x": 0.0, "y": 0.0 }

Use float literals (0.0, not 0). The legacy string form "(0.000, 0.000)" may still appear in older hand-authored trees — read it as equivalent, but always write the object form (the BT editor canonicalizes to this shape on save, so the string form re-serializes to a noisy diff the first time the file is opened).

Editor axes: the BT editor uses a math-convention canvas — +x is right, +y is up (upper-right quadrant is positive). So a child placed at a higher y than its parent appears above the parent on screen.

Layout rule — draw the tree downward: depth grows along −y (children sit below their parent), and siblings spread along ±x around the parent's x. Typical spacing: 200 units between depth levels and 200 units between siblings.

`RootNode` block vs the start node — do not stack them at the same position. RootNode.nodePosition is the canvas anchor and stays at { "x": 0.0, "y": 0.0 }. The start node (the node referenced by startNodeId) must sit one level below that anchor — putting it at (0, 0) makes it visually overlap the RootNode marker on the editor canvas. Treat the RootNode anchor as depth 0 and the start node as depth 1.

• RootNode.nodePosition: { "x": 0.0, "y": 0.0 } (fixed anchor — never moves)
• Start node (depth 1, referenced by startNodeId): { "x": 0.0, "y": -200.0 }
• Single child of the start node (depth 2): { "x": 0.0, "y": -400.0 }
• Two children of the start node (depth 2): { "x": -100.0, "y": -400.0 } and { "x": 100.0, "y": -400.0 }
• Each additional level: parent.y − 200

Never place a child at a y greater than or equal to its parent's y — that draws upward and overlaps the parent visually. The same rule applies between RootNode and the start node: the start node must be at y ≤ -200 (strictly below the anchor).

Decorator nodes do not carry `nodePosition`. The editor lays them out automatically relative to the wrapped child. Omit the field on every btNodeType: 2 node; it appears only on RootNode, Composites (btNodeType: 1), and Actions (btNodeType: 0).

7. Write and validate

Write the JSON file, then run this checklist. In particular:

• [ ] EntryKey is behaviourtree://{uuid} and matches ContentProto.Json.id exactly.
• [ ] Top-level Id, GameId, Content are "". Usage, UseService, DynamicLoading are 0. UsePublish is 1. CoreVersion matches the project (Environment/config). StudioVersion is 0.1.0.0. ContentType is x-mod/behaviourtree. ContentProto.Use is Json.
• [ ] RootNode has no childNodes; RootNode.startNodeId matches exactly one nodeId in Nodes; that start node has nodeParentId: ""; and no other node has nodeParentId: "".
• [ ] Every nodeParentId is "" or an existing nodeId.
• [ ] All nodeId values are unique.
• [ ] For every Composite, the set of childNodes IDs equals the set of nodes whose nodeParentId is this Composite.
• [ ] Every Action has no childNodes. Every Decorator has no childNodes, has exactly one decoChildNodes (single nodeId string — ChildNodeId is the legacy variant; the editor strips it on round-trip), and that id points to exactly one Action, Composite, or Decorator child whose nodeParentId points back to the Decorator. Decorator-to-Decorator parent/child chains are valid and must be checked with the same decoChildNodes ↔ nodeParentId rule.
• [ ] Decorator chain rule: when multiple decorators apply to the same Action, they form a single chain (Composite → ADeco → BDeco → … → Action). Verify by walking each Action upward to its enclosing Composite: the decorators encountered along that one path must all have unique nodeParentId values (i.e. each decorator's parent is the previous decorator, never another decorator that already appeared in the chain). Two decorators in the same chain sharing a nodeParentId is invalid. (Sibling decorators under one Composite that wrap different downstream subtrees are fine — uniqueness is per-chain, not global.)
• [ ] No node serializes "probability". (Legacy 1.0 values may appear on read but are never authored.)
• [ ] Every Composite and Action carries nodePosition in object form { "x": <num>, "y": <num> } with float literals — no legacy "(x.xxx, y.yyy)" strings on write. Decorator nodes carry no `nodePosition` at all.
• [ ] Start node is not stacked on the RootNode anchor. RootNode.nodePosition is { "x": 0.0, "y": 0.0 } and the node referenced by startNodeId has y ≤ -200.0 (typically { "x": 0.0, "y": -200.0 }). If the start node is a Decorator (no nodePosition), the first wrapped Composite/Action down the chain must satisfy this offset instead.
• [ ] No node serializes empty arrays — a Composite with no children omits childNodes; a node with no overrides omits nodeProperties. Do not write "childNodes": [] or "nodeProperties": [].
• [ ] Every custom node's definitionId is copied from bt-spec.md (never invented).
• [ ] Every nodeProperties[].propertyKey matches a property in bt-spec.md for that node.
• [ ] Every *Key property's propertyValue matches a Blackboard.Variables[].Name of the right type.
• [ ] Every type string is copied verbatim from bt-spec.md §4 — version-tagged, typo-fragile.
• [ ] Version cross-check: every MOD.Core.* type string's Version=X.Y.Z.Z substring (in Blackboard.Variables[].Type.type and Nodes[].nodeProperties[].propertyType.type) equals the file's top-level CoreVersion. Mismatch silently breaks deserialization — common when bt-spec.md is stale relative to the project's current CoreVersion. If they differ, re-run Step 0 before writing. (System.* types use the immutable Version=4.0.0.0 and are exempt.)
• [ ] JSON parses:

  node -e "JSON.parse(require('node:fs').readFileSync(process.argv[1],'utf8'))" "<path>"

If any check fails, fix it before reporting done.

---

📂 Files in / consumed by this skill

• `scripts/build-spec.cjs` — Node.js script that scans the project and emits <ProjectRoot>/.behaviourDocs/bt-spec.md. Invoked in Step 0.
• <ProjectRoot>/.behaviourDocs/bt-spec.md — compact generated catalog. Source of truth for node names, definitionId, btNodeType, property names, and type strings. Written by the script above; consumed by Steps 1–7.
• `references/skeleton-minimal.json` — smallest valid tree (empty Blackboard, single Composite root with no children).
• `references/skeleton-full.json` — Composite → Decorator → Action with nodeProperties (literal + Key-suffix) and a populated Blackboard. Use this as the shape reference whenever the tree is non-trivial.
• `references/node-catalog.md` — narrative explanation of btNodeType values, valid graph shapes, the Key-suffix convention, and how the spec builder discovers nodes (kept for reference; the runtime catalog itself lives in bt-spec.md).

---

🔁 Edit workflow (existing file)

1. Read the entire file — never Edit blind. UUIDs and the parent/child graph must stay consistent. 2. Never change the file's wrapper UUID (EntryKey / ContentProto.Json.id) — external references break. 3. Adding a node: mint a fresh nodeId, append to Nodes, update the parent Composite's childNodes, set the new node's nodeParentId. 4. Removing a node: remove from Nodes, remove its ID from any Composite's childNodes. If it was a Composite, decide whether to re-parent or remove its children — never leave dangling nodeParentId references. 5. If the edit involves a custom node name, property, or type that may have changed in the project since the spec was last built, re-run Step 0 first. 6. Re-run the Step 7 validation checklist after every edit.

BT Node Catalog

Reference for filling nodeName, definitionId, and btNodeType correctly. The catalog is project-agnostic — it describes the format and how to discover what nodes are available in any project, not a fixed list of node names.

btNodeType values

Valid graph shapes (parent ↔ child rules)

These are hard constraints — violating them produces a tree that loads but does not behave correctly. Validate before writing the file.

Inverse formulation (top-down):

• Want multiple actions to run? → put a Composite above them.
• Want to gate / loop / cooldown a sub-tree? → put a Decorator above it (above a Composite, an Action, or another Decorator).
• Want multiple gates / loops / cooldowns on the same sub-tree? → chain Decorator → Decorator → Action/Composite/Decorator with one decoChildNodes at each Decorator layer.
• Want a single action at the root? → allowed, but rare; usually wrap with a Composite or Decorator anyway.

Common mistakes to reject during planning:

• ❌ RootNode with a childNodes array. RootNode must only point to one startNodeId.
• ❌ Two or more root-level nodes with nodeParentId: "". The format only executes one startNodeId; multiple root-level actions/composites/decorators are invalid for generated trees.
• ❌ Two or more actions directly under the root (no parent Composite). Put them under a single Composite start node, or under a Composite wrapped by one or more Decorators.
• ❌ An Action with childNodes populated. Actions are leaves.
• ❌ A Decorator with zero children or more than one child. Decorators can only parent one Action, Composite, or Decorator.
• ❌ A Decorator with childNodes. Decorators use singular decoChildNodes (a single nodeId string), and that id must match its single wrapped child.
• ❌ Any node other than the startNodeId node with nodeParentId: "". Re-parent it under the start Composite or remove it.
• ❌ *Multiple decorators meant to apply to the same Action laid out as siblings of a Composite instead of chained. When two or more decorators must wrap one Action, they form a single chain — each decorator's child is the next decorator (or finally the Action), so each decorator in the chain has a unique `nodeParentId`. ✅ `Composite → ADeco → BDeco → CDeco → Action` (chain). ❌ `Composite → [ADeco, BDeco, CDeco, Action]` (decorators flattened as siblings; the decorators are orphaned with no Action to wrap, and the Action is unguarded). ❌ `Composite → [ADeco→Action, BDeco→Action, CDeco→Action]` (Action duplicated to bypass chaining). The shared-`nodeParentId` red flag: if two decorators share the same `nodeParentId` value yet the user described them as gating/modifying the same Action, the structure is wrong — chain them. Sibling decorators under one Composite are only valid when each wraps a distinct* downstream Action/subtree.

Discovering available nodes in any MSW project

The creator should normally consume <ProjectRoot>/.behaviourDocs/bt-spec.md, generated by msw-behaviourtree-spec-builder. That compact spec is the source of truth for node names, definitionId, btNodeType, and valid property names.

If the spec is missing or stale, regenerate it first. If you are debugging discovery manually, use the same logic as the builder:

1. Glob the project for **/*.codeblock. 2. For each .codeblock, read ContentProto.Json.Name and ContentProto.Json.Id. 3. Find the sibling .mlua with the same base name. 4. Classify the node from the .mlua declaration: script X extends ActionNode -> custom action (btNodeType: 0), script X extends DecoratorNode -> custom decorator (btNodeType: 2). 5. Use the codeblock Id as definitionId: codeblock://{Id}.

The ContentProto.Json.Target field can be useful as a fallback, but do not rely on it as the primary classifier; generated BT nodes may have a missing or unreliable target.

Finding property metadata

The compact spec lists only property names. For each property you need to serialize, find the node's paired .mlua. The .mlua's visible property declarations enumerate exactly which propertyKey strings are valid and what mlua type/default each one has.

property string TargetPositionKey = ""    →  propertyKey: "TargetPositionKey", propertyType: System.String
property number MoveSpeed         = 10.0  →  propertyKey: "MoveSpeed",         propertyType: System.Double
property bool   IsActive          = false →  propertyKey: "IsActive",          propertyType: System.Boolean

@HideFromInspector property … declarations are runtime-only state — never include them in nodeProperties.

Confirm built-in composite names

Built-in composites use the node name itself as `definitionId` (no codeblock:// prefix). To find which built-in names this version of the engine accepts, prefer one of:

1. Read an existing .behaviourtree file in the project and harvest the nodeName / definitionId strings used on btNodeType: 1 nodes. 2. Check engine documentation / Environment/NativeScripts/ if available.

Common names that BT engines typically expose — verify before use:

• SequenceNode — runs children left-to-right; fails fast on first failure; succeeds when all succeed.
• SelectorNode — runs children left-to-right; succeeds fast on first success.
• ParallelNode — runs children concurrently.

If a name isn't confirmed by either source, ask the user instead of guessing.

nodeProperties ↔ .mlua property mapping

Each entry in nodeProperties must correspond to a property name listed for that node in bt-spec.md and declared in the node's .mlua. The propertyType.type and propertyValue shape MUST match the declared type — use the type map in bt-spec.md §4.

{V} is the engine version stamped into the file (e.g. 26.5.0.0). Match the project's existing files.

*Primitives (System.)**

MOD.Core types

Component (live binding) and ComponentRef (reference) share the same ComponentId payload shape — <entity-uuid>:<ComponentName> where <ComponentName> is the engine component (TransformComponent, AttackComponent, …) or, for script components, the form is <scriptCodeblockUuid>:<ScriptComponentName>. Mirror an existing serialized example.

For any type not in the table, do not guess — Grep the project for a serialized example and copy the type string verbatim.

`Key`-suffix convention: properties whose name ends with Key (e.g. TargetEntityKey, MoveSpeedKey) are String properties whose propertyValue is the name of a Blackboard variable — the script resolves the actual value at runtime via BlackBoard:GetNumber(self.MoveSpeedKey) etc. Properties without the Key suffix carry the literal value directly.