Branch overview

Contents

• Branch lifecycle
  • Creating a branch
  • Executing a branch
  • Destroying a branch
  • Why do you need to destroy a branch?

---

The TbyBranch is the most important structure in textboxy. It takes a series of commands and executes them in order. The commands can range from displaying text to changing options, evaluating a condition or setting variables.

Branch lifecycle

Creating a branch

To create a branch, use the tby_branch_create() script. It will return the branch, so you need to save it in a variable.
The script takes an array with TbyCmd types as an argument.

Example

var _branch = tby_branch_create([/* ... commands ... */]);

Executing a branch

To run a branch, use the tby_branch_run() script. It takes two arguments - the branch reference and an optional boolean value defining if it should be destroyed upon finishing (Default is false).

Example

// With the  _branch variable from above
// (1)
tby_branch_run(_branch);

// (2)
tby_branch_run(_branch, true); // Destroy the branch automatically

Destroying a branch

If you do not specify that a branch should be destroyed upon finishing, you need to manage how the branch is destroyed yourself. You use the tby_branch_destroy() script for that. It takes the branch reference as an argument.

Example

// With the  _branch variable from above
tby_branch_destroy(_branch);

Why do you need to destroy a branch?

Creating a branch also creates some associated data structures along with it (e.g. ds_map and ds_list types). To prevent memory leaks, it is important that these data structures are destroyed after they are no longer needed.

When to destroy

If the branch you are creating is shown only a single time (e.g. in a cutscene), you can take advantage of the optional argument the tby_branch_run() script offers and destroy the branch automatically after it is finished.
If, however, the branch is shown mutiple times (e.g. NPC dialogue), the branch should be destroyed manually. For example, an NPC could destroy its own branch in the Clean Up or Room End events.

^{See issue #30 for discussion about memory management.}

Example

This is an example NPC obj_npc.

// CREATE event
branch = tby_branch_create([/* ... commands ... */]);
----------------
// STEP event
if (/* player is talking to this npc */) {
	tby_branch_run(branch);
}
----------------
// ROOM END event
tby_branch_destroy(branch);