The Insert menu as a model: settings described once, modules place their own rows, the ImGui menu one presenter #1633

Open
opened 2026-11-18 18:29:30 +00:00 by dyst · 1 comment
Member

Type: refactor · Area: the Insert menu (gpu/vk/vk_menu.cpp), settings, translations · Related: #1493

TL;DR

Every setting, page and one-off widget of the Insert menu lives in one 6,800-line file, and its behaviour is found by pointer and by name all over it, so nearly every feature that adds a row edits that file. This proposes a menu model with no ImGui in it: each setting described once with its own hooks, each module registering its own rows and saying where they go, an order worked out from those wishes, and the ImGui menu as one presenter of the model. The same model could later be shown inside the game's own menu.

Breakdown

  • Who it helps: anyone adding or moving a setting, and later the players, if the menu moves into the game's own menu.
  • What is wrong: behaviour is scattered by row identity; the saved key comes from the label; translation and input are tied to ImGui drawing.
  • What changes: a settings model and a builder; modules place their own rows; the ImGui menu draws the model's snapshot.
  • What does not change: what players see and what longshot_options.ini holds, at every step.
  • How we would prove it: game-free checks that the built menu equals today's, row for row, and that every ini key is unchanged.
  • What is still open: putting the model into the game's own menu (a later piece of work).
  • Risk: medium: many checks read vk_menu.cpp by its text and have to move with it.

Evidence

Read at main c507b98c.

  • One file for everyone. Since 2026-11-10, 116 of 918 commits on main changed vk_menu.cpp, and only about a third were feat(menu) or fix(menu): the rest were features from vk, input and audio that needed a row. Five open PRs add to it now (#1616, #1585, #1629, #1411, #1426), and 89 checks reference it.
  • Behaviour by identity. The rows[] table (about 130 rows) holds a row's tab, label, value, range, text and help. Most of what a row does is decided elsewhere, by about 70 checks of the form r.value == &opts.x and 13 strcmp(r.name, "..."): in row_shown, is_slider, stops_at_ends, the locked rows, the step and apply code, ini_key, and the button rows (NFC, Motion, FPS counter details, the laptop setup, the microphone). One row's behaviour can be in six places.
  • Pretend tabs. Motion, the FPS counter's details and the Controls page's rows are TAB_MOTION, TAB_FPS_DEV and TAB_PAGE, numbered past TAB_COUNT, mapped back to their parent tab by hand.
  • The saved key is the label. ini_key lowercases the row's name unless the row is listed there by hand, so renaming a row renames its setting in longshot_options.ini and loses the player's value.
  • Translation is keyed by the English text and applied in drawing. menu_i18n.h holds 14 languages as {English, translation} pairs; ui::text, ui::para, ui::size_of and ui::spaced look every string up as it is drawn. Editing a row's English drops its translations until every table follows; another presenter would have to call tr() itself.
  • Two maps for the host. The host reads settings by HOS_OPT_* id through t.option in vk_replay.cpp, a chain apart from the rows.

Proposed change

A model with no ImGui or Vulkan in it, which the ImGui menu presents, and which the game's menu could present later.

namespace menu {
enum class Kind { Choice, Toggle, Slider, Action, Page, Heading, Line, Custom };
struct Setting {
    const char* key;            // the ini key, explicit and frozen: renaming the label never moves it
    const char* label;          // a text id, translated by the model
    const char* help = nullptr;
    Kind kind = Kind::Choice;
    int* value = nullptr;
    int lo = 0, hi = 1, step = 1;
    std::vector<const char*> choices;
    int host_option = -1;       // the HOS_OPT_* id, -1 none
    bool restart = false, preset_exempt = false;
    std::function<bool()> shown;                  // the one-off code, beside its setting
    std::function<const char*()> locked;          // why it can't change now
    std::function<const char*(int)> hint;
    std::function<int(int v, int dir)> step_fn;
    std::function<void(int v)> on_change;
    std::function<void()> on_activate;            // Action
};
struct Custom {                 // drawn by its own presenter; others show the fallback
    const char* id;
    std::function<void(Presenter&, Rect)> draw;
    std::function<bool(Input)> input;
    Setting fallback;           // e.g. a Line "In the Insert menu only"
};
}

A module configures itself in its own file and says where its rows go; nothing in the menu's code names it:

MENU_MODULE(input_movie) {
    menu::tab("debug")
        .heading("Input recording", order(800))
        .row({.key = "input_record", .label = "Record input", .kind = Kind::Action,
              .shown = [] { return debug_tools_on(); },
              .on_activate = [] { hos_input_movie_toggle_record(); }})
        .row({.key = "input_snap", .label = "Hold replays to the recording", .kind = Kind::Toggle,
              .value = &snap_on, .on_change = [](int v) { hos_input_movie_set_snap(v); }},
             after("input_record"));
}

Order: collect, then sort. Every module registers at start-up; the menu then works the order out once:

  • Tabs and sections have weights (order(300)); the core's get round numbers with gaps, so a new section lands predictably without naming its neighbours.
  • Inside a group, after(key) and before(key) are edges of a graph, sorted topologically; first() and last() are fixed ends; at(n) is a soft hint.
  • Ties are deterministic (weight, then registration order, then key): the same build always gives the same menu.
  • A central layout file can override a module's wish (place(key, page, after(...))), so a layout decision is made in one place.
  • A missing anchor puts the item at its section's end; a cycle is broken in registration order; both are logged once, and a game-free check fails on them, on duplicate keys and on a changed ini key.

Presenters read a snapshot. menu::snapshot(page) gives the page's items already filtered and translated (label, value text, hint, kind, locked); menu::input(page, index, action) takes Up/Down/Left/Right/Activate/Back. The ImGui menu becomes a loop over it plus the custom items' draw; the game's menu would be another loop over the same call.

Text gets a stable id per string. The first step keeps the English text as the id, so the 7,800 lines of tables do not move; separate ids can come later if wording changes get common.

Steps, each with nothing visible changed and its checks updated in the same PR:

  1. Explicit ini keys for every row, and a check that freezes today's keys.
  2. The model module (types, registration, the sort, the snapshot) beside the menu, the rows registered through it, the menu still drawing as now.
  3. The flag-like special cases (shown, locked, slider, stops at ends) into each setting's hooks, a function at a time.
  4. The step and change special cases into step_fn and on_change; t.option from host_option.
  5. The ImGui menu drawing the snapshot; the pretend tabs become sub-pages.
  6. The custom pages and widgets (the Controls grid, NFC, the debug tools, the microphone test) behind Custom, then features' rows moved into their own modules.

How we would test it

  • Game-free: the menu built through the model equals today's menu, tab by tab and row by row (labels, values, order, shown rows under fixed conditions), at each step.
  • Game-free: every ini key equals today's (a frozen list), and the sort's failure cases are caught.
  • In the game: each step opens the menu on every tab and changes a few rows, with longshot_options.ini compared before and after.
  • #1493 (Renderer rewrite): its Step 1 moves the menu and settings out of the renderer into modules, and its point 6 makes the options struct a config module the menu owns. This is that piece for the menu, and should follow that plan's shape.
  • Open PRs that add to the menu now: #1616, #1585, #1629, #1411, #1426. The steps above are small so they can land between them.

Searched all issues and pull requests, open and closed, for: menu builder, vk_menu split, menu refactor, menu rows, row table, settings registry, menu declarative. None proposes this.

**Type:** refactor · **Area:** the Insert menu (`gpu/vk/vk_menu.cpp`), settings, translations · **Related:** #1493 ## TL;DR Every setting, page and one-off widget of the Insert menu lives in one 6,800-line file, and its behaviour is found by pointer and by name all over it, so nearly every feature that adds a row edits that file. This proposes a menu model with no ImGui in it: each setting described once with its own hooks, each module registering its own rows and saying where they go, an order worked out from those wishes, and the ImGui menu as one presenter of the model. The same model could later be shown inside the game's own menu. ## Breakdown - **Who it helps:** anyone adding or moving a setting, and later the players, if the menu moves into the game's own menu. - **What is wrong:** behaviour is scattered by row identity; the saved key comes from the label; translation and input are tied to ImGui drawing. - **What changes:** a settings model and a builder; modules place their own rows; the ImGui menu draws the model's snapshot. - **What does not change:** what players see and what `longshot_options.ini` holds, at every step. - **How we would prove it:** game-free checks that the built menu equals today's, row for row, and that every ini key is unchanged. - **What is still open:** putting the model into the game's own menu (a later piece of work). - **Risk:** medium: many checks read `vk_menu.cpp` by its text and have to move with it. ## Evidence Read at `main` c507b98c. - **One file for everyone.** Since 2026-11-10, 116 of 918 commits on `main` changed `vk_menu.cpp`, and only about a third were `feat(menu)` or `fix(menu)`: the rest were features from `vk`, `input` and `audio` that needed a row. Five open PRs add to it now (#1616, #1585, #1629, #1411, #1426), and 89 checks reference it. - **Behaviour by identity.** The `rows[]` table (about 130 rows) holds a row's tab, label, value, range, text and help. Most of what a row does is decided elsewhere, by about 70 checks of the form `r.value == &opts.x` and 13 `strcmp(r.name, "...")`: in `row_shown`, `is_slider`, `stops_at_ends`, the locked rows, the step and apply code, `ini_key`, and the button rows (NFC, Motion, FPS counter details, the laptop setup, the microphone). One row's behaviour can be in six places. - **Pretend tabs.** Motion, the FPS counter's details and the Controls page's rows are `TAB_MOTION`, `TAB_FPS_DEV` and `TAB_PAGE`, numbered past `TAB_COUNT`, mapped back to their parent tab by hand. - **The saved key is the label.** `ini_key` lowercases the row's name unless the row is listed there by hand, so renaming a row renames its setting in `longshot_options.ini` and loses the player's value. - **Translation is keyed by the English text and applied in drawing.** `menu_i18n.h` holds 14 languages as `{English, translation}` pairs; `ui::text`, `ui::para`, `ui::size_of` and `ui::spaced` look every string up as it is drawn. Editing a row's English drops its translations until every table follows; another presenter would have to call `tr()` itself. - **Two maps for the host.** The host reads settings by `HOS_OPT_*` id through `t.option` in `vk_replay.cpp`, a chain apart from the rows. ## Proposed change **A model with no ImGui or Vulkan in it**, which the ImGui menu presents, and which the game's menu could present later. ```cpp namespace menu { enum class Kind { Choice, Toggle, Slider, Action, Page, Heading, Line, Custom }; struct Setting { const char* key; // the ini key, explicit and frozen: renaming the label never moves it const char* label; // a text id, translated by the model const char* help = nullptr; Kind kind = Kind::Choice; int* value = nullptr; int lo = 0, hi = 1, step = 1; std::vector<const char*> choices; int host_option = -1; // the HOS_OPT_* id, -1 none bool restart = false, preset_exempt = false; std::function<bool()> shown; // the one-off code, beside its setting std::function<const char*()> locked; // why it can't change now std::function<const char*(int)> hint; std::function<int(int v, int dir)> step_fn; std::function<void(int v)> on_change; std::function<void()> on_activate; // Action }; struct Custom { // drawn by its own presenter; others show the fallback const char* id; std::function<void(Presenter&, Rect)> draw; std::function<bool(Input)> input; Setting fallback; // e.g. a Line "In the Insert menu only" }; } ``` **A module configures itself** in its own file and says where its rows go; nothing in the menu's code names it: ```cpp MENU_MODULE(input_movie) { menu::tab("debug") .heading("Input recording", order(800)) .row({.key = "input_record", .label = "Record input", .kind = Kind::Action, .shown = [] { return debug_tools_on(); }, .on_activate = [] { hos_input_movie_toggle_record(); }}) .row({.key = "input_snap", .label = "Hold replays to the recording", .kind = Kind::Toggle, .value = &snap_on, .on_change = [](int v) { hos_input_movie_set_snap(v); }}, after("input_record")); } ``` **Order: collect, then sort.** Every module registers at start-up; the menu then works the order out once: - Tabs and sections have weights (`order(300)`); the core's get round numbers with gaps, so a new section lands predictably without naming its neighbours. - Inside a group, `after(key)` and `before(key)` are edges of a graph, sorted topologically; `first()` and `last()` are fixed ends; `at(n)` is a soft hint. - Ties are deterministic (weight, then registration order, then key): the same build always gives the same menu. - A central layout file can override a module's wish (`place(key, page, after(...))`), so a layout decision is made in one place. - A missing anchor puts the item at its section's end; a cycle is broken in registration order; both are logged once, and a game-free check fails on them, on duplicate keys and on a changed ini key. **Presenters read a snapshot.** `menu::snapshot(page)` gives the page's items already filtered and translated (label, value text, hint, kind, locked); `menu::input(page, index, action)` takes Up/Down/Left/Right/Activate/Back. The ImGui menu becomes a loop over it plus the custom items' `draw`; the game's menu would be another loop over the same call. **Text** gets a stable id per string. The first step keeps the English text as the id, so the 7,800 lines of tables do not move; separate ids can come later if wording changes get common. **Steps, each with nothing visible changed and its checks updated in the same PR:** 1. Explicit ini keys for every row, and a check that freezes today's keys. 2. The model module (types, registration, the sort, the snapshot) beside the menu, the rows registered through it, the menu still drawing as now. 3. The flag-like special cases (shown, locked, slider, stops at ends) into each setting's hooks, a function at a time. 4. The step and change special cases into `step_fn` and `on_change`; `t.option` from `host_option`. 5. The ImGui menu drawing the snapshot; the pretend tabs become sub-pages. 6. The custom pages and widgets (the Controls grid, NFC, the debug tools, the microphone test) behind `Custom`, then features' rows moved into their own modules. ## How we would test it - Game-free: the menu built through the model equals today's menu, tab by tab and row by row (labels, values, order, shown rows under fixed conditions), at each step. - Game-free: every ini key equals today's (a frozen list), and the sort's failure cases are caught. - In the game: each step opens the menu on every tab and changes a few rows, with `longshot_options.ini` compared before and after. ## Related - #1493 (Renderer rewrite): its Step 1 moves the menu and settings out of the renderer into modules, and its point 6 makes the options struct a config module the menu owns. This is that piece for the menu, and should follow that plan's shape. - Open PRs that add to the menu now: #1616, #1585, #1629, #1411, #1426. The steps above are small so they can land between them. Searched all issues and pull requests, open and closed, for: menu builder, vk_menu split, menu refactor, menu rows, row table, settings registry, menu declarative. None proposes this.
Collaborator

Possibly related, for context:

  • issue #1493 Renderer rewrite — Broader renderer rewrite includes moving menu, settings and translations into modules; this proposes a specific menu model and presenter.
Possibly related, for context: - issue #1493 Renderer rewrite — Broader renderer rewrite includes moving menu, settings and translations into modules; this proposes a specific menu model and presenter.
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot#1633
No description provided.