background

The Background class drives the animated background displayed during gameplay. The visual behaviour is entirely defined by a Lua script selected via the chart's scene_preset field. The C++ class acts as a thin bridge that calls into the Lua object each frame and on gameplay events.

Background

Construction

Background(PlayerNum player_num, float bpm, const string& scene_preset);

Loads the Lua script named by scene_preset, instantiates the Lua object for the given player_num and bpm, and resolves the callable functions listed below. If any function is not defined in the script it is stored as an empty protected_function and calls to it are silently skipped.

Members

Member	Type	Description
lua_object	sol::table	The Lua table instance created by the background script
fn_update	sol::protected_function	Called every frame with current_ms and bpm
fn_handle_good	sol::protected_function	Called when the player hits a GOOD judgment
fn_handle_ok	sol::protected_function	Called when the player hits an OK judgment
fn_handle_bad	sol::protected_function	Called when the player misses (BAD)
fn_handle_drumroll	sol::protected_function	Called on each drumroll hit
fn_handle_balloon	sol::protected_function	Called when a balloon is popped
fn_handle_gauge	sol::protected_function	Called when the gauge value changes
fn_draw_back	sol::protected_function	Draws the background layer (rendered before notes)
fn_draw_fore	sol::protected_function	Draws the foreground layer (rendered after notes)

Methods

void update(double current_ms, float bpm);

Calls fn_update with the current song timestamp and BPM. Should be called once per frame.

void handle_good(PlayerNum player_num);
void handle_ok(PlayerNum player_num);
void handle_bad(PlayerNum player_num);
void handle_drumroll(PlayerNum player_num);
void handle_balloon(PlayerNum player_num);

Each invokes the corresponding Lua callback, passing player_num so scripts that support 2P can react per-player.

void handle_gauge(PlayerNum player_num, float progress, bool is_clear, bool is_rainbow);

Calls fn_handle_gauge with the gauge's normalised progress (0–1) and its current clear/rainbow state.

void draw_back();
void draw_fore();

Invoke the Lua draw functions. draw_back() is called before the note lane is rendered; draw_fore() is called after. game calls both in the correct order.