sandbox

The sandbox screen is an isolated preview environment for testing individual UI objects without running through the full game flow. It renders a checkerboard background, loads the assets for the active fixture's screen, and displays a panel on the left for navigation and controls.

Controls

Input	Action
ESC	Return to the title screen
SPACE or left-click (viewport)	Trigger the active fixture
R or right-click (viewport)	Reset the active fixture
, / .	Step one frame backward / forward while paused
Mouse wheel (over panel)	Scroll the fixture list or type list

The VARIANT button cycles through secondary states (e.g. toggling "big" on a judgment effect). The PAUSE / PLAY button freezes time so frame-stepping with ,/. works.

Fixture list

All registered fixtures are listed in the left panel, grouped by screen name (e.g. game, title, global). Selecting a fixture loads its screen's assets if they are not already loaded, resets it, and centers the viewport on its anchor texture. The type list below the fixture list (when present) lets you select a sub-variant without using VARIANT cycling.

Debug overlay

The top-right corner shows elapsed time since the last reset in milliseconds, plus any lines returned by the fixture's debug_lines(). The bottom of the viewport shows the fixture's control hint string.

---

Creating a fixture

A fixture is a struct that publicly inherits SandboxScreen::Fixture. The full interface is:

struct Fixture {
    std::string name;
    std::string screen = "game";

    virtual void reset(double ms) = 0;
    virtual void update(double ms) = 0;
    virtual void draw() = 0;
    virtual uint32_t anchor_texture_id() = 0;

    virtual void on_space(double ms) {}
    virtual void on_tab(double ms) {}
    virtual std::vector<std::string> debug_lines() { return {}; }
    virtual std::string controls() { return "SPACE/click: trigger  R/r-click: reset"; }
    virtual std::vector<std::string> type_names() { return {}; }
    virtual int  get_type() { return 0; }
    virtual void set_type(int, double) {}
};

Required members

name — The label shown in the fixture list. Set this in the constructor.

screen — The screen whose assets are loaded when the fixture is selected. Defaults to "game". Set to "global" for objects that use only global_tex assets.

reset(double ms) — Called when the fixture is first selected and when the user presses R or right-clicks. Re-create the object under test here. ms is the current real time in milliseconds.

update(double ms) — Called every frame while not paused. Forward ms to the object's own update() call.

draw() — Called every frame after update(). Draw the object under test here. The viewport is already offset so that the anchor texture is centered in the viewport area; you can draw using the texture's own skin-config coordinates and they will appear centered.

anchor_texture_id() — Returns the TexID enum of the texture whose skin position will be used as the viewport center. Prefer a texture that is the visual center of the object. Return 0 if no centering is needed (e.g. for full-screen or 3D objects).

Optional members

on_space(double ms) — Called when the user presses SPACE or left-clicks inside the viewport. Use this to trigger an animation or create the object for the first time.

on_tab(double ms) — Called when the user clicks the VARIANT button. Use this to cycle through secondary states (e.g. toggling a flag, advancing a variant).

debug_lines() — Returns a list of strings drawn in the top-right of the viewport. Use this to expose internal state.

controls() — Returns a one-line hint string drawn at the bottom of the viewport describing the available inputs.

type_names() / get_type() / set_type(int, double) — Implement these three together to expose a scrollable type list in the panel. type_names() returns the labels; get_type() returns the currently selected index; set_type() applies the selection and typically calls reset().

Example

struct MyObjectFixture : public SandboxScreen::Fixture {
    std::optional<MyObject> active;
    int type_idx = 0;

    MyObjectFixture() { name = "MyObject"; screen = "game"; }

    uint32_t anchor_texture_id() override { return MY_SCREEN::SOME_TEXTURE; }

    void reset(double ms) override { active.emplace(/* constructor args */); }
    void on_space(double ms) override { active->trigger(); }

    void update(double ms) override { if (active) active->update(ms); }
    void draw()            override { if (active) active->draw(0, 0); }

    std::string controls() override {
        return "SPACE/L-CLICK: trigger  R/R-CLICK: reset";
    }
};

Registering a fixture

Add a fixtures.push_back(std::make_unique<MyObjectFixture>()) call in SandboxScreen::on_screen_start() in sandbox.cpp, inside the block for the appropriate screen group.