mxbmrp3

AI Development Context for MXBMRP3

Read This First

This is a racing simulator HUD plugin for PiBoSo racing games (MX Bikes, GP Bikes, WRS, KRP). It’s a DLL plugin written in C++ using each game’s proprietary API, with a shared core that works across all supported games.

For deep technical details: See ARCHITECTURE.md (comprehensive documentation with mermaid diagrams, component descriptions, dependency graphs, multi-game architecture). This file is a quick-start guide.

Quick Architecture

Game Engine (MX Bikes / GP Bikes / WRS / KRP)
    ↓ (callbacks via plugin API)
mxb_api.cpp / gpb_api.cpp (per-game DLL exports)
    ↓ (converts to unified types via adapters)
PluginManager (receives unified types only)
    ↓
PluginData (singleton - caches all game state)
    ↓ (notifies on data changes)
HudManager (singleton - owns all HUD instances)
    ↓
Individual HUDs (IdealLap, Standings, Map, etc.)
    ↓ (build render primitives)
Game Engine (renders quads/strings)

PluginData ──(notifies on data changes)──→ HttpServer
    ↓ (builds JSON snapshot on game thread)
SSE stream → Web Overlay (browser/OBS)

Key Singletons:

Multi-Game Support

The plugin supports multiple PiBoSo games from a single codebase:

Game Config Output Status
MX Bikes MXB-Release mxbmrp3.dlo ✅ Full support
GP Bikes GPB-Release mxbmrp3_gpb.dlo ✅ Core features
Kart Racing Pro KRP-Release mxbmrp3_krp.dlo ✅ Core features (no FMX)
WRS - wrsmrp3.dlo ⏳ Stubbed

Translation Layer:

Build & Test

⚠️ IMPORTANT - Build Environment:

⚠️ IMPORTANT - Shell Commands:

Build Instructions (Windows only):

Important Patterns & Constraints

Performance Target: 240fps

The plugin must run efficiently at 240fps (4.17ms frame budget). Many competitive players use high refresh rate monitors. Avoid per-frame allocations, unnecessary string operations, and complex calculations in hot paths like Draw() and RunTelemetry().

DO:

DON’T:

Design Decisions (Don’t “Fix” These)

Singletons Everywhere Required by plugin API - we get one global entry point, everything branches from there.

Lambdas in settings_hud.cpp rebuildRenderData() Intentional - they capture local layout state. Alternatives were worse (passing 8+ parameters).

Public member variables on HUDs (e.g., m_enabledRows) These are configuration data, not encapsulated state. SettingsHud needs direct access.

HUDs don’t cache raw game data HUDs pull fresh from PluginData on rebuild - they only cache formatted render data (m_displayEntries, m_quads, m_strings). This enforces PluginData as single source of truth and prevents synchronization issues.

Settings reset reuses save/load serialization (don’t add a third list) “Reset to defaults” replays a startup snapshot through the same applier loadSettings() uses, never a hand-maintained list of per-setting resets. Two snapshots back this, and they are intentionally separate:

m_hudDefaults (sparse-save baseline, with base-section edits folded in) is not a clean factory snapshot — don’t “simplify” reset by pointing it at m_hudDefaults or by merging the two caches; that reintroduces stale-default-on-reset bugs (e.g. an upgraded HUD default not taking effect). A new setting gets reset coverage for free as long as it’s wired into save/load. See ARCHITECTURE.md “Settings & Persistence”.

Widget vs HUD Distinction Widgets (TimeWidget, PositionWidget, LapWidget, SpeedWidget, GearWidget, ClockWidget, SpeedoWidget, TachoWidget, BarsWidget, FuelWidget, LeanWidget, GForceWidget, TyreTempWidget, EcuWidget, GamepadWidget, VersionWidget, SettingsButtonWidget) are simplified HUD components with:

Full HUDs (StandingsHud, LapLogHud, PitboardHud, TimingHud, NoticesHud, StatsHud, etc.) have:

Helmet Overlay (HelmetOverlayHud) Full-screen immersion overlay — neither a widget nor a typical HUD:

Handler-to-API Event Mapping Each handler corresponds to game API callback(s), but receives unified types:

No unit tests Requires game engine to run. Manual testing in-game is current workflow.

Logger has an internal mutex Logger::log() is called from the game thread and from at least five background threads (HttpServer, UpdateChecker, UpdateDownloader, DiscordManager, RecordsHud). The mutex serializes concurrent writes so log lines don’t interleave. Don’t remove it. The SEH crash filter deliberately doesn’t call Logger to avoid deadlocking on this mutex.

Common Tasks

Adding a New HUD

  1. Create class inheriting from BaseHud (.h and .cpp files in mxbmrp3/hud/)
  2. Add files to Visual Studio project:
    • mxbmrp3/mxbmrp3.vcxproj - Add <ClInclude> for .h and <ClCompile> for .cpp
    • mxbmrp3/mxbmrp3.vcxproj.filters - Add filter entries to place files in Header Files\hud and Source Files\hud
    • Without these entries, the build will fail with linker errors (LNK2019 unresolved externals)
  3. Implement rebuildRenderData() - builds vectors of quads/strings
  4. Register in HudManager constructor (add pointer, getter, initialize in initialize(), null in clear())
  5. Add tab in SettingsHud for configuration
  6. Add save/load in SettingsManager (per-HUD capture/apply, or — for a global single-value setting — one line in writeGlobalSettings() and one branch in applyGlobalLine()). Reset is then automatic via the factory snapshots; no separate reset code needed.

Debugging Rendering Issues

Working with Game API Events

When implementing event handlers or debugging timing/lap data:

Working with the Web Overlay

The embedded HTTP server (core/http_server.cpp) streams race data to browser-based overlays via Server-Sent Events (SSE):

Adding Support for a New Game Feature

  1. Add field to appropriate Unified:: struct in game/unified_types.h
  2. Add conversion in each adapter (game/adapters/*_adapter.h)
  3. Add feature flag to game/game_config.h if game-specific
  4. Update handlers/HUDs to use the new field

Disabling a Feature Per-Game

When an entire feature (HUD, manager, integration) doesn’t apply to one or more games — e.g. FMX freestyle tricks on karts, Discord Rich Presence on non-MXB, the records provider on non-MXB:

  1. Add a GAME_HAS_X flag to game/game_config.h. Examples already in the file: GAME_HAS_DISCORD, GAME_HAS_HTTP_SERVER, GAME_HAS_FMX, GAME_HAS_RECORDS_PROVIDER. Pattern: 
    #if defined(GAME_MXBIKES) || defined(GAME_GPBIKES)
    #define GAME_HAS_FMX 1
#else
    #define GAME_HAS_FMX 0
#endif
  2. Gate the HUD registration in HudManager::initialize(). Leave the member pointer as nullptr; existing null-checks downstream (if (m_pFmxHud)) will fall through silently.
  3. Gate the settings tab in SettingsHud — prefer the runtime null-check pattern used for TAB_RECORDS (if (i == TAB_FMX && !m_fmxHud) continue;) over a #if block. Cleaner and reuses the nullptr you set up in step 2.
  4. Gate the hotkey row in settings_tab_hotkeys.cpp. The hotkey action itself can stay in the enum (the handler in HudManager::processHotkeys is already null-safe), but the row should be hidden so users don’t see a binding that does nothing.
  5. Gate handler entry points that feed the disabled manager (run_telemetry_handler.cpp, race_session_handler.cpp, etc.). Skip the singleton calls entirely so the binary doesn’t pull them in.
  6. Gate SettingsManager save/load if the disabled HUD has its own profile section. Crucial when HudManager::getXxxHud() returns a Hud& with assert(m_pXxxHud) — calling it with a null member crashes in debug and null-derefs in release.
  7. Gate the installer (mxbmrp3.nsi) if the feature has supporting data files (e.g. web/ for HTTP server) so they don’t ship to a build that can’t use them.

If a .cpp file’s GAME_HAS_X reference is in a file that doesn’t transitively include game_config.h, add #include "../../game/game_config.h" (path from the file). The handlers’ plugin_data.h already pulls it in; hud_manager.h pulls it in; isolated tab files like settings_tab_hotkeys.cpp may need the explicit include.

Reference implementations to copy from: FMX (commit deba67f), Discord (GAME_HAS_DISCORD), Records provider (GAME_HAS_RECORDS_PROVIDER).

Files You’ll Likely Need

Core:

Multi-Game Layer:

HUD Base:

Example HUDs:

Web Overlay:

Settings:

Git & Development Workflow

Commit Message Conventions

Branch Naming

Version Management

Peer Reviews

Development Style

This site is open source. Improve this page.