Scripting - Commands

Scripts are json files in the data/scripts/ folder. They drive cutscenes (dialog, camera, characters walking around) and simple in-game events (for example granting a new ability) without changing any code.

The commands are created by the game's ScriptLoader. Lisa Engine provides the generic commands; this page documents the command set of the CoolFox CoolFoxScriptLoader, where say and add_player_ability are CoolFox-specific.

Running a script

Scripts are started by an Action object placed on the Objects layer of a level. When the player overlaps the object, the script runs. The object properties:

Property	Type	Default	Description
path	string		Path of the script, for example data/scripts/cutscenes/level1_intro.json.
cutscene	bool	false	true: runs as a cutscene (dialog, Skip button). false: runs in the background in-game.
once	bool	true	true: runs only once. false: runs again every time the player re-enters the area.

Script structure

The root of a script is always a sequence. Every command is an object with exactly one key, the command name, and its value holds the command properties:

{"sequence": [
    {"move_camera_to": {"target": "barman"}},
    {"say": {"name": "barman", "text": "What's ya flavor,\nmy man?"}},
    {"move_camera_to": {"target": "player"}}
]}

Commands that refer to an entity or a target use the name of an object in the level (set in Tiled). The player can be referred to as player.

Skipping

A cutscene can be skipped with the Skip button. When skipped, waiting commands (delay, walk_to, say) finish immediately, the camera jumps instead of moving, and set_movement_active moves its entity to the end of its path (see finish_on_skip).

Flow commands

sequence

Runs the listed commands one after another. Each command starts when the previous one has finished.

{"sequence": [
    {"delay": {"duration": 1}},
    {"play_music": {"name": "boss_battle"}}
]}

parallel

Runs the listed commands at the same time. Finishes when all of them have finished.

{"parallel": [
    {"walk_to": {"entity": "ufo", "target": "t2"}},
    {"sequence": [
        {"delay": {"duration": 2.6}},
        {"play_music": {"name": "boss_battle"}}
    ]}
]}

delay

Waits for the given time.

Property	Type	Default	Description
duration	float		Wait time in seconds.

{"delay": {"duration": 0.3}}

Dialog

say

Shows a character portrait with a text bubble, and waits until the text has been shown.

Property	Type	Default	Description
name	string	coolfox	The character, the name of the portrait texture.
text	string		The text, at most 3 lines. Use \n for a line break.
left	bool	false	true: the character appears on the left side of the screen, otherwise on the right.
continue	bool	false	true: the character stays on screen, so the next say of the same character continues without sliding in again.

By default every say slides the character in and out. When a character says more than one bubble in a row, set continue on every bubble except the last one:

{"say": {"name": "coolfox", "text": "I'd like to have a...", "left": true, "continue": true}},
{"say": {"name": "coolfox", "text": "What the...", "left": true}}

Use continue only when the next say is the same character. If a different character comes next, the previous portrait is replaced without sliding out.

Camera

move_camera_to

Moves the camera smoothly to an entity, then keeps following it. The command does not wait for the camera to arrive, the next command starts right away. Add a delay after it if you need to wait.

Property	Type	Default	Description
target	string		Name of the entity.
speed	float	256	Camera speed in pixels per second.

{"move_camera_to": {"target": "t2", "speed": 512}}

set_camera_target

Sets the entity the camera follows.

Property	Type	Default	Description
target	string		Name of the entity.
smooth	bool	false	true: the camera transitions smoothly to the new target.

set_camera_limit

Applies the camera limits of a Camera limit trigger object.

Property	Type	Default	Description
entity	string		Name of the Camera limit trigger object.

Entities

walk_to

Walks an entity horizontally to a target with the player's running speed, and waits until it arrives. On arrival the entity is placed exactly on the target (center X, bottom).

Property	Type	Default	Description
entity	string		Name of the walking entity.
target	string		Name of the target entity.

{"walk_to": {"entity": "player", "target": "t1"}}

set_animation

Changes the animation of an entity.

Property	Type	Default	Description
entity	string		Name of the entity.
animation	string		Name of the sprite animation (from resources.json).
layer	int	0	The view layer of the animation.
flip_x	bool		Flip horizontally. Unchanged if not set.
flip_y	bool		Flip vertically. Unchanged if not set.
time	float		Start the animation from this time (seconds).

set_visible

Shows or hides an entity.

Property	Type	Default	Description
entity	string		Name of the entity.
visible	bool		Visible or hidden.

set_parent

Attaches an entity to another, so it moves together with the parent.

Property	Type	Default	Description
entity	string		Name of the child entity.
parent	string		Name of the parent.

{"set_parent": {"entity": "mrs_coolfox", "parent": "ufo"}}

set_movement_active

Starts or stops the path movement of a movable entity (an entity that moves along a path). It also activates the entity.

Property	Type	Default	Description
entity	string		Name of the movable entity.
active	bool		Start or stop the movement.
finish_on_skip	bool	true	When the cutscene is skipped, place the entity at the end of its path and stop it.
finish_index	int	-1	The path point used as the end when skipping. -1 means the last point.

{"set_movement_active": {"entity": "ufo", "active": true, "finish_on_skip": false}}

trigger

Switches on a switchable entity, the same way a switch or a button would.

Property	Type	Default	Description
name	string		Name of the switchable entity.

{"trigger": {"name": "ufo"}}

Game

play_music

Starts playing a music.

Property	Type	Default	Description
name	string		Name of the music (from resources.json).

add_player_ability

Gives an ability to the player and refreshes the HUD.

Property	Type	Default	Description
ability	string	move	One of: move, jump, double_jump, punch, fire_punch.

{"sequence": [
    {"add_player_ability": {"ability": "double_jump"}}
]}