kiln-ecs 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# Kiln
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An agent-first game framework on Three.js: a fixed-step loop, a [Koota](https://github.com/pmndrs/koota)
+ECS, and a render bridge, designed so a coding agent can add a feature with a few exports and one
+scheduling line, and verify it headlessly.
+
+[![Docs](https://img.shields.io/badge/docs-read%20online-orange?style=for-the-badge&logo=readthedocs&logoColor=white)](https://kilnjs.pages.dev)
+
+```bash
+bunx kiln-ecs new my-game    # a playable starter game; npm package kiln-ecs, command kiln
+```
+
+```ts
+// src/systems.ts
+/** Integrates Velocity into Transform. */
+export const Movement = system([Mut(Transform), Velocity], ([t, v], { time }) => {
+  t.x += v.x * time.step
+  t.z += v.z * time.step
+})
+
+// src/main.ts
+export default () =>
+  createApp(config)
+    .use(CorePlugins)
+    .add(Startup, SpawnLevel)
+    .add(Fixed, chain(PlayerMove, Movement, CollectCoins))
+```
+
+```bash
+kiln describe     # the schedule: phases, systems, reads/writes/order
+kiln test         # headless scenario tests (bun test)
+kiln run --steps 600 --snapshot Transform    # the world as JSON after 10 simulated seconds
+kiln check        # determinism lint: Math.random, Date.now and friends in game code
+kiln replay recordings/session.json   # replay a recorded play session headless on the current code
+kiln shot out.png # one frame from headless Chromium
+kiln docs         # AGENTS.md from the code and its JSDoc
+```
+
+## What's included
+
+- `CorePlugins`: time and seeded RNG, rendering, input actions, assets, timers, tweens, a HUD/UI layer
+  (text, bars and buttons as retained data) and a dev debug panel.
+- Game states and run conditions: `state()`, `runIf(inState(...))`, `onEnter`/`onExit`, `despawnOnExit`.
+- Opt-in plugins: `CameraPlugin` (follow, bounds, zoom, trauma shake; 2D and 3D), `savePlugin` (save slots
+  and persisted settings), `SpriteAnimationPlugin` (sprite sheets and atlases), `SkeletalAnimationPlugin`
+  (glTF models), both driven by an animation graph with crossfades and frame events, and Rapier physics
+  (`kiln-ecs/physics`).
+- Session recording: press F8 in the dev server to save a play session, then `kiln replay` it headless to
+  find where the current code stops matching it.
+- Community plugins via `kiln add`: audio, orbit-camera, particles, terrain, water.
+
+## Repo
+
+- `packages/kiln`: the framework (`kiln-ecs`, `kiln-ecs/physics`, `kiln-ecs/test`, `kiln-ecs/vite`, `kiln-ecs/browser`), the CLI,
+  community plugins for `kiln add`, and the `kiln new` template.
+- `examples/coin-collector`: a 3D sample game (states, pause menu, tweens, camera follow, saved best score),
+  with `eval/` tasks for measuring agents.
+- `examples/sprite-hero`: a 2D sprite-sheet hero with an animation graph, footstep dust and hit-frame sword hits.
+- `docs/`: the documentation site (VitePress guides plus a TypeDoc API reference); `cd docs && bun install && bun run dev`.
+  `docs/design.md` is how the build maps to the design doc.
+
+## Develop
+
+```bash
+bun install
+bun test                 # everything, including the examples' scenarios
+bun run typecheck
+cd examples/coin-collector && bunx vite     # play it (or examples/sprite-hero)
+```
+
+Start a game from the checkout: `bun packages/kiln/src/cli/kiln.ts new ../my-game`.
+
+Build the npm package: `cd packages/kiln && bun run build` writes `dist/`, which is what gets published as `kiln-ecs`.

package/community/audio/README.md

@@ -0,0 +1,24 @@
+# audio
+
+Positional sounds tied to Transform, on Web Audio through Three.js (`AudioListener`,
+`PositionalAudio`, `AudioLoader`). The listener rides on the Camera. Buffers are cached by URL.
+Browsers keep audio suspended until the first click or key press; the plugin resumes it then.
+Headless (tests, `kiln run`, scenarios) it does nothing and never throws. A missing or undecodable
+file logs one `[audio]` warning and stays silent.
+
+```ts
+import { AudioPlugin, Sound, PlaySound } from './plugins/audio/index.ts'
+
+app.use(CorePlugins, AudioPlugin)
+
+// a looping sound at a place (put files in public/, they are served from '/'):
+commands.spawn(Transform({ x: 4 }), Sound({ src: '/sfx/campfire.ogg', loop: true, refDistance: 3 }))
+// a one-shot from any system:
+events.emit(PlaySound, { src: '/sfx/coin.ogg', entity: player, volume: 0.8 })
+```
+
+Adds:
+- `Sound` trait: src, volume, loop, autoplay, refDistance. Changing src swaps the sound.
+- `PlaySound` event: `{ entity?, src, volume? }`; positional when the entity has a Transform.
+- `AudioState` resource: `listener` (null headless), master `volume`, `failed` URLs.
+- System (Update): `UpdateAudio`.

package/community/audio/index.ts

@@ -0,0 +1,196 @@
+// Positional sounds tied to Transform, on Web Audio via Three.js. Vendored by `kiln add audio`.
+import * as THREE from 'three'
+import { Camera, event, plugin, resource, Scene, system, trait, Transform, Update, type App, type Entity } from 'kiln-ecs'
+
+/**
+ * A looping or one-time sound at this entity's Transform:
+ * `commands.spawn(Transform({ x: 4 }), Sound({ src: '/sfx/waterfall.ogg', loop: true }))`.
+ * `src` is a URL (files in the game's `public/` folder are served from `/`), `volume` 0..1+,
+ * `refDistance` the distance in world units at which volume starts to fall off. `autoplay` starts it
+ * once the file has loaded (browsers wait for the first click or key press before any audio plays).
+ * Without a Transform the sound is not positional. Headless (tests, `kiln run`) nothing loads or plays.
+ */
+export const Sound = trait({ src: '', volume: 1, loop: false, autoplay: true, refDistance: 4 })
+
+/**
+ * Plays a one-shot: `events.emit(PlaySound, { src: '/sfx/coin.ogg', entity })`. With an entity that
+ * has a Transform the sound plays positionally at that spot; without one it plays flat.
+ */
+export const PlaySound = event<{ entity?: Entity; src: string; volume?: number }>()
+
+/**
+ * Audio state: the `THREE.AudioListener` attached to the Camera (null headless or before the first
+ * frame) and a master `volume`. Change the volume with `res.mut(AudioState).volume = 0.5`.
+ */
+export const AudioState = resource(
+  (): { listener: THREE.AudioListener | null; volume: number; failed: string[] } => ({ listener: null, volume: 1, failed: [] }),
+  { readonlyProxy: false },
+).named('AudioState')
+
+interface Voice {
+  audio: THREE.PositionalAudio | THREE.Audio
+  src: string
+  started: boolean
+  seen: number
+}
+
+/** True only where Web Audio exists and the app is running for real. */
+function canPlay(app: App): boolean {
+  return !app.headless && typeof window !== 'undefined' && (typeof AudioContext !== 'undefined' || typeof (window as any).webkitAudioContext !== 'undefined')
+}
+
+/**
+ * Positional audio: `app.use(AudioPlugin)`, then spawn `Sound` entities or emit `PlaySound`.
+ * A no-op headless. Missing or undecodable files log one warning and stay silent.
+ */
+export const AudioPlugin = plugin((app) => {
+  app.init(AudioState, PlaySound)
+  const voices = new Map<Entity, Voice>()
+  const oneShots = new Set<THREE.Audio | THREE.PositionalAudio>()
+  const buffers = new Map<string, Promise<AudioBuffer | null>>()
+  let loader: THREE.AudioLoader | null = null
+  let frame = 0
+  let unlock: (() => void) | null = null
+
+  const load = (src: string, state: { failed: string[] }): Promise<AudioBuffer | null> => {
+    let p = buffers.get(src)
+    if (p) return p
+    loader ??= new THREE.AudioLoader()
+    const l = loader
+    p = new Promise<AudioBuffer | null>((resolve) => {
+      l.load(
+        src,
+        (buf) => resolve(buf),
+        undefined,
+        (err) => {
+          state.failed.push(src)
+          console.warn(`[audio] couldn't load '${src}' (${(err as Error)?.message ?? err}). Check the path; files in public/ are served from '/'.`)
+          resolve(null)
+        },
+      )
+    })
+    buffers.set(src, p)
+    app.track(p)
+    return p
+  }
+
+  const listenerFor = (state: { listener: THREE.AudioListener | null }, camera: THREE.Camera): THREE.AudioListener => {
+    if (state.listener) return state.listener
+    const listener = new THREE.AudioListener()
+    camera.add(listener)
+    state.listener = listener
+    // Browsers keep the AudioContext suspended until a user gesture.
+    const resume = () => {
+      if (listener.context.state === 'suspended') void listener.context.resume()
+    }
+    window.addEventListener('pointerdown', resume)
+    window.addEventListener('keydown', resume)
+    unlock = () => {
+      window.removeEventListener('pointerdown', resume)
+      window.removeEventListener('keydown', resume)
+    }
+    return listener
+  }
+
+  const stop = (a: THREE.Audio | THREE.PositionalAudio) => {
+    try {
+      if (a.isPlaying) a.stop()
+    } catch {}
+    a.removeFromParent()
+    try {
+      a.disconnect()
+    } catch {}
+  }
+
+  /** Starts, moves and stops Sound entities and plays PlaySound one-shots. */
+  const UpdateAudio = system(
+    { sounds: [Sound] },
+    ({ sounds }, { res, events }) => {
+      const shots = events.read(PlaySound)
+      if (!canPlay(app)) return
+      frame++
+      const state = res.mut(AudioState)
+      const scene = res.mut(Scene)
+      const camera = res.mut(Camera)
+      const listener = listenerFor(state, camera)
+      listener.setMasterVolume(state.volume)
+
+      sounds.forEach((e) => {
+        const s = e.get(Sound)!
+        let v = voices.get(e)
+        if (v && v.src !== s.src) {
+          stop(v.audio)
+          voices.delete(e)
+          v = undefined
+        }
+        const positional = e.has(Transform)
+        if (!v) {
+          if (!s.src) return
+          const audio = positional ? new THREE.PositionalAudio(listener) : new THREE.Audio(listener)
+          scene.add(audio)
+          v = { audio, src: s.src, started: false, seen: frame }
+          voices.set(e, v)
+          const voice = v
+          void load(s.src, state).then((buf) => {
+            if (!buf || voices.get(e) !== voice) return
+            voice.audio.setBuffer(buf)
+            voice.audio.setLoop(s.loop)
+            if (s.autoplay && !voice.started) {
+              voice.started = true
+              voice.audio.play()
+            }
+          })
+        }
+        v.seen = frame
+        v.audio.setVolume(s.volume)
+        if (v.audio.getLoop() !== s.loop && v.audio.buffer) v.audio.setLoop(s.loop)
+        if (positional) {
+          const t = e.get(Transform)!
+          v.audio.position.set(t.x, t.y, t.z)
+          ;(v.audio as THREE.PositionalAudio).setRefDistance?.(s.refDistance)
+        }
+      })
+      for (const [e, v] of voices) {
+        if (v.seen === frame) continue
+        stop(v.audio)
+        voices.delete(e)
+      }
+
+      for (const shot of shots) {
+        if (!shot?.src) continue
+        const at = shot.entity !== undefined && app.world.has(shot.entity) && shot.entity.has(Transform) ? shot.entity.get(Transform)! : null
+        const audio = at ? new THREE.PositionalAudio(listener) : new THREE.Audio(listener)
+        if (at) audio.position.set(at.x, at.y, at.z)
+        audio.setVolume(shot.volume ?? 1)
+        scene.add(audio)
+        oneShots.add(audio)
+        void load(shot.src, state).then((buf) => {
+          if (!buf || !oneShots.has(audio)) return
+          audio.setBuffer(buf)
+          const ended = audio.onEnded.bind(audio)
+          audio.onEnded = () => {
+            ended()
+            oneShots.delete(audio)
+            stop(audio)
+          }
+          audio.play()
+        })
+      }
+    },
+    { name: 'UpdateAudio' },
+  )
+  app.add(Update, UpdateAudio)
+
+  app.hooks.dispose.push(() => {
+    for (const v of voices.values()) stop(v.audio)
+    for (const a of oneShots) stop(a)
+    voices.clear()
+    oneShots.clear()
+    unlock?.()
+    const state = app.hasResource(AudioState) ? app.resource(AudioState) : null
+    if (state?.listener) {
+      state.listener.removeFromParent()
+      state.listener = null
+    }
+  })
+}, 'AudioPlugin')

package/community/audio/kiln-plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "audio",
+  "description": "Positional sounds tied to Transform on Web Audio, plus a PlaySound one-shot event. No-op headless.",
+  "files": ["index.ts", "README.md"],
+  "requires": []
+}

package/community/orbit-camera/README.md

@@ -0,0 +1,20 @@
+# orbit-camera
+
+An orbit camera around a target point. Drag with the `fire` or `alt` action held (left/right mouse
+by default) to rotate, scroll to zoom. Add `CameraFollow` to an entity and the orbit target follows
+its Transform smoothly. Needs the render and input plugins (`CorePlugins`).
+
+```ts
+import { OrbitCameraPlugin, OrbitCamera, CameraFollow } from './plugins/orbit-camera/index.ts'
+
+app.use(CorePlugins, OrbitCameraPlugin)
+
+// in a Startup system:
+commands.spawn(OrbitCamera({ distance: 20, yaw: 0.8, pitch: 0.5 }))
+commands.spawn(Transform({ x: 2 }), Player, CameraFollow({ smoothing: 6, offsetY: 1 })) // the camera follows it
+```
+
+Adds:
+- `OrbitCamera` trait: targetX/Y/Z, distance, yaw, pitch, min/max distance and pitch, rotateSpeed, zoomSpeed, enabled. The first entity with it drives the `Camera` resource.
+- `CameraFollow` trait: smoothing (catch-up rate per second, 0 snaps), offsetX/Y/Z.
+- Systems (Update): `FollowTarget`, then `OrbitControl` (writes `res.mut(Camera)`).

package/community/orbit-camera/index.ts

@@ -0,0 +1,88 @@
+// Orbit camera: drag to rotate, wheel to zoom, optionally follow an entity. Vendored by `kiln add orbit-camera`.
+import { Camera, clamp, Input, Mut, plugin, system, trait, Transform, Update } from 'kiln-ecs'
+
+/**
+ * Orbit camera parameters. Put it on one entity (the first one found drives the Camera):
+ * `commands.spawn(OrbitCamera({ distance: 20, pitch: 0.6 }))`. The camera sits `distance` away from
+ * (targetX, targetY, targetZ), at `yaw` radians around Y and `pitch` radians above the horizon.
+ * Dragging with 'fire' or 'alt' held rotates it, the wheel zooms. Set `enabled: false` to freeze
+ * input while still placing the camera.
+ */
+export const OrbitCamera = trait({
+  targetX: 0,
+  targetY: 0,
+  targetZ: 0,
+  distance: 15,
+  yaw: 0,
+  pitch: 0.5,
+  minDistance: 2,
+  maxDistance: 200,
+  minPitch: -1.45,
+  maxPitch: 1.45,
+  /** Radians per pixel of pointer drag. */
+  rotateSpeed: 0.006,
+  /** Fraction of distance per 100 wheel units. */
+  zoomSpeed: 0.1,
+  enabled: true,
+})
+
+/**
+ * Makes the orbit target follow this entity's Transform: `CameraFollow({ smoothing: 6, offsetY: 1 })`.
+ * `smoothing` is the catch-up rate per second (0 snaps). The first entity with CameraFollow and
+ * Transform is followed.
+ */
+export const CameraFollow = trait({ smoothing: 6, offsetX: 0, offsetY: 0, offsetZ: 0 })
+
+/** Moves the orbit target toward the followed entity, framerate-independently. */
+export const FollowTarget = system(
+  { cams: [Mut(OrbitCamera)], follow: [CameraFollow, Transform] },
+  ({ cams, follow }, { time }) => {
+    const target = follow.first()
+    if (target === undefined || cams.length === 0) return
+    const t = target.get(Transform)!
+    const f = target.get(CameraFollow)!
+    cams.each(([o]) => {
+      const k = f.smoothing <= 0 ? 1 : 1 - Math.exp(-f.smoothing * time.dt)
+      o.targetX += (t.x + f.offsetX - o.targetX) * k
+      o.targetY += (t.y + f.offsetY - o.targetY) * k
+      o.targetZ += (t.z + f.offsetZ - o.targetZ) * k
+    })
+  },
+)
+
+/** Applies pointer drag and wheel to the OrbitCamera, then places the Camera and aims it at the target. */
+export const OrbitControl = system({ cams: [Mut(OrbitCamera)] }, ({ cams }, { res }) => {
+  if (cams.length === 0) return
+  const input = res.has(Input) ? res.get(Input) : null
+  let done = false
+  cams.each(([o]) => {
+    if (done) return // only the first OrbitCamera drives the Camera
+    done = true
+    if (input && o.enabled) {
+      const p = input.pointer
+      if (input.down('fire') || input.down('alt')) {
+        o.yaw -= p.dx * o.rotateSpeed
+        o.pitch += p.dy * o.rotateSpeed
+      }
+      if (p.wheel !== 0) o.distance *= Math.exp((p.wheel / 100) * o.zoomSpeed)
+    }
+    o.pitch = clamp(o.pitch, o.minPitch, o.maxPitch)
+    o.distance = clamp(o.distance, o.minDistance, o.maxDistance)
+    const cam = res.mut(Camera)
+    const cp = Math.cos(o.pitch)
+    cam.position.set(
+      o.targetX + o.distance * cp * Math.sin(o.yaw),
+      o.targetY + o.distance * Math.sin(o.pitch),
+      o.targetZ + o.distance * cp * Math.cos(o.yaw),
+    )
+    cam.lookAt(o.targetX, o.targetY, o.targetZ)
+  })
+})
+
+/**
+ * Orbit camera: `app.use(OrbitCameraPlugin)` after CorePlugins, then spawn an `OrbitCamera` entity.
+ * Runs FollowTarget then OrbitControl in Update; writes `res.mut(Camera)`.
+ */
+export const OrbitCameraPlugin = plugin((app) => {
+  app.add(Update, OrbitControl.after(FollowTarget), FollowTarget)
+}, 'OrbitCameraPlugin')

package/community/orbit-camera/kiln-plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "orbit-camera",
+  "description": "Orbit camera: drag to rotate, wheel to zoom, optional smooth follow of an entity.",
+  "files": ["index.ts", "README.md"],
+  "requires": []
+}

package/community/particles/README.md

@@ -0,0 +1,19 @@
+# particles
+
+Visual-only particle emitters. Each emitter entity gets one `THREE.InstancedMesh` holding all its
+particles, simulated in Update in world space (moving the emitter doesn't drag live particles).
+Particles are not entities, so they never show up in snapshots or queries. Each emitter forks its
+own RNG from the app's seeded `Rng` the first frame it is seen, so runs replay exactly.
+
+```ts
+import { ParticlesPlugin, ParticleEmitter } from './plugins/particles/index.ts'
+
+app.use(CorePlugins, ParticlesPlugin)
+
+// in a Startup system (or on a torch prefab):
+commands.spawn(Transform({ y: 1 }), ParticleEmitter({ rate: 60, lifetime: 1.2, speed: 3, spread: 0.4, size: 0.2, color: 0xffb347 }))
+```
+
+Adds:
+- `ParticleEmitter` trait: rate (per second, 0 stops), lifetime, speed, spread (cone half-angle, radians), size, gravity, color, colorEnd, max.
+- System (Update): `UpdateParticles`. Removing the trait or despawning the entity removes its mesh.

package/community/particles/index.ts

@@ -0,0 +1,167 @@
+// Visual-only particle emitters: one InstancedMesh per emitter. Vendored by `kiln add particles`.
+import * as THREE from 'three'
+import { plugin, Rng, RngState, Scene, system, trait, Transform, Update, type Entity } from 'kiln-ecs'
+
+/**
+ * A particle emitter at this entity's Transform:
+ * `commands.spawn(Transform({ y: 1 }), ParticleEmitter({ rate: 40, color: 0xffaa33 }))`.
+ * `rate` is particles per second, `lifetime` seconds, `speed` the launch speed (units/s),
+ * `spread` the cone half-angle in radians around +Y (π = every direction), `size` the start
+ * diameter (particles shrink to nothing), `gravity` units/s² down, `max` the most alive at once.
+ * `color` fades toward `colorEnd` over a particle's life. Set `rate: 0` to stop emitting.
+ * Particles are not entities: they live in the plugin, in world space, and never touch the
+ * simulation or the gameplay Rng stream after the emitter's first frame.
+ */
+export const ParticleEmitter = trait({
+  rate: 30,
+  lifetime: 1.5,
+  speed: 3,
+  spread: 0.4,
+  size: 0.15,
+  gravity: 2,
+  color: 0xffb347,
+  colorEnd: 0xff3b1f,
+  max: 256,
+})
+
+interface EmitterState {
+  mesh: THREE.InstancedMesh
+  rng: RngState
+  /** Per particle: x y z vx vy vz age life. */
+  data: Float32Array
+  alive: number
+  carry: number
+  max: number
+  seen: number
+}
+
+const STRIDE = 8
+const geometry = new THREE.IcosahedronGeometry(0.5, 0)
+const _m = new THREE.Matrix4()
+const _q = new THREE.Quaternion()
+const _p = new THREE.Vector3()
+const _s = new THREE.Vector3()
+const _c0 = new THREE.Color()
+const _c1 = new THREE.Color()
+const _c = new THREE.Color()
+
+/**
+ * Colours go in a per-instance 'color' geometry attribute (read through vertexColors) rather than
+ * InstancedMesh.instanceColor: WebGPURenderer re-uploads geometry attributes on every render call,
+ * but syncs instanceColor only once per animation frame, which loses updates when a frame renders
+ * several times (kiln shot steps).
+ */
+function makeMesh(max: number): THREE.InstancedMesh {
+  const geo = new THREE.BufferGeometry()
+  geo.setAttribute('position', geometry.getAttribute('position'))
+  geo.setAttribute('color', new THREE.InstancedBufferAttribute(new Float32Array(max * 3), 3))
+  const mat = new THREE.MeshBasicMaterial({ color: 0xffffff, vertexColors: true })
+  const mesh = new THREE.InstancedMesh(geo, mat, max)
+  mesh.name = 'particles'
+  mesh.frustumCulled = false
+  mesh.count = 0
+  return mesh
+}
+
+function disposeMesh(mesh: THREE.InstancedMesh): void {
+  mesh.removeFromParent()
+  mesh.geometry.dispose()
+  ;(mesh.material as THREE.Material).dispose()
+  mesh.dispose()
+}
+
+/**
+ * Particle emitters: `app.use(ParticlesPlugin)`, then spawn `ParticleEmitter` entities with a Transform.
+ * Each emitter gets its own RNG forked from the app's `Rng` when first seen, so runs replay exactly.
+ */
+export const ParticlesPlugin = plugin((app) => {
+  const emitters = new Map<Entity, EmitterState>()
+  let frame = 0
+
+  /** Emits, moves, ages and draws every emitter's particles. */
+  const UpdateParticles = system(
+    { emitters: [ParticleEmitter, Transform] },
+    ({ emitters: q }, { res, time }) => {
+      frame++
+      const dt = time.dt
+      q.each(([em, t], e) => {
+        let st = emitters.get(e)
+        const max = Math.max(1, Math.min(100000, Math.round(em.max)))
+        if (!st || st.max !== max) {
+          if (st) disposeMesh(st.mesh)
+          const mesh = makeMesh(max)
+          res.mut(Scene).add(mesh)
+          st = { mesh, rng: st?.rng ?? new RngState(res.mut(Rng).u32()), data: new Float32Array(max * STRIDE), alive: 0, carry: 0, max, seen: frame }
+          emitters.set(e, st)
+        }
+        st.seen = frame
+        const d = st.data
+        // Age and move; swap-remove the dead.
+        for (let i = 0; i < st.alive; ) {
+          const o = i * STRIDE
+          d[o + 6] += dt
+          if (d[o + 6] >= d[o + 7]) {
+            st.alive--
+            d.copyWithin(o, st.alive * STRIDE, st.alive * STRIDE + STRIDE)
+            continue
+          }
+          d[o + 4] -= em.gravity * dt
+          d[o] += d[o + 3] * dt
+          d[o + 1] += d[o + 4] * dt
+          d[o + 2] += d[o + 5] * dt
+          i++
+        }
+        // Emit.
+        st.carry += Math.max(0, em.rate) * dt
+        const rng = st.rng
+        while (st.carry >= 1) {
+          st.carry -= 1
+          if (st.alive >= max) continue
+          const o = st.alive++ * STRIDE
+          const theta = rng.float(0, Math.PI * 2)
+          const cosPhi = 1 - rng.float() * (1 - Math.cos(Math.min(Math.PI, Math.max(0, em.spread))))
+          const sinPhi = Math.sqrt(Math.max(0, 1 - cosPhi * cosPhi))
+          const v = em.speed * rng.float(0.7, 1)
+          d[o] = t.x
+          d[o + 1] = t.y
+          d[o + 2] = t.z
+          d[o + 3] = Math.cos(theta) * sinPhi * v
+          d[o + 4] = cosPhi * v
+          d[o + 5] = Math.sin(theta) * sinPhi * v
+          d[o + 6] = 0
+          d[o + 7] = em.lifetime * rng.float(0.75, 1.25)
+        }
+        // Write instances.
+        _c0.setHex(em.color)
+        _c1.setHex(em.colorEnd)
+        const mesh = st.mesh
+        const colors = mesh.geometry.getAttribute('color') as THREE.InstancedBufferAttribute
+        for (let i = 0; i < st.alive; i++) {
+          const o = i * STRIDE
+          const k = d[o + 6] / d[o + 7]
+          const sz = em.size * (1 - k)
+          _p.set(d[o], d[o + 1], d[o + 2])
+          _s.set(sz, sz, sz)
+          mesh.setMatrixAt(i, _m.compose(_p, _q, _s))
+          _c.copy(_c0).lerp(_c1, k)
+          colors.setXYZ(i, _c.r, _c.g, _c.b)
+        }
+        mesh.count = st.alive
+        mesh.instanceMatrix.needsUpdate = true
+        colors.needsUpdate = true
+      })
+      // Emitters that lost their trait or were despawned.
+      for (const [e, st] of emitters) {
+        if (st.seen === frame) continue
+        disposeMesh(st.mesh)
+        emitters.delete(e)
+      }
+    },
+    { name: 'UpdateParticles' },
+  )
+  app.add(Update, UpdateParticles)
+  app.hooks.dispose.push(() => {
+    for (const st of emitters.values()) disposeMesh(st.mesh)
+    emitters.clear()
+  })
+}, 'ParticlesPlugin')

package/community/particles/kiln-plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "particles",
+  "description": "Visual-only particle emitters: one InstancedMesh per emitter, seeded from the app Rng.",
+  "files": ["index.ts", "README.md"],
+  "requires": []
+}

package/community/terrain/README.md

@@ -0,0 +1,22 @@
+# terrain
+
+A procedural heightfield: seeded fractal value noise (no Math.random), vertex colours blended from
+`colorLow` to `colorHigh` by height, flat-shaded. `terrainHeightAt` samples the exact same function
+headless, so gameplay can put things on the ground without the mesh.
+
+```ts
+import { TerrainPlugin, Terrain, terrainHeightAt } from './plugins/terrain/index.ts'
+
+app.use(CorePlugins, TerrainPlugin)
+
+const land = { size: 64, resolution: 96, height: 6, seed: 7, scale: 18, octaves: 4, colorLow: 0xd9c99a, colorHigh: 0x2f6b2f }
+// in a Startup system:
+commands.spawn(Transform, Terrain(land))
+commands.spawn(Tree, { x: 3, y: terrainHeightAt(land, 3, -2), z: -2 })
+```
+
+Adds:
+- `Terrain` trait: size, resolution (quads per side, 1..1024), height, seed, scale, octaves, colorLow, colorHigh. Changing any field rebuilds the geometry.
+- `terrainHeightAt(params, x, z)`: height in local space (add the terrain's Transform if it moved).
+- `buildTerrainGeometry(params)`: the BufferGeometry, if you want it elsewhere (e.g. a physics trimesh).
+- Systems (Update): `BuildTerrain` (adds MeshRef via commands), `RebuildTerrain`.