@downdraft/engine 0.0.0 → 0.1.1

package/core/src/scene/streaming.ts

@@ -0,0 +1,304 @@
+import type { AssetManager, AssetPriority } from "../assets/manager";
+import type { Entity } from "../ecs/entity";
+import type { World } from "../ecs/world";
+import { createLogger } from "../util/logger";
+import type { Camera } from "./camera";
+
+const log = createLogger();
+
+export interface ChunkCoord {
+  x: number;
+  z: number;
+}
+
+export interface ChunkKey {
+  coord: ChunkCoord;
+  key: string;
+}
+
+export interface ChunkData {
+  name?: string;
+  coord: ChunkCoord;
+  entities: Entity[];
+  loaded: boolean;
+  loadTime: number;
+  lastAccessed: number;
+}
+
+export interface StreamConfig {
+  chunkSize: number;
+  loadRadius: number;
+  unloadRadius: number;
+  maxConcurrentLoads: number;
+  cameraPos?: () => [number, number, number];
+  loader?: ChunkLoader;
+  unloader?: ChunkUnloader;
+  assetManager?: AssetManager;
+  assetUriPrefix?: string;
+}
+
+export type ChunkLoader = (coord: ChunkCoord) => Promise<Entity[]>;
+export type ChunkUnloader = (coord: ChunkCoord, data: ChunkData) => void;
+
+function distanceToPriority(distSq: number, loadRadius: number): AssetPriority {
+  const dist = Math.sqrt(distSq);
+  const ratio = dist / loadRadius;
+  if (ratio < 0.25) return "critical";
+  if (ratio < 0.5) return "high";
+  if (ratio < 0.75) return "normal";
+  return "low";
+}
+
+export function chunkKey(coord: ChunkCoord): string {
+  return `${coord.x}:${coord.z}`;
+}
+
+export function worldToChunk(pos: [number, number, number], chunkSize: number): ChunkCoord {
+  return {
+    x: Math.floor(pos[0] / chunkSize),
+    z: Math.floor(pos[2] / chunkSize),
+  };
+}
+
+interface ChunkLoadEntry {
+  coord: ChunkCoord;
+  priority: AssetPriority;
+  priorityValue: number;
+}
+
+const CHUNK_PRIORITY_VALUES: Record<AssetPriority, number> = {
+  critical: 0,
+  high: 1,
+  normal: 2,
+  low: 3,
+  background: 4,
+};
+
+const MAX_CHUNK_RETRIES = 5;
+const INITIAL_RETRY_DELAY_MS = 1000;
+
+export class WorldStreamer {
+  private config: StreamConfig;
+  private chunks: Map<string, ChunkData> = new Map();
+  private loadQueue: ChunkLoadEntry[] = [];
+  private loading: Set<string> = new Set();
+  private retryCounts: Map<string, number> = new Map();
+  private world: World;
+  private camera: Camera;
+
+  constructor(world: World, camera: Camera, config: StreamConfig) {
+    this.world = world;
+    this.camera = camera;
+    this.config = config;
+  }
+
+  async update(): Promise<void> {
+    const camPos: [number, number, number] = this.config.cameraPos ? this.config.cameraPos() : [this.camera.position[0], this.camera.position[1], this.camera.position[2]];
+    const camChunk = worldToChunk(camPos, this.config.chunkSize);
+
+    this.checkUnload(camChunk);
+    this.checkLoad(camChunk);
+    await this.processLoadQueue();
+  }
+
+  private checkLoad(camChunk: ChunkCoord): void {
+    const radius = this.config.loadRadius;
+    for (let dx = -radius; dx <= radius; dx++) {
+      for (let dz = -radius; dz <= radius; dz++) {
+        const coord = { x: camChunk.x + dx, z: camChunk.z + dz };
+        const key = chunkKey(coord);
+        const chunk = this.chunks.get(key);
+
+        if (chunk && chunk.loaded) {
+          chunk.lastAccessed = Date.now();
+          continue;
+        }
+
+        if (this.loading.has(key)) continue;
+        if (this.loadQueue.some((e) => e.coord.x === coord.x && e.coord.z === coord.z)) continue;
+
+        const distSq = dx * dx + dz * dz;
+        if (distSq > radius * radius) continue;
+
+        const priority = distanceToPriority(distSq, radius);
+        this.loadQueue.push({
+          coord,
+          priority,
+          priorityValue: CHUNK_PRIORITY_VALUES[priority],
+        });
+      }
+    }
+
+    this.loadQueue.sort((a, b) => {
+      if (a.priorityValue !== b.priorityValue) return a.priorityValue - b.priorityValue;
+      const distA = (a.coord.x - camChunk.x) ** 2 + (a.coord.z - camChunk.z) ** 2;
+      const distB = (b.coord.x - camChunk.x) ** 2 + (b.coord.z - camChunk.z) ** 2;
+      return distA - distB;
+    });
+  }
+
+  private checkUnload(camChunk: ChunkCoord): void {
+    const unloadRadius = this.config.unloadRadius;
+    const toUnload: string[] = [];
+
+    for (const [key, chunk] of this.chunks.entries()) {
+      if (!chunk.loaded) continue;
+      const dx = chunk.coord.x - camChunk.x;
+      const dz = chunk.coord.z - camChunk.z;
+      const distSq = dx * dx + dz * dz;
+      if (distSq > unloadRadius * unloadRadius) {
+        toUnload.push(key);
+      }
+    }
+
+    for (let _i = 0, _it = toUnload, _n = _it.length; _i < _n; _i++) { const key = _it[_i];
+      const chunk = this.chunks.get(key);
+      if (!chunk) continue;
+      if (this.config.unloader) {
+        this.config.unloader(chunk.coord, chunk);
+      } else {
+        chunk.entities.forEach((entity) => {
+          this.world._despawnImmediate(entity);
+        });
+      }
+      chunk.loaded = false;
+      chunk.entities = [];
+      this.chunks.delete(key);
+    }
+  }
+
+  private async processLoadQueue(): Promise<void> {
+    const loader = this.config.loader;
+    if (!loader) return;
+    while (this.loadQueue.length > 0 && this.loading.size < this.config.maxConcurrentLoads) {
+      const entry = this.loadQueue.shift()!;
+      const coord = entry.coord;
+      const key = chunkKey(coord);
+      if (this.loading.has(key)) continue;
+      if (this.chunks.has(key) && this.chunks.get(key)!.loaded) continue;
+
+      this.loading.add(key);
+
+      try {
+        if (this.config.assetManager && this.config.assetUriPrefix) {
+          const assetUri = `${this.config.assetUriPrefix}${key}.chunk`;
+          await this.config.assetManager.load(assetUri, entry.priority);
+        }
+
+        const entities = await loader(coord);
+        const chunk: ChunkData = {
+          coord,
+          entities,
+          loaded: true,
+          loadTime: Date.now(),
+          lastAccessed: Date.now(),
+        };
+        this.chunks.set(key, chunk);
+        this.retryCounts.delete(key);
+      } catch (err) {
+        const retries = this.retryCounts.get(key) ?? 0;
+        if (retries >= MAX_CHUNK_RETRIES) {
+          log.error("WorldStreamer", `Chunk ${key} failed after ${MAX_CHUNK_RETRIES} retries: ${err}`);
+          this.retryCounts.delete(key);
+        } else {
+          const delay = INITIAL_RETRY_DELAY_MS * (1 << retries);
+          this.retryCounts.set(key, retries + 1);
+          log.warn("WorldStreamer", `Chunk ${key} load failed (retry ${retries + 1}/${MAX_CHUNK_RETRIES}), retrying in ${delay}ms: ${err}`);
+          setTimeout(() => {
+            this.loadQueue.push({
+              coord,
+              priority: entry.priority,
+              priorityValue: entry.priorityValue,
+            });
+          }, delay);
+        }
+      } finally {
+        this.loading.delete(key);
+      }
+    }
+  }
+
+  getLoadedChunks(): ChunkData[] {
+    return [...this.chunks.values()].filter((c) => c.loaded);
+  }
+
+  getLoadedCount(): number {
+    return this.getLoadedChunkCount();
+  }
+
+  getLoadedChunkCount(): number {
+    let count = 0;
+    for (const chunk of this.chunks.values()) {
+      if (chunk.loaded) count++;
+    }
+    return count;
+  }
+
+  getPendingLoadCount(): number {
+    return this.loadQueue.length + this.loading.size;
+  }
+
+  getLoadQueuePriorities(): { coord: ChunkCoord; priority: AssetPriority }[] {
+    return this.loadQueue.map((e) => ({ coord: e.coord, priority: e.priority }));
+  }
+
+  isChunkLoaded(coord: ChunkCoord): boolean {
+    const chunk = this.chunks.get(chunkKey(coord));
+    return chunk?.loaded ?? false;
+  }
+
+  getChunk(coord: ChunkCoord): ChunkData | undefined {
+    return this.chunks.get(chunkKey(coord));
+  }
+
+  forceLoad(coord: ChunkCoord): Promise<void> {
+    this.loadQueue.unshift({
+      coord,
+      priority: "critical",
+      priorityValue: 0,
+    });
+    return this.processLoadQueue();
+  }
+
+  forceUnload(coord: ChunkCoord): void {
+    const key = chunkKey(coord);
+    const chunk = this.chunks.get(key);
+    if (!chunk || !chunk.loaded) return;
+    if (this.config.unloader) {
+      this.config.unloader(chunk.coord, chunk);
+    } else {
+      chunk.entities.forEach((entity) => {
+        this.world._despawnImmediate(entity);
+      });
+    }
+    chunk.loaded = false;
+    chunk.entities = [];
+    this.chunks.delete(key);
+  }
+
+  unloadAll(): void {
+    for (const [key, chunk] of this.chunks.entries()) {
+      if (chunk.loaded) {
+        if (this.config.unloader) {
+          this.config.unloader(chunk.coord, chunk);
+        } else {
+          chunk.entities.forEach((entity) => {
+            this.world._despawnImmediate(entity);
+          });
+        }
+      }
+    }
+    this.chunks.clear();
+    this.loadQueue = [];
+    this.loading.clear();
+    this.retryCounts.clear();
+  }
+
+  getStats(): { loaded: number; pending: number; loading: number } {
+    return {
+      loaded: this.getLoadedChunkCount(),
+      pending: this.loadQueue.length,
+      loading: this.loading.size,
+    };
+  }
+}

package/core/src/scene/vegetation.ts

@@ -0,0 +1,163 @@
+import { Component } from "../ecs/component";
+
+export interface VegetationPatchData {
+  [key: string]: unknown;
+  patchX: number;
+  patchZ: number;
+  density: number;
+  instanceCount: number;
+  meshId: number;
+  materialId: number;
+  castShadows: boolean;
+  receiveShadows: boolean;
+  windEnabled: boolean;
+  windStrength: number;
+  windDirection: [number, number];
+  windFrequency: number;
+  lodDistance: number;
+  cullDistance: number;
+}
+
+export const VegetationPatch = Component.register<VegetationPatchData>("VegetationPatch", {
+  patchX: 0,
+  patchZ: 0,
+  density: 1.0,
+  instanceCount: 0,
+  meshId: -1,
+  materialId: -1,
+  castShadows: true,
+  receiveShadows: false,
+  windEnabled: true,
+  windStrength: 0.3,
+  windDirection: [1, 0],
+  windFrequency: 1.5,
+  lodDistance: 50,
+  cullDistance: 200,
+});
+
+export interface VegetationInstance {
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: number;
+  colorVariation: number;
+}
+
+export interface WindState {
+  time: number;
+  gustStrength: number;
+  gustFrequency: number;
+  direction: [number, number];
+}
+
+export class VegetationWindSystem {
+  private time = 0;
+  private config: WindState;
+
+  constructor(config?: Partial<WindState>) {
+    this.config = {
+      time: 0,
+      gustStrength: 0.5,
+      gustFrequency: 0.3,
+      direction: [1, 0],
+      ...config,
+    };
+  }
+
+  update(dt: number): void {
+    this.time += dt;
+    this.config.time = this.time;
+  }
+
+  computeWindOffset(x: number, z: number, height: number): [number, number, number] {
+    const t = this.time;
+    const gust = Math.sin(x * 0.1 + t * this.config.gustFrequency) *
+                 Math.cos(z * 0.1 + t * this.config.gustFrequency * 0.7);
+    const sway = Math.sin(t * 2 + x * 0.3 + z * 0.2) * 0.5 + 0.5;
+    const strength = this.config.gustStrength * (0.5 + gust * 0.5);
+    const heightFactor = Math.min(1, height / 2);
+
+    const dirLen = Math.sqrt(this.config.direction[0] ** 2 + this.config.direction[1] ** 2);
+    const dx = dirLen > 0 ? this.config.direction[0] / dirLen : 1;
+    const dz = dirLen > 0 ? this.config.direction[1] / dirLen : 0;
+
+    return [
+      dx * strength * sway * heightFactor,
+      0,
+      dz * strength * sway * heightFactor,
+    ];
+  }
+
+  packWindUniforms(): Float32Array {
+    const data = new Float32Array(8);
+    data[0] = this.config.gustStrength;
+    data[1] = this.config.gustFrequency;
+    data[2] = this.config.direction[0];
+    data[3] = this.config.direction[1];
+    data[4] = this.time;
+    return data;
+  }
+
+  setDirection(dir: [number, number]): void {
+    this.config.direction = dir;
+  }
+
+  setGustStrength(strength: number): void {
+    this.config.gustStrength = strength;
+  }
+
+  setGustFrequency(freq: number): void {
+    this.config.gustFrequency = freq;
+  }
+}
+
+export function generateInstances(
+  patchX: number,
+  patchZ: number,
+  patchSize: number,
+  density: number,
+  seed: number,
+): VegetationInstance[] {
+  const instances: VegetationInstance[] = [];
+  const count = Math.floor(patchSize * patchSize * density * 0.01);
+
+  for (let i = 0; i < count; i++) {
+    const hash1 = hash(seed + i * 3);
+    const hash2 = hash(seed + i * 3 + 1);
+    const hash3 = hash(seed + i * 3 + 2);
+
+    const x = patchX * patchSize + hash1 * patchSize;
+    const z = patchZ * patchSize + hash2 * patchSize;
+    const y = 0;
+
+    instances.push({
+      position: [x, y, z],
+      rotation: [0, hash3 * Math.PI * 2, 0],
+      scale: 0.8 + hash(seed + i * 7) * 0.4,
+      colorVariation: hash(seed + i * 11),
+    });
+  }
+
+  return instances;
+}
+
+function hash(n: number): number {
+  const s = Math.sin(n * 12.9898) * 43758.5453;
+  return s - Math.floor(s);
+}
+
+export function packInstanceData(instances: VegetationInstance[]): Float32Array {
+  const data = new Float32Array(instances.length * 8);
+  for (let i = 0; i < instances.length; i++) {
+    const inst = instances[i];
+    const offset = i * 8;
+    data[offset] = inst.position[0];
+    data[offset + 1] = inst.position[1];
+    data[offset + 2] = inst.position[2];
+    data[offset + 3] = inst.rotation[1];
+    data[offset + 4] = inst.scale;
+    data[offset + 5] = inst.colorVariation;
+    data[offset + 6] = 0;
+    data[offset + 7] = 0;
+  }
+  return data;
+}

package/core/src/scene/world.ts

@@ -0,0 +1,89 @@
+import type { Entity } from "../ecs/entity";
+import { Hierarchy } from "../ecs/hierarchy";
+import type { World } from "../ecs/world";
+import { ModuleHost } from "../module/host";
+import type { Module } from "../module/module";
+import type { Camera } from "./camera";
+import { PrefabFactory, PrefabRegistry } from "./prefab";
+import type { Scene } from "./scene";
+import { SceneManager } from "./scene-manager";
+
+export interface WorldResources {
+  camera?: Camera;
+  time: number;
+  dt: number;
+  /** Interpolation alpha (0.0–1.0) set by GameLoop for render interpolation. */
+  alpha: number;
+}
+
+export class GameWorld {
+  scene: Scene;
+  sceneManager: SceneManager;
+  world: World;
+  resources: WorldResources = { time: 0, dt: 0, alpha: 0 };
+  moduleHost: ModuleHost;
+  prefabRegistry: PrefabRegistry;
+  prefabFactory: PrefabFactory;
+  hierarchy: Hierarchy;
+
+  constructor(scene: Scene) {
+    this.scene = scene;
+    this.world = scene.world;
+    this.sceneManager = new SceneManager(this.world);
+    this.sceneManager.register(scene);
+    this.hierarchy = new Hierarchy();
+    this.moduleHost = new ModuleHost(this.world);
+    this.prefabRegistry = new PrefabRegistry();
+    this.prefabFactory = new PrefabFactory(this.world, this.prefabRegistry, this.hierarchy);
+  }
+
+  useModule(plugin: Module): void {
+    this.moduleHost.registerModule(plugin);
+  }
+
+  /**
+   * Register multiple plugins and activate them in dependency-resolved order.
+   * Preferred over `useModule()` when registering multiple plugins with
+   * interdependencies, as it activates them in topological order.
+   */
+  useModules(plugins: Module[]): void {
+    for (let i = 0; i < plugins.length; i++) {
+      this.moduleHost.registerModuleDeferred(plugins[i]);
+    }
+    this.moduleHost.activateAll();
+  }
+
+  async loadModule(pluginPath: string): Promise<void> {
+    await this.moduleHost.loadModule(pluginPath);
+  }
+
+  unloadModule(name: string): void {
+    this.moduleHost.unloadModule(name);
+  }
+
+  registerPrefab(name: string, components: Map<number, unknown>, tags?: string[]): void {
+    const entries = [];
+    for (const [componentId, data] of components.entries()) {
+      entries.push({ componentId, data: data as Record<string, unknown> });
+    }
+    this.prefabRegistry.register({ name, components: entries, tags });
+  }
+
+  spawnPrefab(prefabName: string, parent?: Entity): Entity {
+    return this.prefabFactory.spawn(prefabName, parent);
+  }
+
+  step(dt: number, alpha?: number): void {
+    this.resources.dt = dt;
+    this.resources.time += dt;
+    if (alpha !== undefined) {
+      this.resources.alpha = alpha;
+    }
+    this.world.step(dt);
+  }
+
+  dispose(): void {
+    this.sceneManager.dispose();
+    this.moduleHost.disposeAll();
+  }
+}

package/core/src/scripting/binding.ts

@@ -0,0 +1,129 @@
+import type { ComponentId } from "../ecs/component";
+import { getComponentId } from "../ecs/component";
+import type { Entity } from "../ecs/entity";
+import type { Query } from "../ecs/query";
+import { query, queryChanged, queryExcluded } from "../ecs/query";
+import type { ResourceToken } from "../ecs/resource";
+import type { Stage, SystemFn } from "../ecs/system";
+import type { World } from "../ecs/world";
+
+export type { ScriptContext, ScriptHandle, ScriptModule } from "./script";
+
+export interface ScriptBinding {
+  registerSystem(stage: Stage, fn: SystemFn): void;
+  registerEventHandler(eventName: string, handler: (event: unknown) => void): void;
+  query(...componentNames: string[]): Query;
+  queryExcluded(required: string[], excluded: string[]): Query;
+  queryChanged(required: string[], changedComponent: string): Query;
+  getComponent<T>(entity: Entity, componentName: string): T | null;
+  setComponent<T>(entity: Entity, componentName: string, data: T): void;
+  hasComponent(entity: Entity, componentName: string): boolean;
+  spawn(components: Map<string, unknown>): Entity;
+  despawn(entity: Entity): void;
+  getResource<T>(token: ResourceToken<T>): T | undefined;
+  setResource<T>(token: ResourceToken<T>, value: T): void;
+  sendEvent<T>(eventName: string, event: T): void;
+  readEvents<T>(eventName: string): T[];
+}
+
+export function createScriptBinding(
+  world: World,
+  scriptName: string,
+  systems: Array<{ stage: Stage; fn: SystemFn }>,
+): ScriptBinding {
+  const binding: ScriptBinding = {
+    registerSystem(stage: Stage, fn: SystemFn): void {
+      systems.push({ stage, fn });
+      world.schedule.add({
+        name: `script:${scriptName}:${systems.length}`,
+        stage,
+        fn,
+        queries: [],
+      });
+    },
+
+    registerEventHandler(eventName: string, handler: (event: unknown) => void): void {
+      const systemFn: SystemFn = () => {
+        const events = world.events.read<unknown>(eventName);
+        for (let i = 0; i < events.length; i++) {
+          handler(events[i]);
+        }
+      };
+      systems.push({ stage: 1, fn: systemFn });
+      world.schedule.add({
+        name: `script:${scriptName}:event_${eventName}:${systems.length}`,
+        stage: 1,
+        fn: systemFn,
+        queries: [],
+      });
+    },
+
+    query(...componentNames: string[]): Query {
+      const ids = componentNames.map((n) => getComponentId(n));
+      const q = query(...ids);
+      q.updateArchetypes(world.allArchetypes);
+      return q;
+    },
+
+    queryExcluded(required: string[], excluded: string[]): Query {
+      const reqIds = required.map((n) => getComponentId(n));
+      const excIds = excluded.map((n) => getComponentId(n));
+      const q = queryExcluded(reqIds, excIds);
+      q.updateArchetypes(world.allArchetypes);
+      return q;
+    },
+
+    queryChanged(required: string[], changedComponent: string): Query {
+      const reqIds = required.map((n) => getComponentId(n));
+      const changedId = getComponentId(changedComponent);
+      const q = queryChanged(reqIds, changedId);
+      q.updateArchetypes(world.allArchetypes);
+      return q;
+    },
+
+    getComponent<T>(entity: Entity, componentName: string): T | null {
+      const cid = getComponentId(componentName);
+      return world.getComponent<T>(entity, cid);
+    },
+
+    setComponent<T>(entity: Entity, componentName: string, data: T): void {
+      const cid = getComponentId(componentName);
+      world.addComponent(entity, cid, data);
+    },
+
+    hasComponent(entity: Entity, componentName: string): boolean {
+      const cid = getComponentId(componentName);
+      return world.hasComponent(entity, cid);
+    },
+
+    spawn(components: Map<string, unknown>): Entity {
+      const idMap = new Map<ComponentId, unknown>();
+      for (const [name, data] of components.entries()) {
+        idMap.set(getComponentId(name), data);
+      }
+      return world.spawn(idMap);
+    },
+
+    despawn(entity: Entity): void {
+      world.despawn(entity);
+    },
+
+    getResource<T>(token: ResourceToken<T>): T | undefined {
+      return world.getResourceTyped<T>(token);
+    },
+
+    setResource<T>(token: ResourceToken<T>, value: T): void {
+      world.setResourceTyped(token, value);
+    },
+
+    sendEvent<T>(eventName: string, event: T): void {
+      world.events.send(eventName, event);
+    },
+
+    readEvents<T>(eventName: string): T[] {
+      return world.events.read<T>(eventName);
+    },
+  };
+
+  return binding;
+}