Event Command Tree

This script converts a list of event commands into a tree representation. The basic usage is to allow developers to debug event-related scripts that modify event trees. Rather than having to write code to print out an event’s command list, simply create an event command tree and print out the tree.

The event tree begins to shine when it comes to managing an event’s commands such as inserting commands, re-arranging command, or removing commands. Because each command is treated as a node in the tree, you can quickly re-arrange the connections without having to figure out how to move commands around.

Functions for converting a list of commands into a tree, and back to a list of commands is provided for easy use.

Download

Script: download here

Description

To understand how the event tree works, you must first understand how events commands work.

The commands that an event must process is stored in a list consisting of “event commands” object. Each event command consists of a code, an indentation, and some parameters. The game interpreter uses this information to determine how to process a command.

For example, suppose we have a simple event with two Show Choice commands that don’t do anything.

This is what the interpreter sees:

102 SHOW_CHOICE "yes, no"
402 WHEN "yes"
0     END
402 WHEN "no"
0     END
404 END_SHOW_CHOICE
102 SHOW_CHOICE "yes 2, no 2"
402 WHEN "yes 1"
0     END
402 WHEN "no 1"
0     END
404 END_SHOW_CHOICE
0   END

You will notice that there are more commands in this list than what you see in the editor: most of the extra commands are simply used for syntax and is created by the editor so that you don’t need to do it yourself. However, that isn’t true when you’re creating commands yourself, so keep this in mind.

The indentation in the event command list is used for branching: this allows us to skip commands that should not be processed such as branches in a Show Choice command or a Conditional Branch command.

We can visualize this list of commands as a binary tree, connected based on their indentation.

The children on the right are commands with the same indent, while children on the left are commands with a higher indent. In order to add commands, we simply need to add nodes to the tree and indent them as needed.

For example, suppose I wanted to loop the above command list. The two commands needed are

112 BEGIN LOOP
413 END LOOP

By connecting our tree as the left child of the loop command, we have modified our event to loop the command list. To update the event list, we simply need to flatten it back into a list of event commands and assign to the event.

Usage

Start by creating an event tree. Assuming we have a list of event commands:

t = EventCommandTree.new(list)

To create a new event command node, you would say

node = RPG::EventCommand.new(code, indent=0, parameters)

Once you have your tree, you can change the tree however you want at this point, using standard tree-based operations such as inserting nodes, removing nodes, re-arranging nodes, etc. but first you need to know how to actually get to each node in the tree.

You immediately have a reference to the root, which is the first command in the event tree

root = t.root

You can then traverse this tree using three methods

root.left - retrieves the left child of this node
root.right - retrieves the right child of this node
root.parent - retrieves the parent of this node

To print out the tree to console, you can call

t.print_tree

When the modifications are finished, you can convert it back to an event list:

list = t.flatten

You can then assign the list to an event’s page list. Note that each command’s indent value is not important: when you flatten the tree they will be updated automatically to reflect the tree structure, so even if you had created new nodes with incorrect indents, that is ok.

The Event Command Tree provides a few convenient methods for working with nodes:

t.indent(node, indent=1)   

   indents the given node, and all children, by the specified
   indent level