@downdraft/engine 0.0.0 → 0.1.0

package/core/src/scene/scene.ts

@@ -0,0 +1,192 @@
+import { findEntityRow, getColumnValue } from "../ecs/archetype";
+import { isRegisteredComponentId, type ComponentId } from "../ecs/component";
+import { entityEqual, isAlive, type Entity } from "../ecs/entity";
+import type { World } from "../ecs/world";
+import { createLogger } from "../util/logger";
+
+const log = createLogger();
+
+export type SceneState = "unloaded" | "loading" | "loaded" | "active" | "inactive";
+
+export type SceneSetup = (scene: Scene) => void | Promise<void>;
+export type SceneTeardown = (scene: Scene) => void;
+
+export interface SerializedScene {
+  name: string;
+  state: SceneState;
+  persistent: boolean;
+  entities: Array<{
+    index: number;
+    generation: number;
+    components: Array<{ id: number; data: unknown }>;
+  }>;
+}
+
+export class Scene {
+  name: string;
+  world: World;
+  state: SceneState = "unloaded";
+  persistent = false;
+
+  private _entities: Entity[] = [];
+  private _entitySet: Set<string> = new Set();
+  private _setup: SceneSetup | null;
+  private _teardown: SceneTeardown | null;
+
+  constructor(name: string, world: World, setup?: SceneSetup) {
+    this.name = name;
+    this.world = world;
+    this._setup = setup ?? null;
+    this._teardown = null;
+  }
+
+  setSetup(fn: SceneSetup): void {
+    this._setup = fn;
+  }
+
+  setTeardown(fn: SceneTeardown): void {
+    this._teardown = fn;
+  }
+
+  // ── Entity Management (synced with World) ──────────────────────
+
+  spawn(components: Map<ComponentId, unknown>): Entity {
+    const entity = this.world.spawn(components);
+    this.trackEntity(entity);
+    return entity;
+  }
+
+  despawn(entity: Entity): void {
+    this.world.despawn(entity);
+    this.untrackEntity(entity);
+  }
+
+  trackEntity(entity: Entity): void {
+    const key = `${entity.index}:${entity.generation}`;
+    if (this._entitySet.has(key)) return;
+    this._entitySet.add(key);
+    this._entities.push(entity);
+  }
+
+  untrackEntity(entity: Entity): void {
+    const key = `${entity.index}:${entity.generation}`;
+    if (!this._entitySet.delete(key)) return;
+    const idx = this._entities.findIndex((e) => entityEqual(e, entity));
+    if (idx >= 0) this._entities.splice(idx, 1);
+  }
+
+  addEntity(entity: Entity): void {
+    this.trackEntity(entity);
+  }
+
+  removeEntity(entity: Entity): void {
+    this.untrackEntity(entity);
+  }
+
+  getEntities(): Entity[] {
+    return this._entities.filter((e) => isAlive(this.world.entities, e));
+  }
+
+  getEntityCount(): number {
+    return this._entities.length;
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────────
+
+  async load(): Promise<void> {
+    if (this.state !== "unloaded") {
+      log.warn("Scene", `Cannot load "${this.name}" — current state: ${this.state}`);
+      return;
+    }
+    this.state = "loading";
+
+    if (this._setup) {
+      await this._setup(this);
+    }
+
+    this.state = "loaded";
+    log.info("Scene", `Loaded "${this.name}" (${this._entities.length} entities)`);
+  }
+
+  unload(): void {
+    if (this.state === "unloaded") return;
+
+    if (this._teardown) {
+      this._teardown(this);
+    }
+
+    this._entities.forEach((entity) => {
+      this.world._despawnImmediate(entity);
+    });
+
+    this._entities = [];
+    this._entitySet.clear();
+    this.state = "unloaded";
+    log.info("Scene", `Unloaded "${this.name}"`);
+  }
+
+  activate(): void {
+    if (this.state === "unloaded" || this.state === "loading") {
+      log.warn("Scene", `Cannot activate "${this.name}" — not loaded`);
+      return;
+    }
+    this.state = "active";
+  }
+
+  deactivate(): void {
+    if (this.state !== "active") return;
+    this.state = "inactive";
+  }
+
+  isActive(): boolean {
+    return this.state === "active";
+  }
+
+  isLoaded(): boolean {
+    return this.state === "loaded" || this.state === "active" || this.state === "inactive";
+  }
+
+  // ── Serialization ──────────────────────────────────────────────
+
+  serialize(): SerializedScene {
+    const entities: SerializedScene["entities"] = [];
+
+    for (let _i = 0, _it = this._entities, _n = _it.length; _i < _n; _i++) { const entity = _it[_i];
+      if (!isAlive(this.world.entities, entity)) continue;
+      const arch = this.world.getArchetypeForEntity(entity);
+      if (!arch) continue;
+
+      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({ index: entity.index, generation: entity.generation, components });
+    }
+
+    return { name: this.name, state: this.state, persistent: this.persistent, entities };
+  }
+
+  deserialize(data: SerializedScene): void {
+    this.unload();
+
+    this.name = data.name;
+    this.persistent = data.persistent ?? false;
+
+    data.entities.forEach((entry) => {
+      const components = new Map<ComponentId, unknown>();
+      entry.components.forEach((comp) => {
+        if (!isRegisteredComponentId(comp.id)) {
+          throw new RangeError(`Scene deserialize: unregistered component ID ${comp.id}`);
+        }
+        components.set(comp.id, comp.data);
+      });
+      const entity = this.world.spawn(components);
+      this.trackEntity(entity);
+    });
+
+    this.state = data.state === "active" ? "active" : "loaded";
+  }
+}

package/core/src/scene/sky.ts

@@ -0,0 +1,256 @@
+export interface DayNightConfig {
+  dayDuration: number;
+  startTime: number;
+  sunColor: [number, number, number];
+  moonColor: [number, number, number];
+  sunIntensity: number;
+  moonIntensity: number;
+  ambientColor: [number, number, number];
+  ambientIntensity: number;
+  latitude: number;
+  axialTilt: number;
+}
+
+export const DEFAULT_DAY_NIGHT_CONFIG: DayNightConfig = {
+  dayDuration: 120,
+  startTime: 6.0,
+  sunColor: [1.0, 0.95, 0.85],
+  moonColor: [0.5, 0.6, 0.8],
+  sunIntensity: 3.0,
+  moonIntensity: 0.3,
+  ambientColor: [0.3, 0.35, 0.4],
+  ambientIntensity: 0.65,
+  latitude: 45.0,
+  axialTilt: 23.5,
+};
+
+export interface SunMoonState {
+  sunDirection: [number, number, number];
+  sunColor: [number, number, number];
+  sunIntensity: number;
+  moonDirection: [number, number, number];
+  moonColor: [number, number, number];
+  moonIntensity: number;
+  ambientColor: [number, number, number];
+  ambientIntensity: number;
+  timeOfDay: number;
+  dayPhase: "dawn" | "day" | "dusk" | "night";
+}
+
+export class DayNightCycle {
+  private config: DayNightConfig;
+  private time: number;
+
+  constructor(config?: Partial<DayNightConfig>) {
+    this.config = { ...DEFAULT_DAY_NIGHT_CONFIG, ...config };
+    this.time = this.config.startTime;
+  }
+
+  update(dt: number): void {
+    this.time += (24 / this.config.dayDuration) * dt;
+    while (this.time >= 24) this.time -= 24;
+  }
+
+  getState(): SunMoonState {
+    const t = this.time;
+    const sunAngle = ((t - 6) / 24) * Math.PI * 2;
+    const moonAngle = sunAngle + Math.PI;
+
+    const latRad = (this.config.latitude * Math.PI) / 180;
+    const tiltRad = (this.config.axialTilt * Math.PI) / 180;
+
+    const sunDir: [number, number, number] = [
+      Math.cos(sunAngle) * Math.cos(latRad),
+      Math.sin(sunAngle),
+      Math.cos(sunAngle) * Math.sin(latRad) * Math.cos(tiltRad),
+    ];
+    const sunLen = Math.sqrt(sunDir[0] ** 2 + sunDir[1] ** 2 + sunDir[2] ** 2);
+    sunDir[0] /= sunLen; sunDir[1] /= sunLen; sunDir[2] /= sunLen;
+
+    const moonDir: [number, number, number] = [
+      Math.cos(moonAngle) * Math.cos(latRad),
+      Math.sin(moonAngle),
+      Math.cos(moonAngle) * Math.sin(latRad) * Math.cos(tiltRad),
+    ];
+    const moonLen = Math.sqrt(moonDir[0] ** 2 + moonDir[1] ** 2 + moonDir[2] ** 2);
+    moonDir[0] /= moonLen; moonDir[1] /= moonLen; moonDir[2] /= moonLen;
+
+    const sunHeight = sunDir[1];
+    const moonHeight = moonDir[1];
+
+    let sunIntensity = 0;
+    let moonIntensity = 0;
+    let dayPhase: SunMoonState["dayPhase"] = "night";
+
+    if (sunHeight > 0.1) {
+      sunIntensity = this.config.sunIntensity * Math.min(1, sunHeight * 2);
+      dayPhase = "day";
+    } else if (sunHeight > -0.1) {
+      const t2 = (sunHeight + 0.1) / 0.2;
+      sunIntensity = this.config.sunIntensity * t2 * 0.5;
+      dayPhase = t < 12 ? "dawn" : "dusk";
+    }
+
+    if (moonHeight > 0.1) {
+      moonIntensity = this.config.moonIntensity * Math.min(1, moonHeight * 2);
+      if (dayPhase === "night") dayPhase = "night";
+    } else if (moonHeight > -0.1) {
+      moonIntensity = this.config.moonIntensity * ((moonHeight + 0.1) / 0.2) * 0.5;
+    }
+
+    // sqrt curve — sky scattering ramps faster than sun elevation at low angles
+    const ambientIntensity = this.config.ambientIntensity * (0.4 + 0.6 * Math.sqrt(Math.max(0, sunHeight)));
+
+    let sunColor = [...this.config.sunColor] as [number, number, number];
+    if (dayPhase === "dawn" || dayPhase === "dusk") {
+      const warmth = 1 - Math.abs(sunHeight) * 5;
+      sunColor[0] = Math.min(1, this.config.sunColor[0] + warmth * 0.3);
+      sunColor[1] = Math.max(0, this.config.sunColor[1] - warmth * 0.2);
+      sunColor[2] = Math.max(0, this.config.sunColor[2] - warmth * 0.4);
+    }
+
+    return {
+      sunDirection: sunDir,
+      sunColor,
+      sunIntensity,
+      moonDirection: moonDir,
+      moonColor: this.config.moonColor,
+      moonIntensity,
+      ambientColor: this.config.ambientColor,
+      ambientIntensity,
+      timeOfDay: this.time,
+      dayPhase,
+    };
+  }
+
+  setTime(time: number): void {
+    this.time = ((time % 24) + 24) % 24;
+  }
+
+  getTime(): number {
+    return this.time;
+  }
+
+  getConfig(): DayNightConfig {
+    return this.config;
+  }
+
+  setConfig(config: Partial<DayNightConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+}
+
+export interface FogConfig {
+  color: [number, number, number];
+  density: number;
+  start: number;
+  end: number;
+  fogType: "linear" | "exponential" | "exponential2";
+  heightFalloff: number;
+  maxDistance: number;
+}
+
+export const DEFAULT_FOG_CONFIG: FogConfig = {
+  color: [0.5, 0.6, 0.7],
+  density: 0.02,
+  start: 20,
+  end: 200,
+  fogType: "linear",
+  heightFalloff: 0.01,
+  maxDistance: 500,
+};
+
+export class FogSystem {
+  private config: FogConfig;
+
+  constructor(config?: Partial<FogConfig>) {
+    this.config = { ...DEFAULT_FOG_CONFIG, ...config };
+  }
+
+  computeFogFactor(distance: number, height: number = 0): number {
+    let factor: number;
+    switch (this.config.fogType) {
+      case "linear":
+        factor = (distance - this.config.start) / (this.config.end - this.config.start);
+        break;
+      case "exponential":
+        factor = 1 - Math.exp(-this.config.density * distance);
+        break;
+      case "exponential2":
+        factor = 1 - Math.exp(-((this.config.density * distance) ** 2));
+        break;
+    }
+    const heightFactor = Math.exp(-this.config.heightFalloff * Math.abs(height));
+    return Math.min(1, Math.max(0, factor * heightFactor));
+  }
+
+  blendColor(baseColor: [number, number, number], distance: number, height: number = 0): [number, number, number] {
+    const factor = this.computeFogFactor(distance, height);
+    return [
+      baseColor[0] * (1 - factor) + this.config.color[0] * factor,
+      baseColor[1] * (1 - factor) + this.config.color[1] * factor,
+      baseColor[2] * (1 - factor) + this.config.color[2] * factor,
+    ];
+  }
+
+  getConfig(): FogConfig {
+    return this.config;
+  }
+
+  setConfig(config: Partial<FogConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+}
+
+export interface AtmosphereConfig {
+  sunIntensity: number;
+  rayleighCoefficient: number;
+  mieCoefficient: number;
+  mieDirection: number;
+  planetRadius: number;
+  atmosphereRadius: number;
+  samples: number;
+}
+
+export const DEFAULT_ATMOSPHERE_CONFIG: AtmosphereConfig = {
+  sunIntensity: 22.0,
+  rayleighCoefficient: 1.0,
+  mieCoefficient: 0.005,
+  mieDirection: 0.758,
+  planetRadius: 6371,
+  atmosphereRadius: 6471,
+  samples: 16,
+};
+
+export function computeSkyColor(
+  sunDirection: [number, number, number],
+  viewDirection: [number, number, number],
+  config: AtmosphereConfig = DEFAULT_ATMOSPHERE_CONFIG,
+): [number, number, number] {
+  const cosSunView = Math.max(0, viewDirection[0] * sunDirection[0] + viewDirection[1] * sunDirection[1] + viewDirection[2] * sunDirection[2]);
+  const cosSunZenith = Math.max(0, sunDirection[1]);
+  const cosViewZenith = Math.max(0, viewDirection[1]);
+
+  const rayleigh = config.rayleighCoefficient;
+  const mie = config.mieCoefficient;
+
+  const rayleighSun = rayleigh / (cosSunZenith + 0.001);
+  const mieSun = mie / (cosSunZenith + 0.001);
+
+  const rayleighView = rayleigh / (cosViewZenith + 0.001);
+  const mieView = mie / (cosViewZenith + 0.001);
+
+  const totalRayleigh = rayleighSun + rayleighView;
+  const totalMie = mieSun + mieView;
+
+  const rayleighColor: [number, number, number] = [5.8, 13.5, 33.1];
+  const mieColor: [number, number, number] = [1.0, 1.0, 1.0];
+
+  const phase = (1 + config.mieDirection ** 2) / (1 + config.mieCoefficient ** 2 - 2 * config.mieCoefficient * cosSunView) ** 1.5;
+
+  const r = Math.exp(-totalRayleigh * rayleighColor[0] - totalMie * mieColor[0] * phase) * 3.0;
+  const g = Math.exp(-totalRayleigh * rayleighColor[1] - totalMie * mieColor[1] * phase) * 3.0;
+  const b = Math.exp(-totalRayleigh * rayleighColor[2] - totalMie * mieColor[2] * phase) * 3.0;
+
+  return [Math.min(1, r), Math.min(1, g), Math.min(1, b)];
+}

package/core/src/scene/spatial-grid.ts

@@ -0,0 +1,176 @@
+import type { Entity } from "../ecs/entity";
+
+export interface SpatialEntry {
+  entity: Entity;
+  position: [number, number, number];
+  radius: number;
+  layer: number;
+}
+
+export interface GridCell {
+  x: number;
+  z: number;
+  entries: SpatialEntry[];
+}
+
+export interface SpatialQueryResult {
+  entries: SpatialEntry[];
+  cellX: number;
+  cellZ: number;
+}
+
+export class SpatialGrid {
+  private cellSize: number;
+  private cells: Map<string, GridCell> = new Map();
+  private entryCount = 0;
+
+  constructor(cellSize: number = 16) {
+    this.cellSize = cellSize;
+  }
+
+  get cellSizeValue(): number {
+    return this.cellSize;
+  }
+
+  private cellKey(x: number, z: number): string {
+    return `${x}:${z}`;
+  }
+
+  private worldToCell(pos: [number, number, number]): [number, number] {
+    return [
+      Math.floor(pos[0] / this.cellSize),
+      Math.floor(pos[2] / this.cellSize),
+    ];
+  }
+
+  insert(entry: SpatialEntry): void {
+    const [cx, cz] = this.worldToCell(entry.position);
+    const key = this.cellKey(cx, cz);
+    let cell = this.cells.get(key);
+    if (!cell) {
+      cell = { x: cx, z: cz, entries: [] };
+      this.cells.set(key, cell);
+    }
+    cell.entries.push(entry);
+    this.entryCount++;
+  }
+
+  remove(entity: Entity, oldPos: [number, number, number]): void {
+    const [cx, cz] = this.worldToCell(oldPos);
+    const key = this.cellKey(cx, cz);
+    const cell = this.cells.get(key);
+    if (!cell) return;
+    const idx = cell.entries.findIndex(
+      (e) => e.entity.index === entity.index && e.entity.generation === entity.generation,
+    );
+    if (idx >= 0) {
+      const last = cell.entries.length - 1;
+      cell.entries[idx] = cell.entries[last];
+      cell.entries.pop();
+      this.entryCount--;
+      if (cell.entries.length === 0) {
+        this.cells.delete(key);
+      }
+    }
+  }
+
+  update(entity: Entity, oldPos: [number, number, number], newPos: [number, number, number], radius: number, layer: number): void {
+    const [oldCx, oldCz] = this.worldToCell(oldPos);
+    const [newCx, newCz] = this.worldToCell(newPos);
+    if (oldCx === newCx && oldCz === newCz) {
+      const key = this.cellKey(oldCx, oldCz);
+      const cell = this.cells.get(key);
+      if (cell) {
+        const entry = cell.entries.find(
+          (e) => e.entity.index === entity.index && e.entity.generation === entity.generation,
+        );
+        if (entry) {
+          entry.position = newPos;
+        }
+      }
+      return;
+    }
+    this.remove(entity, oldPos);
+    this.insert({ entity, position: newPos, radius, layer });
+  }
+
+  queryRange(min: [number, number, number], max: [number, number, number], layer?: number): SpatialEntry[] {
+    const [minCx, minCz] = this.worldToCell(min);
+    const [maxCx, maxCz] = this.worldToCell(max);
+    const results: SpatialEntry[] = [];
+
+    for (let cx = minCx; cx <= maxCx; cx++) {
+      for (let cz = minCz; cz <= maxCz; cz++) {
+        const cell = this.cells.get(this.cellKey(cx, cz));
+        if (!cell) continue;
+        for (let _i = 0, _it = cell.entries, _n = _it.length; _i < _n; _i++) { const entry = _it[_i];
+          if (layer !== undefined && entry.layer !== layer) continue;
+          if (
+            entry.position[0] >= min[0] && entry.position[0] <= max[0] &&
+            entry.position[2] >= min[2] && entry.position[2] <= max[2]
+          ) {
+            results.push(entry);
+          }
+        }
+      }
+    }
+    return results;
+  }
+
+  queryRadius(center: [number, number, number], radius: number, layer?: number): SpatialEntry[] {
+    const min: [number, number, number] = [
+      center[0] - radius,
+      center[1] - 1e9,
+      center[2] - radius,
+    ];
+    const max: [number, number, number] = [
+      center[0] + radius,
+      center[1] + 1e9,
+      center[2] + radius,
+    ];
+    const candidates = this.queryRange(min, max, layer);
+    const radiusSq = radius * radius;
+    return candidates.filter((entry) => {
+      const dx = entry.position[0] - center[0];
+      const dz = entry.position[2] - center[2];
+      return dx * dx + dz * dz <= radiusSq;
+    });
+  }
+
+  queryCell(cellX: number, cellZ: number, layer?: number): SpatialEntry[] {
+    const cell = this.cells.get(this.cellKey(cellX, cellZ));
+    if (!cell) return [];
+    if (layer === undefined) return [...cell.entries];
+    return cell.entries.filter((e) => e.layer === layer);
+  }
+
+  getActiveCellCount(): number {
+    return this.cells.size;
+  }
+
+  getEntryCount(): number {
+    return this.entryCount;
+  }
+
+  clear(): void {
+    this.cells.clear();
+    this.entryCount = 0;
+  }
+
+  getCellCoords(pos: [number, number, number]): [number, number] {
+    return this.worldToCell(pos);
+  }
+
+  getCellsInRadius(center: [number, number, number], radius: number): GridCell[] {
+    const [cx, cz] = this.worldToCell(center);
+    const cellRadius = Math.ceil(radius / this.cellSize);
+    const result: GridCell[] = [];
+    for (let dx = -cellRadius; dx <= cellRadius; dx++) {
+      for (let dz = -cellRadius; dz <= cellRadius; dz++) {
+        const cell = this.cells.get(this.cellKey(cx + dx, cz + dz));
+        if (cell) result.push(cell);
+      }
+    }
+    return result;
+  }
+}