mxbmrp3

MXBMRP3 Architecture Guide

This document explains how the MXBMRP3 plugin works, from the ground up. It’s designed to help new contributors understand the codebase quickly.

What Is This Project?

MXBMRP3 is a HUD (Heads-Up Display) plugin for PiBoSo racing simulators (MX Bikes, GP Bikes, WRS, KRP). The plugin displays real-time racing information on screen: lap times, standings, speedometer, track map, and more.

The plugin is a Windows DLL (with .dlo extension) that each game loads at startup. The game calls our exported functions to send us data and request rendering instructions. A multi-game translation layer allows the same core code to work across all supported games.

Project Structure

mxbmrp3/
├── mxbmrp3/                    # Main plugin source code
│   ├── vendor/piboso/          # Game API definitions and exports
│   │   ├── mxb_api.h/.cpp      # MX Bikes API header and DLL exports
│   │   ├── gpb_api.h/.cpp      # GP Bikes API header and DLL exports
│   │   ├── krp_api.h/.cpp      # Kart Racing Pro API header and DLL exports
│   │   └── wrs_api.h           # WRS API header (stubbed)
│   ├── game/                   # Multi-game abstraction layer
│   │   ├── unified_types.h     # Game-agnostic data structures
│   │   ├── game_config.h       # Compile-time game selection
│   │   └── adapters/           # Per-game type converters
│   │       ├── mxbikes_adapter.h
│   │       ├── gpbikes_adapter.h
│   │       └── ...
│   ├── core/                   # Core infrastructure: the singletons (plugin_manager,
│   │                           #   plugin_data, hud_manager, settings_*, http_server,
│   │                           #   stats_manager, fmx_manager, companion_window,
│   │                           #   crash_handler, ...) plus plugin_constants.h and
│   │                           #   plugin_utils.*. Each file's header states its job.
│   ├── handlers/               # Event processors (one per API callback type)
│   │   ├── draw_handler.*      # Frame rendering and FPS tracking
│   │   ├── event_handler.*     # Event lifecycle (init/deinit)
│   │   ├── run_*_handler.*     # Player-only events
│   │   └── race_*_handler.*    # Multiplayer race events
│   ├── hud/                    # Display components
│   │   ├── base_hud.*          # Abstract base class for all HUDs
│   │   ├── *_hud.*             # Full HUDs (complex, configurable)
│   │   ├── *_widget.*          # Simple widgets (focused display)
│   │   ├── settings_hud.*      # Main SettingsHud (menu build / _input / _render) - in hud/, matches *_hud.*
│   │   └── settings/           # Settings UI helpers (NOT settings_hud.*)
│   │       ├── settings_layout.*   # Layout helper context
│   │       └── settings_tab_*.cpp  # Individual tab renderers
│   └── diagnostics/            # Debugging tools
│       ├── logger.*            # Debug logging to file
│       └── timer.h             # Performance measurement
├── mxbmrp3_data/               # Runtime assets and packs, discovered by AssetManager;
│                               #   web/ is the overlay HttpServer serves
├── tests/                      # All automated tests; layout and layers in TESTING.md
├── tools/                      # Dev tools, each documented in its own header/README
├── assets/                     # Source art (helmet .pdn, icon .svg)
├── crash_analysis/             # Crash catalogue (known_game_crashes.json + docs)
└── CMakeLists.txt              # Gates + the plugin definition (mxbmrp3/CMakeLists.txt);
                                #   generates build/msvc/mxbmrp3.sln for Visual Studio

The Big Picture

Here’s how data flows through the plugin:

┌─────────────────────────────────────────────────────────────────────────┐
│                    GAME ENGINE (MX Bikes / GP Bikes / etc.)             │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │   mxb_api.cpp / gpb_api.cpp   │
                    │   (Per-Game DLL Exports)      │
                    │                               │
                    │  Startup(), Draw(), RunLap(), │
                    │  RaceEvent(), etc.            │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │      Game Adapters            │
                    │   (mxbikes_adapter.h, etc.)   │
                    │                               │
                    │  Convert game structs to      │
                    │  Unified:: types              │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │      PluginManager            │
                    │   (Main Coordinator)          │
                    │                               │
                    │  Receives Unified:: types,    │
                    │  routes to handlers           │
                    └───────────────────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              ▼                     ▼                     ▼
     ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
     │    Handlers     │   │   DrawHandler   │   │  InputManager   │
     │                 │   │                 │   │                 │
     │ Process events, │   │ Triggers HUD    │   │ Tracks mouse,   │
     │ update data     │   │ render cycle    │   │ keyboard state  │
     └─────────────────┘   └─────────────────┘   └─────────────────┘
              │                     │
              ▼                     │
     ┌─────────────────┐            │
     │   PluginData    │◄───────────┘
     │  (State Cache)  │
     │                 │
     │ Stores all game │
     │ state, notifies │
     │ on changes      │
     └─────────────────┘
              │
              │ notifies
              ├──────────────────────────┐
              ▼                          ▼
     ┌─────────────────┐       ┌─────────────────┐
     │   HudManager    │       │   HttpServer    │
     │                 │       │                 │
     │ Owns all HUDs,  │       │ Builds JSON on  │
     │ marks dirty,    │       │ game thread,    │
     │ collects output │       │ streams via SSE │
     └─────────────────┘       └─────────────────┘
              │                          │
              ▼                          ▼
     ┌─────────────────┐       ┌─────────────────┐
     │      HUDs       │       │  Web Overlay    │
     │                 │       │  (Browser/OBS)  │
     │ Build quads &   │       │                 │
     │ strings for     │       │ Standings tower │
     │ rendering       │       │ Event log       │
     └─────────────────┘       │ Focus card      │
              │                └─────────────────┘
              │ returns render data
              ├──────────────────────────┐
              │                          ▼ (2nd frame, if enabled)
              │                 ┌─────────────────┐
              │                 │ CompanionWindow │
              │                 │ + sw renderer   │
              │                 │                 │
              │                 │ Draws the same  │
              │                 │ quads/strings   │
              │                 │ in its own OS   │
              │                 │ window (2nd mon)│
              │                 └─────────────────┘
              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    GAME ENGINE (MX Bikes / GP Bikes / etc.)             │
│                          (Renders our output)                           │
└─────────────────────────────────────────────────────────────────────────┘

The CompanionWindow is an optional second render target: HudManager builds a second frame with collectSurface(companion) and submits it to a standalone OS window (drag it to a second monitor). It draws the same primitives with an in-process renderer (D3D11, else hud_sw_renderer) instead of the game engine. See Core Components §13; the in-game HUD can be drawn by the plugin too, in the game’s own GL context (§13a).

Core Components

1. The Plugin API (vendor/piboso/*_api.*)

Each PiBoSo game defines a C API that plugins must implement. The APIs are nearly identical, with game-specific struct variations. Each game has its own API file:

Key exported functions (same across all games):

Function When Called Purpose
Startup() Game starts Initialize plugin, return telemetry rate
Shutdown() Game closes Clean up resources
EventInit() Track loaded Receive track/vehicle info
RunInit() Player goes on track Session begins
RunTelemetry() Every physics tick Receive vehicle telemetry (100Hz)
RunLap() Lap completed Receive lap time
Draw() Every frame Return quads/strings to render
RaceEvent() Online race starts Receive race info
RaceClassification() Continuously Receive standings updates

The API uses C structs to pass data. Each game’s structs have different field names and contents:

The adapter layer (game/adapters/*.h) converts these game-specific structs to unified types (Unified::TelemetryData, Unified::VehicleEventData, etc.) that the core plugin uses.

Exception barrier (vendor/piboso/api_guard.h): Every DLL export wraps its body in API_GUARD_CATCH("ExportName"). The host game doesn’t support C++ exceptions across the DLL boundary, so any uncaught throw from PluginManager downward would terminate the host process. The macro catches std::exception and ... at the boundary, logs via DEBUG_WARN_F, and returns a sensible fallback value. When adding a new export, follow the same pattern.

Boundary validation (version skew): PiBoSo has reshaped plugin structs between game versions before - the EventInit/RaceCommunication defensive copies exist for exactly that - so the array-style callbacks don’t trust the game’s framing. RaceClassification/RaceTrackPosition/SpectateVehicles reject a mismatch between the game-supplied _iElemSize and the compiled sizeof (warn-once, then return - the feature fails safe instead of indexing with the wrong stride, which misreads every entry past index 0 and runs off the real array), null-check _pData/_pArray when counts are positive, guard the defensive-copy memcpy against a null _pData, and std::clamp entry counts to 0..MAX_RACE_ENTRIES (clamping negatives too, not just capping from above). Applied identically across MXB/GPB/KRP. The symptom of skew is empty standings/map plus a single “element size N != expected M” log line. New array-style callbacks must follow the same pattern.

2. PluginManager (core/plugin_manager.*)

The central coordinator. It:

Note: PluginManager is game-agnostic - it never sees raw game API structs, only Unified::* types.

// Example: mxb_api.cpp converts and forwards to PluginManager:
// In mxb_api.cpp:
void RunLap(void* _pData, int _iDataSize) {
    auto* gameData = static_cast<SPluginsBikeLap_t*>(_pData);
    auto unified = Adapter::toPlayerLap(gameData);  // Convert to unified type
    PluginManager::getInstance().handleRunLap(&unified);
}

// PluginManager receives unified type:
void PluginManager::handleRunLap(Unified::PlayerLapData* psLapData) {
    Handlers::handleRunLap(psLapData);
}

3. PluginData (core/plugin_data.*)

The single source of truth for all game state. This singleton:

What came out of it, and what deliberately did not. It is a large class and the standing direction is to shrink it, but only where a piece is genuinely separable rather than merely movable. The bar each of these cleared: its inputs are a handful of numbers per rider, so it can be unit-tested with a plain g++ instead of only through the DLL under Wine. Each header states its own rules and the trap it exists to avoid; this is the index, not a second copy.

Extracted What it is Unit test
core/blue_flag_detect.h blue-flag/lapping pairwise proximity pass test_blue_flag_detect.cpp
core/proximity_tuning.h the seven INI-only blue-flag/hazard knobs, each clamp beside its field -
core/battle_groups.h battle-group partitioning, shared by the director and the overlay panel test_battle_groups.cpp
core/lap_timer.h the display rider’s live lap-timer state machine test_lap_timer.cpp
core/live_gap_engine.h the live leader-relative gap core test_live_gap_engine.cpp

PluginData keeps the flattening, the caches, the eligibility filtering and the notification coalescing around each of them. The hazard state machine stays put on purpose: its per-rider state lives inside RiderTrackState and is updated inline in the 30 Hz position loop, so extracting it would add a hash lookup per rider per batch and produce a component that reached back into PluginData for everything.

Key data structures:

Per-rider containers are declared PerRider<>, which registers their erase-and-clear so a reused race number cannot inherit a departed rider’s state. It is enforced by construction in plugin_data.h and pinned by racenum_reuse_test.cpp; the rule and the one exception (derived caches, which are dirtied instead) are in CLAUDE.md’s Maintenance Invariants.

// Example: Handler stores data, HUD reads it
// In handler:
PluginData::getInstance().updateSpeedometer(speed, gear, rpm, fuel);

// In HUD:
const BikeTelemetryData& data = PluginData::getInstance().getBikeTelemetry();
int speedMph = data.speedometer * MS_TO_MPH;

4. HudManager (core/hud_manager.*)

Owns and orchestrates all HUD instances. It:

5. Handlers (handlers/*)

Each handler processes a specific category of game events.

Almost all of them are stateless dispatch - they read the unified event struct, push it into PluginData, and return. Those are plain free functions in namespace Handlers (one translation unit per callback category), because a singleton around a class with no members buys nothing and costs a global: Handlers::handleRaceLap(psRaceLap), not RaceLapHandler::getInstance().handleRaceLap(...). The two handlers that genuinely carry state across callbacks (DrawHandler, SpectateHandler) remain singleton classes, and DEFINE_HANDLER_SINGLETON exists for exactly those two.

Run handlers (player-only, single-player or your own bike):

Race handlers (all riders in online races):

Other:

6. ProfileManager (core/profile_manager.*)

Manages HUD layout profiles for different game contexts:

Features:

7. Rumble: RumbleProfileManager + XInputReader (core/rumble_profile_manager.*, core/xinput_reader.*)

RumbleProfileManager keeps per-bike rumble profiles in {save_path}/mxbmrp3/mxbmrp3_rumble_profiles.json, keyed by bike name, each holding a complete RumbleConfig. A toggle chooses between the global INI settings and per-bike profiles; enabling it auto-creates a profile for the current bike. XInputReader reads the active config at runtime.

XInputReader runs its OS calls on a dedicated I/O thread, and that split is the part worth knowing at this level because it is the same rule three subsystems follow. Every XInputGetState/XInputSetState happens on ioThreadMain - started in PluginManager::initialize, stopped in shutdown after the plugin worker is joined - so a degraded controller driver can never stall whichever thread drives telemetry and hotkeys (the game thread in legacy mode, the plugin worker in threaded mode). Same state producer vs. blocking I/O division as HttpServer and DiscordManager: the caller keeps all policy and effect math, because that feeds RumbleHud’s graph and must stay on the state thread; only the syscalls move. update() became a cheap copy of the snapshot the I/O thread published, setVibration() runs its unchanged policy and posts an 8-bit motor pair for the I/O thread to execute, and setControllerIndex() sets an atomic slot plus a poll-now flag.

Two hardware constraints shape the tuning, and both are documented where they are enforced - the empty-slot backoff inside ioThreadMain(), the send policy at setVibration(), with the reasoning inline at each. In outline: XInputGetState on a disconnected slot triggers device enumeration and can cost milliseconds, so scans are throttled; and controllers decay rumble without a continuous feed while some Bluetooth stacks choke on a sustained one, so nonzero values are re-sent on a user-tunable cap rather than deduped. The reasons are opposing and unobvious, which is exactly why they live next to the code that obeys them rather than in a second copy here. Pinned by xinput_thread_test.cpp and rumble_effect_test.cpp; CLAUDE.md carries the one-line “don’t simplify this” warning.

8. StatsManager (core/stats_manager.*)

Unified stats system that tracks per-track/bike stats, global race stats, personal bests, and odometer data in a single JSON file ({save_path}/mxbmrp3/mxbmrp3_stats.json).

Per track+bike stats (TrackBikeStats):

Personal bests (StatsPersonalBestData):

Global stats (GlobalStats):

Per-bike odometers:

Session transients (not persisted):

Features:

Non-finite hardening. The persisted floats (per-bike odometer, totalDistanceM, topSpeedMs) are integrated from speed × dt, and the >=/> comparisons that gate them reject NaN but not +Inf - so one bad physics sample corrupts state that survives restarts. updateTelemetry sanitises at the sample, finiteOrZero() in stats_manager_persistence.cpp heals an already-corrupted file on load, and the reasoning sits at both. Any new persisted float needs the same guard at both ends - that is a Maintenance Invariant in CLAUDE.md, pinned by stats_test.cpp and odometer_test.cpp.

8a. AchievementManager (core/achievement_manager.*, core/achievements.h)

Lifetime achievements over the numbers StatsManager keeps. achievements.h is the pure, header-only catalogue (id, title, templates, icon, metric, thresholds) plus the tier/progress arithmetic, unit-tested by test_achievements.cpp. AchievementManager holds the earned tier per row, evaluates on StatsManager’s record points and on the RELOAD_CONFIG hotkey (the “Tinkerer” row, the on-demand way to see a toast), and queues toasts for AchievementWidget.

9. FmxManager (core/fmx_manager.*)

Manages FMX (Freestyle Motocross) trick detection and scoring:

Data types are defined in fmx_types.h:

Display settings are split between global and per-profile:

10. HttpServer (core/http_server.*)

Embedded HTTP server streaming race data to browser overlays (an OBS browser source). It serves mxbmrp3_data/web/ at /, pushes JSON snapshots over SSE at /api/events, answers /api/state for pollers, and scans web/logos/ for the slideshow. Compile-time gated by GAME_HAS_HTTP_SERVER; runtime-gated by a settings toggle that starts and stops the server on demand.

The snapshot is built on the game thread and cached behind an annotated mutex for the SSE threads, because PluginData is not thread-safe. That, the connection limits, the throttle and the client-activity gating that keeps the build off the game thread when nobody is listening are all documented in http_server.h and at the code that enforces them; the gating asymmetry - frequent types gated, rare transition types never - is a Maintenance Invariant in CLAUDE.md and is pinned by http_gating_test.cpp.

The snapshot is a contract between two languages, which is the part no single file can state. Adding a field means extending buildJsonSnapshot(), consuming it in the client, and regenerating tests/fixtures/overlay_snapshot.json - a real captured snapshot read from both sides, so a rename cannot pass silently (overlay_snapshot_test.cpp checks the C++ side, overlay_snapshot.spec.js drives that same fixture through the real render()). CLAUDE.md’s Working with the Web Overlay holds the boundary rules themselves: that the plugin ships raw data and the overlay decides presentation, which helpers are mirrored, why colour roles are chosen per renderer, and why liveGapValid and canUseLiveForRider answer different questions.

The overlay’s own structure - the standings tower’s cycling bottom slot (fastest-last-lap, fastest-laps, best-sectors, down-the-order, session-charts, battle), the ?demo mode that replays a synthetic race with no plugin attached - lives in mxbmrp3_data/web/js/overlay-*.js, each file’s header describing its own area.

11. Event Log System (core/event_log_types.h, hud/event_log_hud.*)

Timestamped feed of race events, used by both the in-game HUD and web overlay:

Event types (defined in event_log_types.h):

Filter flags:

Storage:

12. CrashHandler (core/crash_handler.*)

Top-level Structured Exception Handling (SEH) filter for unhandled hardware faults: access violations, stack overflows, divide-by-zero, illegal instructions. These faults live below the C++ exception system: catch (...) doesn’t intercept them, so they would otherwise crash the host without leaving any diagnostic context behind. The CrashHandler complements the C++ exception barrier at the DLL boundary by handling the failure modes the C++ machinery can’t reach.

What it does:

Inside the filter the heap may be corrupt and other threads may hold locks, so it uses only stack buffers and Win32 calls behind a re-entry guard. The minidump flags, that rule, and the one try-lock Logger flush it allows are commented in core/crash_handler.cpp; the next-launch pending_crash.json report is in its header. Install is transactional: if PluginManager::initialize() throws after CrashHandler::install, the filter is uninstalled before the exception leaves, so the OS never holds a pointer into an unloaded DLL.

What it does NOT do:

13. CompanionWindow & Software Renderer (core/companion_window.*, core/hud_sw_renderer.*)

A standalone, in-process OS window that renders the plugin’s own HUD outside the game, so a player can drag it to a second monitor (telemetry on one screen, standings on another). It is not a network mirror and shares nothing with the web overlay - it reads the plugin’s live render primitives directly from memory and draws them itself.

How it renders. The companion has no engine, so it draws the same quads/strings the game would. It tries a D3D11 backend first (core/hud_gpu_renderer.*, INI-only [Advanced] hwAccel, default on) and falls back to the from-scratch software rasterizer hud_sw_renderer on ANY init or runtime failure, so the worst case equals software-only. Both consume the same hudsw::Frame, share the .tga/.fnt decoders and text-layout math (core/render_asset_decode.h), and reproduce the game’s texture stage (texel × quad colour), so per-quad opacity and white-icon tinting match the game. Normalized coords map into a centered 16:9 scale viewport while the renderer draws into the full client, so elements outside [0,1] land in the surrounding area instead of a letterbox. Each renderer’s header documents its own mechanism; hud_gpu_renderer.h also records why Direct2D, DirectXTK and UpdateLayeredWindow were rejected.

Threading: the game thread calls submit() once per Draw with a cheap POD copy of the current frame under a mutex; a dedicated window thread owns the Win32 message loop and renders the latest snapshot on its own cadence, so the window stays live in menus, when the game issues no Draw calls. Focus (it never takes it), cursor hiding, geometry persistence and the close-button fallback to In-game are handled in companion_window.cpp and commented there.

Per-surface decoupling (the “two settings menus” model): each HUD carries an optional second instance of its on/off + position (base_hud.h), which falls back to the game values until the first companion-side edit snapshots them. HudManager::collectSurface(companion) builds the companion frame as a second pass gated on CompanionWindow::isEnabled(), and InputManager::getActiveSurface() picks which surface the settings menu or a drag edits. Everything else - colours, fonts, sizes, columns - stays shared (one profile). The four places a new per-surface setting must be wired are CLAUDE.md’s Maintenance Invariants.

Feature gating: runtime only (the [Display] target: In-game / Companion / Both). Wired to analytics as feat_companion.

In-game overlay renderer - REMOVED. A transparent click-through window that drew the game-surface frame on its own thread once lived here (roughly +30% fps). It was removed when hud_gl_renderer (§13a) reached the same goal inside the game’s OWN GL context: every bug that path had - capture hooks, plane promotion, z-order, taskbar, focus, monitor-sized-window scanout - existed because it was a second window, and in-context GL makes that category unrepresentable. The [Advanced] overlayInGame and overlayRefreshHz keys are accepted and ignored so an old INI does not look corrupt.

13a. Direct GL Rendering - the in-game HUD, drawn by us (core/hud_gl_renderer.*)

The plugin normally hands its quads and strings to the game to draw. With [Advanced] glInGame on it draws them itself, inside the game’s own GL context, and reports zero primitives back (*piNumQuads = 0) so the engine draws nothing. No window, no swapchain, no compositor: the HUD lands in the game’s own framebuffer, so game capture sees it exactly as it sees the rest of the HUD. Phase 1 measured the engine at ~0.94 us per quad against this path’s ~0.007, which is where the frame time comes back.

It runs from PluginManager::handleDraw, never from produceFrame. A GL context is current on a THREAD, and produceFrame runs on the worker under [Advanced] pluginThread; the Draw callback is the only place the game’s context is guaranteed current. The threaded path therefore builds the frame on the worker and renders it here, on the game thread, like the companion window’s split.

GL 1.1, deliberately - client-side vertex arrays, GL_MODULATE, no shaders, no VBOs. The win is BATCHING (one draw call per texture run), not any modern feature, and every draw entry point is a real opengl32.dll export resolved with GetProcAddress, so there is no import table entry to fail at load (check_lazy_module_imports.sh). The few wglGetProcAddress names are all NEUTRALISERS - state the game may have left that a fixed-function draw must undo - and each is reached only when something implies its own availability. The header states the rule.

Inherited fixed-function state is the failure mode, and it is silent. A tester’s HUD drew panels correctly while every glyph and icon came out a solid block: the game had left texture unit 7 active and fog on. Nothing raises a GL error for that, so nothing reaches the error-based fallback. The renderer now sets every state it depends on - texture units down to unit 0, texgen, fog, logic op, polygon mode/stipple, clip planes, sample coverage, and any bound program/VBO/VAO - inside one push/pop window that also brackets batch building. Anything that DOES raise a GL error latches the backend off for the session and the engine draws the HUD, which is also what a non-GL game gets.

Two consequences worth knowing. Text and icons are sampled from mip chains (hudassets::buildFntMips / buildTexMips) because the shipped .fnt cell is 135 px and HUD text is ~20 px - ~7x minification, which is what made unmipped glyphs look thin and broken up. And the settings row is a STATUS, not a toggle (Off / On / Failed): the backend can stand down by itself, and a plain toggle would keep reading “on” while the engine was drawing. Turning it on arms hud/gl_confirm_hud.h - a countdown the user confirms or lets expire, which is the way back for someone whose HUD came out unreadable. Pinned by gl_render_test.cpp (real GL under Xvfb).

14. DirectorManager (core/director_manager.*)

An auto-director for spectating and replays: it scores an “interest” model over the field and cuts the broadcast camera to the most compelling story, with broadcast-style pacing. Global (broadcast) feature persisted in the [Director] INI section like HelmetOverlay/Rumble - not per-profile - passive except while spectating or replaying, and off by default so an upgrade never seizes a spectator’s camera. The Director switch in the Toggles strip is the discoverability path: one click enables, and the choice persists.

What it can and cannot control. The plugin can choose the spectated rider (SpectateVehicles) and a named camera (SpectateCameras) through SpectateHandler, but it cannot author camera angles beyond the game’s named set. So its job is exactly two decisions: subject selection, plus a name-based camera baseline (CameraRole). Auto hands framing to the game’s own trackside director; Trackside is the plugin-picked TV shot used for every story cut.

Three drivers, one decision function. Everything funnels into evaluate(), which coalesces to ~3×/sec and early-outs unless enabled and spectating/replaying:

The priority ladder. After yielding to a hand-flown camera and honouring the rider lock, evaluate() runs a fixed ladder over the racing, on-track field - incident, fastest lap, fastest sectors, timing show, scored stories (leader / battle / overtake / lapper / drop), finish lock - each rung a cutTo()+return, so higher stories pre-empt lower ones. The rungs, the scoring weights, the min/max-shot pacing and the onboard-variety rules are documented at the mechanism, in director_manager.h - they are tuning, they move, and a second copy here would drift.

Consumers. Two, both reading the director’s published status:

The cut log is a contract. Every cut logs one parseable line - Director cut: t=<ms> #<num> shot=<type> cam=<name> partner=<num> reason=<reason> - so a whole broadcast can be reconstructed offline. tools/director_report.py parses it from a real log and tests/integration/tests/director_broadcast_test.cpp runs the same analysis headless off a recorded tape, so a one-sided change to cutTo() silently breaks both. testSetNowMs() injects a simulated wall-clock so a headless replay drives the real pacing from recorded timestamps.

Threading. All access (hotkeys, settings, UI dispatch, onDataChanged, the per-frame polls) is on the game thread, so the members are deliberately non-atomic; a background writer would have to make the touched fields atomic (see the cross-thread-flags invariant in CLAUDE.md).

15. PluginThread - game-thread isolation (core/plugin_thread.*) - EXPERIMENTAL, opt-in

An opt-in mode ([Advanced] pluginThread=1, off by default) that moves all per-frame and per-event work onto a dedicated worker thread, so a hiccup on our side can never stall the game’s frame. core/plugin_thread.h’s header states the threading model, the two O(1) game-thread touchpoints, what is deliberately not routed through the worker, and why reconcileEnabled() must run on the game thread; render_frame_buffer.h covers the triple buffer. What belongs at this altitude is how it changes the shape of the system:

16. SpotterManager (core/spotter_manager.*, core/spotter_*.h)

An audio spotter: short spoken callouts over the game audio, the way a crew chief talks on the radio. It is a global (per-install) feature in the [Spotter] INI section, and it is the largest subsystem added since the HTTP server - the hub class plus ten pure headers, each with its own tests.

Where the pieces are. spotter_manager.* is the hub and the only stateful part; everything it decides is delegated to the pure core/spotter_*.h headers, which is why the logic is unit-testable without a game. The hub’s header maps them, and also owns the output ladder (pack mix, pack wav, SAPI TTS - and why a default install is silent under Wine/Proton), the threading model, the volume path and the backend’s single-channel limits.

One emit path, one category gate. Every cue goes through emitCue(key, category, vars…). The category a cue is emitted as is the same one that mutes it, by construction - this used to be checked at each of twenty-odd emitters and three had drifted, leaving settings switches that did not silence what they named. Ambient variables (position, gaps, rider names) are filled in emitCue from live state rather than carried by each event, so a new variable reaches every template at once.

Packs are content, not configuration. mxbmrp3_data/spotters/<name>/spotter.ini is a pack’s whole vocabulary. A pack is chosen by NAME, never by discovery index (the asset-pack invariant in CLAUDE.md), and every pack type - theme, gamepad, pit board, gauges, voice - opens its ini with the same [pack] section and takes the same optional base =. docs/spotter.md is the author’s guide; docs/spotter-reference.md is generated from the registry by tools/spottergen, so the documented cue set cannot drift from the code.

Threading. All audio runs on one worker started lazily at the first cue, so the 480fps game thread never touches COM, disk or a speech engine. The worker is joined by the orchestrated PluginManager::shutdown(), never by the destructor, per the DLL-detach invariant. Tests are catalogued in TESTING.md (test_spotter_*.cpp, spotter_test.cpp).

17. Stream Chat (core/twitch_*, core/youtube_*, core/chat_*.h, hud/stream_chat_hud.*)

Read-only, no login: Twitch over an anonymous IRC WebSocket, YouTube through the chat popout’s unofficial web interface (when that changes the status reads Unavailable; the UI never promises a fix). Each manager’s lazily started worker does the network, parsing and UTF-8 to CP1252 conversion, and hands messages to the game thread through a bounded queue behind an atomic flag. Blocking WinHTTP calls are cancelled by closing their handle; both workers are joined by PluginManager::shutdown().

The HUD System

BaseHud (hud/base_hud.*)

Abstract base class that all HUDs inherit from. Provides:

Rendering Infrastructure:

Dirty Flag System (for performance):

Positioning & Scaling:

Visibility & Interaction:

Two Types of Display Components

Full HUDs (complex, highly configurable):

Overlays (full-screen, telemetry-driven):

Widgets (simple, focused):

HUD Lifecycle

  1. Creation: HudManager creates all HUDs in initialize()
  2. Configuration: SettingsManager loads saved positions/settings
  3. Data Update: PluginData changes -> HudManager notifies -> HUD marked dirty
  4. Render Cycle: Every frame:
    • update() called -> if dirty, calls rebuildRenderData()
    • getQuads() and getStrings() return render data
  5. Shutdown: Settings saved, HUDs destroyed

Creating a New HUD

CLAUDE.md → Common Tasks → “Adding a New HUD” is the authoritative step list and is kept current with the registries it names (the CMake source glob, HudManager, the s_tabRegistry tab row, the per-HUD serializer registry row). It is deliberately not restated here - a second copy drifts, and the reader can’t tell which one is stale.

What this layer contributes is the BaseHud contract those steps assume:

Pure decision logic - which rows to draw, which gap to show, where a glyph sits

Rendering System

The game engine handles actual rendering. We just provide instructions.

Quads (SPluginQuad_t)

Rectangles with 4 corners. Used for:

struct SPluginQuad_t {
    float m_aafPos[4][2];    // 4 corners, each with (x, y)
    int m_iSprite;           // 0 = solid color, 1+ = sprite index
    unsigned long m_ulColor; // ABGR format
};

Strings (SPluginString_t)

Text to render:

struct SPluginString_t {
    char m_szString[100];    // Text content
    float m_afPos[2];        // Position (x, y)
    int m_iFont;             // Font index (1-based)
    float m_fSize;           // Font size
    int m_iJustify;          // 0=left, 1=center, 2=right
    unsigned long m_ulColor; // ABGR format
};

Font format & text encoding. The game’s .fnt bitmap fonts are a byte-indexed 256-glyph table built from CP1252 (code_page = 1252, glyphs 32–255). The renderer indexes by raw byte, so it cannot render UTF-8 - multi-byte rider names garble regardless of any truncation logic, which makes UTF-8-safe truncation in-game moot. The web overlay is the only UTF-8-aware renderer and handles names client-side. m_szString is char[100], so in-game strings are also length-bounded by the struct.

Header/label convention. Table column headers and row labels go through BaseHud::addLabel() - the STRONG font at the Small size, vertically centered in the row via labelRowYOffset() - rather than a hand-rolled addString at data-font size. Chart axis labels instead use the SMALL font (addStripChartFrame, SessionChartsHud). New HUDs should use the helper.

Coordinate System

Color Format

Colors use ABGR (Alpha-Blue-Green-Red) format:

// Helper in plugin_utils.h
constexpr unsigned long makeColor(uint8_t r, uint8_t g, uint8_t b, uint8_t a = 255) {
    return (static_cast<unsigned long>(a) << 24) |
           (static_cast<unsigned long>(b) << 16) |
           (static_cast<unsigned long>(g) << 8) |
           static_cast<unsigned long>(r);
}

Settings & Persistence

SettingsManager (core/settings_manager.*)

The settings layer is split across several TUs (all SettingsManager): settings_manager.cpp (path resolution, serialize/build, save/load orchestration), settings_manager_global.cpp (global-section registry + writeGlobalSettings/applyGlobalLine), settings_hud_profiles.cpp (per-profile capture/apply orchestration + profile switch/copy/reset), and settings_hud_registry.{cpp,h} (the per-HUD serializer registry, below). Shared free helpers live in settings_keys.h (INI key constants), settings_serde.h (the HUD-free half: generic enum⇄string, bitmask primitives, base-HUD capture/apply, validators) and settings_serde_hud.h (the HUD-typed half: per-HUD enum converters and column/row bitmask save/loads - TUs that serialize concrete HUD types include this one), all in namespace Settings.

Saves/loads HUD configuration to INI file format:

[StandingsHud]
visible=1
showTitle=1
backgroundOpacity=0.8
scale=1.0
offsetX=0.05
offsetY=0.1
displayRowCount=20

[SpeedWidget]
visible=1
scale=1.0
offsetX=0.4125
offsetY=0.6882

Settings are saved:

Parse robustness. Hand-editing the INI is a supported workflow (auto_save off, then the RELOAD_CONFIG hotkey), so every value-parsing site in loadSettings() must be exception-guarded - a single naked std::stoul/std::stof on a typo’d value throws out of the loader and aborts the parse mid-file, leaving the plugin half-configured for the session. The one offender found was the v4 base-section color path calling parseColorHex (a bare std::stoul) without a try/catch. parseColorHex itself stays a thin wrapper, so the guard belongs at each call site, wrapping the whole section’s branch.

Per-profile vs global sections

Settings fall into two kinds, persisted differently:

Per-HUD serializer registry (one list for capture / apply / serialize)

The per-profile HUD sections are driven by a single ordered table - Settings::hudSectionRegistry() in settings_hud_registry.cpp - where each row is { section name, capture fn, apply fn }. All three consumers iterate it:

So a HUD is registered for capture, apply, and on-disk serialization in exactly one place. This replaced three parallel hardcoded lists (the old captureToCache/applyProfile blocks plus a hudOrder[] array): a HUD present in capture/apply but missing from hudOrder was silently never written and reverted to default on restart (the FriendsHud bug). That drift is now structurally impossible, not merely caught. The cap_*/app_* functions are private static SettingsManager members (declared in settings_hud_registry_decls.inc) so they inherit its friend-ship with the HUD classes; hudSectionRegistry() is a friend so it can take their addresses. Guarded end-to-end by settings_sections_test (capture ⊆ serialized) and the two apply-path tests (settings_idempotency_test, settings_apply_values_test).

One serialization, three consumers (save / load / reset)

Both save and load route global sections through a single pair of functions, so they can’t drift as settings are added:

Reset = replay the factory snapshot through the same applier. At startup (before the user’s INI is parsed, while every singleton holds its constructor defaults), captureFactoryDefaults() captures two snapshots:

Why two HUD caches? m_hudDefaults is the sparse-save baseline and has the user’s hand-edited base [HudName] keys folded in at load (so they round-trip). That makes it the wrong source for “reset to defaults” - it would restore the file’s baseline (or, after a plugin upgrade, an old version’s default) instead of this build’s. m_hudFactoryDefaults is captured before any folding, so reset always means this build’s defaults. Don’t collapse the two. (Migration note: legacy keys are read from their old section as a fallback and migrate to the new section on next save - e.g. update keys [General]/[Advanced] → [Updates], units [General] → [Display].)

SettingsHud (hud/settings_hud.*)

In-game settings menu (toggle with ~ key). Allows users to:

Settings Layout System

The settings UI uses a helper class (SettingsLayoutContext) for consistent layout across all tabs:

mxbmrp3/hud/settings_hud.h/.cpp  # Main SettingsHud class (in hud/, alongside settings_hud_input.cpp / settings_hud_render.cpp / settings_hud_reset.cpp)
mxbmrp3/hud/settings/
├── settings_layout.h/.cpp       # SettingsLayoutContext helper
├── settings_tab_general.cpp     # General preferences & profiles
├── settings_tab_appearance.cpp  # Fonts & colors
├── settings_tab_standings.cpp   # Standings HUD options
├── settings_tab_map.cpp         # Track map options
├── settings_tab_radar.cpp       # Radar options
├── settings_tab_*.cpp           # Other tab implementations
└── ...

SettingsLayoutContext provides standardized control rendering:

Method Purpose
addSectionHeading(title) Section divider with label
addToggleControl(label, value, ...) On/Off toggle with < value > arrows
addCycleControl(label, value, ...) Multi-value cycle control
addStandardHudControls(hud) Common controls (Visible, Title, Texture, Opacity, Scale)
addWidgetRow(name, hud, ...) Table row for Widgets tab
addSpacing(factor) Vertical spacing

Control Width Standardization: All controls use VALUE_WIDTH = 10 to ensure vertical alignment - users can toggle settings by moving the mouse vertically without horizontal adjustment.

Tooltip System

Tooltips provide contextual help when hovering over controls. Strings are compiled into the plugin (no external file).

TooltipManager (core/tooltip_manager.h) is a header-only singleton that:

Tooltips are rendered when hovering over:

The row-wide tooltip regions are created by passing a tooltipId parameter to control helpers like addToggleControl() and addCycleControl().

Asset Management

The plugin uses a dynamic asset discovery system that scans subdirectories at startup.

AssetManager (core/asset_manager.*)

Discovers and registers assets from plugins/mxbmrp3_data/ subdirectories:

Directory File Type Purpose
fonts/ .fnt Bitmap fonts (game engine format)
textures/ .tga HUD background textures with variants (e.g., standings_hud_1.tga)
icons/ .tga Rider icons for map/radar display

Texture Variants: Textures can have numbered variants (e.g., standings_hud_1.tga, standings_hud_2.tga). Users can cycle through variants in settings.

Icon Discovery: Icons are discovered alphabetically. Use AssetManager::getIconSpriteIndex(filename) to get the sprite index for a specific icon by filename. Settings store icon filenames for persistence.

User Asset Overrides: Users can override bundled assets by placing custom files in the save directory:

FontConfig (core/font_config.*)

Maps semantic font categories to user-selected fonts:

Category Default Font Usage
TITLE EnterSansman-Italic HUD titles
NORMAL RobotoMono-Regular Standard text
STRONG RobotoMono-Bold Emphasized text
DIGITS RobotoMono-Regular Numeric displays
MARKER FuzzyBubbles-Regular Handwritten style
SMALL Tiny5-Regular Map/radar labels

The authoritative category set and defaults live in the FontCategory enum + FontConfig defaults (core/font_config.*) - add a category there and this table is illustrative, not exhaustive. Access via PluginConstants::Fonts::getTitle(), getNormal(), etc.

ColorConfig (core/color_config.*)

User-configurable color palette with semantic slots:

Input Handling

InputManager (core/input_manager.*)

Polls Windows for input state each frame:

Drag-and-Drop

HUDs can be dragged with right-click:

  1. handleMouseInput() detects click within bounds
  2. Saves initial position as drag origin
  3. Updates offset while button held
  4. validatePosition() keeps HUD on screen

Auto-Update System

The plugin includes an optional auto-update system that checks for new versions on GitHub.

UpdateChecker (core/update_checker.*)

Checks GitHub releases API for newer versions:

UpdateDownloader (core/update_downloader.*)

Downloads and installs plugin updates:

Update Flow:

  1. UpdateChecker detects new version → status = UPDATE_AVAILABLE
  2. User clicks “Install” in settings → UpdateDownloader starts
  3. Download → Verify → Backup existing → Extract → Install
  4. Status = READY → Restart required

Vendor Dependency: Uses vendor/miniz/ for ZIP extraction (public domain, single-file library).

Key Design Patterns

Singletons

Most core components are singletons:

class PluginData {
public:
    static PluginData& getInstance() {
        static PluginData instance;
        return instance;
    }
private:
    PluginData() = default;
};

Why? The plugin API gives us one entry point. The game calls our exported functions - we don’t create multiple instances.

Dirty Flag Pattern

Instead of rebuilding every frame:

  1. Data changes -> mark dirty
  2. Next render -> check dirty flag
  3. If dirty -> rebuild, clear flag
  4. If clean -> reuse cached data

This is crucial for performance since Draw() is called every frame.

Gate on the flags, not the frame. A HUD must rebuild only when isDataDirty()/isLayoutDirty() is set, never unconditionally per frame (unless the rebuild is trivially cheap). TelemetryHud was re-tessellating ~1600 line segments (each with a sqrt) every frame at 480fps for data that only changes at the 100Hz telemetry rate, so more than half the rebuilds produced identical output. (Becoming visible sets data-dirty via BaseHud::setVisible, so the first rebuild is unaffected.) The same proportionality applies to input polling: HotkeyManager refreshes only the bound keys each frame, doing the full 256-key GetAsyncKeyState sweep only while capturing a new binding.

The visibility/dirty flags are atomic. m_bVisible, m_bDataDirty, and m_bLayoutDirty are std::atomic<bool> - and setDataDirty() writes both dirty flags. Background workers legitimately mark HUDs dirty: the records fetch thread (RecordsFetcher) flags RecordsHud and TimingHud on completion, and the update-checker/downloader callbacks reach SystemMessages::offerUpdate (the atomic m_owesUpdate, read by the Dash) and SettingsHud::setDataDirty. The reads happen every frame on the game thread; plain bools made that a data race (benign on x86-64 but UB). Keep any flag written cross-thread atomic.

Second-level render caches key on their inputs. Where a rebuild is dominated by sub-geometry that doesn’t change every rebuild, cache it keyed on everything that affects its output. MapHud’s renderTrack() does this: every RaceTrackPosition marks the map dirty, but with rotation/zoom off the track ribbon is bit-identical between rebuilds, so its two tessellation passes are cached in m_ribbonQuads keyed by TrackRibbonKey (rotation, render bounds, scales, HUD offset, clip rect, LOD, zoom params, title row, the two colors - every input baked into the emitted quads). Any new input to the ribbon output must be added to the key, or the cache serves stale geometry. In rotate-to-player/zoom-follow modes the key changes every rebuild by design, so it’s a transparent pass-through there.

Standard Pattern (Most HUDs)

Use processDirtyFlags() for HUDs that rely on DataChangeType notifications:

void MyHud::update() {
    processDirtyFlags();  // Handles isDataDirty/isLayoutDirty automatically
}

Self-Detection Pattern (Polling Widgets)

Some widgets display values that don’t trigger DataChangeType notifications (e.g., session time updates continuously but doesn’t fire SessionData). These widgets must poll PluginData and detect changes themselves:

void TimeWidget::update() {
    // 1. Poll fresh data
    int currentTime = pluginData.getSessionTime();

    // 2. Compare to cached "last rendered" value
    if (currentSeconds != m_cachedSeconds) {
        setDataDirty();  // Self-mark dirty
    }

    // 3. Process dirty flags
    if (isDataDirty()) {
        rebuildRenderData();
        m_cachedSeconds = currentSeconds;  // Update cache AFTER rebuild
        clearDataDirty();
        clearLayoutDirty();
    }
    else if (isLayoutDirty()) {
        rebuildLayout();
        clearLayoutDirty();
    }
}

Why can’t these use processDirtyFlags()? The cache update must happen after rebuildRenderData() using local variables calculated before the dirty check. The onAfterDataRebuild() hook exists for simpler cases, but these widgets use values computed at the top of update().

Hybrid Pattern (Change Detection Before, Standard After)

Some HUDs do change detection but don’t need post-rebuild caching:

void NoticesHud::update() {
    // Change detection - updates member state and marks dirty
    if (wrongWay != m_bIsWrongWay) {
        m_bIsWrongWay = wrongWay;  // State updated BEFORE dirty check
        setDataDirty();
    }

    processDirtyFlags();  // Can use standard helper
}

When to Use Which Pattern

Pattern Use When Examples
processDirtyFlags() HUD relies on DataChangeType notifications StandingsHud, IdealLapHud, MapHud
Hybrid Polls data but caches state BEFORE dirty check NoticesHud, GapBarHud
Self-Detection Needs to cache “last rendered value” AFTER rebuild TimeWidget, PositionWidget, LapWidget

Handler Singleton Macro

Stateless handlers are free functions in namespace Handlers; only the stateful ones are singletons, via DEFINE_HANDLER_SINGLETON (core/handler_singleton.h). HANDLER_NULL_CHECK(data) guards the incoming API pointer in either shape.

Data Change Notifications

// PluginData notifies HudManager directly (no observer pattern overhead)
void PluginData::notifyHudManager(DataChangeType changeType) {
    HudManager::getInstance().onDataChanged(changeType);
}

// HudManager marks relevant HUDs as dirty
void HudManager::onDataChanged(DataChangeType changeType) {
    for (auto& hud : m_huds) {
        if (hud->handlesDataType(changeType)) {
            hud->setDataDirty();
        }
    }
}

The Standings firehose. DataChangeType::Standings is the highest-frequency notification: updateRealTimeGaps() runs on every RaceTrackPosition callback, and the per-rider GAP_UPDATE_THRESHOLD_MS (100ms) filter is structurally defeated on full grids - leader timing is quantized to 100 points per lap, so a gap steps by ~lapTime/100 (well above the threshold) whenever any rider crosses a quantization boundary, which on a 30+ grid is nearly every callback. Left unchecked, that rebuilt every table HUD (Standings/Timing/Pitboard/Friends) every frame during close racing. So the notification is time-coalesced to at most one per gapNotifyIntervalMs (default 100ms): a skipped notify is carried in m_gapNotifyPending and flushed by a later call, so the final change is never dropped. MapHud/RadarHud are unaffected - they rebuild from their own updateRiderPositions path.

New consumers must respect the firehose. Any new onDataChanged consumer beyond the HUDs sits on this hot path and must be trivially cheap or short-circuit before any string/alloc work, gated on whether its output is even consumed: HttpServer gates the snapshot build on hasActiveClients() (see HttpServer above), and SteamFriendsManager::updateLocalPresence fingerprints its raw inputs in a POD PresenceInputs compare and returns before building ~10 strings when nothing changed (session time bucketed per second, the finest granularity the self-row clock displays).

Constants & Configuration

Magic numbers live in plugin_constants.h - but the LAYOUT ones do not, and that distinction is the point of the split:

namespace PluginConstants {
    // Colors are configurable via ColorConfig singleton
    // ColorConfig::getInstance().getPrimary(), getSecondary(), etc.

    namespace Session {
        constexpr const char* RACE_1 = "Race 1";
        constexpr const char* RACE_2 = "Race 2";
    }
}

The layout vocabulary is DATA (core/layout_metrics.h)

Font sizes, the snap grid, panel padding and the settings panel’s block metrics live in one struct (core/layout_metrics.h) rather than as constexpr blocks spread across plugin_constants.h and a settings-panel header, where three copies of the grid axis once drifted 5.4% apart.

Two of them are settable, from [Advanced] in the settings INI: uiFontSize (base text size as a fraction of screen height) and uiLineHeight (row pitch as a multiple of it). Both feed derive(), so every tier, row and grid cell follows. Everything else is a compiled constant.

It was all settable once, from a defaults ini under the themes folder that documented forty keys, each of which a theme could override. That went because the usage evidence was unambiguous: across every theme a user would actually pick, the number of layout keys set was zero - the themes of the day set slice values, colours and fonts, and the only file exercising the tuning surface was the debug theme, whose job is to demonstrate that the surface exists. (Every shipped theme states the full box now, so the surface is exercised by all of them.) Two of the knobs were also measurably dishonest: [panel] padding-x was inert below 6 cells because the frame clearance dominated it, and [panel] border-x/-y existed only to work around a quantisation dead zone that no longer exists.

The grid IS the character box, divided by cellsPerChar / cellsPerRow (1 and 2: one cell is one character wide and half a text row tall). Nothing else defines a lattice - snapX/snapY/ceilX/ceilY hang off LayoutMetrics, and the grid overlay draws those same numbers. The lattice is SHARED, which is why it is not per-theme: HUDs align to each other by landing on the same grid lines.

Panel themes (ThemeAsset, hud/nine_slice.h)

A theme is a folder of .tga under mxbmrp3_data/themes/<name>/ plus that ini. Three slice SETS, each with its own border in GRID CELLS: [frame] (the panel frame), [card] (title bands, settings section cards, HUD body cards) and [button]. [card] also takes title border, sizing the TITLE BAND’s border alone on those same sprites; absent it follows border (ThemeAsset::titleBorderOverride).

NINE files per set (center + four corners + four edges); ThemeAsset says why.

Sprite order (discoverThemes() vs setupDefaultResources()) is the Theme sprite order invariant in CLAUDE.md, which names its startup check and test; the asset packs removed the class by walking one shared kStems table.

Title bands and body cards are new geometry rather than frame decoration - a band behind the caption, a card behind the content, both spanning the panel’s inner width and placed from [title]. The band is universal; the body card is opt-in (m_bContentCard), and widgets may take one - a lint once banned that, and its post-mortem is at core/panel_box.h. [card] widget-content is the per-theme choice that replaced the ban.

Which themes ship is not stated here - mxbmrp3_data/themes/ is the list, and a count in prose only goes stale. The .tga are edited directly, or cut from a single master by tools/themeslice - which slices, never draws; the masters live in assets/themes/, alongside debug (master + ini, slices deliberately NOT built: it is a measuring instrument for a skinner, so it costs a checkout rather than every install).

They share one GEOMETRY and differ only in art, colour and typeface, so a panel measures the same whichever a player picks and a retune is one decision rather than one per theme. Enforced by tools/check_docs.py, which compares the themes against each other rather than against a canonical copy - a copy in the checker would be the first place to go stale. debug is the one exemption, and the checker names it.

Their semantic colours follow the PLUGIN’s ramp, not their design language’s: green positive, orange warning, yellow neutral, red negative, as ColorConfig’s built-in defaults do. The hues are the language’s own; only which slot each fills is ours. A theme that reassigned them would make a delta mean something different depending on the theme, which is the one thing a palette must not do.

debug is a measuring instrument rather than a look: every slice of every set is its own flat colour, so a skinner can see which file is authored wrong and which margin a knob just moved. Its legend is the header of assets/themes/debug.ini.

INI-only tuning knobs. Power-user settings with no in-game control, edited directly in the INI (documented inline, clamped on load, reset covered by the global-snapshot replay):

Debugging

Debug Logging

DEBUG_INFO("Plugin initialized");
DEBUG_INFO_F("Received %d riders", count);
DEBUG_WARN("Something unexpected");

Logs go to {save_path}/mxbmrp3/mxbmrp3.log

Performance Timing

SCOPED_TIMER_THRESHOLD("MyFunction", 100);  // Logs if > 100us

Measuring the engine’s render cost (render-load probe)

The plugin can time how long it takes to build the quads/strings (BenchmarkWidget per-callback + collectRenderTimeUs), but the game engine’s cost to render them happens after Draw() returns and no in-plugin timer can see it. It is, however, measurable differentially: emit a controlled number of extra quads and watch the frame time rise - the slope (Δframe-time / Δquads) is the engine’s per-primitive cost.

[Advanced] renderProbeQuads=N (INI-only, off by default; HudManager::produceFrame appends N synthetic primitives to the game frame). renderProbeType picks WHICH primitive, because the three the plugin emits have different engine costs: 0=solid-fill quad (cheapest - just fill; renderProbeFullscreen=1 makes them full-screen), 1=sprite quad (textured - a texture fetch per pixel, and it cycles across every registered sprite so it also exercises texture-switch / batch-break cost), 2=text string (glyph-atlas sampling). The count flows into bm.totalQuads/totalStrings, so the BenchmarkWidget report already logs the (primitives, frame-time p50/p99) pairs. Sweep each type separately - flat quads are the lower bound; sprites and text cost more. In-game recipe: uncap FPS (no vsync/limiter - else adding load won’t move frame time until you blow the budget), sit at a fixed spot (a paused replay is ideal so the game’s own frame cost is constant), sweep N (0, 2k, 5k, 10k…) via RELOAD_CONFIG, and read the frame-time from each report. Two modes separate the two GPU costs: tiny quads isolate per-primitive submit/draw-call cost; fullscreen quads isolate fill-rate (what a full-screen overlay like the helmet costs). This is inherently an in-game measurement

Build Configurations

Testing

The game-independent logic is covered by automated tests that run headless on Linux (and in CI) with no game engine. TESTING.md is the canonical guide: the six layers (unit, integration under Wine, specialized runners, web overlay, memory safety, visual), how to run them, how to add a test, and what still needs manual in-game testing.

Two seams are architectural rather than test detail. Observation: logic tests read PluginHost::snapshot() - buildJsonSnapshot() called directly through a test hook, with no server, socket or rebuild gating - so they depend on the plugin’s computation, not the serving layer; internal state that never reaches the JSON is read through typed MXBMRP3_Test_* hooks (core/test_hooks*.cpp, gated on MXBMRP3_TEST_BUILD, excluded from every shipping target). Fidelity: the in-plugin recorder (core/event_recorder, hidden [Recorder] enabled=1) captures the real callback stream in-game; PluginHost::replayTape() replays it headlessly, so committed real-race tapes anchor the synthetic scenarios.

Common Gotchas

  1. Don’t cache game data in HUDs for rendering - Always read fresh from PluginData when building render data. HUDs only cache formatted render data (m_quads, m_strings). Exception: Widgets that poll continuously-changing values (like session time) may cache “last rendered value” for change detection - see “Self-Detection Pattern” in Dirty Flag Pattern section.

  2. 0-based vs 1-based indexing - API uses 0-based lap numbers, UI shows 1-based. Check the API header comments.

  3. C++ exceptions must not cross the DLL boundary - The host game terminates if a C++ exception escapes a DLL export. Every export in vendor/piboso/*_api.cpp wraps its body in API_GUARD_CATCH (see vendor/piboso/api_guard.h). When adding a new export, follow the same pattern. Similarly, every std::thread body wraps itself in a top-level try/catch, since an uncaught throw in a std::thread calls std::terminate(). For hardware faults that don’t go through the C++ exception system (null deref, OOB, divide-by-zero), the SEH filter in core/crash_handler.* writes a minidump for diagnosis but doesn’t prevent the crash.

  4. Game thread vs background threads - All PiBoSo API callbacks (Draw, RunTelemetry, etc.) run on the game thread. PluginData, HudManager, SettingsManager, and the various other managers are game-thread-only and not thread-safe. Background threads (I/O and off-thread work; the Logger entry in CLAUDE.md lists them) must NOT touch those singletons directly. They consume snapshots built on the game thread instead (see HttpServer::buildJsonSnapshot, DiscordManager::updateSnapshot). The Logger has its own internal mutex and is safe to call from any thread. Two corollaries for any worker serving a HUD - guard a mutex-guarded member at every access site, and snapshot game-thread inputs at task start and join before teardown - are stated with their enforcement in CLAUDE.md → Maintenance Invariants; the records fetch thread (core/records_fetcher.*) is the worked example of both.

  5. Sprite indices are 1-based - Index 0 means “solid color fill”, not “first sprite”.

  6. Font indices are 1-based - Font index 0 is invalid.

  7. Icon ordering is alphabetical - Icons in mxbmrp3_data/icons/ are discovered alphabetically. Use filename-based lookups via AssetManager for persistence; icon additions/removals won’t break saved settings.

Multi-Game Support

The plugin supports multiple PiBoSo racing games from a single codebase using compile-time game selection.

Supported Games

Game Mod ID Vehicle Type Splits Unique Features
MX Bikes mxbikes Bike (2 wheels) 2 Straight Rhythm
GP Bikes gpbikes Bike (2 wheels) 3 ECU/TC/AW, Tread temps
WRS wrs Car (4-6 wheels) 2 Rolling start, Turbo, Handbrake
KRP krp Kart (4 wheels) 2 Session series, Qualify heats

Build Targets

The game is the target, not the configuration - Debug/Release are plain configurations, and each game its own CMake target:

Target Output Install Location
mxbmrp3 mxbmrp3.dlo MX Bikes plugins/
mxbmrp3_gpb mxbmrp3_gpb.dlo GP Bikes plugins/
mxbmrp3_krp mxbmrp3_krp.dlo Kart Racing Pro plugins/
(future) mxbmrp3_wrs.dlo WRS plugins/

One mxb_add_plugin(NAME GAME_DEF API_TU) call per game in mxbmrp3/CMakeLists.txt builds the shared sources plus exactly one export TU, so the API file is selected rather than excluded:

mxb_add_plugin(mxbmrp3     GAME_MXBIKES mxb_api.cpp)
mxb_add_plugin(mxbmrp3_gpb GAME_GPBIKES gpb_api.cpp)
mxb_add_plugin(mxbmrp3_krp GAME_KRP     krp_api.cpp)

Output lands in build/<GAME>-<Config>/. DEVELOPMENT.md has the presets and deploy variables.

Feature Flags

Compile-Time (game/game_config.h):

#if GAME_HAS_RACE_SPEED
void handleRaceSpeed(const Unified::RaceSpeedData* data);
#endif

Runtime (adapter constants):

if constexpr (Game::Adapter::HAS_RACE_SPEED) {
    // Show speed trap data
}

Key feature flags:

Variable Split Count

Games have different numbers of timing splits. Unified types use a dynamic count:

struct RaceLapData {
    int splits[MAX_SPLITS];  // MAX_SPLITS = 3
    int splitCount;          // Actual count (2 for MXB, 3 for GPB)
};

Updating Vendor APIs

When PiBoSo releases a new API version:

  1. Update the vendor header (mxb_api.h, gpb_api.h, etc.)
  2. Update the adapter to handle new/changed fields
  3. Update the API cpp if new callbacks are added
  4. Update unified types if new data needs to be shared

The adapter layer isolates changes - core HUDs don’t need modification for most API updates.

API Differences

Identical across all games:

Per-game variations:

Quick Reference: File Locations

Deliberately not a table of every file - the tree is the index, and a hand-maintained mirror of it goes stale on the first rename. See Project Structure above for the directory map and CLAUDE.md’s Where Things Live for the handful of placements that aren’t guessable.

Runtime paths, which are the part you genuinely can’t find by looking:

What Where
Settings, stats, rumble profiles, log {save_path}/mxbmrp3/
Crash dumps {save_path}/mxbmrp3/crashes/
Callback tapes (recorder) {save_path}/mxbmrp3/tapes/
Shipped assets {game_path}/plugins/mxbmrp3_data/{fonts,textures,icons,themes,gamepads,pitboards,spotters,web}/
User asset overrides (synced on launch) {save_path}/mxbmrp3/ + the same subfolders
Build output build/<GAME>-<Config>/, e.g. build/MXB-Release/

Quick Reference: Adding Features

CLAUDE.md → Common Tasks is the authoritative version of this list and is kept current with the registries it describes (adding a HUD, a per-HUD or global setting, a settings tab, a web-overlay field, a game-specific feature, a new game). It used to be duplicated here in a shorter, vaguer form - two descriptions of one subject, where the copy drifts and the reader can’t tell which is stale. Only the entries CLAUDE.md doesn’t cover live here:

Task Steps
Add new data type Add struct to PluginData, add DataChangeType enum
Add tooltip Add entry to the maps in core/tooltip_manager.h, pass tooltipId to control helper
Add keyboard shortcut Handle in HudManager::processKeyboardInput()
Add new handler Create handler class, route from PluginManager
Add new font Place .fnt file in mxbmrp3_data/fonts/ (auto-discovered)
Add new texture Place .tga file in mxbmrp3_data/textures/ (auto-discovered)
Add new icon Place .tga file in mxbmrp3_data/icons/ (auto-discovered, alphabetical order)
Add new event log type Add enum to event_log_types.h, add flag, update eventLogTypeToFlag(), add to handlers
This site is open source. Improve this page.