Scene Loading and Save/Load System

This document describes how LBA2 loads scenes (cubes), how the save/load system works, and what data is persisted. Understanding this flow is important for modders who want to hook into scene transitions or need to understand what state survives a save/load cycle.

Scene Loading Flow (ChangeCube)

In OBJECT.cpp, the ChangeCube method is the single entry point for all scene transitions:

• New game start — loading cube 0
• Loading a saved game — restoring a previously saved scene
• Moving between scenes — transitioning during gameplay

Step-by-step flow

1. Basic hero resets — Some hero object parameters are reset.

2. LoadScene — Reads all scene objects and zones from the HQR file.

   • At this point, the IdaJS onAfterLoaded hook fires, allowing mods to modify objects as if they were part of the HQR data.

3. Set start position (skipped when loading a save):

   • If FlagChgCube is 0 (new game) or 2 (teleport): SceneStart is set to CubeStart.
   • If FlagChgCube is 1 (scene-to-scene movement): SceneStart is set to NewPos, determined by the transposition zone between scenes.
   • If FlagChgCube is 3: Hero position is not overwritten (usage unknown).

4. Object initialization (skipped when loading a save):

   • Sprites, animations, initial velocities, etc., are initialized.
   • Changing initial animation or body at this stage would require re-initialization, so no IdaJS hooks should be added here.

5. Load game branch — If this is a save-load, LoadContexte is called instead, which overwrites most object states from the save file (see below).

Save/Load Data (LoadContexte)

The LoadContexte function in SAVEGAME.cpp restores the following data from a save file:

Global state

The next 2 sections are conditional based on whether it's a death restore or a full load.

Death restore vs full load

When restoring after death (clover box used), only a subset is restored:

• Hero start position
• Camera position
• Hero body (read from the last Cube variable — this variable must not be modified by the mod engine)
• flagInit is set to true — view objects and scene parameters are not re-initialized

Full save load — scene state

For a real save load, the following additional scene data is restored:

Patches

Patches are parts of the Life and Track scripts that can be modified at runtime and must be persisted across saves. They are represented as an array of offsets and byte sizes baked into the HQR file, generated by the editor at compile time.

Some bytecode commands overwrite themselves and their arguments during execution to persist intermediate state (e.g., timer values). Patches capture those mutations so they survive save/load.

Track commands with patches: TM_ANGLE, TM_ANGLE_RND, TM_WAIT_NB_*, TM_FACE_TWINSEN, TM_LOOP

Life commands with patches: if-trigger operations — SWIF, SNIF, ONEIF

Other persisted data

After all parameters are loaded, rain is re-initialized if needed. If rain is modified from a script, it must be re-initialized as well.

The function returns flagInit == false, meaning a full game load was performed and all view objects need initialization.

Game Variables and Inventory

Some game variables are reserved for inventory and built-in properties. These are defined in COMMON.H (line 244+) and their names start with FLAG_.

All vanilla inventory is managed through game variables — to add or remove vanilla items, set the corresponding FLAG_ variable. Supporting additional custom inventory items requires a custom IdaJS hook.

Restrictions

Other special variables may also need restrictions — check how they are used in the engine code before modifying them.