dotframe 0.1.0

package/cli/main.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import pkg from "../package.json" with { type: "json" };
+import { build, deploy, device, relay } from "./commands/ship";
+import { doctor } from "./commands/doctor";
+import { configCmd } from "./commands/config";
+import { desync, record, sim, verify } from "./commands/play";
+import { snap } from "./commands/snap";
+import { skills } from "./commands/skills";
+import { create, dev } from "./commands/new";
+import { CliError, type Ctx, fail } from "./lib";
+
+const HELP = `dotframe ${pkg.version}: build, test, and export dotframe games
+
+Agents: run \`dotframe skills get core\` before anything else.
+
+Play (headless, deterministic)
+  sim      [--inputs f.jsonl | --mash <seed>] [--frames 600] [--seed 1] [--options json] [--every n]
+  snap     --frame <n> [--out frame.png] [--inputs f | --mash <seed>] [--seed 1] [--options json]
+  replay   record <file> | verify <file...>
+  desync   [--latency 100ms] [--jitter 0ms] [--delay 2] [--frames 1800] [--renders 3]
+
+Build and ship
+  build    <target> [--release]         targets come from dotframe.json
+  deploy   <target> [--prod]            gated: --yes, preview with --dry-run
+  relay    deploy [--region eze]        gated
+  device   install <target>             gated
+  doctor   [--fix]                      toolchain, links, config, signing
+  config   get [key] | set <key> <json>
+
+Project
+  new      <name> [--template fighter|platformer|blank] [--no-install]
+  dev      [--port 5173]                build web, serve it, rebuild on change
+  skills   list | get <name...> [--full] | get --all | path [name]
+
+Global: --json  --yes  --dry-run  --help  --version`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  strict: false,
+  options: {
+    json: { type: "boolean" },
+    yes: { type: "boolean", short: "y" },
+    "dry-run": { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean" },
+    full: { type: "boolean" },
+    all: { type: "boolean" },
+    fix: { type: "boolean" },
+    prod: { type: "boolean" },
+    release: { type: "boolean" },
+    inputs: { type: "string" },
+    mash: { type: "string" },
+    frames: { type: "string" },
+    frame: { type: "string" },
+    seed: { type: "string" },
+    options: { type: "string" },
+    every: { type: "string" },
+    out: { type: "string" },
+    latency: { type: "string" },
+    jitter: { type: "string" },
+    delay: { type: "string" },
+    renders: { type: "string" },
+    region: { type: "string" },
+    template: { type: "string" },
+    port: { type: "string" },
+    "no-install": { type: "boolean" },
+  },
+});
+
+const ctx: Ctx = { json: values.json === true, yes: values.yes === true, dryRun: values["dry-run"] === true };
+const v = values as Record<string, string | undefined>;
+const [command, ...rest] = positionals;
+
+try {
+  if (values.version) console.log(pkg.version);
+  else if (!command || values.help) console.log(HELP);
+  else if (command === "sim") await sim(ctx, v);
+  else if (command === "snap") await snap(ctx, v);
+  else if (command === "replay" && rest[0] === "record") await record(ctx, rest[1], v);
+  else if (command === "replay" && rest[0] === "verify") await verify(ctx, rest.slice(1));
+  else if (command === "desync") await desync(ctx, v);
+  else if (command === "build") await build(ctx, rest[0], values.release === true);
+  else if (command === "deploy") await deploy(ctx, rest[0], values.prod === true);
+  else if (command === "relay" && rest[0] === "deploy") await relay(ctx, v.region);
+  else if (command === "device" && rest[0] === "install") await device(ctx, rest[1] ?? "ios");
+  else if (command === "doctor") await doctor(ctx, values.fix === true);
+  else if (command === "config") await configCmd(ctx, rest);
+  else if (command === "skills") await skills(ctx, rest, values.full === true, values.all === true);
+  else if (command === "new") await create(ctx, rest[0], v.template ?? "blank", values["no-install"] !== true);
+  else if (command === "dev") await dev(ctx, Number(v.port ?? "5173"));
+  else throw new CliError("UNKNOWN_COMMAND", `unknown command: ${positionals.join(" ")}`, "dotframe --help");
+} catch (error) {
+  fail(ctx, error);
+}

package/cli/simkit.ts

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Sim, SimRun } from "../src/sim";
+import type { RenderGpu, Texture } from "../src/gpu";
+import { CliError, type Config } from "./lib";
+
+let nextTexture = 1;
+// Texture ids restart per run so two runs of the same game have identical state graphs.
+export function resetStubGpu(): void {
+  nextTexture = 1;
+}
+export const stubGpu: RenderGpu = {
+  createBuffer: (): number => 0,
+  writeBuffer: (): void => {},
+  destroyBuffer: (): void => {},
+  createPipeline: (): number => 0,
+  bind: (): number => 0,
+  createTexture: (width: number, height: number): Texture => ({ id: nextTexture++, width, height }) as Texture,
+  frame: (): void => {},
+  aspect: (): number => 16 / 9,
+} as RenderGpu;
+
+export function simPath(config: Config): string {
+  if (!config.sim) throw new CliError("NO_SIM", `dotframe.json has no "sim" module`, `add "sim": "path/to/sim.ts" exporting defineSim(...)`, "core");
+  const path = resolve(config.root, config.sim);
+  if (!existsSync(path)) throw new CliError("SIM_MISSING", `sim module ${config.sim} does not exist`, "create it with defineSim from dotframe/src/sim", "core");
+  return path;
+}
+
+export async function loadSim(config: Config): Promise<Sim> {
+  const mod = (await import(simPath(config))) as { default?: Sim };
+  if (!mod.default || typeof mod.default.create !== "function") throw new CliError("BAD_SIM", `${config.sim} must default-export defineSim({...})`, "see dotframe skills get core", "core");
+  return mod.default;
+}
+
+export async function headlessRun(sim: Sim, root: string): Promise<SimRun> {
+  resetStubGpu();
+  const run = sim.create({ gpu: stubGpu, load: async (p: string): Promise<Uint8Array> => new Uint8Array(await Bun.file(resolve(root, p)).arrayBuffer()), headless: true });
+  await run.ready;
+  return run;
+}
+
+export function lcg(seed: number): () => number {
+  let s = seed >>> 0;
+  return (): number => {
+    s = (Math.imul(s, 1103515245) + 12345) >>> 0;
+    return s / 4294967296;
+  };
+}
+
+export interface InputSource {
+  // Encoded inputs per frame, one number per player.
+  at: (frame: number) => number[];
+  describe: string;
+}
+
+// JSONL lines are either [p0, p1, ...] (one line per frame) or {"frame": N, "inputs": [...]} (held until the next).
+export function inputsFromFile(sim: Sim, path: string): InputSource {
+  if (!existsSync(path)) throw new CliError("INPUTS_MISSING", `inputs file ${path} does not exist`, "pass --inputs <file.jsonl> or --mash <seed>");
+  const keyed: { frame: number; inputs: number[] }[] = [];
+  const lines = readFileSync(path, "utf8").split("\n").filter((l: string): boolean => l.trim() !== "");
+  lines.forEach((line: string, i: number): void => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      throw new CliError("BAD_INPUTS", `${path}:${i + 1} is not JSON`, "one JSON array or {frame, inputs} object per line");
+    }
+    const entry = Array.isArray(parsed) ? { frame: i, inputs: parsed } : (parsed as { frame: number; inputs: unknown[] });
+    if (!Array.isArray(entry.inputs) || entry.inputs.length !== sim.players) {
+      throw new CliError("BAD_INPUTS", `${path}:${i + 1} needs ${sim.players} inputs`, "one input per player");
+    }
+    keyed.push({ frame: entry.frame, inputs: entry.inputs.map((v: unknown): number => (typeof v === "number" ? v : sim.encode(v))) });
+  });
+  keyed.sort((a, b): number => a.frame - b.frame);
+  const neutral = new Array(sim.players).fill(sim.neutral);
+  return {
+    describe: path,
+    at: (frame: number): number[] => {
+      let cur = neutral;
+      for (const k of keyed) {
+        if (k.frame > frame) break;
+        cur = k.inputs;
+      }
+      return cur;
+    },
+  };
+}
+
+// Mashing players: a new random input per player every 6 frames.
+export function mash(sim: Sim, seed: number): InputSource {
+  const cache: number[][] = [];
+  const next = lcg(seed);
+  return {
+    describe: `mash:${seed}`,
+    at: (frame: number): number[] => {
+      while (cache.length <= frame) {
+        const f = cache.length;
+        cache.push(f % 6 === 0 ? Array.from({ length: sim.players }, (): number => sim.random(next)) : cache[f - 1].slice());
+      }
+      return cache[frame];
+    },
+  };
+}
+
+export function inputSource(sim: Sim, root: string, inputs: string | undefined, mashSeed: string | undefined): InputSource {
+  if (inputs) return inputsFromFile(sim, resolve(process.cwd(), inputs));
+  if (mashSeed !== undefined) return mash(sim, Number(mashSeed));
+  return { describe: "neutral", at: (): number[] => new Array(sim.players).fill(sim.neutral) };
+}
+
+export function parseOptions(sim: Sim, raw: string | undefined): Record<string, unknown> {
+  if (!raw) return { ...sim.options };
+  try {
+    return { ...sim.options, ...(JSON.parse(raw) as Record<string, unknown>) };
+  } catch {
+    throw new CliError("BAD_OPTIONS", "--options must be a JSON object", `example: --options '${JSON.stringify(sim.options)}'`);
+  }
+}
+
+// Flattens an object graph into path -> primitive, in key order, visiting each object once. Functions and typed
+// arrays are skipped (closures and pixel data are not comparable state).
+export function flatten(root: unknown): Map<string, unknown> {
+  const out = new Map<string, unknown>();
+  const seen = new Set<unknown>();
+  const walk = (v: unknown, path: string): void => {
+    if (typeof v === "function") return;
+    if (v === null || typeof v !== "object") {
+      out.set(path, typeof v === "number" ? Math.round(v * 1e6) / 1e6 : v);
+      return;
+    }
+    if (seen.has(v) || ArrayBuffer.isView(v)) return;
+    seen.add(v);
+    if (v instanceof Map) {
+      out.set(`${path}.size`, v.size);
+      for (const [k, item] of v) walk(item, `${path}[${String(k)}]`);
+    } else if (v instanceof Set) out.set(`${path}.size`, v.size);
+    else for (const k of Object.keys(v)) walk((v as Record<string, unknown>)[k], `${path}.${k}`);
+  };
+  walk(root, "state");
+  return out;
+}
+
+export function firstDifference(a: Map<string, unknown>, b: Map<string, unknown>): string {
+  for (const [k, v] of a) {
+    if (!b.has(k)) return `${k}: missing`;
+    const w = b.get(k);
+    if (v !== w && !(Number.isNaN(v) && Number.isNaN(w))) return `${k}: ${String(v)} vs ${String(w)}`;
+  }
+  for (const k of b.keys()) if (!a.has(k)) return `${k}: extra`;
+  return "";
+}

package/cli/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "types": ["@webgpu/types", "bun"],
+    "resolveJsonModule": true
+  },
+  "include": ["../src/*.ts", "./**/*.ts"]
+}

package/native/df_audio.c

@@ -0,0 +1,266 @@
+// Software mixer over an SDL3 audio stream: decoded sound effects, square tones and one streamed music track.
+// All entry points are called from the game thread; the SDL callback mixes on the audio thread under g_lock.
+#include <SDL3/SDL.h>
+#include <math.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define DR_MP3_IMPLEMENTATION
+#include "third_party/dr_mp3.h"
+
+#define OUTPUT_RATE 48000
+#define MAX_SOUNDS 256
+#define MAX_VOICES 64
+#define MAX_TONES 16
+#define MAX_TRACKS 32
+
+typedef struct {
+  float *frames;  // interleaved stereo
+  uint64_t count;
+  uint32_t rate;
+} Sound;
+
+typedef struct {
+  int32_t sound;
+  double position;
+  double step;
+  float volume;
+} Voice;
+
+typedef struct {
+  double phase;
+  double step;
+  double elapsed;
+  double duration;
+  float volume;
+} Tone;
+
+typedef struct {
+  uint8_t *data;  // owned copy of the MP3 bytes the decoder streams from
+  size_t size;
+} Track;
+
+static SDL_AudioStream *g_stream;
+static SDL_Mutex *g_lock;
+static Sound g_sounds[MAX_SOUNDS];
+static int32_t g_sound_count;
+static Voice g_voices[MAX_VOICES];
+static int32_t g_voice_count;
+static Tone g_tones[MAX_TONES];
+static int32_t g_tone_count;
+static Track g_tracks[MAX_TRACKS];
+static int32_t g_track_count;
+
+static drmp3 g_music;
+static int g_music_open;
+static int g_music_loop;
+static int g_music_paused;
+static float g_music_volume = 1.0f;
+static float g_music_buffer[4096 * 2];
+static uint64_t g_music_buffered;
+static double g_music_position;
+static double g_music_step;
+static float g_master = 0.8f;
+
+static float clampf(float v) { return v < -1.0f ? -1.0f : v > 1.0f ? 1.0f : v; }
+
+// Pulls the next music frame pair through a small linear resampler; returns 0 at the end of a non-looping track.
+static int music_frame(float *left, float *right) {
+  while (g_music_position + 1.0 >= (double)g_music_buffered) {
+    if (g_music_buffered >= 1) {
+      // Keep the last frame so interpolation stays continuous across refills.
+      g_music_buffer[0] = g_music_buffer[(g_music_buffered - 1) * 2];
+      g_music_buffer[1] = g_music_buffer[(g_music_buffered - 1) * 2 + 1];
+      g_music_position -= (double)(g_music_buffered - 1);
+      g_music_buffered = 1;
+    }
+    uint64_t read = drmp3_read_pcm_frames_f32(&g_music, 4095, g_music_buffer + g_music_buffered * 2);
+    if (read == 0) {
+      if (!g_music_loop || !drmp3_seek_to_pcm_frame(&g_music, 0)) return 0;
+      read = drmp3_read_pcm_frames_f32(&g_music, 4095, g_music_buffer + g_music_buffered * 2);
+      if (read == 0) return 0;
+    }
+    g_music_buffered += read;
+  }
+  uint64_t i = (uint64_t)g_music_position;
+  float t = (float)(g_music_position - (double)i);
+  *left = g_music_buffer[i * 2] * (1 - t) + g_music_buffer[(i + 1) * 2] * t;
+  *right = g_music_buffer[i * 2 + 1] * (1 - t) + g_music_buffer[(i + 1) * 2 + 1] * t;
+  g_music_position += g_music_step;
+  return 1;
+}
+
+static void SDLCALL mix(void *userdata, SDL_AudioStream *stream, int additional, int total) {
+  (void)userdata;
+  (void)total;
+  float out[1024 * 2];
+  while (additional > 0) {
+    int frames = additional / (int)(sizeof(float) * 2);
+    if (frames > 1024) frames = 1024;
+    if (frames <= 0) break;
+    memset(out, 0, sizeof(float) * 2 * (size_t)frames);
+    SDL_LockMutex(g_lock);
+    for (int32_t v = 0; v < g_voice_count;) {
+      Voice *voice = &g_voices[v];
+      Sound *sound = &g_sounds[voice->sound];
+      int done = 0;
+      for (int f = 0; f < frames; f++) {
+        uint64_t i = (uint64_t)voice->position;
+        if (i + 1 >= sound->count) {
+          done = 1;
+          break;
+        }
+        float t = (float)(voice->position - (double)i);
+        out[f * 2] += (sound->frames[i * 2] * (1 - t) + sound->frames[(i + 1) * 2] * t) * voice->volume;
+        out[f * 2 + 1] += (sound->frames[i * 2 + 1] * (1 - t) + sound->frames[(i + 1) * 2 + 1] * t) * voice->volume;
+        voice->position += voice->step;
+      }
+      if (done) g_voices[v] = g_voices[--g_voice_count];
+      else v++;
+    }
+    for (int32_t k = 0; k < g_tone_count;) {
+      Tone *tone = &g_tones[k];
+      for (int f = 0; f < frames && tone->elapsed < tone->duration; f++) {
+        // Exponential decay from volume to 0.1% over the duration, like Web Audio's exponentialRamp.
+        float gain = tone->volume * powf(0.001f / tone->volume, (float)(tone->elapsed / tone->duration));
+        float value = fmod(tone->phase, 1.0) < 0.5 ? gain : -gain;
+        out[f * 2] += value;
+        out[f * 2 + 1] += value;
+        tone->phase += tone->step;
+        tone->elapsed += 1.0 / OUTPUT_RATE;
+      }
+      if (tone->elapsed >= tone->duration) g_tones[k] = g_tones[--g_tone_count];
+      else k++;
+    }
+    if (g_music_open && !g_music_paused) {
+      for (int f = 0; f < frames; f++) {
+        float left, right;
+        if (!music_frame(&left, &right)) {
+          drmp3_uninit(&g_music);
+          g_music_open = 0;
+          break;
+        }
+        out[f * 2] += left * g_music_volume;
+        out[f * 2 + 1] += right * g_music_volume;
+      }
+    }
+    SDL_UnlockMutex(g_lock);
+    for (int f = 0; f < frames * 2; f++) out[f] = clampf(out[f] * g_master);
+    SDL_PutAudioStreamData(stream, out, (int)(sizeof(float) * 2 * (size_t)frames));
+    additional -= (int)(sizeof(float) * 2 * (size_t)frames);
+  }
+}
+
+int32_t df_audio_open(void) {
+  if (g_stream) return 0;
+  if (!SDL_InitSubSystem(SDL_INIT_AUDIO)) return -1;
+  g_lock = SDL_CreateMutex();
+  SDL_AudioSpec spec = {SDL_AUDIO_F32, 2, OUTPUT_RATE};
+  g_stream = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &spec, mix, NULL);
+  if (!g_stream) return -2;
+  SDL_ResumeAudioStreamDevice(g_stream);
+  return 0;
+}
+
+// Decodes MP3 bytes into a playable sound.
+int32_t df_sound(const uint8_t *mp3, size_t len) {
+  if (g_sound_count >= MAX_SOUNDS) return -1;
+  drmp3_config config;
+  drmp3_uint64 count = 0;
+  float *mono_or_stereo = drmp3_open_memory_and_read_pcm_frames_f32(mp3, len, &config, &count, NULL);
+  if (!mono_or_stereo) return -2;
+  float *frames = malloc(sizeof(float) * 2 * (size_t)count);
+  for (drmp3_uint64 i = 0; i < count; i++) {
+    frames[i * 2] = mono_or_stereo[i * config.channels];
+    frames[i * 2 + 1] = mono_or_stereo[i * config.channels + (config.channels > 1 ? 1 : 0)];
+  }
+  drmp3_free(mono_or_stereo, NULL);
+  SDL_LockMutex(g_lock);
+  int32_t id = g_sound_count++;
+  g_sounds[id] = (Sound){frames, count, config.sampleRate};
+  SDL_UnlockMutex(g_lock);
+  return id;
+}
+
+void df_play(int32_t sound, double volume, double rate) {
+  if (!g_stream || sound < 0 || sound >= g_sound_count) return;
+  SDL_LockMutex(g_lock);
+  if (g_voice_count < MAX_VOICES) {
+    g_voices[g_voice_count++] =
+        (Voice){sound, 0.0, (double)g_sounds[sound].rate / OUTPUT_RATE * rate, (float)volume};
+  }
+  SDL_UnlockMutex(g_lock);
+}
+
+void df_tone(double frequency, double duration, double volume) {
+  if (!g_stream || duration <= 0 || volume <= 0) return;
+  SDL_LockMutex(g_lock);
+  if (g_tone_count < MAX_TONES) g_tones[g_tone_count++] = (Tone){0.0, frequency / OUTPUT_RATE, 0.0, duration, (float)volume};
+  SDL_UnlockMutex(g_lock);
+}
+
+// Keeps a copy of MP3 bytes for streaming playback.
+int32_t df_track(const uint8_t *mp3, size_t len) {
+  if (g_track_count >= MAX_TRACKS) return -1;
+  uint8_t *copy = malloc(len);
+  memcpy(copy, mp3, len);
+  g_tracks[g_track_count] = (Track){copy, len};
+  return g_track_count++;
+}
+
+int32_t df_music_play(int32_t track, uint8_t loop, double volume) {
+  if (!g_stream || track < 0 || track >= g_track_count) return -1;
+  SDL_LockMutex(g_lock);
+  if (g_music_open) drmp3_uninit(&g_music);
+  g_music_open = drmp3_init_memory(&g_music, g_tracks[track].data, g_tracks[track].size, NULL);
+  g_music_loop = loop;
+  g_music_paused = 0;
+  g_music_volume = (float)volume;
+  g_music_buffered = 0;
+  g_music_position = 0;
+  g_music_step = g_music_open ? (double)g_music.sampleRate / OUTPUT_RATE : 1.0;
+  SDL_UnlockMutex(g_lock);
+  return g_music_open ? 0 : -2;
+}
+
+void df_music_stop(void) {
+  SDL_LockMutex(g_lock);
+  if (g_music_open) drmp3_uninit(&g_music);
+  g_music_open = 0;
+  SDL_UnlockMutex(g_lock);
+}
+
+void df_music_pause(uint8_t paused) {
+  SDL_LockMutex(g_lock);
+  g_music_paused = paused;
+  SDL_UnlockMutex(g_lock);
+}
+
+void df_music_volume(double volume) {
+  SDL_LockMutex(g_lock);
+  g_music_volume = (float)volume;
+  SDL_UnlockMutex(g_lock);
+}
+
+void df_master_volume(double volume) { g_master = (float)volume; }
+
+// Number of currently mixing sound and tone voices, for tests and diagnostics.
+int32_t df_audio_active(void) {
+  SDL_LockMutex(g_lock);
+  int32_t active = g_voice_count + g_tone_count + (g_music_open && !g_music_paused ? 1 : 0);
+  SDL_UnlockMutex(g_lock);
+  return active;
+}
+
+void df_audio_close(void) {
+  if (g_stream) SDL_DestroyAudioStream(g_stream);
+  g_stream = NULL;
+  if (g_music_open) drmp3_uninit(&g_music);
+  g_music_open = 0;
+  for (int32_t i = 0; i < g_sound_count; i++) free(g_sounds[i].frames);
+  for (int32_t i = 0; i < g_track_count; i++) free(g_tracks[i].data);
+  g_sound_count = g_track_count = g_voice_count = g_tone_count = 0;
+  if (g_lock) SDL_DestroyMutex(g_lock);
+  g_lock = NULL;
+}