dotframe 0.1.0

package/src/ecs.ts

@@ -0,0 +1,30 @@
+import type { Vec3 } from "./math";
+
+// Minimal ECS: entities are numbers, each component kind lives in its own Map.
+
+export interface Transform {
+  position: Vec3;
+  rotation: Vec3;
+  scale: Vec3;
+}
+
+export interface MeshRef {
+  mesh: number;
+  color: Vec3;
+}
+
+export interface World {
+  nextEntity: number;
+  transforms: Map<number, Transform>;
+  meshes: Map<number, MeshRef>;
+}
+
+export function createWorld(): World {
+  return { nextEntity: 0, transforms: new Map<number, Transform>(), meshes: new Map<number, MeshRef>() };
+}
+
+export function spawn(world: World): number {
+  const entity = world.nextEntity;
+  world.nextEntity = entity + 1;
+  return entity;
+}

package/src/gltf.ts

@@ -0,0 +1,82 @@
+// Reads the first mesh primitive of a binary glTF (.glb): positions, normals and indices.
+
+export interface MeshData {
+  positions: Float32Array;
+  normals: Float32Array;
+  indices: Uint32Array;
+}
+
+interface GltfAccessor {
+  bufferView: number;
+  byteOffset?: number;
+  componentType: number;
+  count: number;
+}
+
+interface GltfBufferView {
+  byteOffset?: number;
+  byteLength: number;
+}
+
+interface GltfDocument {
+  accessors: GltfAccessor[];
+  bufferViews: GltfBufferView[];
+  meshes: { primitives: { attributes: { POSITION: number; NORMAL: number }; indices: number }[] }[];
+}
+
+const GLB_MAGIC = 0x46546c67;
+const CHUNK_JSON = 0x4e4f534a;
+const CHUNK_BIN = 0x004e4942;
+const COMPONENT_UNSIGNED_SHORT = 5123;
+const COMPONENT_UNSIGNED_INT = 5125;
+
+export function parseGlb(bytes: Uint8Array): MeshData {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0, true) !== GLB_MAGIC) throw new Error("not a GLB file");
+
+  let offset = 12;
+  let json = "";
+  let binOffset = -1;
+  while (offset < bytes.byteLength) {
+    const length = view.getUint32(offset, true);
+    const type = view.getUint32(offset + 4, true);
+    if (type === CHUNK_JSON) json = new TextDecoder().decode(bytes.subarray(offset + 8, offset + 8 + length));
+    if (type === CHUNK_BIN) binOffset = bytes.byteOffset + offset + 8;
+    offset += 8 + length;
+  }
+  if (json === "" || binOffset < 0) throw new Error("GLB is missing its JSON or BIN chunk");
+
+  const doc = JSON.parse(json) as GltfDocument;
+  const primitive = doc.meshes[0].primitives[0];
+
+  const accessorStart = (index: number): number => {
+    const accessor = doc.accessors[index];
+    const bufferView = doc.bufferViews[accessor.bufferView];
+    return binOffset + (bufferView.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+  };
+
+  const readVec3 = (index: number): Float32Array => {
+    const count = doc.accessors[index].count;
+    const start = accessorStart(index);
+    const out = new Float32Array(count * 3);
+    const source = new DataView(bytes.buffer, start, count * 12);
+    for (let i = 0; i < count * 3; i++) out[i] = source.getFloat32(i * 4, true);
+    return out;
+  };
+
+  const indexAccessor = doc.accessors[primitive.indices];
+  const indexStart = accessorStart(primitive.indices);
+  const indices = new Uint32Array(indexAccessor.count);
+  const indexView = new DataView(bytes.buffer, indexStart);
+  for (let i = 0; i < indexAccessor.count; i++) {
+    if (indexAccessor.componentType === COMPONENT_UNSIGNED_SHORT) indices[i] = indexView.getUint16(i * 2, true);
+    else if (indexAccessor.componentType === COMPONENT_UNSIGNED_INT) indices[i] = indexView.getUint32(i * 4, true);
+    else throw new Error(`unsupported index component type ${indexAccessor.componentType}`);
+  }
+
+  return {
+    positions: readVec3(primitive.attributes.POSITION),
+    normals: readVec3(primitive.attributes.NORMAL),
+    indices,
+  };
+}

package/src/gpu.ts

@@ -0,0 +1,86 @@
+import type { Platform } from "./platform";
+
+// Backend-agnostic surface shared by game code. Backends return plain objects of functions:
+// scriptc compiles structural types as record copies, so classes cannot stand in for interfaces.
+
+export interface WindowOptions {
+  width: number;
+  height: number;
+  title: string;
+}
+
+export interface Color {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export const BufferUsage = { Vertex: 1, Index: 2, Uniform: 4 };
+// Unorm8x4: four bytes read as a vec4f in [0, 1], for packed colors.
+export const VertexFormat = { Float32x2: 0, Float32x3: 1, Float32x4: 2, Float32: 3, Unorm8x4: 4 };
+
+export interface VertexAttribute {
+  format: number;
+  offset: number;
+  location: number;
+}
+
+export interface PipelineOptions {
+  wgsl: string;
+  // Bytes per vertex; 0 when the shader generates vertices itself.
+  stride: number;
+  attributes: VertexAttribute[];
+  depth: boolean;
+  // Standard alpha blending, for 2D and transparent sprites.
+  blend: boolean;
+}
+
+export interface Texture {
+  id: number;
+  width: number;
+  height: number;
+}
+
+// Negative handles mean "none". first/count are uint32 indices with an index buffer, vertices otherwise.
+export interface Draw {
+  pipeline: number;
+  bindGroup: number;
+  vertexBuffer: number;
+  indexBuffer: number;
+  first: number;
+  count: number;
+}
+
+// Synchronous rendering surface. Code that must also run in scriptc library mode (iOS), where promises are
+// unavailable, depends on this instead of Gpu.
+export interface RenderGpu {
+  createBuffer: (usage: number, data: Uint8Array) => number;
+  writeBuffer: (buffer: number, data: Uint8Array) => void;
+  destroyBuffer: (buffer: number) => void;
+  createPipeline: (options: PipelineOptions) => number;
+  // Group 0: binding 0 uniform buffer, binding 1 texture, binding 2 nearest sampler; -1 skips one.
+  bind: (pipeline: number, buffer: number, texture: number) => number;
+  // smooth: linear filtering (fonts, photos); otherwise nearest (pixel art).
+  createTexture: (width: number, height: number, rgba: Uint8Array, smooth: boolean) => Texture;
+  frame: (clear: Color, draws: Draw[]) => void;
+  aspect: () => number;
+}
+
+export interface Gpu extends RenderGpu {
+  // Decodes PNG bytes.
+  createImage: (png: Uint8Array, smooth: boolean) => Promise<Texture>;
+}
+
+// Called every frame with elapsed seconds; return false to stop.
+export type Frame = (time: number) => boolean;
+
+// Called once after the backend is ready.
+export type Setup = (platform: Platform) => Frame;
+
+export function f32Bytes(data: Float32Array): Uint8Array {
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+
+export function u32Bytes(data: Uint32Array): Uint8Array {
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}

package/src/input.ts

@@ -0,0 +1,215 @@
+// Engine-level key ids. Each maps to a KeyboardEvent.code (web) and an SDL scancode (native).
+// Codes are physical positions: Semicolon is the key right of L, which reads Ñ on a Spanish layout.
+
+export const Key = {
+  Left: 0,
+  Right: 1,
+  Up: 2,
+  Down: 3,
+  Space: 4,
+  W: 5,
+  A: 6,
+  S: 7,
+  D: 8,
+  J: 9,
+  K: 10,
+  L: 11,
+  Escape: 12,
+  Enter: 13,
+  B: 14,
+  C: 15,
+  E: 16,
+  F: 17,
+  G: 18,
+  H: 19,
+  I: 20,
+  M: 21,
+  N: 22,
+  O: 23,
+  P: 24,
+  Q: 25,
+  R: 26,
+  T: 27,
+  U: 28,
+  V: 29,
+  X: 30,
+  Y: 31,
+  Z: 32,
+  Digit0: 33,
+  Digit1: 34,
+  Digit2: 35,
+  Digit3: 36,
+  Digit4: 37,
+  Digit5: 38,
+  Digit6: 39,
+  Digit7: 40,
+  Digit8: 41,
+  Digit9: 42,
+  Tab: 43,
+  Backspace: 44,
+  Minus: 45,
+  Equal: 46,
+  BracketLeft: 47,
+  BracketRight: 48,
+  Backslash: 49,
+  Semicolon: 50,
+  Quote: 51,
+  Backquote: 52,
+  Comma: 53,
+  Period: 54,
+  Slash: 55,
+  ShiftLeft: 56,
+  ShiftRight: 57,
+  ControlLeft: 58,
+  ControlRight: 59,
+  AltLeft: 60,
+  AltRight: 61,
+  F1: 62,
+  F2: 63,
+  F3: 64,
+  F4: 65,
+  F5: 66,
+  F6: 67,
+  F7: 68,
+  F8: 69,
+  F9: 70,
+  F10: 71,
+  F11: 72,
+  F12: 73,
+};
+
+// KeyboardEvent.code for each Key id.
+export const keyCodes: string[] = [
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "ArrowDown",
+  "Space",
+  "KeyW",
+  "KeyA",
+  "KeyS",
+  "KeyD",
+  "KeyJ",
+  "KeyK",
+  "KeyL",
+  "Escape",
+  "Enter",
+  "KeyB",
+  "KeyC",
+  "KeyE",
+  "KeyF",
+  "KeyG",
+  "KeyH",
+  "KeyI",
+  "KeyM",
+  "KeyN",
+  "KeyO",
+  "KeyP",
+  "KeyQ",
+  "KeyR",
+  "KeyT",
+  "KeyU",
+  "KeyV",
+  "KeyX",
+  "KeyY",
+  "KeyZ",
+  "Digit0",
+  "Digit1",
+  "Digit2",
+  "Digit3",
+  "Digit4",
+  "Digit5",
+  "Digit6",
+  "Digit7",
+  "Digit8",
+  "Digit9",
+  "Tab",
+  "Backspace",
+  "Minus",
+  "Equal",
+  "BracketLeft",
+  "BracketRight",
+  "Backslash",
+  "Semicolon",
+  "Quote",
+  "Backquote",
+  "Comma",
+  "Period",
+  "Slash",
+  "ShiftLeft",
+  "ShiftRight",
+  "ControlLeft",
+  "ControlRight",
+  "AltLeft",
+  "AltRight",
+  "F1",
+  "F2",
+  "F3",
+  "F4",
+  "F5",
+  "F6",
+  "F7",
+  "F8",
+  "F9",
+  "F10",
+  "F11",
+  "F12",
+];
+
+// SDL scancode for each Key id.
+export const keyScancodes: number[] = [
+  80, 79, 82, 81, 44, 26, 4, 22, 7, 13, 14, 15, 41, 40, 5, 6, 8, 9, 10, 11, 12, 16, 17, 18, 19, 20, 21, 23, 24, 25, 27, 28, 29, 39, 30, 31, 32, 33, 34, 35, 36, 37, 38, 43, 42, 45, 46, 47, 48, 49, 51, 52, 53, 54, 55, 56, 225, 229, 224, 228, 226, 230, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69,
+];
+
+export const GamepadAxis = { LeftX: 0, LeftY: 1, RightX: 2, RightY: 3 };
+// Button ids follow the W3C "standard" gamepad layout on every backend.
+export const GamepadButton = {
+  South: 0,
+  East: 1,
+  West: 2,
+  North: 3,
+  LeftShoulder: 4,
+  RightShoulder: 5,
+  LeftTrigger: 6,
+  RightTrigger: 7,
+  Back: 8,
+  Start: 9,
+  LeftStick: 10,
+  RightStick: 11,
+  DpadUp: 12,
+  DpadDown: 13,
+  DpadLeft: 14,
+  DpadRight: 15,
+  Guide: 16,
+};
+// SDL_GamepadButton for each standard id; -1 marks the triggers, which SDL reports as axes 4 and 5.
+export const sdlGamepadButtons: number[] = [0, 1, 2, 3, 9, 10, -1, -1, 4, 6, 7, 8, 11, 12, 13, 14, 5];
+export const MouseButton = { Left: 1, Middle: 2, Right: 4 };
+
+export interface Pointer {
+  // Normalized to the window content: [0, 1] inside, past those bounds outside it.
+  x: number;
+  y: number;
+  // Bitmask of MouseButton values.
+  buttons: number;
+}
+
+export interface Touch {
+  // Stable while the finger stays down.
+  id: number;
+  // Normalized to the window content, [0, 1] on each axis.
+  x: number;
+  y: number;
+}
+
+export interface Input {
+  down: (key: number) => boolean;
+  // First held key, or -1; used to rebind controls.
+  firstDown: () => number;
+  // Gamepad slot pad (0 is player 1); 0 or false when the slot is empty.
+  axis: (pad: number, axis: number) => number;
+  button: (pad: number, button: number) => boolean;
+  pointer: () => Pointer;
+  // Fingers currently down, in no particular order.
+  touches: () => Touch[];
+}

package/src/math.ts

@@ -0,0 +1,113 @@
+// Column-major 4x4 matrices in Float32Array, WebGPU clip space (z in [0, 1]).
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export function vec3(x: number, y: number, z: number): Vec3 {
+  return { x, y, z };
+}
+
+export function identity(): Float32Array {
+  const m = new Float32Array(16);
+  m[0] = 1;
+  m[5] = 1;
+  m[10] = 1;
+  m[15] = 1;
+  return m;
+}
+
+export function multiply(a: Float32Array, b: Float32Array): Float32Array {
+  const out = new Float32Array(16);
+  for (let col = 0; col < 4; col++) {
+    for (let row = 0; row < 4; row++) {
+      let sum = 0;
+      for (let k = 0; k < 4; k++) sum += a[k * 4 + row] * b[col * 4 + k];
+      out[col * 4 + row] = sum;
+    }
+  }
+  return out;
+}
+
+export function perspective(fovY: number, aspect: number, near: number, far: number): Float32Array {
+  const f = 1 / Math.tan(fovY / 2);
+  const m = new Float32Array(16);
+  m[0] = f / aspect;
+  m[5] = f;
+  m[10] = far / (near - far);
+  m[11] = -1;
+  m[14] = (far * near) / (near - far);
+  return m;
+}
+
+export function lookAt(eye: Vec3, target: Vec3, up: Vec3): Float32Array {
+  let zx = eye.x - target.x;
+  let zy = eye.y - target.y;
+  let zz = eye.z - target.z;
+  const zl = Math.hypot(zx, zy, zz);
+  zx /= zl;
+  zy /= zl;
+  zz /= zl;
+  let xx = up.y * zz - up.z * zy;
+  let xy = up.z * zx - up.x * zz;
+  let xz = up.x * zy - up.y * zx;
+  const xl = Math.hypot(xx, xy, xz);
+  xx /= xl;
+  xy /= xl;
+  xz /= xl;
+  const yx = zy * xz - zz * xy;
+  const yy = zz * xx - zx * xz;
+  const yz = zx * xy - zy * xx;
+  const m = new Float32Array(16);
+  m[0] = xx;
+  m[1] = yx;
+  m[2] = zx;
+  m[4] = xy;
+  m[5] = yy;
+  m[6] = zy;
+  m[8] = xz;
+  m[9] = yz;
+  m[10] = zz;
+  m[12] = -(xx * eye.x + xy * eye.y + xz * eye.z);
+  m[13] = -(yx * eye.x + yy * eye.y + yz * eye.z);
+  m[14] = -(zx * eye.x + zy * eye.y + zz * eye.z);
+  m[15] = 1;
+  return m;
+}
+
+// Translation * rotation (Y, then X, then Z, in radians) * scale.
+export function compose(position: Vec3, rotation: Vec3, scale: Vec3): Float32Array {
+  const cx = Math.cos(rotation.x);
+  const sx = Math.sin(rotation.x);
+  const cy = Math.cos(rotation.y);
+  const sy = Math.sin(rotation.y);
+  const cz = Math.cos(rotation.z);
+  const sz = Math.sin(rotation.z);
+  // R = Ry * Rx * Rz
+  const r00 = cy * cz + sy * sx * sz;
+  const r01 = -cy * sz + sy * sx * cz;
+  const r02 = sy * cx;
+  const r10 = cx * sz;
+  const r11 = cx * cz;
+  const r12 = -sx;
+  const r20 = -sy * cz + cy * sx * sz;
+  const r21 = sy * sz + cy * sx * cz;
+  const r22 = cy * cx;
+  const m = new Float32Array(16);
+  m[0] = r00 * scale.x;
+  m[1] = r10 * scale.x;
+  m[2] = r20 * scale.x;
+  m[4] = r01 * scale.y;
+  m[5] = r11 * scale.y;
+  m[6] = r21 * scale.y;
+  m[8] = r02 * scale.z;
+  m[9] = r12 * scale.z;
+  m[10] = r22 * scale.z;
+  m[12] = position.x;
+  m[13] = position.y;
+  m[14] = position.z;
+  m[15] = 1;
+  return m;
+}

package/src/native/backend.ts

@@ -0,0 +1,142 @@
+// Native platform pieces shared by the executable loop (run.ts) and the library-mode runtime (library.ts).
+// Everything here is synchronous so it also compiles in scriptc library mode, where promises are unavailable.
+import type { AudioPlayer } from "../audio";
+import type { Color, Draw, PipelineOptions, RenderGpu, Texture } from "../gpu";
+import { type Input, keyScancodes, type Pointer, sdlGamepadButtons, type Touch } from "../input";
+import {
+  dfAudioOpen,
+  dfBegin,
+  dfBind,
+  dfBuffer,
+  dfBufferDestroy,
+  dfBufferWrite,
+  dfDraw,
+  dfEnd,
+  dfGamepadAxis,
+  dfGamepadButton,
+  dfHeight,
+  dfImage,
+  dfKeyDown,
+  dfMasterVolume,
+  dfMouse,
+  dfMusicPause,
+  dfMusicPlay,
+  dfMusicStop,
+  dfMusicVolume,
+  dfPipeline,
+  dfPlay,
+  dfSound,
+  dfTexture,
+  dfTextureSize,
+  dfTone,
+  dfTouch,
+  dfTouchCount,
+  dfTrack,
+  dfWidth,
+} from "./ffi";
+
+const PIPELINE_DEPTH = 1;
+const PIPELINE_BLEND = 4;
+
+export function createNativeRenderGpu(): RenderGpu {
+  const depthPipelines = new Set<number>();
+  return {
+    createBuffer: (usage: number, data: Uint8Array): number => {
+      const buffer = dfBuffer(usage, data);
+      if (buffer < 0) throw new Error(`dfBuffer failed: ${buffer}`);
+      return buffer;
+    },
+    writeBuffer: (buffer: number, data: Uint8Array): void => dfBufferWrite(buffer, data),
+    destroyBuffer: (buffer: number): void => dfBufferDestroy(buffer),
+    createPipeline: (pipelineOptions: PipelineOptions): number => {
+      const attributes = new Uint32Array(pipelineOptions.attributes.length * 3);
+      for (let i = 0; i < pipelineOptions.attributes.length; i++) {
+        const attribute = pipelineOptions.attributes[i];
+        attributes[i * 3] = attribute.format;
+        attributes[i * 3 + 1] = attribute.offset;
+        attributes[i * 3 + 2] = attribute.location;
+      }
+      const flags = (pipelineOptions.depth ? PIPELINE_DEPTH : 0) | (pipelineOptions.blend ? PIPELINE_BLEND : 0);
+      const attributeBytes = new Uint8Array(attributes.buffer, attributes.byteOffset, attributes.byteLength);
+      const pipeline = dfPipeline(pipelineOptions.wgsl, pipelineOptions.stride, attributeBytes, flags);
+      if (pipeline < 0) throw new Error(`dfPipeline failed: ${pipeline}`);
+      if (pipelineOptions.depth) depthPipelines.add(pipeline);
+      return pipeline;
+    },
+    bind: (pipeline: number, buffer: number, texture: number): number => {
+      const group = dfBind(pipeline, buffer, texture);
+      if (group < 0) throw new Error(`dfBind failed: ${group}`);
+      return group;
+    },
+    createTexture: (width: number, height: number, rgba: Uint8Array, smooth: boolean): Texture => {
+      const id = dfTexture(width, height, rgba, smooth);
+      if (id < 0) throw new Error(`dfTexture failed: ${id}`);
+      return { id, width, height };
+    },
+    frame: (clear: Color, draws: Draw[]): void => {
+      // Pipelines without depth cannot run in a pass with a depth attachment.
+      let usesDepth = false;
+      for (const draw of draws) if (depthPipelines.has(draw.pipeline)) usesDepth = true;
+      if (dfBegin(clear.r, clear.g, clear.b, usesDepth) !== 0) return;
+      for (const draw of draws) {
+        dfDraw(draw.pipeline, draw.bindGroup, draw.vertexBuffer, draw.indexBuffer, draw.first, draw.count);
+      }
+      dfEnd();
+    },
+    aspect: (): number => dfWidth() / Math.max(dfHeight(), 1),
+  };
+}
+
+// Decodes PNG bytes into a texture immediately.
+export function createNativeImage(png: Uint8Array, smooth: boolean): Texture {
+  const id = dfImage(png, smooth);
+  if (id < 0) throw new Error(`dfImage failed: ${id}`);
+  return { id, width: dfTextureSize(id, 0), height: dfTextureSize(id, 1) };
+}
+
+export function createNativeInput(): Input {
+  return {
+    down: (key: number): boolean => key >= 0 && key < keyScancodes.length && dfKeyDown(keyScancodes[key]),
+    firstDown: (): number => {
+      for (let key = 0; key < keyScancodes.length; key++) if (dfKeyDown(keyScancodes[key])) return key;
+      return -1;
+    },
+    axis: (pad: number, axis: number): number => dfGamepadAxis(pad, axis),
+    button: (pad: number, button: number): boolean => {
+      if (button === 6 || button === 7) return dfGamepadAxis(pad, button === 6 ? 4 : 5) > 0.5;
+      const sdl = button >= 0 && button < sdlGamepadButtons.length ? sdlGamepadButtons[button] : -1;
+      return sdl >= 0 && dfGamepadButton(pad, sdl);
+    },
+    pointer: (): Pointer => ({ x: dfMouse(0), y: dfMouse(1), buttons: dfMouse(2) }),
+    touches: (): Touch[] => {
+      const out: Touch[] = [];
+      const count = dfTouchCount();
+      for (let i = 0; i < count; i++) out.push({ id: dfTouch(i, 0), x: dfTouch(i, 1), y: dfTouch(i, 2) });
+      return out;
+    },
+  };
+}
+
+// Opens the audio device; returns false without one, so games continue silently.
+export function openNativeAudio(): boolean {
+  const ready = dfAudioOpen() === 0;
+  if (!ready) console.error("dotframe: no audio device, continuing without sound");
+  return ready;
+}
+
+export function createNativeAudioPlayer(): AudioPlayer {
+  return {
+    play: (sound: number, volume: number, rate: number): void => dfPlay(sound, volume, rate),
+    tone: (frequency: number, duration: number, volume: number): void => dfTone(frequency, duration, volume),
+    playMusic: (track: number, loop: boolean, volume: number): void => {
+      dfMusicPlay(track, loop, volume);
+    },
+    stopMusic: (): void => dfMusicStop(),
+    pauseMusic: (paused: boolean): void => dfMusicPause(paused),
+    setMusicVolume: (volume: number): void => dfMusicVolume(volume),
+    setMasterVolume: (volume: number): void => dfMasterVolume(volume),
+  };
+}
+
+export const decodeNativeSound = (mp3: Uint8Array): number => dfSound(mp3);
+export const storeNativeTrack = (mp3: Uint8Array): number => dfTrack(mp3);