CMAPI Mod Menu 0.2.2

CMAPI Mod Menu is an optional, actionable in-game trainer and command interface integrated into the CMAPI runtime. Its version is intentionally independent:

CMAPI             1.0.0
CMAPI Mod Menu    0.2.2

The menu is an experimental beta. CMAPI's public API, launcher, backups, console, and mod loading are the release-critical product; the optional menu may still have documented UI/controller rough edges. Safety defects—background game activation, stuck input/cursor state, repeated state oscillation, or save mutation—are blockers even during beta.

Known beta limitations in the current checkpoint

• The L3+R3 controller hold did not open the menu reliably on the latest physical-controller test. Use Insert or cmapi_inject/cmapi_uninject from the external console. View+Menu remains intentionally unused because Steam owns that chord on common configurations.
• Inventory's Browse/Search Item Catalog submenu did not activate reliably in the latest in-game test. The external items and give_item commands remain the supported fallback and use the same authoritative item IDs.

These two navigation defects are explicitly accepted only for Mod Menu 0.2.2 beta. Input leaking into Planet Crafter, a stuck cursor after hide/uninject, save mutation, or repeating trainer side effects are still release blockers.

Both version constants live in CMAPI.Shared.dll as CMAPIVersion.Current and CMAPIModMenuVersion.Current, so the launcher, runtime, diagnostics, mods, and menu can report the same authoritative values.

The menu is not a separately installed DLL. CMAPI creates no menu GameObject or IMGUI callback until the player runs cmapi_inject for the current process.

Inject, hide, and remove

cmapi_menu
cmapi_inject
cmapi_uninject

Commands are case-insensitive, so CMAPI_Inject and CMAPI_Uninject work too.

• cmapi_menu reports the menu version, state, and configured keyboard toggle.
• cmapi_inject creates one overlay. Repeating it is safe and only shows the existing instance.
• Insert hides or shows the injected overlay by default. Set ModMenuToggleKey in CMAPI\config.json while CMAPI is closed to choose another Unity Input System key.
• Before showing, CMAPI compares the configured key to Planet Crafter's live input bindings. A collision is rejected for that session and CMAPI selects an unbound fallback key instead of invoking both actions.
• cmapi_uninject destroys the overlay and disables/restores all trainer state. CMAPI, its console, save backups, public APIs, and installed mods remain active.

Existing F8 and F9 configurations migrate to Insert because Planet Crafter 2.008 uses F8 for feedback/help and F9 can invoke the Steam store/wishlist path. Use the dedicated Insert key. On compact keyboards where Ins is printed under numpad 0, that secondary function may require Num Lock off or an Fn modifier.

Injection fails closed until a local PlayerInputDispatcher exists. If no world is loaded, the module stays injected but hidden and explains that the player must load a world before trying again.

Compact drill-down pages

Menu actions execute the same canonical commands as the external console. They therefore retain the same parsing, bounds, host checks, active-weather refusal, logging, native HUD notifications, and error text. The menu does not maintain a second mutation implementation.

Trainer behavior and limits

Trainer commands exist only when EnableCheatCommands is true. Every trainer mutation also requires the local player to be the world host; this host rule is not weakened by RequireHostForCheatCommands.

Survival locks use the game's public network-aware gauge paths at a bounded five updates per second and send nothing while a gauge is already full. God Mode is a survival lock, not a patch over every scripted game event; test new story sequences and extreme damage on a backed-up save.

Planet Crafter 2.008 has no separate stamina gauge in the tested assembly. CMAPI labels health as health/food and exposes movement speed/flight instead of inventing a value the game does not own.

Infinite Power is an isolated, fail-closed adapter over the tested runtime's machine-energy manager. Planet Crafter normally recalculates that manager every two seconds and after some machine changes. While enabled, CMAPI suspends the periodic checker and its immediate recalculation gate, applies one powered transition to existing requesters, and keeps new requests on the stable powered state without replaying status transitions. Switching it off or uninjection starts one native grid calculation and resumes the normal checker. It does not change construction, generator, consumer, or save data.

Reversible lifecycle

CMAPI captures the local player's original fly flag, walk speed, run speed, and fall-damage component state before changing them. It restores those values when the corresponding controls are disabled, the controlled player changes, host authority is lost, the menu is uninjected, or CMAPI shuts down. Survival locks hold no persistent player setting. Power returns to the game's calculated grid.

Uninjecting does not unload arbitrary mods. Safe live mod unloading still needs an enforceable cleanup contract for patches, created objects, tasks, event subscriptions, commands, and mod-owned state.

Polished, resolution-aware layout

The default frame is 410 by 530 pixels and shrinks against the current Unity safe area. It rechecks the render size every frame, so windowed, borderless, fullscreen, resizing, resolution changes, and display safe areas remain clamped. The old dashboard tabs and cards were replaced by a classic trainer layout: a narrow vertical list, one cyan selection row, concise values on the right, and drill-down pages. Long pages and activity output share one bounded scroll area, so neither can be pushed below the window. Drag the header to move it; the target icon restores the current safe-area center.

Every normal, hover, active, focused, selected, and on-state for the window, rows, buttons, text fields, and activity panel is explicitly styled. This prevents Unity from falling back to Planet Crafter's bright focused-window skin when a menu control is clicked.

The position remains for the current injection. Persistent layout/scale settings remain deferred until the UI format is stable.

Controls

Mouse and keyboard

• Click rows, fields, toggles, actions, and scroll normally.
• Drag the header to move; click the target icon to recenter.
• Press Insert by default to hide/show. Change ModMenuToggleKey in config.json.
• Up/down selects a row, Enter activates it, and Backspace returns to the main page or hides the menu from the main page. These keys do not navigate while a CMAPI text field owns keyboard focus.
• Click Uninject or run cmapi_uninject to remove the menu and trainer state.

Controller

• D-pad up/down: select an actionable control.
• A: open a page or activate the selected control.
• LB/RB: scroll long content by one block.
• X: center the window.
• B: return to the main page; from there, hide the menu.
• Hold L3 + R3 (press both sticks) for about half a second: hide/show while injected. CMAPI no longer uses View + Menu because Steam reserves that chord for its overlay on common controller configurations.
• Y twice within three seconds: uninject.

Text entry still requires a keyboard or platform text-input layer. When the experimental Item Catalog submenu activates, it can be browsed and selected entirely with the controller, and its amount row cycles common values. Every toggle, preset, quick grant, diagnostic, weather entry, and recovery action remains controller-activatable. The cyan selection automatically scrolls into view and shows what A will run; green indicates an enabled trainer toggle.

Cursor and multiplayer

When shown, the overlay captures the prior cursor lock/visibility, the exact set of enabled action maps on Planet Crafter's PlayerInputDispatcher, and the game EventSystem UI-input state. It disables both game input layers so movement, pause, exit, inventory, construction, mouse clicks, and controller submissions cannot fire behind CMAPI. IMGUI continues receiving the mouse, which stays visible and unlocked no matter which device opened the menu. Hiding, uninjection, component disable, or destruction restores only the states CMAPI captured. If a Planet Crafter window is already open, cursor ownership returns to that window instead of blindly restoring a gameplay lock. A scene transition is rescanned while the menu is visible.

If that capture cannot be established, the overlay immediately hides and reports why. CMAPI reads raw keyboard/controller devices for its own UI, so its navigation continues while Planet Crafter's action maps are disabled. The overlay does not stop simulation time or pause a multiplayer world.

The L3 + R3 hold starts input capture immediately and opens only after its hold threshold. Releasing early restores the captured maps. CMAPI also inspects the live gamepad bindings and reports any individual L3/R3 overlaps through cmapi_menu and the log.

See INPUT-CAPTURE-RESEARCH.md for the inspected game surface, restoration contract, and failure behavior.