# Nerddi OS Game SDK · Manifest Contract v1

## Master Controller starter path

Nerddi OS now uses one GameHub-derived Master Controller for all titles. Start from `controller-profile.template.json`, save the completed profile under `controllers/profiles/<game>.json`, register the title, then open `../controller-template.php?game=<game>` to preview the exact production controller without creating a room. Do not copy `controller.php` for individual games.

The stable hardware slots are `left_stick`, `right_stick`, `dpad`, `l1`, `l2`, `r1`, `r2`, `triangle`, `circle`, `cross`, and `square`. The profile decides their bindings and labels. Use `dpad` only when the game actually needs digital directions; it replaces the left stick instead of being squeezed beside it. The game receives normalized InputFrame v2 state and publishes player-scoped telemetry, layouts, GameScreen panes, and effects.

Nerddi OS separates **games** from **rooms, identity, pairing, and SmartControllers**. A title declares a compact manifest; Nerddi owns the platform plumbing.

## Manifest
Validate against `nerddi-game.schema.json`. The required fields are:

- `slug`: stable lowercase game id.
- `title`, `publisher`: user-facing metadata.
- `entrypoint`: local path for native games, secure bridge/external entrypoint otherwise.
- `controller_profile`: JSON profile name under `controllers/profiles/`.
- `players.min/max`: 1–8.
- `modes`: supported game modes.
- `capabilities`: short controller/platform capability labels.
- `native`: true when the shared engine ships inside Nerddi OS.
- `bridge`: true when Nerddi wraps an external engine through a controlled integration layer.

## SmartController contract
Controller profiles define touch/analog/button layout. Games read normalized room input from the authenticated host channel and may publish per-player telemetry, private panels, effects, haptics, and live layout switches. A game must never receive permanent CentroShield secrets or another player's private controller credential.

## Network contract
Current Nerddi OS matchmaking supports head-to-head `pong`, `racers`, and `vba27`. Matchmaking assigns identities to a private room and mints credentials only on authenticated handoff. This contract does not require or imply distributed rendering: a game engine that wants multi-console synchronized visuals must implement that simulation/transport separately.

## Security rules
1. Never place permanent secrets in manifests, browser JavaScript, iframe URLs, or controller profiles.
2. Treat room host/controller credentials as short-lived bearer credentials.
3. Use the redacted public room endpoint for lobby/status surfaces.
4. Keep private per-player state on authenticated controller views.
5. Validate all inbound input and telemetry through Nerddi's server normalization.

## Installed manifest API
`GET /api/platform/games.php` returns the validated v1 manifests for installed titles.

## SmartController 3.0

SmartController 3.0 treats the phone as a dynamic personal console rather than a fixed gamepad. A game publishes per-player controller state with:

- `layout`: selects a profile-defined control layout.
- `telemetry`: small live values such as score, phase, stamina, alert, speed.
- `private_screen`: private player information rendered only on that phone (terminal, radar, map, cards, vehicle dashboard, mission status).
- `panel`: private choice/answer data.
- `effect`: haptic/flash feedback.

Reusable controls include `virtual_stick`, `steering_wheel`, `pedal`, `button`, `choice_grid`, `touch_pad`, `keypad`, and `radial_pad`.

The transport contract keeps direct WebRTC and HTTP Fast Relay simultaneously available. Critical button edges are sequenced; analog state is replaceable. Recovery is make-before-break: an existing direct path remains active until the replacement data channels are open.

### Authority modes

`local_authority` is appropriate for solo/couch play where the display browser is the game simulation authority. `server_authority` is reserved for online/ranked play when `NERDDI_MATCH_SERVER_URL` points to a real persistent match service. The OS must not label a local browser simulation as dedicated server authority.

See `controllers/profiles/heist.json` and `games/heist/` for the asymmetric reference implementation.


## Nerddi GameScreen OS

ControlDeck Run 22 promotes the phone center display into a reusable GameScreen operating layer. Every controller state may include a `game_screen` object whose panes map to the standard console modes:

**LIVE · STATS · REPLAY · GAME · COACH · PAUSE**

`LIVE` falls back to `private_screen`, while `STATS` can be derived automatically from `telemetry`. Games may publish richer `replay`, `game`, `coach`, and `pause` panes without rebuilding controller HTML. Each pane can expose `title`, `subtitle`, `signal`, `progress`, `code`, `lines`, `items`, `available`, `empty`, and up to six `actions`. GameScreen actions travel as reliable controller button edges using the `gs_action_<command>` namespace.

Example controller state:

```json
{
  "status": "PLAYING",
  "telemetry": {"score": 12, "stamina": "82%"},
  "private_screen": {"title": "PLAYER HUD", "subtitle": "LIVE POSSESSION"},
  "game_screen": {
    "replay": {"title": "LAST PLAY", "subtitle": "DUNK · 2 PTS", "available": true},
    "coach": {"title": "COACHPAD", "actions": [{"id": "coach_open", "label": "OPEN COACH"}]},
    "pause": {"title": "GAME RUNNING", "actions": [{"id": "pause_toggle", "label": "PAUSE", "tone": "primary"}]}
  }
}
```

The platform owns rendering, mode switching, privacy, controller transport, and fallback handling. A game only publishes player-scoped GameScreen state.

### Run 23 game-feel tuning

Native games may consume `assets/game-tuning.js` after `NerddiGameInput` to apply deterministic game-specific response behavior (repeat timing, steering curves, sports pace, role movement). This layer must never replace or bypass InputFrame/FastPath; it only interprets already-normalized game input.

## ControlDeck Run 24 adaptive hardware
Controller profiles may declare `motion` inside a layout with `mode: "steer"` or `mode: "aim"`. Motion is always opt-in and touch remains the fallback. A gamepad layout may also declare a `virtual_stick` with `slot: "right_stick"`; the value travels in canonical InputFrame v2 `frame.right` without changing FastPath or relay protocols. Games that want a player-selectable controller personality can set top-level `remember_layout: true`; the controller restores that preference through a compact reliable `layout_pref_<layout>` action and the game remains authoritative over the final live layout.

## Game-published tool computer

The GameScreen is an interactive computer inside the controller. Any controller state pane (`private_screen`, `game_screen.game`, `game_screen.coach`, and the other GameScreen panes) may publish a `tool` object. Run 29 supports `keypad`, `piece_preview`, `choice_grid`, and `touch_pad`. Tool buttons emit the declared canonical binding through the same sequenced FastPath, relay, and dedicated database hook as physical controls.

The player can expand the tool computer to the full phone screen and minimize it back into the controller. The game can therefore keep its normal controller hardware while temporarily turning the center screen into a vault keypad, surveillance console, playbook, map, puzzle surface, inventory, dialogue choice, or next-piece display.

A gamepad layout with both `left_stick` and `dpad` may declare `direction_modes` with `options: ["stick", "dpad", "both"]`. Nerddi OS remembers the player's selection. In `both` mode the joystick is stacked above the D-pad rather than sharing the same space.