Openplanet Plugin Development

Core guide for Openplanet AngelScript plugins on TM2020 (TMNEXT) and ManiaPlanet 4 (MP4/TM2). Deep material lives in references/ — load only what the task needs (index at the bottom).

Golden rules

1. Verify API members against the reflection DB before writing code.
   • Game Nod classes live in <GameDir>/Openplanet4.json under ns.Game.<Class>.m[] (entries n=name, t=type, p=parent). Walk it with the procedure in references/static-verify-workflow.md.
   • Openplanet script namespaces (UI::, IO::, Time::, Json::, Math::, Text::, Net::, Audio::, Icons::, getExceptionInfo()) are NOT in Openplanet4.json. They live in OpenplanetCore.json (same game dir) under functions[] (filter by ns), classes[], enums[]. Extraction recipes + verified signatures: references/openplanet-core-json.md. Before assuming a built-in exists (e.g. IO::WriteFile, UI::ListBox, Time::Format(string)), grep OpenplanetCore.json — false assumptions here cost a full kill+relaunch recompile cycle each time.
   • MP4 game-class specifics: references/mp4-api-verified.md (editor) and references/mp4-runtime-and-dev-memory.md (in-race / playground).
   • A class can appear in the DB with an EMPTY m[] (e.g. ns.Scene.CSceneVehicleVis is {"i":...,"s":3464} with no members). That is not a lookup failure — it means the class has no scriptable named members and the only way in is raw Dev::GetOffset* / Dev::SetOffset against its byte size. Report that honestly instead of inventing member names.
2. Target game matters. TM2020 examples often DON'T compile on MP4 (missing UI overloads, missing members, wstring vs string). MP4 specifics: references/mp4-api-verified.md, references/mp4-api-mismatches.md, references/mp4-supplement.md, references/mp4-ui-rendering.md.
3. Unsigned folder plugins need Developer signature mode. Launch with ManiaPlanet.exe /openplanet:developer (or F3 → Developer → Signature Mode). Otherwise the log shows Invalid file hash + not suitable for the current signature mode and the plugin silently doesn't appear.
4. Debug via the log, not the GUI. Clear Openplanet.log, launch, wait ~50 s, then grep for ERR : / compilation failed / Loaded plugin. Full command recipes: references/launch-and-verify.md.
5. A running game holds the compiled state. After editing sources, kill the game (taskkill /F /IM ManiaPlanet.exe) and relaunch for a clean recompile — stale errors in the log mean the old build, not a failed patch.
6. Null-safe editor access. Route all App.Editor access through one gateway that re-checks every handle each frame; wrap each UI module in try/catch. Proven skeleton: references/mapforge-architecture.md.
7. Cross-game (TMNEXT + MP4) plugins. One plugin can target BOTH games via the predefined TMNEXT / MP4 preprocessor defines (Openplanet injects them per-game; no info.toml flag needed). CGameCtnApp is the shared base, so app.Switcher.ModuleStack, app.RootMap, app.Editor, app.CurrentPlayground work on BOTH. Gate TMNEXT-only API (cast<CTrackManiaMenus>, NGameLoadProgress::EState, app.LoadProgress) behind #if TMNEXT and add an #elif MP4 branch. Keep TMNEXT and MP4 pause reasons/settings SEPARATE — do NOT collapse Pause In Menu + Pause While Loading into one inMenuOrLoading check (Copilot flagged exactly this in the green-timer port: a combined ModuleStack<1 || RootMap is null with return true always reports "Loading Screen" and lets "menu" setting pause during load). Correct MP4 form: bool inMenu = app.Switcher.ModuleStack.Length < 1; bool inLoading = !inMenu && app.RootMap is null; then two separate ifs. Deprecated calls to fix while porting: nvg::LoadFont("x.ttf", true, true) → nvg::LoadFont("x.ttf"); Time::Format(int, bool, bool, bool) → Time::Format(uint64, bool fractions, bool forceMinutes, bool forceHours, bool short). Verified pattern, shared-member list, deprecated fixes, and the nvg::LoadFont root-path pitfall: references/crossgame-tmnext-mp4.md.
8. Never hardcode memory offsets you did not verify on THIS build. Dev:: read/write/hook is fully available on MP4, but offsets are build-specific. Discover them with a live correlation panel, freeze them behind a load-time self-check (re-read a known field and compare it to a reflected value), and fall back to read-only mode when the check fails — a bad SetOffset into a physics object crashes the game, not just the plugin. Procedure: references/mp4-runtime-and-dev-memory.md §6.
9. A plugin whose logic lives in a bundled native .dll is a REWRITE, not a port. Unpack the .op (it is a ZIP) and check whether the .as files are just an Import::GetLibrary shell. If so, say that up front instead of promising a port — the offsets target a different executable and no sources ship in the package. Analysis recipe + verdict/brief template: references/op-package-analysis-and-porting.md.
10. Prefer dynamic, runtime-observed game state over static/parsed lists. The user explicitly asks for this ("statyczne checkpointy → zrób dynamiczne"). Example: bucket by the live CurTriggerIndex the driver actually crosses rather than a precomputed checkpoint table; it adapts to any map, multilap included. See references/mp4-runtime-and-dev-memory.md §7. Offer the static form as an explicitly-labelled fallback in the same module, never as the primary design — the user accepts "static if dynamic proves impossible", which is not the same as being handed static first.
11. In-plugin AngelScript beats any external process for reading game state. When asked "can this be done in Python / .NET instead", the deciding fact is pointer acquisition: Openplanet hands you the live nod via GetApp() for free, so Dev::GetOffset(nod, off) is one line. An external Python ctypes/pymem or .NET process must first find that same object by scanning process memory — hours of work for something already solved. Answer with that comparison (a 3-row table works well), then keep Python for offline tooling: reflection-DB queries, code generation, Kanban seeding, and the static pre-flight gate. Do not accept "rewrite it in Python" as a way to avoid .NET when the real answer is "neither — it belongs in the plugin".
12. Stage delivery as Tier 1 (safe) then Tier 2 (memory writes). Tier 1 = read-only reflection + teleport-style restore, ships immediately and cannot crash the game. Tier 2 = velocity/physics restore via Dev::SetOffset, gated behind a load-time offset self-check with automatic Tier-1 fallback. Ship and verify Tier 1 first; it also proves the nod chain before you build anything on top of it. A read-only telemetry tab is the cheapest possible proof that the whole context chain resolves — build it first and ask the user to confirm the numbers move before writing further modules.

Project documentation convention (where knowledge lives)

For OpenPlanet plugin projects on disk, the user's preferred layout:

• IDEA.md (project root) = project catalog only. List what each plugin/project does (name → one-line description + module map). It is NOT a dumping ground for API knowledge or verified facts.
• API knowledge → README.md + this skill's references/ (esp. references/mp4-api-verified.md). Put the verified member list, error→fix table, and the "no MapForge.* SDK / no Lua-C# / MwFastBuffer is a value type" facts in README (a summary) and in references/.
• Do not keep API facts in IDEA.md; keep IDEA.md a plain index so a future session finds projects fast without re-learning the API.

Plugin skeleton (callback style)

MyPlugin/
├── info.toml        # metadata (see references/launch-and-verify.md §info.toml)
└── src/
    ├── Main.as      # Main(), Render(), RenderMenu(), OnDestroyed()
    ├── Core/        # context/gateway, module manager
    └── Modules/     # one feature per file

// Main.as — minimal
[Setting name="Show window"] bool S_ShowWindow = true;

void Main() { /* init; yield in loops */ }

void RenderMenu() {
    if (UI::MenuItem("\\$0f0" + Icons::Wrench + " MyPlugin", "", S_ShowWindow))
        S_ShowWindow = !S_ShowWindow;
}

void Render() {
    if (!S_ShowWindow) return;
    if (UI::Begin("MyPlugin", S_ShowWindow)) {
        // guard editor access every frame:
        auto app = cast<CGameCtnApp>(GetApp());
        auto editor = cast<CGameCtnEditorFree>(app.Editor);
        if (editor is null) UI::Text("Open the map editor.");
        else { /* modules */ }
    }
    UI::End();
}

info.toml minimum:

[meta]
name = "MyPlugin"
author = "you"
category = "Map Editing"
version = "1.0.0"

[script]
timeout = 5000

Top MP4 compile-error killers (details in references/mp4-api-verified.md)

• tostring(uint) ambiguous → Text::Format("%d", int(v))
• no char() / char literals → byte math ('A'=65, 'Z'=90)
• MwFastBuffer is a value type → never Buf is null
• ternary cond ? x.Name : "?" with wstring Name → string(x.Name) both branches
• UI::InputInt3, UI::BeginTable, UI::Columns, flag args on CollapsingHeader/BeginTabBar → don't exist; use BeginChild+SameLine
• no string::ToLower → manual byte compare helper

Reference index (load on demand)