Creating Timelines

Timelines are special scripts located in "data/timelines" which are executed within levels. They are written in a custom mini-language which can also include Python calls if necessary. Timelines should be used for things like cutscenes and special level events.

Because ReTux is licensed under the GNU GPL and timelines link to ReTux, all timelines legally must be under a GPL-compatible license. Please indicate such a license with a comment or series of comments at the top of the timeline. See the timelines included with ReTux for an example.

Table of Contents

Timeline Syntax

ReTux timelines are standard JSON files connecting moments of time with lists of instructions.

The base of any timeline is an object with "steps" in time from the moment the timeline started as keys, and lists of strings indicating instructions as values. A step is 1/56 of a second.

Each instruction consists of a command followed by an argument, separated by whitespace. The argument may be interpreted as multiple arguments depending on the command; in this case, arguments are separated by whitespace, but the final argument expected includes the entire remaining text. For example, if the "spam" command takes two arguments, the instruction "spam a b c d" will result in the first argument being "a" and the second argument being "b c d". If a command starts with or is a "#" character, the instruction is treated as a comment and not interpreted.

Commands

The following commands are available for use in timelines:

• "setattr": Sets an attribute of an object. Takes three arguments: the first argument indicates the unique ID of the object, the second argument indicates the attribute to set, and the third argument indicates the value to set the attribute to (evaluated as a Python expression). The first argumnent can also be given as "__level__" to set an attribute of the current level.
• "call": Calls a method of an object. Takes two arguments: the first argument indicates the unique ID of the object, and the second argument indicates the method to call. The first argumnent can also be given as "__level__" to call a method of the current level.
• "dialog": Shows a dialog box to the player. Takes two arguments: the first argument indicates the character portrait to use, and the second argument indicates the text to show. The name of any image found in data/images/portraits minus the extension (e.g. "tux" for tux.png) can be specified as a portrait. Any other value will result in no portrait being used. To deliberately use no portrait, you should specify the first argument as "_".
• "play_music": Changes the currently playing music to the file specified by the argument (located in "data/music"). Set the argument to "_" for no music.
• "timeline": the timeline file specified by the argument (located in "data/timelines"), immediately ending the currently active timeline.
• "skip_to": Skips all remaining instructions in the current step and skips to the step indicated by the argument. Note: this can only go forwards.
• "exec": Executes the argument as Python code.
• "if": Evaluates the argument as a Python expression. If the result is false, skips all remaining instructions in the current step.
• "if_watched": If the currently active timeline has not been watched before, skips all remaining instructions in the current step.
• "if_not_watched": If the currently active timeline has been watched before, skips all remaining instructions in the current step.
• "while": Evaluates the argument as a Python expression. If the result is true, this instruction and all remaining instructions are duplicated for execution next step, and all future steps are shifted one step later. Otherwise, skips all remaining instructions in the current step. Effectively, this causes the affected instructions to repeat every step until the condition is satisfied.