@downdraft/engine 0.0.0 → 0.1.0

package/core/src/save/schema.ts

@@ -0,0 +1,46 @@
+import { createLogger } from "../util/logger";
+
+const log = createLogger();
+
+export const CURRENT_SCHEMA_VERSION = 1;
+
+export type MigrationFn = (data: unknown) => unknown;
+
+export class SchemaRegistry {
+  private migrations: Map<number, MigrationFn> = new Map();
+  private currentVersion: number = CURRENT_SCHEMA_VERSION;
+
+  registerMigration(fromVersion: number, fn: MigrationFn): void {
+    this.migrations.set(fromVersion, fn);
+  }
+
+  getCurrentVersion(): number {
+    return this.currentVersion;
+  }
+
+  migrate(data: unknown, fromVersion: number, targetVersion: number = this.currentVersion): unknown {
+    let current = data;
+    let version = fromVersion;
+
+    while (version < targetVersion) {
+      const fn = this.migrations.get(version);
+      if (!fn) {
+        version++;
+        continue;
+      }
+      try {
+        current = fn(current);
+      } catch (e) {
+        log.warn("SchemaRegistry", `Migration v${version}→v${version + 1} failed: ${e} — returning data at v${version}`);
+        return current;
+      }
+      version++;
+    }
+
+    return current;
+  }
+
+  hasMigration(fromVersion: number): boolean {
+    return this.migrations.has(fromVersion);
+  }
+}

package/core/src/save/serializer.ts

@@ -0,0 +1,180 @@
+import { getColumnValue } from "../ecs/archetype";
+import { getComponentName } from "../ecs/component";
+import type { Entity } from "../ecs/entity";
+import type { World } from "../ecs/world";
+import { SchemaRegistry } from "./schema";
+
+/** Maximum number of entities allowed in a deserialized scene. */
+const MAX_ENTITY_COUNT = 1_000_000;
+/** Maximum number of components per entity in a deserialized scene. */
+const MAX_COMPONENTS_PER_ENTITY = 256;
+
+export interface SaveData {
+  schemaVersion: number;
+  scene: {
+    name: string;
+    entities: Array<{
+      index: number;
+      generation: number;
+      components: Array<{ id: number; data: unknown }>;
+    }>;
+  };
+  binaryBlobs?: Record<string, ArrayBuffer>;
+}
+
+export class Serializer {
+  serialize(world: World, sceneName: string): SaveData {
+    const entities: SaveData["scene"]["entities"] = [];
+    const binaryBlobs: Record<string, ArrayBuffer> = {};
+
+    for (let i = 1; i < world.entities.length; i++) {
+      const meta = world.entities[i];
+      if (!meta.alive) continue;
+
+      const arch = world.archetypeById.get(meta.archetypeId);
+      if (!arch) continue;
+
+      const entity: Entity = { index: i, generation: meta.generation };
+      const components: Array<{ id: number; data: unknown }> = [];
+
+      for (const [cid, col] of arch.columns.entries()) {
+        const row = arch.entities.findIndex(
+          (e) => e.index === entity.index && e.generation === entity.generation,
+        );
+        if (row >= 0) {
+          const data = getColumnValue(col, row);
+          if (data instanceof ArrayBuffer) {
+            const blobKey = `blob_${i}_${cid}`;
+            binaryBlobs[blobKey] = data;
+            components.push({ id: cid, data: { __blobRef: blobKey } });
+          } else if (data instanceof Float32Array || data instanceof Float64Array ||
+                     data instanceof Int32Array || data instanceof Uint32Array ||
+                     data instanceof Uint8Array || data instanceof Int8Array ||
+                     data instanceof Int16Array || data instanceof Uint16Array) {
+            const blobKey = `blob_${i}_${cid}`;
+            const buf = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+            binaryBlobs[blobKey] = buf instanceof ArrayBuffer ? buf : new ArrayBuffer(buf.byteLength);
+            new Uint8Array(binaryBlobs[blobKey]).set(new Uint8Array(buf));
+            components.push({ id: cid, data: { __blobRef: blobKey } });
+          } else {
+            components.push({ id: cid, data });
+          }
+        }
+      }
+
+      entities.push({ index: i, generation: meta.generation, components });
+    }
+
+    return {
+      schemaVersion: 1,
+      scene: { name: sceneName, entities },
+      binaryBlobs: Object.keys(binaryBlobs).length > 0 ? binaryBlobs : undefined,
+    };
+  }
+
+  deserialize(data: SaveData, world: World, schemaRegistry: SchemaRegistry): void {
+    const migrated = schemaRegistry.migrate(data, data.schemaVersion) as SaveData;
+    const blobs = migrated.binaryBlobs ?? {};
+
+    // Bounds validation — prevent OOM / integer overflow from malformed saves.
+    const entityCount = migrated.scene.entities.length;
+    if (entityCount > MAX_ENTITY_COUNT) {
+      throw new RangeError(
+        `deserialize: entity count ${entityCount} exceeds maximum ${MAX_ENTITY_COUNT}`,
+      );
+    }
+
+    for (let i = 0; i < world.entities.length; i++) {
+      const meta = world.entities[i];
+      if (meta.alive) {
+        world.despawn({ index: i, generation: meta.generation });
+      }
+    }
+    world.flushCommands();
+
+    for (let i = 0; i < migrated.scene.entities.length; i++) {
+      const entry = migrated.scene.entities[i];
+
+      // Validate component count per entity.
+      if (entry.components.length > MAX_COMPONENTS_PER_ENTITY) {
+        throw new RangeError(
+          `deserialize: entity ${i} has ${entry.components.length} components, exceeds maximum ${MAX_COMPONENTS_PER_ENTITY}`,
+        );
+      }
+
+      const components = new Map<number, unknown>();
+      for (let j = 0; j < entry.components.length; j++) {
+        const comp = entry.components[j];
+
+        // Validate component ID exists in the component registry.
+        const compName = getComponentName(comp.id);
+        if (compName.startsWith("Unknown(")) {
+          throw new Error(
+            `deserialize: entity ${i} references unregistered component ID ${comp.id}`,
+          );
+        }
+
+        if (comp.data && typeof comp.data === "object" && "__blobRef" in (comp.data as Record<string, unknown>)) {
+          const ref = (comp.data as Record<string, string>).__blobRef;
+          components.set(comp.id, blobs[ref] ?? new ArrayBuffer(0));
+        } else {
+          components.set(comp.id, comp.data);
+        }
+      }
+      world.spawn(components);
+    }
+  }
+
+  toJSON(data: SaveData): string {
+    return JSON.stringify(data, (_key, value) => {
+      if (value instanceof ArrayBuffer) {
+        return { __type: "ArrayBuffer", __data: arrayBufferToBase64(value) };
+      }
+      if (typeof value === "object" && value !== null && value.buffer instanceof ArrayBuffer && !Array.isArray(value)) {
+        return { __type: "TypedArray", __data: arrayBufferToBase64(value.buffer) };
+      }
+      return value;
+    }, 2);
+  }
+
+  fromJSON(json: string): SaveData {
+    return JSON.parse(json, (_key, value) => {
+      if (value && typeof value === "object" && value.__type === "ArrayBuffer" && typeof value.__data === "string") {
+        return base64ToArrayBuffer(value.__data);
+      }
+      if (value && typeof value === "object" && value.__type === "TypedArray" && typeof value.__data === "string") {
+        return base64ToArrayBuffer(value.__data);
+      }
+      return value;
+    });
+  }
+
+  toBinary(data: SaveData): ArrayBuffer {
+    const json = this.toJSON(data);
+    const encoder = new TextEncoder();
+    return encoder.encode(json).buffer;
+  }
+
+  fromBinary(buffer: ArrayBuffer): SaveData {
+    const decoder = new TextDecoder();
+    return this.fromJSON(decoder.decode(buffer));
+  }
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}

package/core/src/scene/builder.ts

@@ -0,0 +1,65 @@
+import type { ComponentDefinition } from "../ecs/component";
+import type { Entity } from "../ecs/entity";
+import type { Hierarchy } from "../ecs/hierarchy";
+import type { World } from "../ecs/world";
+import type { Prefab, PrefabComponentEntry } from "./prefab";
+
+export interface ComponentSpec<T extends Record<string, unknown>> {
+  def: ComponentDefinition<T>;
+  overrides?: Partial<T>;
+}
+
+export function c<T extends Record<string, unknown>>(
+  def: ComponentDefinition<T>,
+  overrides?: Partial<T>,
+): ComponentSpec<T> {
+  return { def, overrides };
+}
+
+export function spawn(
+  world: World,
+  ...specs: ComponentSpec<any>[]
+): Entity {
+  const components = new Map<number, unknown>();
+  specs.forEach((spec) => {
+    const data = spec.def.create(spec.overrides);
+    components.set(spec.def.id, data);
+  });
+  return world.spawn(components);
+}
+
+export function spawnChild(
+  world: World,
+  hierarchy: Hierarchy,
+  parent: Entity,
+  ...specs: ComponentSpec<any>[]
+): Entity {
+  const entity = spawn(world, ...specs);
+  hierarchy.setParent(entity, parent);
+  return entity;
+}
+
+export function batch(
+  world: World,
+  count: number,
+  factory: (i: number) => ComponentSpec<any>[],
+): Entity[] {
+  const entities: Entity[] = [];
+  for (let i = 0; i < count; i++) {
+    const specs = factory(i);
+    entities.push(spawn(world, ...specs));
+  }
+  return entities;
+}
+
+export function builderToPrefab(
+  name: string,
+  specs: ComponentSpec<any>[],
+  tags?: string[],
+): Prefab {
+  const components: PrefabComponentEntry[] = specs.map((spec) => ({
+    componentId: spec.def.id,
+    data: { ...spec.def.defaults, ...spec.overrides } as Record<string, unknown>,
+  }));
+  return { name, components, tags };
+}

package/core/src/scene/camera.ts

@@ -0,0 +1,142 @@
+import { mat4, vec3, type Mat4 } from "wgpu-matrix";
+
+export interface CameraData {
+  position: [number, number, number];
+  target: [number, number, number];
+  up: [number, number, number];
+  fov: number;
+  aspect: number;
+  near: number;
+  far: number;
+  yaw: number;
+  pitch: number;
+  distance: number;
+}
+
+export class Camera {
+  position: [number, number, number] = [0, 5, 10];
+  target: [number, number, number] = [0, 0, 0];
+  up: [number, number, number] = [0, 1, 0];
+  fov: number = 60;
+  aspect: number = 1;
+  near: number = 0.1;
+  far: number = 1000;
+  yaw: number = 0;
+  pitch: number = 0.3;
+  distance: number = 10;
+
+  private viewMatrix: Mat4 = mat4.identity();
+  private projMatrix: Mat4 = mat4.identity();
+  private viewProjMatrix: Mat4 = mat4.identity();
+  private viewDirty: boolean = true;
+  private projDirty: boolean = true;
+
+  setPosition(x: number, y: number, z: number): void {
+    this.position = [x, y, z];
+    this.viewDirty = true;
+  }
+
+  setTarget(x: number, y: number, z: number): void {
+    this.target = [x, y, z];
+    this.viewDirty = true;
+  }
+
+  setAspect(width: number, height: number): void {
+    this.aspect = width / height;
+    this.projDirty = true;
+  }
+
+  setFov(degrees: number): void {
+    this.fov = degrees;
+    this.projDirty = true;
+  }
+
+  orbit(deltaYaw: number, deltaPitch: number): void {
+    this.yaw += deltaYaw;
+    this.pitch += deltaPitch;
+    const maxPitch = Math.PI / 2 - 0.01;
+    if (this.pitch > maxPitch) this.pitch = maxPitch;
+    if (this.pitch < -maxPitch) this.pitch = -maxPitch;
+    this.updatePosition();
+  }
+
+  zoom(delta: number): void {
+    this.distance -= delta;
+    if (this.distance < 0.1) this.distance = 0.1;
+    if (this.distance > 500) this.distance = 500;
+    this.updatePosition();
+  }
+
+  pan(deltaX: number, deltaY: number): void {
+    const forward = vec3.normalize(vec3.subtract(this.target, this.position));
+    const right = vec3.normalize(vec3.cross(forward, this.up));
+    const panAmount = this.distance * 0.001;
+    this.target = vec3.subtract(this.target, vec3.scale(right, deltaX * panAmount)) as [number, number, number];
+    this.target = vec3.add(this.target, vec3.scale(this.up, deltaY * panAmount)) as [number, number, number];
+    this.updatePosition();
+  }
+
+  private updatePosition(): void {
+    const cosPitch = Math.cos(this.pitch);
+    const sinPitch = Math.sin(this.pitch);
+    const cosYaw = Math.cos(this.yaw);
+    const sinYaw = Math.sin(this.yaw);
+
+    this.position = [
+      this.target[0] + this.distance * cosPitch * sinYaw,
+      this.target[1] + this.distance * sinPitch,
+      this.target[2] + this.distance * cosPitch * cosYaw,
+    ];
+    this.viewDirty = true;
+  }
+
+  isViewDirty(): boolean {
+    return this.viewDirty;
+  }
+
+  isProjDirty(): boolean {
+    return this.projDirty;
+  }
+
+  getViewMatrix(): Mat4 {
+    if (this.viewDirty || this.projDirty) this.updateMatrices();
+    return this.viewMatrix;
+  }
+
+  getProjectionMatrix(): Mat4 {
+    if (this.viewDirty || this.projDirty) this.updateMatrices();
+    return this.projMatrix;
+  }
+
+  getViewProjectionMatrix(): Mat4 {
+    if (this.viewDirty || this.projDirty) this.updateMatrices();
+    return this.viewProjMatrix;
+  }
+
+  private updateMatrices(): void {
+    if (this.viewDirty) {
+      this.viewMatrix = mat4.lookAt(this.position, this.target, this.up);
+      this.viewDirty = false;
+    }
+    if (this.projDirty) {
+      this.projMatrix = mat4.perspective(this.fov * (Math.PI / 180), this.aspect, this.near, this.far);
+      this.projDirty = false;
+    }
+    this.viewProjMatrix = mat4.multiply(this.projMatrix, this.viewMatrix);
+  }
+
+  getData(): CameraData {
+    return {
+      position: [this.position[0], this.position[1], this.position[2]],
+      target: [this.target[0], this.target[1], this.target[2]],
+      up: [this.up[0], this.up[1], this.up[2]],
+      fov: this.fov,
+      aspect: this.aspect,
+      near: this.near,
+      far: this.far,
+      yaw: this.yaw,
+      pitch: this.pitch,
+      distance: this.distance,
+    };
+  }
+}

package/core/src/scene/checkpoint.ts

@@ -0,0 +1,109 @@
+import { findEntityRow, getColumnValue } from "../ecs/archetype";
+import type { Entity } from "../ecs/entity";
+import type { World } from "../ecs/world";
+
+export interface CheckpointData {
+  name: string;
+  timestamp: number;
+  entities: Array<{
+    entity: Entity;
+    components: Array<{ id: number; data: unknown }>;
+  }>;
+}
+
+export class CheckpointManager {
+  private checkpoints: Map<string, CheckpointData> = new Map();
+  private history: string[] = [];
+  private maxHistory: number = 50;
+
+  create(name: string, world: World): CheckpointData {
+    const entities: CheckpointData["entities"] = [];
+
+    for (let i = 1; i < world.entities.length; i++) {
+      const meta = world.entities[i];
+      if (!meta.alive) continue;
+
+      const arch = world.archetypeById.get(meta.archetypeId);
+      if (!arch) continue;
+
+      const entity: Entity = { index: i, generation: meta.generation };
+      const components: Array<{ id: number; data: unknown }> = [];
+
+      for (const [cid, col] of arch.columns.entries()) {
+        const row = findEntityRow(arch, entity);
+        if (row >= 0) {
+          components.push({ id: cid, data: getColumnValue(col, row) });
+        }
+      }
+
+      entities.push({ entity, components });
+    }
+
+    const cp: CheckpointData = {
+      name,
+      timestamp: Date.now(),
+      entities,
+    };
+
+    this.checkpoints.set(name, cp);
+    this.history.push(name);
+    if (this.history.length > this.maxHistory) {
+      const old = this.history.shift()!;
+      this.checkpoints.delete(old);
+    }
+
+    return cp;
+  }
+
+  restore(name: string, world: World): boolean {
+    const cp = this.checkpoints.get(name);
+    if (!cp) return false;
+
+    // Despawn all existing alive entities (including root) to prevent duplicates
+    for (let i = 0; i < world.entities.length; i++) {
+      const meta = world.entities[i];
+      if (meta.alive) {
+        const entity: Entity = { index: i, generation: meta.generation };
+        world.despawn(entity);
+      }
+    }
+    world.flushCommands();
+
+    // Spawn entities from checkpoint
+    for (let i = 0; i < cp.entities.length; i++) {
+      const entry = cp.entities[i];
+      const components = new Map<number, unknown>();
+      for (let j = 0; j < entry.components.length; j++) {
+        components.set(entry.components[j].id, entry.components[j].data);
+      }
+      world.spawn(components);
+    }
+
+    return true;
+  }
+
+  list(): CheckpointData[] {
+    return [...this.checkpoints.values()];
+  }
+
+  diff(a: string, b: string): { added: string[]; removed: string[]; changed: string[] } | null {
+    const cpA = this.checkpoints.get(a);
+    const cpB = this.checkpoints.get(b);
+    if (!cpA || !cpB) return null;
+
+    const entitiesA = new Set(cpA.entities.map((e) => `${e.entity.index}.${e.entity.generation}`));
+    const entitiesB = new Set(cpB.entities.map((e) => `${e.entity.index}.${e.entity.generation}`));
+
+    const added: string[] = [];
+    const removed: string[] = [];
+
+    for (const id of entitiesB.values()) {
+      if (!entitiesA.has(id)) added.push(id);
+    }
+    for (const id of entitiesA.values()) {
+      if (!entitiesB.has(id)) removed.push(id);
+    }
+
+    return { added, removed, changed: [] };
+  }
+}