DKR-R MODDING SDK 2.0 AND DEV MENU - APPROVED IMPLEMENTATION PLAN
17 October 2026

STATUS

The user approved this plan. The reviewed SDK 2.0 and nine-screen Dev Menu
implementation is compiled and packaged as the beta 7 playtest. WORK-STATUS.txt
and the delivery BUILD-RECEIPT.txt record the actual engineering gates and
supported/protected boundaries. Runtime acceptance remains with the user.
Beta 6's Camera++ shadow correction is composed as an accepted baseline.

All implementation must go through the Patch Pipeline. Do not edit checked-out
submodules, RecompiledFuncs, RecompiledPatches or earlier generated outputs.
The user does gameplay, visual, multiplayer and performance testing. Agent work
is source inspection, compilation, static checks and packaging unless the user
explicitly changes that instruction.

1. WHAT THE CURRENT CODE ACTUALLY DOES

This is not an SDK that only supports a few cheats. API 1 already provides
guest-memory access, eligible function hooks/replacements, named callbacks,
native game calls, dependencies, resources, deterministic RNG and saved mod
settings. It already has a rewindable mod World and host-owned online sets.
Keep those capabilities. The missing part is a complete, reusable development
toolset around them, not simply access to more memory.

Evidence inspected in this workspace:

- modding/include/dkr/magic_codes.h: API 1 ABI, callbacks, hooks, replacements,
  raw symbols/context/calls, resources, settings, cups and extended lap support.
- modding/include/dkr/game.h: the convenience setters only cover position,
  racer speed/bananas, object scale and camera position/boom/shake. Collision
  floor queries are static, bounded and confined to one segment. HUD drawing
  is text-only with phase, string and glyph limits.
- runtime-recomp/src/game/mods/magic_code_package.hpp/.cpp: schema/API 1 only;
  module requirements currently accept version 1 only. Settings currently
  support Enum, Number and String, with a 128-option schema limit.
- runtime-recomp/src/game/mods/magic_code_world.cpp: private mod state, RNG,
  checkpoints, queued effects and native guest RAM access.
- runtime-recomp/src/game/mods/magic_code_game_world.cpp: separate hook/call
  permissions, curated audio calls, named events and offline/owned dispatch.
- runtime-recomp/src/game/mods/magic_code_link.hpp/.cpp: 8 MiB session-resident
  budget, fixed per-package heaps/stacks, dependency ordering and hook conflicts.
- runtime-recomp/src/game/mods/magic_code_vm.hpp: default 200,000 instruction
  and 128 native-call budget; this is not an unlimited execution environment.
- runtime-recomp/src/game/runtime_code_mods_ui.inl: generic scalar settings,
  but the trophy editor is special-cased by package ID. Authors cannot build
  an equivalent reusable runtime editor through a generic UI module today.
- patches/camera-plus: a separate local presentation domain is now available;
  it must remain separate from shared gameplay state.
- extern/dkr-decomp/src/objects.c, game.c, thread3_main.c, racer.c, weather.c
  and audio.c: references for spawning/freeing, race state, safe scene loading,
  AI, original weather and audio. Do not call their low-level paths blindly
  from an overlay callback.

2. COMPATIBILITY CONTRACT - KEEP EXISTING MODS WORKING

Brand the authoring kit SDK 2.0, while retaining both executable API 1 and API 2.

- Load current .nrm/.dkrcode files unchanged. Do not require recompilation,
  new signatures, ID changes or modified metadata for old packages.
- Preserve API 1 import names, struct layouts, callbacks, return values,
  settings interpretation, dependency order and hook/replacement semantics.
- An API 1 package still sees version 1 from its existing version import.
- Add an explicit API 2 metadata/loader path and capability query. Negotiate
  module versions per package; do not globally replace every module's 1 with 2.
- Keep current API 1 settings, cup documents, approvals, installed editions
  and offline/online selections. Migration is needed only for new data formats,
  is explicit and recoverable, and never silently rewrites an original file.
- Mixed API 1/API 2 sets share a canonical dependency order. Report an exact
  conflicting package/system/function instead of letting two owners win by chance.
- Keep compatibility with the supplied trophy, AI difficulty and Camera++ mods.
  Camera++ stays presentation-only, not part of shared race rules.
- Old apps reject an API 2 mod clearly. New apps do not advertise API 2 support
  on an online CPU path until all its services actually exist there.
- A new engine/protocol must reject an incompatible peer before game startup.
  API compatibility does not mean different app builds can safely cross-connect.

Acceptance is preservation by design plus compilation/static ABI inspection;
runtime compatibility with the user's installed mod set is for user testing.

3. EXECUTION MODEL AND NEW API MODULES

Retain the portable C -> MIPS O32 -> .nrm workflow. No host DLL requirement,
no OS shell inside a mod, no renderer/device/scheduler access disguised as
gameplay freedom. Trusted advanced guest-memory/hooks remain available under
their established boundary. A checked VM cannot make arbitrary native game
calls harmless; trust warnings must say that plainly.

Keep C as the stable ABI. Add optional freestanding C++ convenience wrappers
and an API 2 build path, without host STL/threads, exceptions or RTTI. Existing
C projects and their compiler flags remain valid. Ship project scaffolding,
package inspection, API capability reports and source-map generation with the
authoring tools, not just a collection of headers.

Add the following versioned modules:

A. Types, reflection and capabilities
   - Opaque world/scene/entity handles with generation/lifetime validation.
   - Decomp-derived type/property catalogs for both supported ROM revisions.
   - Names, types, ranges, units, enums, read/write flags, allowed phase and
     online policy for every exposed field and operation.
   - Bulk queries and filtered/paged enumeration, not hundreds of tiny calls.
   - Explicit status codes for stale handles, wrong phase, missing assets,
     denied authority, unavailable feature and exceeded budgets.
   - Expert symbol/hook catalog identifies protected and unsupported entries.

B. Events, hooks and rules
   - Documented deterministic tick phases and lifecycle subscriptions.
   - Rich racer, lap, checkpoint, item, collision and result event payloads.
   - Ordered filters and cooperative modifiers where composition is meaningful.
   - Explicit exclusive ownership for replacements or mutually exclusive rules.
   - Typed native-call wrappers for reviewed operations; retain the expert
     hook/context path without routing through process-global function tables.

C. Transactional world editing
   - Validate an edit batch first, queue it to the correct simulation boundary,
     apply it once, and return a result/handle through the command interface.
   - Position/rotation/velocity, racer state, handling and AI parameters,
     object transforms/approved properties, triggers and session race rules.
   - Spawn/clone/despawn through native ownership/initialisation helpers.
     Never memcpy a live Object or expose a host allocation pointer.
   - Safe teleport updates segment/path/collision bookkeeping, not just XYZ.
   - Course/restart/vehicle changes use a transition request. Rebuild colliders,
     animation or scene resources when required rather than leaving stale caches.
   - Declare which edits are live, require a scene reload, or require a restart.

D. Resources and track tooling
   - Versioned catalogs for installed native/legacy tracks, cups, characters,
     object templates, models, textures, sounds and sequences.
   - Logical content IDs and declared dependencies, never absolute host paths.
   - Resolve/freeze required resources before a scene or online match uses them.
   - Static ray/floor/wall/sweep queries and explicitly supported dynamic
     collider queries, with bounded results and meaningful capability reporting.
   - Track checkpoints, AI routes, triggers, spawn points and material/property
     overlays can be inspected and edited through typed adapters.
   - Runtime adjustments export as a versioned development-patch document.
     Do not quietly rewrite an installed .dkrmap, ROM or someone else's pack.
   - Structural mesh/collision edits use the existing track authoring/reload
     path, not arbitrary replacement of live render/physics buffers.

E. Generic runtime UI and local presentation
   - A reusable controller-first panel API, supplied by a mod, rendered by the
     existing launcher/overlay style. No special case for the Dev Menu's ID.
   - Pages, tabs, lists/tables, search, buttons, toggles, enums, numbers/sliders,
     colours, vectors, editable collections, status and confirmation dialogs.
   - Conditions/read-only state, presets, grouped settings and clear live vs
     reload-required changes. All text fields have the existing OSK available.
   - Copy UI/view data; never lend ImGui, GPU, window or process pointers.
   - UI interactions become typed commands. An overlay draw does not mutate
     rewindable gameplay memory or advance the shared RNG.
   - Debug lines, boxes, labels, routes, normals, collision and trigger overlays
     use a bounded local presentation list with correct camera/viewport ownership.
   - Free/spectator cameras use presentation APIs, not a camera writer that
     moves another player's view or changes the simulation.

F. Live development, diagnostics and storage
   - Per-package metrics: callbacks, service cost, instruction/native-call
     usage, memory, events, active overrides and last fault with source mapping.
   - Watch typed values; event/command tracing; command search/history/macros.
   - Scoped scratch documents/presets and user-selected import/export. No
     arbitrary mod filesystem/network access or automatic shell commands.
   - Offline safe-point reload for packages explicitly declaring compatible
     live-reload/cleanup/migration. Other packages reload the scene/restart.
   - No unilateral online code/resource reload: return to lobby and readmit.
   - Local timing/profiling never becomes a gameplay clock or source of RNG.

4. ONLINE DESIGN - BUILT IN, NOT BOLTED ON AFTERWARDS

Separate three categories from day one:

LOCAL: browsing panels, read-only inspectors, debug draw and presentation cameras.
SHARED: race/racer/object changes and agreed live rule/configuration overrides.
PERSISTENT: imports/exports, files and save operations, outside gameplay callbacks.

- Add an explicit Development Lobby option. Require consent before enabling
  game-changing Dev Menu commands. Ordinary lobbies do not accept debug edits.
- The host grants command authority. Clients can inspect and request actions;
  they do not write shared state locally. Commands target the current epoch,
  frame, package identity and entity generation.
- Validate and order a shared command once; include it in the authoritative
  deterministic input/command stream. Execute the same command on every peer.
- Checkpoint command IDs, queues/results, runtime overrides, spawned ownership,
  mod memory and RNG. Replaying a frame must not duplicate a spawn or sound.
- Confirm external effects before logging/exporting/playing them, reusing the
  existing confirmed-effect/audio model.
- Shared pause/step/timescale, if enabled, apply to everyone together. Keep
  transport and window/UI handling alive while simulation is parked. Never
  pause one client's simulation just because their menu is open.
- Admit dependencies, SDK/module versions and deterministic configuration
  before launch. Support Auto/Experimental Rollback first, matching the current
  code-mod support policy; do not pretend other modes support shared code mods.
- Prefer command validation errors. Do not swallow a genuine VM/native fault
  and continue a now-divergent online simulation.

5. EXAMPLE MOD: DKR-R DEV MENU

Ship one importable .nrm plus its complete source, UI resource/schema, presets,
project manifest and build instructions. It must exercise public SDK 2.0 APIs
that other modders can use; it must not require new hard-coded launcher screens.

ENTRY AND NAVIGATION

- A remappable shortcut/controller chord and an in-game menu entry.
- A full-width tools hub with dedicated screens, not nested scrolling modals.
- Controller/keyboard/mouse navigation; clear focus; one main vertical scroll
  area; fixed footer; OSK on every textbox; readable centred action buttons.
- B/back returns predictably; opening/closing consumes the shortcut and restores
  input cleanly. It must not accidentally steer, fire an item or open twice.
- Search tools/commands/objects; pin favourites; display current target and
  whether an action is local, shared or requires a reload.

SCREEN 1 - SESSION / SIMULATION

- Current scene/course ID and name, revision, world epoch/frame, mode, player
  ownership, vehicles, active mods and developer-session/save status.
- Restart this race/scene, restart at a chosen entrance, reload track assets,
  return to Track Select or menu using normal transition ownership.
- Offline pause/resume, one simulation tick, bounded slow/fast time presets,
  and the equivalent synchronised host actions in an opted-in dev lobby.
- Warp picker for stock/custom courses and admitted cups, with vehicle and
  entrance choices. Show missing dependencies before attempting a load.
- Session rule overrides for laps/order/AI/items as supported by the typed rule
  adapters, with the correct result/timing array limits and custom-cup ownership.

SCREEN 2 - RACERS / AI / BOSSES

- Select any human or CPU racer and inspect identity, position, orientation,
  velocity/speed, vehicle, lap/checkpoint, place, bananas, items and status.
- Teleport to coordinates, a checkpoint or another selected target; reset to
  track; stop velocity; mark/return to a test position.
- Adjust supported acceleration/top speed/handling/gravity/traction/boost
  parameters, item/ammo/banana counts and temporary invulnerability.
- Freeze/resume CPUs, tune AI/boss pace and other reviewed AI parameters, show
  route/progress and compare behaviour against the current difficulty mod.
- Reset an individual override or all Dev Menu overrides. Do not silently
  stomp a different mod's exclusive AI/racing system.
- Vehicle/character changes perform the necessary model/physics reinitialisation
  or a scene reload. Do not just change an ID byte and hope it works.
- Retain the real native roster/player limits; this is not a hidden promise
  of extra human-player slots or arbitrary racer counts.

SCREEN 3 - OBJECTS / ENTITIES

- Search/filter by name, behaviour, ID, distance, segment and owning mod.
- Select from a list or presentation pick/ray; highlight a target; follow it
  with the inspector; watch supported state/property changes.
- Edit transform, opacity and declared behaviour/collision/trigger parameters.
- Spawn and duplicate supported object templates at the camera/target/coordinates;
  move/rotate them; enable/disable supported behaviours; delete tool-owned spawns.
- Track ownership, capacity and resource requirements. Protect essential racers,
  camera/scheduler owners and unsupported cross-referenced objects from unsafe
  deletion. Stale handles cannot hit a newly allocated object at the same address.
- Undo/redo typed transactions while the original entities/scene still exist.
  An arbitrary API 1 memory patch is not falsely advertised as reversible.

SCREEN 4 - TRACK / COLLISION / ROUTES

- Segment bounds, collision wireframe/normals, surface/material IDs, collision
  floor/ray/sweep probes and hit details.
- Checkpoints, AI route nodes/links, trigger volumes, entrances, spawn positions,
  finish/lap crossings and supported water/surface properties.
- Visualise a selected racer's route/checkpoint and identify nearby obstacles.
- Adjust supported nodes/triggers/spawn points, with a reload when native
  collision/navigation data must be rebuilt.
- Save named test positions, reset a test run quickly, export/import a scene
  adjustment document with content/revision/schema validation and a preview.
- Keep structural geometry authoring in the track tool/reload path. The Dev
  Menu complements Track Lab; it is not an unbounded live mesh editor.

SCREEN 5 - CAMERA / PRESENTATION

- Free camera, follow selected object, spectator, frame target, return to the
  normal camera and coordinate bookmarks using local presentation ownership.
- Camera speed/FOV/smoothing, HUD/debug visibility and screenshot-friendly
  controls. Respect existing Camera++ and multiplayer viewport ownership.
- Never let the Dev Menu silently take over another camera provider; explicit
  temporary ownership/handoff and clean restoration are required.

SCREEN 6 - ENVIRONMENT / AUDIO

- Inspect/tune the original game's fog/ambient and directional parameters,
  supported weather intensity/direction and native scene effects.
- Preflight/reload resource-dependent weather changes; do not call an uninitialised
  rain/snow path. This does not reintroduce the removed atmosphere/RTX system.
- Sequence/sound browser with verified IDs, play/stop/fade commands and local
  volume/debug-mute controls. Respect confirmed audio online and avoid replayed
  duplicate output or stealing the audio device from the engine.

SCREEN 7 - MODS / HOOKS / VALUES

- Installed/active package and module versions, dependencies, conflicts, resources,
  event subscriptions, hook/replacement owners and execution/memory budgets.
- Inspect live API 2 settings and submit supported changes; label API 1 frozen
  settings correctly as next-launch instead of pretending they changed live.
- Typed/property watches, event tracing, callback/native-call diagnostics and a
  searchable decomp symbol/hook catalog. Optional bounded guest-memory inspection
  is explicitly advanced; no host memory or OS command execution.
- Offline compatible reload/reapply/reset via safe points; clear reasons when
  a scene restart or full relaunch is required.

SCREEN 8 - COMMANDS / PRESETS / REPORTS

- Searchable registered command console, completion, parameter validation,
  history and recorded command macros. These are SDK commands, not a shell.
- Save/load named presets, favourites, watches and camera/test bookmarks.
- Export/import development patches and diagnostics with a review/confirmation.
  Store IDs/parameters/source references, not a ROM, extracted Nintendo assets,
  passwords, lobby secrets or someone else's private save.
- Console and buttons use exactly the same permission/transaction pathway.

SCREEN 9 - ONLINE DEVELOPMENT

- Host/client ownership, consent, command authority and each pending request.
- Epoch/frame/confirmation and useful desync/command-validation diagnostics.
- Host approve/deny and revoke command permission; audit recent shared actions.
- A read-only client inspector works without acquiring command permission.
- No one-click unilateral rewind, reload or save mutation during a normal match.

6. SAVE PROTECTION, PERFORMANCE AND FAULTS

- A development session starts in an isolated development save scope before
  game initialisation. Never reroute the immutable save owner halfway through
  play or overwrite an ordinary offline/online save from a tool callback.
- Temporary unlocks/progress use that session image. Export is an explicit
  user action through the established save/storage owner, not automatic.
- Pause/step is controlled at the simulation boundary, not by blocking the UI,
  renderer, network worker or a native function's stack.
- Debug UI/draw/watchers have bounded work and are idle when unused. Filtered
  bulk snapshots and refresh throttles avoid scanning every object on every
  rendered frame. No new ray tracing or full extra scene render for this menu.
- Preserve API 1 limits. For API 2, declare per-package memory/work requests,
  preflight the complete session and expose bounded portable profiles. Do not
  solve every limitation by removing budgets or copying full state per mod.
- Errors identify the mod, callback/command, argument and execution phase.
  Reject invalid transactions without corrupting state. A fatal native/raw
  guest failure may still require a safe scene/session stop; do not claim
  the VM can recover perfectly from arbitrary game-memory/native-call damage.

7. IMPLEMENTATION ORDER AND DELIVERY GATES

Phase A - Freeze the compatibility baseline
   Catalog existing APIs, modules, layouts, data, imports, hooks and current
   example mod digests. Identify stale/contradictory author documentation.
   Keep the existing mod files and saved settings unchanged.

Phase B - Additive loader/runtime and command foundation
   Dual API admission, per-owner module versions, stable handles, capability
   descriptors, phase/authority checks, deterministic command records/results,
   checkpointed state and the development save scope.

Phase C - Decomp adapters and gameplay coverage
   Generate reviewed per-revision metadata/wrappers inside new pipeline output.
   Implement the racer/object/rule/track/resource/collision/environment/audio
   services used by the feature list on both ordinary and owned CPU paths.
   Do not mark a module available before its paths are genuinely connected.

Phase D - Reusable UI/presentation/development layer
   Generic panels/settings/OSK, debug primitives, inspectors, metrics, commands,
   documents/presets and safe-point reload. Maintain simulation/render separation.

Phase E - Complete the example mod
   Implement all nine screens as an ordinary package using those public APIs.
   Source and resources ship with the example. No fake buttons or silent no-ops;
   unsupported states explain the precise resource/phase/authority requirement.

Phase F - Online integration and compatibility review
   Finish opted-in dev-lobby admission/consent, shared command scheduling,
   checkpoint/replay/confirmation and fault handling. Compile/static-inspect
   old and new ABI paths, protected ownership and cross-platform data layouts.
   Provide a user-run acceptance list for existing mods, new tools, course
   changes, entity lifetimes, save isolation and Windows/Linux online sessions.

Phase G - Documentation and v1.0.7 beta 7 packages
   SDK reference and migration guide, full Dev Menu guide, sample projects,
   supported/protected feature matrix, authoring/build/import instructions,
   release notes and updated linked modding documentation.
   Compile/package Windows and Linux with an AppImage, keeping the C ABI
   portable for ARM64/Android rather than requiring per-platform mod binaries.
   Package the Dev Menu .nrm, its complete source and SDK 2.0 authoring kit.
   Runtime/visual/performance/online acceptance remains with the user.

Beta 7 is the SDK/Dev Menu milestone, not a rename of the beta 6 shadow build.
Approval of this plan precedes SDK implementation. Do not merge/push unrelated
work or modify protected dependency/generated directories to deliver it.
