Stark/TLJ Debugging

Getting started

The resource tree

A level is a place in the game. It can have several viewing angles called locations.

TLJ's game resources are organized in a tree structure. The root contains all the levels in the game. Each level contains the locations that are specific to that level. Each location contains items for that location, ect ...

Each resource (tree node) has at least the following properties: - A type - A sub-type (which meaning is type-specific) - A name - An index (its order in the list of the node's parent children -- Often used to locate resources in the resource tree)

Being tree nodes they additionally have a parent resource and a list of children resources.

Each node can have more type-specific properties.

There is a C++ class for each resource type. The engine instanciates a class with the appropriate type when it loads a resource-subtree. These classes are used to store the type-specific properties, to store the resource state, and define the associated behaviors.

Resource references

Game resources are referenced by other resources by their address in the resource tree. Addresses are made of a list of pairs (Type, Index). The list contains all of the ancestors of the target resource as well as the resource itself. The designated resource can thus be retrieved in the tree by walking it down, consuming a list element in the address for each tree level.

Example reference for an item : (Level, 10) (Location, 0) (Item, 5)

This designates the Item with index 5 in the location with index 0 in the Level with index 10 in the tree root.

Game events

The engine calls event handlers for currently loaded resources on some occasions:

• Once per gameloop
• When the player enters the location the resource is in
• When saving the state
• ...

The resource classes must implement these event handlers in order to provide features to the game.

Debugging

Most debugging features are accessed through ScummVM's console. Some of the notable commands are :

• listLocations: Lists all the locations in the game
• location: Display the current location
• changeLocation: Jump to another location
• chapter: Display the current chapter -- Some scripts are conditionned by this value
• changeChapter: Set the current chapter
• dumpLevel: Print the current level's resource sub-tree to stdout
• dumpLocation: Print the current location's resource sub-tree to stdout
• dumpGlobal: Print the global level's resource sub-tree to stdout
• dumpStatic: Print the static level's resource sub-tree to stdout

The dump* commands are especially useful when trying to correlate the game data to behaviors.

Scripts

Scripts are resources in the resource tree, just like everything else. They are made of a list of command resources. Each command has a subtype designating an operation code in the game engine, as well as a list of parameters for that operation.

The script execution flow depends on the current opcode 'kind':

• After executing a 'standard' opcode, the script execution continues to the command which index in the script is the value of the current command's first argument.
• After executing a 'branch' opcode, the script execution continues to the command corresponding to either the first or the second argument value.
• After executing a 'suspending' opcode, the script execution is paused until a suspending resource has completed playing (such as a sound resource)