MTropolis/Debugging

This page describes the process for debugging mTropolis titles.

Reading MTropolis/Adding_Games is recommended for getting games to boot. There currently is no generic boot process.

mTropolis paradigm basics

mTropolis is a relatively simple authoring system that builds more complex behaviors out of simpler parts. A mTropolis project is a tree structure consisting of structural components and modifiers. Modifiers usually affect the structural component that they are applied to, but modifiers are also used for variables and for some types of behavior that don't affect the structural component (such as saving and restoring the game).

The parent of a modifier is always either a structural component, a compound variable modifier (which contains only variables), or a behavior modifier (which is a container of other modifiers).

Modifiers may also be aliased: There is a global modifier template list which can be used by an alias in the scene structure, which is replaced with a copy from the modifier template list when the scene is loaded.

Types of structural components

Project: Container of sections, this is always the topmost structural component and there is exactly one per project.
Section: Container of subsections. Each section is contained entirely in one segment (data file), so disc swaps always transfer out of a section.
Subsection: Container of scenes. Typically subsections are used in situations where changing the active shared scene is desired. Note that there is NOT a scene structural component type, scenes are just elements.
Graphic element: A simple vector graphic element (usually just a rectangle).
Movie element: A QuickTime or AVI movie.
mToon element: An animation object using mTropolis's internal flipbook animation format.
Image element: A still image.
Sound element: A sound.
Text label element: A text label, which may be pre-rendered or rendered at runtime.

Messages

Most actions in mTropolis happen via messages. A message always has a type and subtype. So far, the subtype appears to be 0 for all built-in message types and is only used for author-created message types, which always have the type ID 900.

When a message is dispatched, it always has a source, a target, possibly a single-value data payload, and propagation flags. There are 3 important propagation flags:

Immediate: The message is sent and propagated before any other actions. (If this is not set, the message is placed in the message queue and dispatched later).
Cascade: The message is sent to the target's structural children.
Relay: The message continues propagating after a modifier consumes to it. (Otherwise, propagation stops at the first modifier to consume it.)

Labels

The boot stream also contains a label map, which is used for defining several things:

Author messages (custom event types)
mToon frame range names
Sound markers (which can be used with media cue modifiers to fire events at certain points during a sound's playback)

Using the debugger dashboard

To use the debug dashboard, go to the game options and select "Start with debugger"

This adds a debug overlay to the game with 3 buttons:

The first button is the scene tree viewer, which shows the complete project hierarchy as it's currently loaded. Clicking the "Go To" button next to an active scene at the top will scroll to that scene in the debug view.
The second button is the inspector, which shows various properties of selected objects in the scene view.

Using MTDisasm project disassembler

You can use the MTDisasm tool to disassemble a mTropolis project, decompile its script bytecode to readable form, and extract its assets. See: [MTDisasm on GitHub]

How to diagnose a bug?

Many bugs are script failures, which will be reported via a toast notification when using the debug dashboard. You can then track down what's causing the error. However, please note that script errors are non-fatal and it's very common for script errors to exist in the actual game, so not all reported script errors are fixable issues.

The overwhelming majority of bugs that aren't script errors are bugs where something that is supposed to happen doesn't trigger. When this happens, start the game with debug level 3 or higher ("-d 3" on the command line) to enable message logging in the console. Try to determine what element or modifier is responsible for the behavior that you're expecting and try to figure out the chain of events that's supposed to cause it to happen, then compare that to the message log and see what's missing. Typically this means identifying what event type causes it to happen and searching the disassembly for what's supposed to send it, and so on.

Some bugs are also due to incorrect cascade/relay flags on built-in messages. What messages are supposed to be sent with which flags varies, so it's an easy thing to get wrong.

How to determine the meaning of data in plug-ins?

Plug-ins in project data nearly always contain just a sequence of PlugInTypeTaggedValue in their data section, so you can use that to determine what data it contains and what type. Most modifiers will have at least an "enable" event that activates the modifier, followed by other things.