dotframe 0.1.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "dotframe",
+  "version": "0.1.0",
+  "description": "TS-first game engine and agent-first CLI: one codebase for web, Discord, iOS and native binaries",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@scriptc/runtime-win32-x64-msvc": "0.2.0",
+    "@types/bun": "^1.4.2",
+    "@webgpu/types": "^0.1.74",
+    "typescript": "^7.0.2"
+  },
+  "bin": {
+    "dotframe": "cli/main.ts"
+  },
+  "files": [
+    "cli",
+    "src",
+    "skills",
+    "templates",
+    "assets",
+    "tools/*.ts",
+    "native",
+    "scripts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crafter-games/dotframe"
+  },
+  "homepage": "https://github.com/crafter-games/dotframe#readme",
+  "keywords": [
+    "game-engine",
+    "webgpu",
+    "typescript",
+    "scriptc",
+    "rollback",
+    "netplay",
+    "agent",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/build-native.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Builds a native binary. Usage: scripts/build-native.sh <macos|windows> <example-name | path/to/main.native.ts> [out-name]
+set -e
+target=$1
+entry=${2:-triangle}
+root=$(cd "$(dirname "$0")/.." && pwd)
+case $entry in
+  *.ts) entry_file=$(cd "$(dirname "$entry")" && pwd)/$(basename "$entry"); name=${3:-$(basename "$(dirname "$entry_file")")} ;;
+  *) entry_file="$root/examples/$entry/main.native.ts"; name=${3:-$entry} ;;
+esac
+mkdir -p "$root/build/$target"
+case $target in
+  macos)
+    for unit in df_native df_audio; do
+      clang -O2 -c "$root/native/$unit.c" -I"$root/vendor/SDL3-3.4.16/include" -I"$root/vendor/wgpu/macos/include" \
+        -mmacosx-version-min=14.0 -o "$root/build/macos/$unit.o"
+    done
+    ar rcs "$root/build/macos/libdf_native.a" "$root/build/macos/df_native.o" "$root/build/macos/df_audio.o"
+    cd "$(dirname "$entry_file")" && scriptc build "$(basename "$entry_file")" --ffi "$root/native/ffi.macos.json" \
+      -o "$root/build/macos/$name"
+    ;;
+  windows)
+    for unit in df_native df_audio; do
+      zig cc -target x86_64-windows-gnu -O2 -c "$root/native/$unit.c" -I"$root/vendor/SDL3-3.4.16/include" \
+        -I"$root/vendor/wgpu/windows/include" -o "$root/build/windows/$unit.o"
+    done
+    zig ar rcs "$root/build/windows/libdf_native.a" "$root/build/windows/df_native.o" "$root/build/windows/df_audio.o"
+    cd "$(dirname "$entry_file")" && SCRIPTC_RUNTIME_PACK="$root/node_modules/@scriptc/runtime-win32-x64-msvc" \
+      SCRIPTC_TARGET=x86_64-windows-gnu scriptc build "$(basename "$entry_file")" --ffi "$root/native/ffi.windows.json" \
+      --windows-subsystem gui -o "$root/build/windows/$name.exe"
+    ;;
+  *) echo "usage: $0 <macos|windows> <example | path/to/main.native.ts> [out-name]" >&2; exit 2 ;;
+esac

package/scripts/build-web.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Bundles an example for the browser. Usage: scripts/build-web.sh [example]
+set -e
+example=${1:-triangle}
+root=$(cd "$(dirname "$0")/.." && pwd)
+out="$root/build/web/$example"
+mkdir -p "$out"
+bun build "$root/examples/$example/main.web.ts" --outfile "$out/main.js" --target browser
+cp "$root/examples/$example/index.html" "$out/"
+mkdir -p "$out/assets" && cp -R "$root"/assets/. "$out/assets/"

package/scripts/vendor.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+# Downloads wgpu-native prebuilts and builds SDL3 static for a target. Usage: scripts/vendor.sh <macos|windows>
+set -e
+target=$1
+root=$(cd "$(dirname "$0")/.." && pwd)
+wgpu_version=v29.0.1.1
+sdl_version=3.4.16
+vendor="$root/vendor"
+mkdir -p "$vendor/build"
+
+case $target in
+  macos) wgpu_asset=wgpu-macos-aarch64-release ;;
+  windows) wgpu_asset=wgpu-windows-x86_64-gnu-release ;;
+  *) echo "usage: $0 <macos|windows>" >&2; exit 2 ;;
+esac
+
+if [ ! -f "$vendor/wgpu/$target/lib/libwgpu_native.a" ]; then
+  mkdir -p "$vendor/wgpu/$target"
+  curl -fsSL "https://github.com/gfx-rs/wgpu-native/releases/download/$wgpu_version/$wgpu_asset.zip" -o "$vendor/wgpu/$target.zip"
+  unzip -oq "$vendor/wgpu/$target.zip" -d "$vendor/wgpu/$target"
+  rm "$vendor/wgpu/$target.zip"
+fi
+
+if [ ! -d "$vendor/SDL3-$sdl_version" ]; then
+  curl -fsSL "https://github.com/libsdl-org/SDL/releases/download/release-$sdl_version/SDL3-$sdl_version.tar.gz" | tar xz -C "$vendor"
+fi
+
+if [ ! -f "$vendor/build/sdl-$target/libSDL3.a" ]; then
+  case $target in
+    macos) extra="-DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0" ;;
+    windows) extra="-DCMAKE_TOOLCHAIN_FILE=$vendor/toolchain/zig-windows.cmake" ;;
+  esac
+  cmake -S "$vendor/SDL3-$sdl_version" -B "$vendor/build/sdl-$target" -DCMAKE_BUILD_TYPE=Release \
+    -DSDL_SHARED=OFF -DSDL_STATIC=ON -DSDL_TEST_LIBRARY=OFF $extra
+  cmake --build "$vendor/build/sdl-$target" -j 4
+fi

package/skills/assets/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: assets
+description: Asset licensing and loading for dotframe games. Use when adding sprites, audio, or fonts, or before any release or store build.
+---
+# assets
+
+- Mark every asset you cannot distribute in `assets.localOnly` in dotframe.json (paths relative to the repo). `dotframe build <target> --release` fails with `ASSETS_LOCAL_ONLY` while any of them exists. Debug builds and local play are unaffected.
+- To ship, replace the files with licensed ones (original art, CC0, or licensed packs), record the source and license next to them, then remove the path from `localOnly`.
+- Fonts render through SDF atlases baked by `tools/bake-font.c`. Keep the font license (for example SIL OFL) with the atlas.
+- Headless runs (`sim`, `replay`, `desync`) skip asset loading. If gameplay depends on asset data (sprite boxes, frame counts), load that data in headless too, or the sim will differ from the real game.
+- `snap` loads assets from the game root over HTTP, so asset paths must be relative to the repo root.

package/skills/core/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: core
+description: Core dotframe usage. Read before running any dotframe command: the edit, sim, snap, replay loop, the Sim contract, the trust ladder, and how to read errors.
+---
+# dotframe core
+
+dotframe is a TypeScript game engine. One codebase runs on the web (WebGPU), in Discord Activities, and as native macOS, Windows and iOS builds. The CLI lets an agent play the game without a screen: the simulation is deterministic, so the same seed and inputs always produce the same state.
+
+## The loop
+
+1. Edit game code.
+2. `dotframe sim --mash 7 --frames 600 --json`: run it headless and read `state` and `checksum`.
+3. `dotframe snap --frame 300 --mash 7 --out f300.png`: render one frame with the real WebGPU renderer, then open the PNG and look at it. The JSON state tells you what the simulation did; only the image tells you what a player sees.
+4. `dotframe replay verify replays/*.json`: golden replays must still pass. If a change is meant to alter gameplay, re-record them on purpose and say so.
+5. For online games, `dotframe desync` (see `dotframe skills get netplay`).
+6. Only then `dotframe build <target>`.
+
+Never claim a visual change works from the JSON alone. Snap it and look.
+
+## Inputs
+
+- `--mash <seed>`: random mashing players, new input every 6 frames. Good default for smoke tests.
+- `--inputs file.jsonl`: one line per frame, `[p0, p1]`, or sparse `{"frame": 120, "inputs": [p0, p1]}` held until the next line. Each input is the game's JSON shape (for example `{"right": true, "attack": true}`) or an already-encoded number.
+- `--seed <n>` seeds the simulation; `--options '<json>'` overrides match options (stage, characters, stocks).
+- `--every <n>` on `sim` adds a checksum trace.
+
+## The Sim contract
+
+`dotframe.json` names a module (`"sim": "sim.ts"`) whose default export is `defineSim({...})` from `dotframe/src/sim`: `players`, `window`, `options`, `neutral`, `encode`, `random`, and `create(platform)` returning `start`, `step`, `checksum`, `state`, `over`, `save`, `restore`, and optionally `inspect` and `render`. Rules that keep it honest:
+
+- All simulation state changes only inside `step`. `render` reads, never writes (no spawning particles or texts from draw code).
+- Randomness comes from a seeded generator that `save`/`restore` capture.
+- `inspect` returns the whole state graph so `desync` can name the exact field that differs.
+
+## Trust ladder
+
+| Level | Commands | Rule |
+|---|---|---|
+| Read | `sim`, `snap`, `replay verify`, `desync`, `doctor`, `config get`, `skills` | Run freely |
+| Local write | `build`, `replay record`, `config set`, `new`, `dev`, `doctor --fix` | Run freely, report what changed |
+| External | `deploy`, `relay deploy`, `device install` | Run `--dry-run` first, show the plan, rerun with `--yes` only after the human approves |
+
+`--yes` is the human's approval, not yours. Never add it on your own.
+
+## Output and errors
+
+Pass `--json` and read `ok`. Errors look like `{"ok": false, "error": {"code", "message", "fix", "skill"}}`. Apply `fix`, and when it is not obvious run `dotframe skills get <skill>`. Exit codes: 0 ok, 1 failure, 2 approval required. Full list: `dotframe skills get core --full`.
+
+## Other guides
+
+`dotframe skills list`. Load the one that matches the task: netplay, export-web, discord, ios, macos, relay, game-design, assets.

package/skills/core/references/errors.md

@@ -0,0 +1,22 @@
+# Error codes
+
+| Code | Meaning | Fix |
+|---|---|---|
+| NO_CONFIG | No dotframe.json here or above | cd into the game, or `dotframe new` |
+| BAD_CONFIG | dotframe.json does not parse | Fix the JSON |
+| NO_SIM / SIM_MISSING / BAD_SIM | The sim module is not set, missing, or not `defineSim` | See the Sim contract in core |
+| INPUTS_MISSING / BAD_INPUTS | Inputs file missing or a line has the wrong shape | One JSON array or `{frame, inputs}` per line, one input per player |
+| BAD_OPTIONS | `--options` is not a JSON object | Quote it: `--options '{"stocks": 1}'` |
+| UNKNOWN_TARGET | Target not in dotframe.json | Use a listed target or add one |
+| STEP_FAILED | A build step exited non-zero | Read the step output; `dotframe doctor` |
+| ASSETS_LOCAL_ONLY | A release would ship unlicensed assets | See `assets` |
+| APPROVAL_REQUIRED (exit 2) | External action without `--yes` | Show the `--dry-run` plan to the human |
+| DEPLOY_SOURCE_DIR | Deploy dir looks like source (repo root, .git, dotframe.json) | Point `out` at the build folder |
+| NOT_BUILT | Artifact missing | `dotframe build <target>` |
+| CONFIG_PLACEHOLDER | Template value never filled in | `dotframe config set ...` |
+| DEPLOY_FAILED / INSTALL_FAILED | Provider command failed | Message carries the provider output |
+| TOOL_MISSING | A required CLI is not installed | `dotframe doctor` lists the install command |
+| SNAP_TIMEOUT / SNAP_PAGE_ERROR / BROWSER_FAILED | The snap page did not report ready | Usually no WebGPU in the browser; see message |
+| UNSUPPORTED | The command does not apply (e.g. desync on a 1-player sim) | |
+| REPLAY_MISSING | Replay file not found | `dotframe replay record` |
+| UNKNOWN_SKILL / UNKNOWN_TEMPLATE / UNKNOWN_COMMAND | Typo | Read the `fix` list |

package/skills/discord/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: discord
+description: Run a dotframe web build as a Discord Activity. Use when setting up or debugging a Discord Activity, its URL mappings, the relay path, or stale bundles inside Discord.
+---
+# discord
+
+A Discord Activity is the web build served through Discord's proxy, so `dotframe build discord` and `dotframe deploy discord` use the web pipeline (see `export-web`).
+
+- URL mappings in the Discord developer portal: `/` to the web deployment, `/relay` to the relay. The game connects to `wss://<activity host>/relay`, never to an outside host (the proxy blocks it).
+- The room is the Activity instance id, so everyone in the same launch meets.
+- Discord caches aggressively. Hashed bundle names plus a no-cache `index.html` fix it; if a change does not show up, check the bundle hash in the served page first.
+- Test 1P vs CPU first, then online. Online quality is bound by relay latency (see `relay`); run `dotframe desync --latency <measured ping>` before blaming the netcode.

package/skills/export-web/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: export-web
+description: Build and deploy the web target of a dotframe game. Use when bundling for the browser, serving locally, or deploying to Vercel.
+---
+# export-web
+
+```sh
+dotframe build web --json            # runs targets.web.steps
+dotframe dev                         # build, serve on :5173, rebuild on change
+dotframe deploy web --dry-run        # show the plan
+dotframe deploy web --prod --yes     # only after the human approved the plan
+```
+
+## Rules
+
+- Deploy only the built folder (`targets.web.out`). The CLI refuses a folder that looks like source (repo root, `.git`, `dotframe.json`): that mistake once put the wrong game in production.
+- Do not connect the repo to Vercel's Git integration for these games. A push deploys the repo root.
+- Content-hash the bundle (`main.<hash>.js`) and serve `index.html` with `Cache-Control: no-cache`, so browsers and Discord's proxy never run a stale build.
+- `deploy` without `--prod` makes a preview. Prefer it for checks.
+- Verify a deploy by opening the URL with agent-browser and taking a screenshot, not by the exit code.

package/skills/game-design/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: game-design
+description: Start and structure a new dotframe game. Use when scaffolding a game, choosing a template, or organizing game state so it stays deterministic and testable.
+---
+# game-design
+
+```sh
+dotframe new my-game --template fighter    # or platformer, blank
+cd my-game && dotframe sim --mash 7 --json && dotframe dev
+```
+
+Templates: `fighter` (two players, knockback, stocks), `platformer` (one player, one-way platforms, coins), `blank` (two moving squares). Each one has:
+
+- `src/game.ts`: pure state plus `createGame`, `step`, `render`, `encode`, `checksum`, `state`, `snapshot`.
+- `sim.ts`: the Sim contract over game.ts. The CLI drives it.
+- `main.web.ts`: keyboard to encoded input, fixed 60 Hz steps, render.
+- `dotframe.json`, `AGENTS.md`, a stub skill, `replays/`.
+
+## Shape the game for agents
+
+- Keep all state in one plain object graph. Then `structuredClone` is a snapshot and `inspect` is free.
+- Encode input as a small number per player. Replays, netplay and mashing all reuse it.
+- Make `state()` the summary a reviewer needs: positions, scores, who won. Agents read it after every sim.
+- Record a golden replay as soon as a mechanic works (`dotframe replay record replays/<name>.json --mash 7`) and keep `bun test` running them.
+- Add `--options` for anything you want to test in isolation (stage, character, one stock).
+
+See `dotframe skills get game-design --full` for a sim.ts walkthrough.

package/skills/game-design/references/sim-walkthrough.md

@@ -0,0 +1,32 @@
+# sim.ts walkthrough
+
+```ts
+import { defineSim } from "dotframe/src/sim";
+import { checksum, createGame, encode, randomInput, render, snapshot, state, step, WINDOW, PLAYERS } from "./src/game";
+
+export default defineSim({
+  players: PLAYERS,
+  window: WINDOW,
+  options: {},                 // defaults merged under --options
+  neutral: 0,                  // encoded "nothing pressed"
+  encode,                      // JSON input -> number
+  random: randomInput,         // used by --mash
+  create: () => {
+    let game = createGame(1);
+    return {
+      ready: Promise.resolve(),               // load assets here when not headless
+      start: (seed) => { game = createGame(seed); },
+      step: (inputs) => step(game, inputs),
+      checksum: () => checksum(game),
+      state: () => state(game),
+      over: () => game.winner >= 0,
+      save: () => snapshot(game),
+      restore: (s) => { Object.assign(game, snapshot(s)); },
+      inspect: () => game,
+      render: (draw) => render(game, draw),
+    };
+  },
+});
+```
+
+A game with classes, closures, or GPU handles in its state (like Crafter Smash) needs an identity-preserving snapshotter instead of structuredClone, and a `ready` promise that loads assets onto `platform.gpu` and `platform.draw` when `platform.headless` is false.

package/skills/ios/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: ios
+description: Build and install the iOS target of a dotframe game. Use when building for iPhone, fixing vendor links, signing, or installing on a device.
+---
+# ios
+
+```sh
+dotframe doctor --json               # vendor links, scriptc, xcodegen, xcodebuild
+dotframe doctor --fix                # creates missing vendor symlinks
+dotframe build ios --json            # glue, scriptc library, xcodegen, xcodebuild
+dotframe device install ios --dry-run
+dotframe device install ios --yes    # after approval; phone unlocked and trusted
+```
+
+- The iOS build needs SDL3 and wgpu-native iOS builds under `vendor/dotframe/vendor/`. They are local symlinks (`links` in dotframe.json), not in git. `doctor --fix` creates them when the targets exist.
+- Signing uses the team in the Xcode project; `-allowProvisioningUpdates` lets xcodebuild fetch profiles. A locked password manager can fail signing with `failed to fill whole buffer`: ask the human to unlock it and retry.
+- `targets.ios.app` is the built `.app`; `targets.ios.device` comes from `xcrun devicectl list devices`.
+- `build ios --release` refuses assets marked local-only (see `assets`). Debug builds for your own phone are fine.
+- Confirm on the device by asking the human, or with a screenshot if available. A successful install is not a working game.

package/skills/macos/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: macos
+description: Build and run native macOS (and Windows) binaries of a dotframe game with scriptc. Use when compiling natively, benchmarking, or debugging the native backend.
+---
+# macos
+
+```sh
+dotframe build macos --json
+```
+
+The step runs dotframe's `scripts/build-native.sh macos <entry> <name>`: it compiles the C shim (SDL3 + wgpu-native) and the game with scriptc into one binary with no JavaScript engine. Windows cross-builds with zig (`build-native.sh windows`).
+
+- Games may need env vars at run time (Crafter Smash: `CHARS=railly,anthony SMASH_ROOT=<repo> DOTFRAME=<repo>/vendor/dotframe`).
+- Benchmarks mean nothing while other processes load the machine. Check `top` first and say what else was running.
+- Hidden or occluded windows skip frames and can spin a core. Keep test windows visible.
+- scriptc compiles a subset of TypeScript: structural types become record copies, so engine backends are plain objects of functions, not classes behind interfaces.

package/skills/netplay/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: netplay
+description: Rollback netplay for dotframe games. Use when building or debugging online play, a desync, rollbacks, input delay, or render code that might change simulation state.
+---
+# netplay
+
+dotframe online play is rollback netcode: each peer predicts the remote input (repeat the last one), simulates ahead, and when the real input arrives and differs, restores a snapshot and resimulates. It only works if every peer computes bit-identical state from the same inputs.
+
+## Test before going online
+
+```sh
+dotframe desync --latency 120ms --jitter 30ms --frames 3000 --mash 7 --json
+```
+
+It runs a reference simulation and two peers over a deterministic simulated link. Peer 1 also renders 3 times per step (`--renders`), like a 144 Hz screen. Read per peer:
+
+- `firstDivergentFrame`: the checksum differed. A rollback or determinism bug.
+- `firstStateDifference`: `{frame, path}` of the first field that differs at a checkpoint (`--every 30`). Catches state the checksum does not cover. Needs `inspect()` in the sim.
+- `rollbacks`, `maxRollbackFrames`: how hard the link worked. Keep max under the game's rollback window.
+
+Run several seeds and a high latency (474 ms is what a transatlantic relay measured). A pass on one seed proves little.
+
+## Reading a failure
+
+- Only peer 1 differs: rendering changes state. Look for draw code that spawns effects, advances timers, moves the camera, or consumes the seeded random. Move it into `step`.
+- Both peers differ: `save`/`restore` misses state, or something non-deterministic (Math.random, Date, Map iteration over unordered keys, floating state touched outside step).
+- The path is the lead. `state.fx.texts.0.x: extra` means a text exists on one side only: find who pushes into `fx.texts` outside step.
+
+## Rules
+
+- The camera, effects, and HUD timers are simulation state if the simulation ever reads them. Update them once per step, never per drawn frame.
+- Render must restore any random state it uses, or use a separate visual generator.
+- Input delay (`--delay`, default 2) trades latency for fewer rollbacks.
+- After a fix, rerun desync across seeds, then `dotframe replay verify`, then test a real match.

package/skills/relay/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: relay
+description: Deploy and place the WebSocket relay that pairs netplay peers. Use when online play is laggy, choosing a relay region, or redeploying the relay.
+---
+# relay
+
+The relay forwards inputs between peers in a room. It does no simulation, so its only job is to be close to the players: every input crosses peer to relay to peer.
+
+```sh
+dotframe relay deploy --dry-run
+dotframe relay deploy --yes                 # dokploy: redeploys the compose stack
+dotframe relay deploy --region eze --yes    # fly: Buenos Aires; scl is Santiago
+```
+
+- Providers live in `relay` in dotframe.json: `{"provider": "dokploy", "compose": "<id>"}` or `{"provider": "fly", "app": "...", "config": "fly.toml", "region": "eze"}`. Dokploy runs on one fixed VPS and ignores regions.
+- Measure before and after: in-game ping, rollbacks per minute, stalls. A relay in Europe gave 474 ms between two players in South America.
+- Dokploy applies compose domain changes only on redeploy.
+- After moving the relay, update the Discord `/relay` URL mapping if the host changed.

package/src/audio.ts

@@ -0,0 +1,19 @@
+// Backend-agnostic audio: decoded sound effects, square tones and one streamed music track.
+
+// Synchronous playback controls, usable in scriptc library mode (iOS) where promises are unavailable.
+export interface AudioPlayer {
+  // rate scales pitch and speed together, like AudioBufferSourceNode.playbackRate.
+  play: (sound: number, volume: number, rate: number) => void;
+  // Square wave decaying exponentially to silence over duration seconds.
+  tone: (frequency: number, duration: number, volume: number) => void;
+  playMusic: (track: number, loop: boolean, volume: number) => void;
+  stopMusic: () => void;
+  pauseMusic: (paused: boolean) => void;
+  setMusicVolume: (volume: number) => void;
+  setMasterVolume: (volume: number) => void;
+}
+
+export interface Audio extends AudioPlayer {
+  loadSound: (mp3: Uint8Array) => Promise<number>;
+  loadMusic: (mp3: Uint8Array) => Promise<number>;
+}