# RunXR — building games for the platform (spec for AI agents)

> RunXR (https://runxr.app) is a controller-first web game portal. Any HTML5 game that runs in a browser can be listed. A game is one catalog entry (title, artwork, metadata) plus a URL that RunXR loads in a full-screen iframe. Human guide: https://runxr.app/docs

## Two ways to provide a game
1. Hosted (preferred, "Poki-style"): the game lives on your own HTTPS host (Vercel, Netlify, GitHub Pages, itch.io...). Catalog URL = full https:// address.
2. Uploaded: static files placed under RunXR's `games/` folder, served at `/games/<file>.html` with the right headers. Catalog URL = `/games/your-game.html`.

## Hard requirements (a game is rejected if these fail)
- Serve over HTTPS. No mixed content.
- Must load inside an iframe: do NOT send `X-Frame-Options: DENY|SAMEORIGIN`; if you send a CSP it must include `frame-ancestors https://runxr.app`.
- Never navigate the top window (`window.top.location`, `target="_top"`); never assume a fixed viewport — the frame is full-screen at any aspect ratio, read `innerWidth/innerHeight` and listen to `resize`.
- Fully playable with a gamepad only (every screen: title, menus, pause, game over). Keyboard fallback must also work. No mouse-only or text-input-only flows.
- Reserved input, never bind these: `Esc`, `Start + Select` together, the Guide/Home button. All three open the RunXR Quick Menu (Resume / Restart / Fullscreen / Favorite / Quit) over the game.
- Pause when told: freeze gameplay, timers and audio on `gs-pause` (`RunXR.onPause`), continue on `gs-resume` (`RunXR.onResume`). The game keeps running behind the Quick Menu otherwise.
- Start = pause. A = confirm/primary. B = back/cancel. D-pad or left stick = move/navigate.

## Iframe permissions RunXR grants the game
`gamepad, fullscreen, autoplay, accelerometer, gyroscope, xr-spatial-tracking` (pointer lock is not granted). Audio still needs a user gesture: create/resume the AudioContext on the first button press.

## The RunXR SDK (optional, recommended)
Include once: `<script src="https://runxr.app/sdk/runxr.js"></script>` — inert outside RunXR, safe to ship permanently.
- `RunXR.ready()`  — call after the first frame renders; hides the launcher's "how to exit" toast.
- `RunXR.score(n)` — call whenever the score changes; RunXR keeps each signed-in player's best per game and shows it on the detail card.
- `RunXR.menu()`   — open the RunXR Quick Menu (from your own pause screen).
- `RunXR.exit()`   — quit straight back to the RunXR menu (wire to your own Quit button).
- `RunXR.onPause(fn)` / `RunXR.onResume(fn)` — Quick Menu opened / closed; freeze and unfreeze the game.
- `RunXR.paused`   — boolean, true while the Quick Menu is open.
- `RunXR.embedded` — boolean, true only inside RunXR.
The SDK also binds Esc, Start+Select and Guide to menu() and posts `gs-hello` on load. `window.GameStation` is a legacy alias.

## postMessage protocol (what the SDK does; any game may post these to window.parent with target origin "*")
Game -> RunXR:
- `{ type: 'gs-hello' }`                informational
- `{ type: 'gs-ready' }`                hides the exit hint toast
- `{ type: 'gs-score', score: <number> }` records the score (best is kept)
- `{ type: 'gs-menu' }` or `{ type: 'gp-menu' }`  open the RunXR Quick Menu
- `{ type: 'gs-exit' }` or `{ type: 'gp-exit' }`  quit straight to the RunXR menu
RunXR -> game:
- `{ type: 'gs-pause' }`   Quick Menu opened: freeze
- `{ type: 'gs-resume' }`  Quick Menu closed: continue
RunXR -> game (same-origin uploaded games only):
- `{ type: 'gp-key', key: <KeyboardEvent.key>, down: <bool> }` forwarded keyboard events

## Input mapping (Gamepad API standard layout, button indices)
A=0 B=1 X=2 Y=3 LB=4 RB=5 LT=6 RT=7 SELECT=8 START=9 UP=12 DOWN=13 LEFT=14 RIGHT=15 HOME=16; left stick = axes[0] (x), axes[1] (y), use a ~0.25 dead zone.
Keyboard mirror: Arrows/WASD -> D-pad · Space/Enter/Z -> A · X -> B · C -> X · V -> Y · Q/E -> LB/RB · P -> Start · Shift -> Select · Esc -> Quick Menu.
RunXR's own prompts adapt to Xbox (A/B/X/Y), PlayStation (✕○□△) and Nintendo (B/A/Y/X) pads and can put confirm on the right face button; games should still read the standard mapping (index 0 = bottom face button).
Poll `navigator.getGamepads()` once per frame; track "held" (down now) vs "pressed" (down now, up last frame).

## Uploaded games: helper library
`<script src="/games/lib/pad.js"></script>` gives `Pad` — `poll() held(btn) pressed(btn) axis(0|1) dir() vdir() menu() exit() sysPaused()` (GameKit.loop freezes while sysPaused()) with buttons `A B X Y LB RB LT RT START SELECT UP DOWN LEFT RIGHT HOME` — plus a touch overlay (thumb-stick, A, B, X, Pause, Menu) on phones/tablets, and `GameKit` — `setup(w,h) loop({update,draw,w,h,ctx}) text() overlay() best(key) setBest(key,v) beep() rand(a,b)`.

## Rendering & UX rules
- Render to a fixed logical resolution (e.g. 960x540 or 1280x720) on a canvas and letterbox it with CSS to the window. Set `touch-action: none` on the canvas; hide overflow.
- Title screen starts on A (not on click). Show a short controls hint. Large, high-contrast text readable from a couch; no hover-only UI.
- Save progress/high scores in localStorage. Keep load small; show a loading state.
- Touch: to tick Mobile Phone / Tablet, ship on-screen controls (uploaded games get them from pad.js automatically).
- Engines: Phaser, PixiJS, Three.js, Godot, Unity WebGL, Construct, GDevelop, PlayCanvas, Babylon.js all work if the exported page follows the rules above.

## Making an EXISTING game compatible — checklist
1. Embeddable: HTTPS + no frame-blocking headers (test with a local `<iframe src=...>` page).
2. Frame-safe: no top navigation; responsive to resize; don't depend on owning fullscreen.
3. Add gamepad support (paste the Pad block from the template); every menu reachable with the pad.
4. Unbind Esc and Guide; never require Start+Select (all open the RunXR Quick Menu).
5. Add the SDK: ready() after load, score(n) on change, exit() from Quit, pause in onPause()/resume in onResume().
6. Touch controls if targeting phones/tablets; `touch-action: none`.
7. Resume AudioContext on first input.
8. Assets over HTTPS with CORS where needed.
9. Prepare listing artwork + metadata (below), then add it in the Dev Studio.

## Listing fields (Dev Studio form)
Required for developers: title (<=120 chars), description (<=2000), category, age rating, game URL (https://... or /games/... path), thumbnail URL, cover URL.
Optional: search title (<=60 chars, shown in Google instead of the title; use the words people search for, e.g. "Brick Blaster - Free Brick Breaker Game Online"), background URL, features, device compatibility, controls (one line per control, shown on the detail card).
- Age ratings: EC (Early Childhood), E (Everyone), E10 (Everyone 10+), T (Teen), M (Mature 17+)
- Features: Gamepad Controls, VR, Multiplayer, Local Co-op, Screen Controls
- Devices: VR, Mobile Phone, Retro Emulator, TV, Tablet, Computer
- Thumbnail: landscape 16:9 (used on tiles/shelves, small screens). Cover: portrait 3:4 box art (Shelf/Case/Carousel/Coverflow views, large screens). Background: wide hero image (optional; falls back to cover). Host images over HTTPS anywhere.
- "Verified" badge is admin-only. Players leave 1-5 star reviews with comments (one per player per game).

## Publishing flow
Sign in -> account menu (Select on a controller) -> "Activate dev mode" -> Dev Studio -> Add game -> fill the fields -> save. New games are drafts until a moderator publishes them. Published games get a shareable deep link at https://runxr.app/<slug>. RunXR is an installable PWA.

## Starter template (https://runxr.app/sdk/template.html)
Single self-contained HTML file that already satisfies every rule above. Copy it and replace update()/draw().

```html
<!doctype html>
<!-- RunXR starter game. Works standalone AND inside RunXR (https://runxr.app/docs). -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, user-scalable=no">
<title>My RunXR Game</title>
<style>
  html, body { margin: 0; height: 100%; background: #07090f; overflow: hidden; touch-action: none; }
  canvas { display: block; margin: 0 auto; background: #10162a; }
</style>
</head>
<body>
<canvas id="c"></canvas>

<!-- 1. RunXR SDK: inert outside RunXR. Reports ready/score; Esc / Start+Select / Guide open the RunXR Quick Menu. -->
<script src="https://runxr.app/sdk/runxr.js"></script>

<script>
// 2. Input: gamepad + keyboard with the RunXR button names.  (No dependency on RunXR; copy freely.)
//    Buttons: A B X Y LB RB LT RT SELECT START UP DOWN LEFT RIGHT   Keyboard: arrows/WASD, Space/Enter=A, X=B, C=X, V=Y, P=Start
const Pad = (() => {
  const MAP = { A: 0, B: 1, X: 2, Y: 3, LB: 4, RB: 5, LT: 6, RT: 7, SELECT: 8, START: 9, UP: 12, DOWN: 13, LEFT: 14, RIGHT: 15 };
  const KEYS = { ArrowUp: 'UP', ArrowDown: 'DOWN', ArrowLeft: 'LEFT', ArrowRight: 'RIGHT', w: 'UP', s: 'DOWN', a: 'LEFT', d: 'RIGHT', ' ': 'A', Enter: 'A', x: 'B', c: 'X', v: 'Y', p: 'START', Shift: 'SELECT' };
  const keys = {}; let cur = {}, prev = {};
  addEventListener('keydown', (e) => { const k = KEYS[e.key.length === 1 ? e.key.toLowerCase() : e.key]; if (k) { keys[k] = true; e.preventDefault(); } });
  addEventListener('keyup', (e) => { const k = KEYS[e.key.length === 1 ? e.key.toLowerCase() : e.key]; if (k) keys[k] = false; });
  addEventListener('blur', () => { for (const k in keys) keys[k] = false; });
  function poll() {
    prev = cur; cur = { ...keys, ax: 0, ay: 0 };
    for (const g of navigator.getGamepads ? navigator.getGamepads() : []) {
      if (!g) continue;
      for (const n in MAP) if (g.buttons[MAP[n]]?.pressed) cur[n] = true;
      const ax = g.axes[0] || 0, ay = g.axes[1] || 0;
      if (Math.abs(ax) > 0.25) { cur.ax = ax; cur[ax < 0 ? 'LEFT' : 'RIGHT'] = true; }
      if (Math.abs(ay) > 0.25) { cur.ay = ay; cur[ay < 0 ? 'UP' : 'DOWN'] = true; }
    }
  }
  const held = (n) => !!cur[n], pressed = (n) => !!cur[n] && !prev[n];
  return { poll, held, pressed, axis: (i) => (i ? cur.ay : cur.ax) };
})();

// 3. Fixed logical resolution, letterboxed to the window (RunXR frames are full-screen, any aspect).
const W = 960, H = 540, c = document.getElementById('c'), ctx = c.getContext('2d');
c.width = W; c.height = H;
function fit() { const s = Math.min(innerWidth / W, innerHeight / H); c.style.width = Math.floor(W * s) + 'px'; c.style.height = Math.floor(H * s) + 'px'; }
addEventListener('resize', fit); fit();

// 4. Game state
let x = W / 2, y = H / 2, score = 0, paused = false, last = performance.now();
function update(dt) {
  const speed = 320;
  if (Pad.held('LEFT')) x -= speed * dt; if (Pad.held('RIGHT')) x += speed * dt;
  if (Pad.held('UP')) y -= speed * dt; if (Pad.held('DOWN')) y += speed * dt;
  x = Math.max(20, Math.min(W - 20, x)); y = Math.max(20, Math.min(H - 20, y));
  if (Pad.pressed('A')) { score += 10; if (window.RunXR) RunXR.score(score); } // report best score to RunXR
}
function draw() {
  ctx.fillStyle = '#10162a'; ctx.fillRect(0, 0, W, H);
  ctx.fillStyle = '#7c9cff'; ctx.beginPath(); ctx.arc(x, y, 20, 0, Math.PI * 2); ctx.fill();
  ctx.fillStyle = '#fff'; ctx.font = '800 24px system-ui, sans-serif'; ctx.textAlign = 'left'; ctx.fillText('Score ' + score, 20, 36);
  ctx.textAlign = 'center'; ctx.font = '600 16px system-ui, sans-serif'; ctx.fillStyle = '#8a94ad';
  ctx.fillText(paused ? 'PAUSED — Start to resume' : 'Move: stick / arrows · A: score · Start: pause · Guide / Start+Select / Esc: RunXR menu', W / 2, H - 24);
}
function frame(now) {
  requestAnimationFrame(frame);
  const dt = Math.min(0.05, (now - last) / 1000); last = now;
  Pad.poll();
  if (Pad.pressed('START')) paused = !paused;   // Start = pause. Never bind Start+Select, Guide or Esc: RunXR uses them.
  if (!paused) update(dt);
  draw();
}
requestAnimationFrame(frame);
if (window.RunXR) {
  RunXR.ready();                             // 5. tell RunXR the game is up (hides the launcher's hint toast)
  RunXR.onPause(() => { paused = true; });   // 6. freeze while the RunXR Quick Menu is open
}
</script>
</body>
</html>

```