CommandGraph: Node-Based Event Scripting

The CommandGraph is MCE's visual scripting system for creating NPC behaviors, cutscenes, quests, and interactive events. It provides a node-based editor where you connect commands to define event sequences -- no C# code required.

This is the primary tool for game designers working with MCE at all tiers, including DLL tiers where source code is not accessible.

What is CommandGraph?

CommandGraph is a node graph attached to an Actor (any interactable entity in the world). When the player triggers the actor (by interacting, stepping on it, or entering its area), the graph executes its nodes in sequence.

Think of it as a visual script where each node is a game action:

[Start] → [Show Dialog] → [Branch: Has Badge?]
                              ├─ Yes → [Give Item] → [End]
                              └─ No  → [Show Dialog: "Come back later"] → [End]

Creating Your First Event

Step 1: Create an Actor

1. In your scene, create an empty GameObject where you want the NPC.
2. Add an Actor component (or one of its variants: SimpleActor, TriggerActor).
3. Add a SpriteRenderer for the NPC's visual.
4. The actor will automatically register with the GridController.

Step 2: Open the CommandGraph Editor

1. Select your Actor GameObject.
2. In the Inspector, find the CommandGraph section.
3. Click Edit Graph to open the node editor window.

Step 3: Add Nodes

1. Right-click in the graph editor to open the Add Node menu.
2. Nodes are organized by category (see below).
3. Select a node type to add it to the graph.
4. Connect nodes by dragging from one node's output port to another's input port.

Step 4: Configure Nodes

Click on a node to see its properties in the Inspector panel:

• Dialog nodes: Enter the text to display, speaker name, and portrait.
• Branch nodes: Select the game variable to check and the comparison.
• Item nodes: Choose which item to give/take and the quantity.
• Warp nodes: Set the target scene and position.

Actor Types

MCE provides several actor variants:

Actor Type	Trigger	Use Case
Actor	Player interacts (presses action button while facing)	NPCs, signs, objects
SimpleActor	Player interacts, simplified setup	Basic NPCs
TriggerActor	Player steps on or enters an area	Auto-triggers, hidden events
GridSubscribingActor	Responds to grid events	Pressure plates, proximity
PushableActor	Player pushes it by walking into it	Boulders, puzzle blocks
ActorItem	Player interacts, gives an item and disappears	Item pickups on the ground

Node Categories

Dialogs

Show text, choose responses, and manage conversations.

Node	Description
ShowDialog	Display a text box with the speaker's message
ShowChoiceDialog	Present the player with multiple-choice options
ShowMonsterDialog	Display a dialog related to a monster (shows sprite)
CharacterPopUp	Show a popup above an NPC's head (!, ?, ...)

ShowDialog Example:

Speaker: "Professor Elm"
Text: "Welcome to the world of monsters!"
Portrait: oak_portrait
Wait for Input: true

Branches

Control the flow based on conditions.

Node	Description
BranchOnVariable	Check a GameVariable and branch Yes/No
BranchOnBadge	Check if the player has a specific badge
BranchOnItem	Check if the player has a specific item
BranchOnMonster	Check if the player has a specific species in their party
BranchOnMoney	Check if the player has enough money
BranchOnRosterCount	Check how many monsters are in the party

Each branch node has two output ports: True and False.

Items

Manage the player's inventory.

Node	Description
GiveItem	Add an item to the player's bag
TakeItem	Remove an item from the player's bag
GiveMonster	Add a monster to the player's party
GiveMoney	Add money to the player's wallet
TakeMoney	Remove money from the player's wallet

Monsters

Interact with the player's monsters.

Node	Description
HealParty	Fully heal all monsters in the party
SelectMonster	Open the party screen for the player to choose a monster
TeachMove	Teach a specific move to a monster
EvolutionCheck	Trigger evolution checks for all party members
SetNickname	Let the player rename a monster

Battles

Trigger and configure battles.

Node	Description
StartTrainerBattle	Begin a trainer battle with configured team
StartWildBattle	Begin a wild encounter with a specific monster
BranchOnBattleResult	Check whether the player won the last battle

Variables

Read and write game state.

Node	Description
SetVariable	Set a GameVariable to a value
AddToVariable	Add to a numeric GameVariable
CheckVariable	Read a GameVariable's value for logic

GameVariables are the global state system. They persist in save data and can be checked from any CommandGraph or script.

Sounds

Control audio playback.

Node	Description
PlayBGM	Change the background music
PlaySE	Play a sound effect
StopBGM	Stop the current music
FadeOutBGM	Fade the music out over a duration

Animations

Animate characters and the camera.

Node	Description
MoveActor	Move an NPC to a target position
TurnActor	Turn an NPC to face a direction
WaitSeconds	Pause the graph for a duration
FadeScreen	Fade the screen to black or back
ShakeScreen	Shake the camera

Warps

Move the player between locations.

Node	Description
TeleportPlayer	Move the player to a specific tile in the current scene
WarpToScene	Transition the player to another scene

Quests (Pro Tier+)

Manage quest progression.

Node	Description
StartQuest	Begin a quest
CompleteObjective	Mark a quest objective as done
FailQuest	Fail a quest
BranchOnQuestState	Check a quest's current state
GiveQuestReward	Grant the rewards for a quest

Shops

Open shop interfaces.

Node	Description
OpenShop	Open the buy/sell shop UI with a configured item list

Saves

Manage save data.

Node	Description
SaveGame	Trigger a save to the current slot

Utils

Miscellaneous utility nodes.

Node	Description
DeactivateActor	Hide an actor (e.g., after giving an item pickup)
EnablePlayer	Enable/disable player movement

Connecting Nodes

The CommandGraph uses a flow-based connection model:

• Each node has an input port (left side) and one or more output ports (right side).
• Connect an output port to another node's input port to define the execution order.
• Branch nodes have labeled output ports (True/False, Choice1/Choice2/etc.).
• A node without a connected output port ends the graph execution.

Example: Shop NPC

[Start]
  → [ShowDialog: "Welcome! Would you like to browse my wares?"]
    → [ShowChoiceDialog: "Buy" / "Sell" / "No thanks"]
      ├─ Choice 1 ("Buy") → [OpenShop: item_list_potions]
      ├─ Choice 2 ("Sell") → [OpenShop: sell_mode]
      └─ Choice 3 ("No thanks") → [ShowDialog: "Come back anytime!"]

Example: Quest Giver

[Start]
  → [BranchOnVariable: "rescued_lost_monster" == true]
    ├─ True → [ShowDialog: "Thank you for finding my monster!"]
    │           → [BranchOnVariable: "quest_reward_given" == true]
    │             ├─ True → [ShowDialog: "Enjoy the TM!"]
    │             └─ False → [GiveItem: TM_Thunderbolt, 1]
    │                         → [SetVariable: "quest_reward_given" = true]
    │                         → [ShowDialog: "Take this as thanks!"]
    └─ False → [ShowDialog: "Please help me find my lost monster!"]
               → [ShowDialog: "It ran off into the cave to the north."]
               → [SetVariable: "quest_find_monster" = true]

Example: Gym Leader

[Start]
  → [BranchOnBadge: "BoulderBadge"]
    ├─ HasBadge → [ShowDialog: "You've already proven yourself!"]
    └─ NoBadge
      → [ShowDialog: "I am the Gym Leader! Prepare for battle!"]
      → [StartTrainerBattle: gym_leader_team]
      → [BranchOnBattleResult]
        ├─ Won → [ShowDialog: "Impressive! You've earned this."]
        │        → [GiveBadge: "BoulderBadge"]
        │        → [GiveItem: TM_RockTomb, 1]
        └─ Lost → [ShowDialog: "Train harder and come back!"]

Testing Events

1. Enter Play Mode in the editor.
2. Walk your character to the actor.
3. Press the interact button (default: Z or A on gamepad).
4. The CommandGraph will execute and you can observe the flow.

Debug Mode

If a graph is not behaving as expected:

1. Check the Console for errors.
2. Verify that referenced GameVariables, items, and monsters exist.
3. Make sure all output ports are connected -- an unconnected branch will silently end the graph.
4. Use Debug nodes (if available) to log variable states during execution.

Best Practices

1. Name your actors descriptively. "NPC_Professor_Lab" is better than "Actor (3)".
2. Use GameVariables for state. Do not rely on actor enable/disable alone.
3. Test both branches. Every BranchOnVariable should work for both True and False paths.
4. Keep graphs readable. Use spatial layout to make the flow clear. Group related nodes together.
5. Reuse patterns. Once you have a working shop NPC, duplicate and modify it for other shops.
6. Save before testing. CommandGraph changes are scene-level changes that can be lost if Unity crashes.