1681-engine 0.5.9 → 0.6.0

package/CHANGELOG.md

@@ -3,7 +3,98 @@
 All notable changes to this package are written here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and versions follow [Semantic Versioning](https://semver.org/); before 1.0 a minor version may break the API.
 
-## Unreleased
+## 0.6.0
+
+### Added
+
+- **Interest management**: `Room` takes `interest: { radius, leaveMargin, canSee }` and sends each player only the
+  bodies near it, with a margin so one on the edge is not spawned and removed over and over. `room.place(id, x, y)`.
+  `SpatialHash` (points in square cells, `near` and `inRect`) is exported for a game's own use.
+- **Lag compensation**: `Room` takes `rewindMs` and keeps `history`, a `LagCompensator` recorded as each round of
+  snapshots goes out and blended as `InterpolationBuffer` blends, so a shot is judged against what the shooter saw:
+  `at`, `all`, `near`, `alongRay`. `RoomHost.rewindTime(claimed)` and `LagCompensator.clampTime` hold a client's
+  claim within the window; `InterpolationBuffer.viewTime(now)` is the time a client sends with a shot.
+- **Server bodies**: `Room.addBody(data, x, y)` and `removeBody` for monsters, projectiles and crates the server
+  moves, sent beside the players with the same interest and rewind history (`RoomBody`, `RoomSeen`, `BODY_ID_BASE`).
+  `canSee` now gets either kind.
+- **Rebinding the gamepad**: `Keymap` keeps a first binding per device, so pad buttons are rebindable beside keys
+  (`keysFor(action, device)`); `InputCapture` waits for the next key, pad button or stick push for a settings
+  screen; `padLabel` and `deviceOf`.
+- **Input replays**: `InputRecorder` keeps an `Actions`' steps as a JSON `InputTape` (changes only); `InputPlayer`
+  plays one back through `Actions.replay`, exactly. `Actions.tap` hands every step's values to a listener.
+- **Tools**: the `dialogue` example, a playground that checks a script as it is typed and plays it with its
+  variables in view; `formatTrace` prints a behaviour tree's last tick.
+- **Crowds**: `flowField` and `followField` (one search for a crowd, by `findPath`'s own rules), and steering:
+  `seek`, `flee`, `arrive`, `separation`, `alignment`, `cohesion`, `followFlow`, `combineSteering`, `applySteering`.
+- **Behaviour trees**: `BehaviorTree` and `BtAgent` (one tree, many agents, each with its own memory), `sequence`,
+  `selector`, `reactiveSequence`, `reactiveSelector`, `parallel`, `invert`, `succeed`, `repeat`, `retry`, `cooldown`,
+  `timeout`, `wait`, `condition`, `action` with `onHalt`, a trace for debugging, and `buildTree` from JSON.
+- **Dialogue**: `DialogueRunner` runs a branching script written as data (lines, choices with conditions, `once`
+  and locked choices, variables, commands, `{…}` in text, translation, save and restore); `validateDialogue` checks
+  a script; `compileExpr` is its safe expression language.
+- **Prefabs**: `definePrefab`, `prefabPart`, `spawnPrefab` and `isPrefabOf`, with variants laid over their base
+  field by field; `PrefabLibrary` loads them from data.
+- **Sounds in the world**: `SpatialAudio` places any buffer at a point, panned, faded and muffled by distance from a
+  moving listener, loops paused out of range and picked up where they would be; `spatialMix` is the mix on its own.
+- **`1681-engine/mobile`**: `capacitorConfig` (a Capacitor config with a game's defaults), `BackStack`,
+  `doubleBackToExit` and `installBackButton` for Android's back button, `safeAreaInsets`, `keepScreenOn`, and
+  `nativeBuildOf` for `pickWebUpdate`. Capacitor is handed in, never imported.
+
+### Changed
+
+- `RoomInterest.canSee(viewer, other)` gets a `RoomSeen` (a player or a body the server moves), told apart by
+  `other.kind`; `RoomPlayer` has `kind: 'player'`. `Room` and `RoomHost` take a second type parameter for bodies' data.
+- `Keymap.bind` replaces the action's first binding of the same device (a pad input its first pad input, a key its
+  first key) instead of its first binding of any kind. Keymaps of keys only behave as before.
+
+### Fixed
+
+- `WebPatcher.tidy` called while the tidy `startEntry` began was still running deleted the same folders twice at
+  once; one failed, and the old webs after it were left on disk. Calls now run one after another.
+- `ScrollView.measure` read the content as no taller than the view (Pixi cuts a masked container's bounds to its
+  mask), so a view measured that way never scrolled. It now measures the content without the clip.
+
+## 0.5.10
+
+### Added
+
+- **LDtk import**: `parseLdtk` reads a project's levels into the same `TileMap` Tiled maps use, so `TilemapView`,
+  `collisionFromTiled` and `objectsOf` work on them: IntGrid, AutoLayer, Tiles and Entities layers, entity and level
+  fields, tile custom data and enum tags, world layouts, multi-worlds projects and separate `.ldtkl` level files.
+  `levelByName`, `levelAt`, `entitiesOf`, `intGridAt`, `ldtkExternalLevels`, `loadLdtkLevel`;
+  `AssetLoader.ldtk(key, url, { levels })` and `ldtkProject(key)`; `collisionFromIntGrid(grid, solid)`.
+- **Autotiling**: `autotile`, `updateAutotile` and `paintTerrain` on 4-bit edge masks or 47-tile blob masks
+  (`edgeMask`, `blobMask`, `BLOB47_MASKS`, `blob47Index`), with stable variants, fallbacks and `connectsTo`; an edit
+  retiles only its 3x3 neighbourhood. `TilemapView.refreshTiles(layer, cells)` repaints only the chunks touched, and
+  `x`/`y` place a map at a world position. The `ldtk` example.
+- **Ambient life**: `Drift` (leaves, seeds, embers, motes, ash), `Birds`, `Butterflies`, `Fireflies` and
+  `ChimneySmoke`, bounded pools that live only in view on whole pixels, spawned from a `LifeSource` callback
+  (`sourceOf`, `pickInView`) under a `LifeAir`; `paintLifeArt` in `1681-engine/pixel` paints their art.
+- `Haptics` and `HapticGate`: a per-kind rate-limited buzz with an injectable player (`navigator.vibrate` by default).
+- `ApiClient` and `ApiError`: a JSON REST client with a timeout, a bearer token, a 401 refreshed once and retried,
+  status and error hooks, and abort.
+- `Prepainter` and `workerPainter`: big textures painted ahead in a worker for the neighbours of the current key, the
+  rest freed.
+- React kit: `ConfirmButton` (a button asked twice), `useJsonSelector`, `useStoreJson`, the optional label
+  `confirmAgain`.
+- **`1681-engine/updates`**: the pure half of file-by-file web updates from a release store, shared by desktop,
+  browser and phone builds — `LatestJson`/`WebManifest`/`WebFile`, `validManifest`, `planWeb`, `pickWebUpdate`,
+  `apkUpdateOf`, `pluginEntries`, `heldBundle`.
+- **`1681-engine/electron`**, the main-process side of an Electron build: `WebPatcher` (each newer web built beside the
+  running one, checked by sha256, only for the same shell; one that never boots is dropped for the last good one),
+  `shellId`, `SessionStore`/`registerSessionStore` (an OS-encrypted `safeStorage` secret, refused under `basic_text`),
+  `lockDownWindow`, `denyPermissions`, `refuseDebugLaunch` and the pure link rules. Both subpaths ship as ES modules
+  and CommonJS (`dist/cjs`); `electron` is an optional peer dependency that nothing imports.
+- **Browser tests** (`npm run test:browser`, Vitest browser mode on headless Chromium with SwiftShader): WebGL pixels
+  read back, canvas text, `FontFace`, `decodeAudioData`, TexturePacker atlases, silhouettes, `RichText`, `PixelLayer`,
+  `PixelMarks`, `Darkness`, the React `Panel`'s fitting, fullscreen and pointer lock, `Engine.create` and
+  `DrawCallCounter`, in a CI job of their own; `npm run check` stays node-only.
+- Guide page "Desktop: patching, sessions, lockdown"; the tilemap page covers LDtk and autotiling.
+
+### Fixed
+
+- `AssetLoader` names the URL when an image, sprite sheet or atlas page cannot be decoded, and the family and URL when
+  a font cannot be loaded; the browser's bare message named neither.
 
 ## 0.5.9
 

package/README.md

@@ -41,6 +41,7 @@ await engine.scenes.replace(new Level());
 | `1681-engine/pixel` | pixel-art games | `PixelLayer`, `pixelPaint` shapes, colour ramps, dithered `Darkness` lighting, `Evaporation`, sprite pixel tools |
 | `1681-engine/ui` | games with menus and a HUD | canvas widgets, focus, the pure layout maths, the DOM/React bridge (`DomOverlay`, `createStore`, `InputShield`) |
 | `1681-engine/postfx` | full-screen effects | `PostFx` (a chain of filters, flashes, shockwaves, animated uniforms), bloom, vignette, colour adjust, chromatic aberration, CRT, pixelate, shockwave, and `FxFilter` to write your own in GLSL and WGSL |
+| `1681-engine/mobile` | a phone app on Capacitor | `capacitorConfig`, the Android back button (`BackStack`), `safeAreaInsets`, `keepScreenOn`, `nativeBuildOf`; Capacitor is handed in, never imported |
 | `1681-engine/react` | a UI written in React | `Panel`, `TabStrip`, `SplitPane`, `Select`, `Tooltip`/`TitleTips`, `ConfirmDialog`, `ChoiceDialog`, `Slider`, `PixelImage`, `Glyph`, `UiProvider`, `useStore`, themed by CSS custom properties (`baseCss`) |
 
 The core never imports the pixel module (a test holds it to that), so a game that does not use it does not ship it.
@@ -53,29 +54,35 @@ pixels. Without it, textures are smooth and drawn at the screen's own density.
 | Area | What you get |
 |---|---|
 | **Engine** | `Engine` (canvas, renderer, frame loop), a stack of `Scene`s (`replace`, `push`, `pop`, async loading), a fixed-step `FixedLoop` with interpolation and spiral-of-death protection, typed `EventBus`. |
-| **ECS** | `World` on sparse sets: typed components, `query`, allocation-free `each`, numeric components in typed-array columns (`defineFields`) walked through a cached `slots()` list — a step over 50,000 bodies in 0.1 ms. Systems in `fixed` and `frame` phases, recycled ids with generations, error isolation. |
+| **ECS** | `World` on sparse sets, prefabs with variants (`definePrefab`, `PrefabLibrary` from data): typed components, `query`, allocation-free `each`, numeric components in typed-array columns (`defineFields`) walked through a cached `slots()` list — a step over 50,000 bodies in 0.1 ms. Systems in `fixed` and `frame` phases, recycled ids with generations, error isolation. |
 | **Assets** | `AssetLoader`: images, sprite sheets, JSON, text and Tiled maps with their tilesets, with progress and a concurrency limit. |
 | **Tilemaps** | Tiled JSON maps (CSV or base64 layers, groups, objects, properties, flipped tiles), drawn in culled chunks by `TilemapView`, with collision from a layer or a tile property. |
 | **Animation** | `Animator` clips (fps or per-frame durations, looping or finishing) and an animation system for sprites. |
-| **Input** | `Actions`: named actions bound to keys, chords, gamepad buttons and sticks, and on-screen touch buttons, with per-step edges and analog values. `Keymap` rebinding, `AimGesture` and `TargetLock` for touch, stick maths, touch detection. [Guide](docs/guide/input.md) |
+| **Input** | `Actions`: named actions bound to keys, chords, gamepad buttons and sticks, and on-screen touch buttons, with per-step edges and analog values. `Keymap` rebinding of keys and pad buttons, `InputCapture` for "press a key", input recording and exact replay, `AimGesture` and `TargetLock` for touch, stick maths, touch detection. [Guide](docs/guide/input.md) |
 | **Camera** | Zoom, bounds, shake, flash, and `track` with a soft follow that is the same at any frame rate, a deadzone and an offset. |
 | **Rendering** | `Stage` with world and screen layers, display objects, tweens, timers, bitmap labels, a texture atlas that splits pages by the GPU's limit, guards that keep one bad frame from stopping the loop. |
 | **Characters** | A 2D skeleton rig drawn by `RigView` from cut-out images or vector shapes, `PosePlayer` blending key poses with crossfades, and a built-in humanoid with 72 poses and ready clips (idle, walk, run, roll, slash, thrust, cast, throw, emotes). |
 | **Light** | `LightLayer`: smooth darkness with soft radial lights, colour washes and flicker (the pixel module has its own dithered `Darkness`). |
-| **Audio** | Web Audio `sound` engine (synthesized recipes, recorded takes cleaned in a worker, voice limiting, distance muffling, panning) and `music`: streamed tracks crossfaded and looped. iOS unlock handled. |
-| **Multiplayer** | An authoritative `Room` and its socket host for Node, a client `Connection`, `PredictedMover` (prediction and reconciliation over deterministic movement: in tests and in the example the server never has to correct it), `InterpolationBuffer` for everyone else, binary snapshots, clock sync, input validation and flood limits, cadence rules. A `LobbyHost` with rooms (host, codes, ready, chat, settings), a rating `Matchmaker` that keeps parties whole and balances teams, ready checks with decline lockouts, and a `LobbyClient`. [Guide](docs/guide/lobby.md) |
+| **Audio** | Web Audio `sound` engine (synthesized recipes, recorded takes cleaned in a worker, voice limiting, distance muffling, panning), `SpatialAudio` for looping sounds placed in the world, and `music`: streamed tracks crossfaded and looped. iOS unlock handled. [Guide](docs/guide/audio.md) |
+| **Multiplayer** | An authoritative `Room` and its socket host for Node, a client `Connection`, `PredictedMover` (prediction and reconciliation over deterministic movement: in tests and in the example the server never has to correct it), `InterpolationBuffer` for everyone else, binary snapshots, clock sync, input validation and flood limits, cadence rules, bodies the server moves, interest management by distance and lag compensation for shots. A `LobbyHost` with rooms (host, codes, ready, chat, settings), a rating `Matchmaker` that keeps parties whole and balances teams, ready checks with decline lockouts, and a `LobbyClient`. [Guide](docs/guide/lobby.md) |
 | **Pixel art** (`/pixel`) | `PixelLayer` (thousands of pixel rects in one pooled texture), `pixelPaint` shapes shaded from hue-shifted ramps and faded by ordered dither, `Darkness` with dithered lamps and transient lights, `Evaporation`, the selective outline. |
 | **UI** (`/ui`) | Canvas widgets with keyboard and gamepad focus, the pure layout maths, and a DOM/React bridge laid over the canvas. [Guide](docs/guide/ui.md) |
 | **React kit** (`/react`) | Windows, tabs, split panes, drop-downs, tooltips and dialogs that never overflow the screen, themed by `--e1681-*` properties. [Guide](docs/guide/react.md) |
 | **Physics** | `PhysicsWorld`: circles, boxes and convex polygons that turn when asked (contact points, torque, rolling), sensors, layers, kinematic platforms and spinners, one-way `preSolve`, raycasts, tiles merged into boxes with snag-free seams. [Guide](docs/guide/physics.md) |
 | **Post-processing** (`/postfx`) | Bloom, vignette, colour grade and flash, chromatic aberration, CRT, pixelate, shockwaves; WebGL and WebGPU. [Guide](docs/guide/post-processing.md) |
 | **Particles** | `Emitter` on one pooled `ParticleContainer`, curves over life, a shared budget that thins under reduced effects. [Guide](docs/guide/particles.md) |
-| **Navigation** | A* `findPath` with reach, costs and end-only tiles, `straightenPath`, `floodFill`, `nearestOpen`. [Guide](docs/guide/navigation.md) |
+| **Navigation** | A* `findPath` with reach, costs and end-only tiles, `straightenPath`, `floodFill`, `nearestOpen`; flow fields for crowds and steering (seek, arrive, separation, flocking). [Guide](docs/guide/navigation.md) |
+| **AI** | Behaviour trees shared by many agents, reactive composites that halt what they interrupt, a trace, trees from JSON. [Guide](docs/guide/behaviour-trees.md) |
+| **Dialogue** | Branching scripts as data with conditions, variables, commands, translation and saves; a checker and a playground. [Guide](docs/guide/dialogue.md) |
 | **Saves** | `SaveStore` slots with migrations, checksums and a backup, pluggable backends, `Autosaver`. [Guide](docs/guide/saves.md) |
 | **Transitions** | `transitionTo` with fade, crossfade and dithered wipe, `Letterbox`. [Guide](docs/guide/transitions.md) |
 | **Localisation** | `Translator` with the English source as key, contexts, plurals, live switching; `extractStrings`. [Guide](docs/guide/i18n.md) |
 | **Ambient** | `DayClock`, deterministic `weatherAt` and `WeatherLayer`, `ColorGrade`; in `/pixel`, `NightShade`, `SwayProp`, `DitherVignette`. [Guide](docs/guide/ambient.md) |
 | **Game feel** | Pooled `FloatingText` for damage numbers, hit-stop, recoil and flash curves. [Guide](docs/guide/game-feel.md) |
+| **LDtk and autotiling** | LDtk projects (IntGrid, auto-layers, entities with fields, world layouts, level files) read into the same tile map as Tiled; 4-bit and 47-tile blob autotiling that retiles only what an edit touched. [Guide](docs/guide/tilemap.md) |
+| **Ambient life** | Drifting leaves, embers and ash, birds, butterflies, fireflies and chimney smoke, pooled and alive only in view. [Guide](docs/guide/ambient.md) |
+| **Desktop** (`/electron`, `/updates`) | File-by-file web patching by sha256, an OS-encrypted session store and a window lockdown for Electron; the update rules shared with phones. [Guide](docs/guide/desktop.md) |
+| **Mobile** (`/mobile`) | A Capacitor config with a game's defaults, the Android back button, the safe area, a screen kept on, the native build for over-the-air updates. [Guide](docs/guide/mobile.md) |
 | **Diagnostics** | Error capture, WebGL context loss, a boot watch, frame sampling, and a `DebugOverlay` with collision boxes. [Guide](docs/guide/diagnostics-and-debug.md) |
 
 ### A React UI
@@ -132,7 +139,8 @@ locally.
   [particles](docs/guide/particles.md), [game feel](docs/guide/game-feel.md), [ambient](docs/guide/ambient.md),
   [transitions](docs/guide/transitions.md), [post-processing](docs/guide/post-processing.md),
   [lobby and matchmaking](docs/guide/lobby.md), [UI](docs/guide/ui.md), [React kit](docs/guide/react.md),
-  [localisation](docs/guide/i18n.md), [saves](docs/guide/saves.md), [diagnostics and debug](docs/guide/diagnostics-and-debug.md).
+  [localisation](docs/guide/i18n.md), [saves](docs/guide/saves.md), [diagnostics and debug](docs/guide/diagnostics-and-debug.md),
+  [behaviour trees](docs/guide/behaviour-trees.md), [dialogue](docs/guide/dialogue.md), [mobile](docs/guide/mobile.md).
 - [Examples](examples/), run with `npm run dev`:
   - `top-down`: a Tiled map, asset loading, an animated hero, input actions on keyboard, gamepad and touch, camera follow.
   - `platformer`: physics from a tile grid (crates, a moving platform, one-way planks, sensor coins), particles, a canvas
@@ -144,6 +152,7 @@ locally.
   - `physics-toys`: bodies that turn (crates, balls, polygons, a spinning bar) under bloom, a vignette and the other effects.
   - `lobby`: `npm run example:lobby`, then the page: rooms, codes, ready flags, chat, the queue and a ready check.
   - `walk-room`: the smallest whole game, with pixel effects.
+  - `dialogue`: a playground for dialogue scripts, checked as they are typed and played with their variables in view.
 
 ## Develop