@downdraft/engine 0.0.0 → 0.1.1

package/libraries/water/src/water-sab.ts

@@ -0,0 +1,161 @@
+// ============================================================================
+// Water SAB Channel — SharedArrayBuffer protocol for water heightfield data
+// Uses defineChannel framework for zero-copy sim→renderer transfer.
+// ============================================================================
+
+import { defineChannel } from "@downdraft/engine/sab/define";
+
+export const WaterChannel = defineChannel({
+  name: "game-water",
+  magic: 0x57415452,
+  version: 1,
+  mode: "grid",
+  header: {
+    size: 64,
+    fields: {
+      gridSize: { type: "u32" },
+      patchSize: { type: "u32" },
+      originX: { type: "i32" },
+      originZ: { type: "i32" },
+    },
+  },
+  grid: {
+    size: 256,
+    layers: {
+      heights: { type: "f32", components: 1 },
+      normals: { type: "f32", components: 3 },
+      flow: { type: "f32", components: 2 },
+    },
+  },
+});
+
+export const WATER_MAGIC_SAB = 0x57415452;
+export const WATER_VERSION_SAB = 1;
+export const WATER_GRID_SAB = 256;
+export const WATER_HEIGHT_OFFSET_SAB = 64;
+export const WATER_NORMAL_OFFSET_SAB = WATER_HEIGHT_OFFSET_SAB + WATER_GRID_SAB * WATER_GRID_SAB * 4;
+export const WATER_FLOW_OFFSET_SAB = WATER_NORMAL_OFFSET_SAB + WATER_GRID_SAB * WATER_GRID_SAB * 12;
+
+// Header field offsets (u32 indices within header, after reserved magic/version/sequence)
+export const WATER_HDR_SAB = {
+  MAGIC: 0,
+  VERSION: 1,
+  GRID_SIZE: 3,
+  PATCH_SIZE: 4,
+  SEQUENCE: 2,
+  ORIGIN_X: 5,
+  ORIGIN_Z: 6,
+} as const;
+
+export class WaterBufferWriter {
+  private writer: ReturnType<typeof WaterChannel.writer>;
+  heights: Float32Array;
+  normals: Float32Array;
+  flow: Float32Array;
+
+  constructor(sab: SharedArrayBuffer) {
+    this.writer = WaterChannel.writer(sab);
+    this.heights = this.writer.layers.heights as Float32Array;
+    this.normals = this.writer.layers.normals as Float32Array;
+    this.flow = this.writer.layers.flow as Float32Array;
+  }
+
+  init(patchSize: number) {
+    const w = this.writer;
+    const h = WaterChannel.offsets.header;
+    w.header.u32[h.gridSize] = WATER_GRID_SAB;
+    w.header.u32[h.patchSize] = patchSize;
+    w.header.i32[h.originX] = 0;
+    w.header.i32[h.originZ] = 0;
+  }
+
+  getPatchSize(): number { return this.writer.header.u32[WaterChannel.offsets.header.patchSize]; }
+
+  getOrigin(): { x: number; z: number } {
+    return {
+      x: this.writer.header.i32[WaterChannel.offsets.header.originX],
+      z: this.writer.header.i32[WaterChannel.offsets.header.originZ],
+    };
+  }
+
+  setOrigin(x: number, z: number) {
+    this.writer.header.i32[WaterChannel.offsets.header.originX] = x;
+    this.writer.header.i32[WaterChannel.offsets.header.originZ] = z;
+  }
+
+  incrementSequence() {
+    this.writer.bumpSequence();
+  }
+
+  setHeight(gx: number, gz: number, h: number) {
+    this.heights[gz * WATER_GRID_SAB + gx] = h;
+  }
+
+  getHeight(gx: number, gz: number): number {
+    return this.heights[gz * WATER_GRID_SAB + gx];
+  }
+
+  sampleHeight(gx: number, gz: number): number {
+    const x0 = Math.floor(gx);
+    const z0 = Math.floor(gz);
+    const x1 = Math.min(x0 + 1, WATER_GRID_SAB - 1);
+    const z1 = Math.min(z0 + 1, WATER_GRID_SAB - 1);
+    const fx = gx - x0;
+    const fz = gz - z0;
+
+    const h00 = this.heights[z0 * WATER_GRID_SAB + x0];
+    const h10 = this.heights[z0 * WATER_GRID_SAB + x1];
+    const h01 = this.heights[z1 * WATER_GRID_SAB + x0];
+    const h11 = this.heights[z1 * WATER_GRID_SAB + x1];
+
+    const h0 = h00 * (1 - fx) + h10 * fx;
+    const h1 = h01 * (1 - fx) + h11 * fx;
+    return h0 * (1 - fz) + h1 * fz;
+  }
+}
+
+export class WaterBufferReader {
+  private reader: ReturnType<typeof WaterChannel.reader>;
+  heights: Float32Array;
+  normals: Float32Array;
+  flow: Float32Array;
+
+  constructor(sab: SharedArrayBuffer) {
+    this.reader = WaterChannel.reader(sab);
+    this.heights = this.reader.layers.heights as Float32Array;
+    this.normals = this.reader.layers.normals as Float32Array;
+    this.flow = this.reader.layers.flow as Float32Array;
+  }
+
+  isValid(): boolean {
+    return this.reader.isValid();
+  }
+
+  getSequence(): number { return this.reader.getSequence(); }
+  getGridSize(): number { return this.reader.header.u32[WaterChannel.offsets.header.gridSize]; }
+  getPatchSize(): number { return this.reader.header.u32[WaterChannel.offsets.header.patchSize]; }
+  getOrigin(): { x: number; z: number } {
+    return {
+      x: this.reader.header.i32[WaterChannel.offsets.header.originX],
+      z: this.reader.header.i32[WaterChannel.offsets.header.originZ],
+    };
+  }
+
+  sampleHeight(gx: number, gz: number): number {
+    const x0 = Math.floor(gx);
+    const z0 = Math.floor(gz);
+    const x1 = Math.min(x0 + 1, WATER_GRID_SAB - 1);
+    const z1 = Math.min(z0 + 1, WATER_GRID_SAB - 1);
+    const fx = gx - x0;
+    const fz = gz - z0;
+
+    const h00 = this.heights[z0 * WATER_GRID_SAB + x0];
+    const h10 = this.heights[z0 * WATER_GRID_SAB + x1];
+    const h01 = this.heights[z1 * WATER_GRID_SAB + x0];
+    const h11 = this.heights[z1 * WATER_GRID_SAB + x1];
+
+    const h0 = h00 * (1 - fx) + h10 * fx;
+    const h1 = h01 * (1 - fx) + h11 * fx;
+    return h0 * (1 - fz) + h1 * fz;
+  }
+}

package/libraries/water/src/wave-sources.ts

@@ -0,0 +1,84 @@
+// ============================================================================
+// Wave Sources — wake and shore source collection from game entities
+// Wave/shore source system
+// ============================================================================
+
+import type { ShoreSource } from "./shore-damping";
+export type { ShoreSource };
+
+export interface WakeSource {
+  x: number;
+  z: number;
+  dirX: number;
+  dirZ: number;
+  speed: number;
+}
+
+export interface WakeProvider {
+  x: number;
+  z: number;
+  heading: number;
+  speed: number;
+}
+
+export interface ShoreProvider {
+  x: number;
+  z: number;
+  radius: number;
+  cutoutRadius?: number;
+}
+
+export const MAX_WAKES = 16;
+export const MAX_SHORES = 128;
+export const WAKE_FLOATS = 6; // pos.x, pos.y, dir.x, dir.y, speed, _pad
+export const SHORE_FLOATS = 4; // pos.x, pos.y, radius, cutoutRadius
+
+export function collectWakeSources(
+  providers: WakeProvider[],
+  out: Float32Array,
+): number {
+  const maxByBuffer = Math.floor(out.length / WAKE_FLOATS);
+  const n = Math.min(providers.length, MAX_WAKES, maxByBuffer);
+  for (let i = 0; i < n; i++) {
+    const p = providers[i];
+    const off = i * WAKE_FLOATS;
+    out[off] = p.x;
+    out[off + 1] = p.z;
+    out[off + 2] = Math.sin(p.heading);
+    out[off + 3] = Math.cos(p.heading);
+    out[off + 4] = p.speed;
+    out[off + 5] = 0; // padding
+  }
+  return n;
+}
+
+export function collectShoreSources(
+  providers: ShoreProvider[],
+  out: ShoreSource[],
+): number {
+  const n = Math.min(providers.length, MAX_SHORES, out.length);
+  for (let i = 0; i < n; i++) {
+    const p = providers[i];
+    out[i].x = p.x;
+    out[i].z = p.z;
+    out[i].radius = p.radius;
+    out[i].cutoutRadius = p.cutoutRadius ?? 0;
+  }
+  return n;
+}
+
+export function packShoreSources(
+  sources: ShoreSource[],
+  count: number,
+  out: Float32Array,
+): void {
+  const maxCount = Math.min(count, MAX_SHORES, Math.floor(out.length / SHORE_FLOATS));
+  for (let i = 0; i < maxCount; i++) {
+    const s = sources[i];
+    const off = i * SHORE_FLOATS;
+    out[off] = s.x;
+    out[off + 1] = s.z;
+    out[off + 2] = s.radius;
+    out[off + 3] = s.cutoutRadius;
+  }
+}

package/libraries/weather/README.md

@@ -0,0 +1,20 @@
+# `@downdraft/engine/libraries/weather`
+
+Weather state simulation — fronts, precipitation, and environmental conditions as sim-side state.
+
+## Install
+
+```sh
+bun add @downdraft/engine/libraries/weather
+```
+
+## Key exports
+
+- `DEFAULT_WEATHER_CONFIG`
+- `WeatherBlend`
+- `WeatherLib`
+- `WeatherSystem`
+- `WeatherTok`
+- `WeatherType`
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/libraries/weather/src/index.ts

@@ -0,0 +1,9 @@
+export { DEFAULT_WEATHER_CONFIG, WeatherType } from "./types";
+export type { BiomeProvider, WeatherConfig, WeatherState } from "./types";
+export { WeatherBlend } from "./weather-blend";
+export type { WeatherLightingParams } from "./weather-blend";
+export { WeatherSystem } from "./weather-system";
+
+// Engine library descriptor
+export { WeatherLib, WeatherTok, type WeatherLibConfig } from "./library";
+

package/libraries/weather/src/library.ts

@@ -0,0 +1,72 @@
+// ============================================================================
+// WeatherLib — declarative engine library descriptor for @downdraft/engine/libraries/weather
+//
+// Dynamic weather simulation with rare events, rain collectors, wind, and
+// visibility. WeatherSystem depends on a BiomeProvider interface (game-supplied)
+// to drive biome-aware weather transitions.
+//
+// Games declare `libraries: [WeatherLib]` (or
+// `[[WeatherLib, { weatherIntensityMul: 1.5 }]]` to override config) in their
+// GameModule. The host creates the WeatherSystem (sim-side) during sim worker
+// init and exposes it via the WeatherTok token.
+//
+// Games that need full control can still import WeatherSystem directly
+// (escape hatch). Note: a BiomeProvider must be provided to the constructor —
+// games supply it via the config or inject it from another library/plugin.
+// ============================================================================
+
+import { resourceToken, type EngineLibrary } from "@downdraft/engine";
+import { WeatherSystem } from "./weather-system";
+import { DEFAULT_WEATHER_CONFIG, type BiomeProvider, type WeatherConfig } from "./types";
+
+// ── Config ──
+
+export interface WeatherLibConfig {
+  /** Game-supplied biome provider (required for biome-aware transitions). */
+  biomeProvider: BiomeProvider;
+  /** Multiplier for weather intensity (0 = calm, 1 = normal, >1 = extreme). Default: 1. */
+  weatherIntensityMul?: number;
+  /** Partial weather config overrides (merged with DEFAULT_WEATHER_CONFIG). */
+  weatherConfig?: Partial<WeatherConfig>;
+}
+
+// ── Typed tokens (DI) ──
+
+/** Token for the sim-side WeatherSystem. Inject in sim systems. */
+export const WeatherTok = resourceToken<WeatherSystem>("weather:system");
+
+// ── Descriptor ──
+
+export const WeatherLib: EngineLibrary<WeatherLibConfig> = {
+  name: "weather",
+  version: "1.0.0",
+
+  provides: [WeatherTok],
+
+  sim: {
+    create(config, ctx) {
+      const weather = new WeatherSystem(
+        config.biomeProvider,
+        config.weatherIntensityMul ?? 1.0,
+        config.weatherConfig,
+      );
+      ctx.provide(WeatherTok, weather);
+      return weather;
+    },
+    dispose(_weather) {
+      // WeatherSystem holds no GPU resources or external handles — it is
+      // pure simulation state (weather type, wind, visibility, rain
+      // collectors). No explicit destroy/cleanup method is needed.
+    },
+    // tick is game-specific (calls weather.tick(dt, timeOfDay) each sim
+    // step) — games wire this via onReady or a sim tick system.
+  },
+
+  tickPhase: "pre-physics",
+
+  defaultConfig: {
+    biomeProvider: undefined as unknown as BiomeProvider,
+    weatherIntensityMul: 1.0,
+    weatherConfig: DEFAULT_WEATHER_CONFIG,
+  },
+};

package/libraries/weather/src/types.ts

@@ -0,0 +1,64 @@
+// ============================================================================
+// Weather Plugin — Types and Interfaces
+// ============================================================================
+
+export enum WeatherType {
+  Clear = 0,
+  PartlyCloudy = 1,
+  Overcast = 2,
+  Rain = 3,
+  Storm = 4,
+  Fog = 5,
+  Eclipse = 6,
+  FullMoon = 7,
+  HellStorm = 8,
+  Snow = 9,
+}
+
+export interface WeatherState {
+  type: WeatherType;
+  intensity: number;
+  windDirection: { x: number; y: number; z: number };
+  windSpeed: number;
+  visibility: number;
+  temperature: number;
+  duration: number;
+  cooldown: number;
+  isRareEvent: boolean;
+}
+
+// Biome provider interface — games implement this to supply biome data
+export interface BiomeProvider {
+  getBiomeAt(worldX: number, worldZ: number): number;
+  getBiomeName(biome: number): string;
+  getTemperatureRange(biome: number): { min: number; max: number };
+}
+
+// Weather config — games can override these values
+export interface WeatherConfig {
+  clearChance: number;
+  fullClearChance: number;
+  partlyCloudyChance: number;
+  overcastChance: number;
+  maxDuration: number;
+  minDuration: number;
+  rareEventChance: number;
+  rainCollectorCapacity: number;
+  rainCollectorFillRate: number;
+  nightStartFrac: number;
+  nightEndFrac: number;
+}
+
+export const DEFAULT_WEATHER_CONFIG: WeatherConfig = {
+  clearChance: 0.80,
+  fullClearChance: 0.30,
+  partlyCloudyChance: 0.40,
+  overcastChance: 0.30,
+  maxDuration: 300,
+  minDuration: 60,
+  rareEventChance: 0.02,
+  rainCollectorCapacity: 50,
+  rainCollectorFillRate: 5,
+  nightStartFrac: 0.7,
+  nightEndFrac: 0.25,
+};

package/libraries/weather/src/weather-blend.ts

@@ -0,0 +1,112 @@
+// ============================================================================
+// WeatherBlend — smooth weather transition blending for lighting/rendering
+// ============================================================================
+// Provides eased blending between previous and current weather states so
+// lighting/rendering systems can smoothly transition over time.
+//
+
+import { WeatherType } from "./types";
+
+export interface WeatherLightingParams {
+  ambient: number;
+  sunIntensity: number;
+  wetness: number;
+}
+
+export class WeatherBlend {
+  private prevWeatherType: WeatherType = WeatherType.Clear;
+  private displayedWeatherType: WeatherType = WeatherType.Clear;
+  private blend: number = 1.0;
+  private readonly transitionDuration: number;
+
+  constructor(transitionDuration: number = 30.0) {
+    this.transitionDuration = transitionDuration;
+  }
+
+  update(weatherType: WeatherType, dt: number): void {
+    if (weatherType !== this.displayedWeatherType) {
+      this.prevWeatherType = this.displayedWeatherType;
+      this.displayedWeatherType = weatherType;
+      this.blend = 0.0;
+    }
+    if (this.blend < 1.0) {
+      this.blend = Math.min(1.0, this.blend + dt / this.transitionDuration);
+    }
+  }
+
+  getBlendFactor(): number {
+    return this.blend;
+  }
+
+  getEasedBlend(): number {
+    return this.blend * this.blend * (3 - 2 * this.blend);
+  }
+
+  getPrevWeatherType(): WeatherType {
+    return this.prevWeatherType;
+  }
+
+  getDisplayedWeatherType(): WeatherType {
+    return this.displayedWeatherType;
+  }
+
+  isTransitioning(): boolean {
+    return this.blend < 1.0;
+  }
+
+  blendValues(prev: number, curr: number): number {
+    const t = this.getEasedBlend();
+    return prev + (curr - prev) * t;
+  }
+
+  getLightingParams(
+    timeOfDay: number,
+    weatherType: WeatherType,
+    visibility: number,
+  ): WeatherLightingParams {
+    const sunAngle = timeOfDay * Math.PI * 2 - Math.PI / 2;
+    const sunIntensityRaw = Math.max(0, Math.sin(sunAngle));
+    const moonIntensity = Math.max(0, -Math.sin(sunAngle));
+    const baseAmbient = 0.7 + Math.sqrt(sunIntensityRaw) * 0.8;
+
+    const prev = this.applyWeatherLighting(this.prevWeatherType, baseAmbient, sunIntensityRaw, moonIntensity);
+    const curr = this.applyWeatherLighting(this.displayedWeatherType, baseAmbient, sunIntensityRaw, moonIntensity);
+    const ambient = this.blendValues(prev.ambient, curr.ambient);
+    const sunIntensity = this.blendValues(prev.sunIntensity, curr.sunIntensity);
+
+    const prevWetness = this.weatherWetness(this.prevWeatherType);
+    const currWetness = this.weatherWetness(this.displayedWeatherType);
+    const wetness = this.blendValues(prevWetness, currWetness);
+
+    void visibility;
+
+    return { ambient, sunIntensity, wetness };
+  }
+
+  private applyWeatherLighting(
+    weatherType: WeatherType,
+    baseAmbient: number,
+    baseSunIntensity: number,
+    moonIntensity: number,
+  ): { ambient: number; sunIntensity: number } {
+    let ambient = baseAmbient;
+    let sunIntensity = baseSunIntensity;
+    if (weatherType === WeatherType.PartlyCloudy) { ambient *= 0.97; sunIntensity *= 0.93; }
+    if (weatherType === WeatherType.Overcast) { ambient *= 0.7; sunIntensity *= 0.4; }
+    if (weatherType === WeatherType.Rain) { ambient *= 0.6; sunIntensity *= 0.3; }
+    if (weatherType === WeatherType.Storm) { ambient *= 0.4; sunIntensity *= 0.15; }
+    if (weatherType === WeatherType.Fog) { ambient *= 0.5; sunIntensity *= 0.2; }
+    if (weatherType === WeatherType.HellStorm) { ambient *= 0.3; sunIntensity *= 0.1; }
+    if (weatherType === WeatherType.Eclipse) { ambient *= 0.2; sunIntensity *= 0.05; }
+    if (weatherType === WeatherType.Snow) { ambient *= 0.7; sunIntensity *= 0.4; }
+    if (weatherType === WeatherType.FullMoon) ambient += moonIntensity * 0.15;
+    return { ambient, sunIntensity };
+  }
+
+  private weatherWetness(weatherType: WeatherType): number {
+    if (weatherType === WeatherType.Rain) return 0.7;
+    if (weatherType === WeatherType.Storm) return 1.0;
+    if (weatherType === WeatherType.HellStorm) return 1.0;
+    return 0.0;
+  }
+}