Animations

Animations

Animations are defined in animation.json inside a screen folder (e.g. Graphics/background/animation.json). The file is a JSON array where every entry has a unique numeric id that Lua scripts and C++ reference at runtime.

Common Fields

Field	Type	Description
id	integer	Unique identifier used by Lua to retrieve this animation
type	string	Animation type (see below)
duration	number	Duration in milliseconds
loop	boolean	Whether the animation loops (default false)
delay	number or object	Delay in ms before starting, or a reference to another animation's property
reverse_delay	number	Delay before the animation reverses (use 0 for instant reverse)
ease_in	string	Easing function applied at the start ("quadratic", "cubic")
ease_out	string	Easing function applied at the end ("quadratic", "cubic")
comment	string	Human-readable note; ignored by the engine

Animation Types

move

Moves an element along one axis.

Field	Type	Description
total_distance	integer	Pixels to move (negative = move left/up)
start_position	integer	Starting offset in pixels (default 0)

{
    "id": 0,
    "type": "move",
    "duration": 3000,
    "total_distance": -328,
    "loop": true
}

fade

Changes the opacity of an element.

Field	Type	Description
initial_opacity	number	Starting opacity (0.0–1.0)
final_opacity	number	Ending opacity (0.0–1.0)

{
    "id": 1,
    "type": "fade",
    "duration": 150,
    "initial_opacity": 0.0,
    "final_opacity": 1.0
}

texture_change

Swaps between frames of an animated texture on a timeline.

Field	Type	Description
textures	array	Array of [start_ms, end_ms, frame_index] keyframes

{
    "id": 13,
    "type": "texture_change",
    "duration": 600,
    "textures": [
        [0,   100, 0],
        [100, 200, 1],
        [200, 300, 2]
    ],
    "loop": true
}

text_stretch

Stretches text over the animation duration. No additional fields beyond the common ones.

texture_resize

Scales a texture between two sizes.

Field	Type	Description
initial_size	number	Starting scale factor (default 1.0)
final_size	number	Ending scale factor (default 0.0)

Delay References

A delay can reference the duration of another animation so animations chain without hard-coding numbers:

{
    "id": 5,
    "type": "move",
    "duration": 266,
    "total_distance": -40,
    "delay": {
        "reference_id": 4,
        "property": "duration"
    }
}

Delays can also nest to chain multiple animations:

"delay": {
    "init_val": {
        "reference_id": 4,
        "property": "duration"
    },
    "reference_id": 5,
    "property": "duration"
}

This resolves to anim[4].duration + anim[5].duration.