1681-engine 0.0.0-stage → 0.5.9

package/CHANGELOG.md

@@ -0,0 +1,357 @@
+# Changelog
+
+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.5.9
+
+### Added
+
+- **Platform helpers**: `enterFullscreen`/`exitFullscreen`/`toggleFullscreen`/`isFullscreen`/`fullscreenSupported`/
+  `onFullscreenChange` (with webkit fallbacks), `lockOrientation`/`unlockOrientation`/`currentOrientationKind`,
+  `prefersReducedMotion`/`onReducedMotionChange`/`followReducedMotion`, `requestPointerLock`/`exitPointerLock`/
+  `isPointerLocked`/`onPointerLockChange`, `onAppResume` and `timeoutSignal` (an `AbortSignal.timeout` stand-in for
+  older iOS); each does nothing safely where unsupported.
+- `Engine.create({ pauseWhenHidden, followReducedMotion })` (both off by default): pause while the page is hidden with
+  no catch-up steps on return, and copy the system's reduced-motion setting into `engineSettings.reducedFx`.
+  `HiddenPause` holds the rule on its own.
+- **Gamepad rumble**: `rumble`, `rumblePad`, `stopRumble`, `rumbleParams` and `Actions.rumble`. `Pointer` gains
+  `lock`, `unlock`, `locked` and `takeMovement` for mouse-look.
+- **`AssetLoader`** loads `atlas` (TexturePacker/Pixi JSON, hash or array, multipack, trimmed and rotated frames;
+  `getAtlas`), `font` (a `FontFace` into `document.fonts`) and `audio` (`getAudio`/`decodeAudio`, decoded through the
+  sound context or kept until one exists). `parseAtlas`, `collectAtlasPages`, `duplicateFrames`,
+  `TextureRegistry.addAtlas`, `CanvasTexture.addPacked`, `SoundEngine.audioContext`.
+- **`RichText`** (`1681-engine/ui`): inline markup for colour, bold, italic, size and icons, wrapped and aligned, on
+  canvas or bitmap fonts; the pure `parseRichText`, `escapeRichText`, `stripRichText` and `layoutRichText`.
+- **Hit flashes and dash ghosts without a filter pass**: `solidSilhouette`, `fillSolid`, `clearSilhouettes` and pooled
+  `Afterimages`.
+- **Pixel-art zoom maths**: `worldZoom`, `baseZoom`, `zoomSteps`, `zoomResolution`, `fitScale` (whole steps and an
+  optional half step with the resolution that keeps a world pixel whole).
+- `blendLayer`: one container per stage for additive sprites, so they do not split batches.
+- In `1681-engine/pixel`: `spark`, `tail`, `pixelOn`; `PixelMarks` and `aimPixels` (chevron aim lines and lock rings
+  in world pixels).
+- `Connection`: `fatalCloseCodes` (close codes that never reconnect) and `resumeProbeMs` (a socket that does not answer
+  a ping after the app returns from the background is dropped with `CLOSE_NO_ANSWER` and reconnected);
+  `reconnectDelay` and `shouldReconnect`.
+- Guide pages: assets, platform, ECS, rig, tilemaps, audio, rich text, netcode.
+
+### Changed
+
+- Movement numbers no longer need a fork: `MovementParams` takes `dashFlag` and `stepDt` (defaults `INPUT_FLAG_DASH`,
+  1/60 s); the tile size and body half extents were already the grid's. `TILE_SIZE`, `BODY_HALF_*` and
+  `INPUT_FLAG_DASH` are kept as the defaults.
+- `Darkness` takes `{ carriedLight }` (default `CARRIED_LIGHT`, 80) and `update()`'s radius defaults to it; the pixel
+  module no longer imports `net/`.
+- `Clock` runs timers without allocating a frame; a timer that throws is reported to `Clock.onError` and dropped.
+- `DrawCallCounter` counts `drawRangeElements` and leaves a later wrapper in place when it uninstalls.
+- A socket replaced by a newer one no longer emits a stale `close`.
+- The package ships no source maps (`ENGINE_SOURCEMAP=1` builds them; they pointed at an unpublished `src/`) and no
+  longer declares `engines.node`; `Room`, `RoomHost` and `LobbyHost` on a server need Node 22 or later. The tarball went
+  from 931 kB to about 420 kB.
+- Typechecks against pixi.js 8.6, the peer floor, tested in CI along with the examples build. Workflows use v5 actions;
+  publishing pins npm 11 and uses no cache.
+
+### Tests
+
+- Golden bytes for the snapshot codec, cadence, `LobbyRooms`, `Connection`, the platform helpers, sparse sets, field
+  columns, sticks, long press, eases, synth, view culling, touch detection, the spatial hash and transient lights.
+
+## 0.5.8
+
+### Added
+
+- **Bodies that turn**: `PhysicsWorld` bodies made with `rotates: true` have an `angle`, an `angularVelocity`, a moment
+  of inertia from their shape and are turned by contacts (each with one or two contact points: `ContactInfo.points`),
+  `applyImpulse`/`applyForce` at a point, `applyTorque`, `applyAngularImpulse`; `angularDamping`, `setAngle`,
+  `velocityAt`, `toWorld`/`toLocal`. Convex **polygons** (`polygonShape`, `polygonCentroid`, `regularPolygon`, up to 16
+  corners) and boxes at an angle collide by the separating axis test with clipped edges; turning bodies never push out
+  of a merged tile box's internal face, so seams stay snag-free. Kinematic spinners, rolling balls, raycasts against
+  turned shapes, sleep that counts spin. `syncToBody` turns a view with its body. Bodies that do not rotate behave
+  exactly as before.
+- **`1681-engine/postfx`**: `PostFx` lays a chain of full-screen filters over the whole picture or the world layer,
+  switched one by one, with `flash`, `shockwave` and `animate` for effects that come and go (skipped under reduced
+  effects); `BloomFilter`, `VignetteFilter`, `ColorAdjustFilter`, `ChromaticAberrationFilter`, `CrtFilter`,
+  `PixelateFilter`, `ShockwaveFilter`; `FxFilter` builds an effect from one spec in GLSL and WGSL with shared helpers.
+- **Lobby and matchmaking**: `LobbyHost` (transport-free like `RoomHost`): rooms with a host, a share code, private
+  rooms, ready flags, kick and promote, chat, the game's settings, a room starting its own game; a queue per mode
+  filled by `Matchmaker` (pure: rating windows widening with the wait, both sides' windows respected, parties never
+  split, teams balanced by `balanceTeams`); ready checks with a deadline, decline lockouts and requeueing at the old
+  place; `onStart` hands each player where to go, `finish` opens the rooms again; message rate limits. `LobbyClient`
+  keeps the state for a lobby screen over a `Connection`.
+- React kit: `UiProvider classNames` hangs a game's own class names beside the kit's (`{ tabs: 'tabs', button: 'btn',
+  picked: 'active' }`), states included, so a game whose stylesheet already styles its own names takes the kit without
+  rewriting it; `useCx` / `UiSettings.cx` join them, `classJoiner` is the pure rule.
+- `DebugOverlay`'s `colliders` callback also gets a line drawer, and `drawColliders` draws turned shapes as outlines.
+- Examples: `physics-toys` (turning bodies under every post effect) and `lobby` (a React lobby screen, a server with
+  bots). Guide pages: post-processing, lobby and matchmaking; the physics page covers turning bodies.
+
+## 0.5.7
+
+### Added
+
+- **Aseprite import**: `parseAseprite` reads Aseprite's sprite-sheet JSON (hash or array frames) into `Animator`
+  clips, one per tag, with every tag direction and repeat count, per-frame durations, trimmed frames, slices with their
+  9-slice centre and pivot (`sliceAt`, `sliceBorders`), layers, and cel user data as frame markers (`clipMarkers`);
+  `loadAseprite` / `addAsepriteTextures` register the sheet's frames as textures.
+- **`AnimStateMachine`** drives an `Animator` from named states: transitions on bool, number and trigger parameters,
+  clip-end and exit-time transitions, any-state transitions by priority, events on frame markers (a footstep on
+  frame 3), no allocation per update; `AnimStateComponent` and `animStateSystem` run it in the ECS.
+- **`Timeline`**: sequenced and overlapping tweens and calls with positions (`'<'`, `'+=200'`, labels), `parallel`
+  groups, nesting, repeat/yoyo/repeatDelay, timeScale, pause/seek/reverse/restart, `finished`; made with
+  `stage.tweens.timeline()` or stepped by hand. `Tweener` gains `run(steppable)` and `timeline()`.
+- **`Parallax` / `ParallaxLayer`**: scenery that scrolls at a share of the camera's travel on x and y, tiled textures
+  repeating forever (covering only the view), offset and drift, whole-pixel snapping on pixel-perfect engines,
+  culling and depth; works with the camera's zoom.
+- Examples: `aseprite` (a generated sheet, the state machine and its events); the platformer's hills are a
+  `Parallax` and reaching the goal plays a `Timeline`.
+- Documentation: a guide page for every module (input, animation, physics, navigation, particles, game feel, ambient,
+  tweens and parallax, transitions, UI, React kit, localisation, saves, diagnostics and debug); the API reference
+  covers `1681-engine/ui` and `1681-engine/react`.
+
+### Fixed
+
+- The docs build no longer fails on `{{` quoted in inline code of the API reference.
+
+## 0.5.6
+
+### Added
+
+- **React kit** (`1681-engine/react`, React 19 as an optional peer dependency): `Panel` (a window fitted into the
+  screen by `fitToViewport`, its body scrolling; a full-screen sheet on touch), `TabStrip` (wraps with `wrap`),
+  `SplitPane` with `usePicked` and `useFillSheet` (list beside detail, one pane at a time on a narrow touch screen),
+  `Select` (a drop-down whose list opens in a portal as wide as its longest label, placed by `listWidth` and
+  `placeTooltip`), `Tooltip` and `TitleTips` (every `title=` drawn as the kit's tooltip, flipped at the edges, desktop
+  only), `Modal`, `ConfirmDialog` / `askConfirm` / `askQuantity`, `ChoiceDialog` / `askChoice`, `Slider`, `PixelImage`
+  (sprites at whole multiples), `Glyph` (pixel marks a pixel font lacks, `registerGlyph`), `UiProvider` (touch mode,
+  window scale, viewport, portal, labels) and `useStore` over `createStore`. Themed by CSS custom properties
+  (`--e1681-*`, frames as 9-slice `border-image`s) in `baseCss` / `injectBaseCss()`; every word is a prop or a label
+  with an English default. Pure placement helpers (`windowStyle`, `cursorTip`, `listPlacement`, `pixelFit`,
+  `splitModeFor`) are exported and tested under node.
+- `Scene.delay(ms, fn)`: timers owned by the scene, cancelled when it exits (`stage.time.delayedCall` timers belong to
+  the stage and fire after the scene has gone). `Scene.useInput(actions)` registers input to flush when a scene pushed
+  over this one pops.
+- `Actions.flush()` drops pending press and release edges; held keys stay held but are not pressed again.
+- Key chords in bindings: `Shift+Tab`, `Ctrl+KeyS` (`Shift`, `Ctrl`, `Alt`, `Meta`, either side). A held chord keeps
+  the bare key's action off until that key comes up. `parseChord`, `chordHeld`; `keyLabel` reads a chord.
+- `Keymap` takes `fixed` inputs per action (gamepad, touch, a reserved key such as Escape for pause), laid after the
+  player's keys by `applyTo` and never saved; `fixedFor(action)`.
+- `Camera.clearBounds()`, `Camera.reset()` (no target, no bounds, `defaultZoom`, scroll 0, no shake or flash),
+  `Camera.defaultZoom` (set from the engine's `zoom`), `tracking` and `boundsRect`.
+- `PhysicsWorld.bodies` (read-only), and `drawColliders(world, draw, colors?, colorOf?)` for `DebugOverlay`'s
+  `colliders` callback.
+- `parent` options: `FloatingText` (labels under a scene's `root`) and `UiRoot` (under a scene's `hud`, destroyed
+  with it). `ColorGrade` takes `parent` and `placement: 'bottom'`, which keeps it under every HUD whatever the order
+  they were made in.
+- `ColourSkin.fillAlpha` and `borderAlpha`: a bare ring is `fillAlpha: 0`.
+- `Dialog` without a `height` takes its content's, padding included, measured again on every layout.
+- `installLabelFont`, `BitmapLabel`, `Label.bitmap`, `ObjectFactory.label` and `FloatingText` take `glyphs` a font
+  bakes besides ASCII.
+
+### Changed
+
+- `SceneManager.replace` resets the shared camera between the old scenes leaving and the new one entering, so a
+  level's follow target and bounds no longer hold over the next scene. `push` and `pop` leave it alone; `pop` flushes
+  the resumed scene's registered input before `onResume`.
+- `Keymap.applyTo` accepts an `Actions` with more actions than the keymap's and binds only the keymap's.
+- A `ColourSkin` border is drawn as four strips round its fill rather than a box under it, so a see-through fill no
+  longer shows the border colour through it (opaque skins look the same).
+- `Button` centres its content again when the content (a `Label` given new text) changes size; widgets tell their
+  parent through `Widget.childResized`.
+- Documented: `Scene`'s `world`/`root`/`hud` and Pixi's `Container.label` are taken names for subclass fields; a
+  `Keyboard` knows only keys pressed after it was made; bitmap label fonts bake ASCII unless given more; the save
+  envelope keeps its `'lantern-save'` tag so existing saves still load.
+
+### Fixed
+
+- `DebugOverlay` prevents its toggle key's browser action (F3 opened find-in-page).
+- `Slider` draws its focus face under the knob, not over it.
+
+## 0.5.5
+
+### Changed
+
+- **Renamed to 1681 Engine**: the package is `1681-engine` (`1681-engine/pixel`, `1681-engine/ui`) and the repository
+  `Phadec/1681-engine`. The pixel module keeps its name, Dither.
+- `World.entities()` and `World.componentsOf(e)` list live entities and what they hold, for tools.
+
+### Added
+
+- **UI** (`1681-engine/ui`): canvas widgets on the stage's screen layer (`UiRoot`, `Panel` 9-slice or colour box,
+  `Button`, `Label`, `Bar` with a delayed drain, `Slider`, `Toggle`, `Stack`, `ScrollView`, `List`, modal `Dialog`),
+  keyboard and gamepad focus through `Actions`, screen anchoring that follows resizes, whole-pixel layout, presses on
+  widgets kept from the world (`UiPointerGate`); a DOM/React bridge (`DomOverlay`, `DomWorldAnchors`, `createStore`,
+  `InputShield`); pure layout maths shared by both (`stackLayout`, `anchorPosition`, `fitToViewport`,
+  `placeTooltip`, `wrapRow`, `listWidth`, scrolling, focus navigation).
+- **Physics**: `PhysicsWorld`, rigid circles and axis-aligned boxes (dynamic, static, kinematic) with restitution,
+  friction, damping, gravity scale, sensors and layers; a grid broad phase, warm-started impulses, sub-steps against
+  tunnelling, optional sleeping; contact events, `grounded`, `raycast`, a `preSolve` hook; `tileBodies` merges a tile
+  grid into static boxes; `syncToBody` draws a view between steps. Not deterministic across machines.
+- **Particles**: `Emitter` (bursts and rates, spread, gravity, drag, size/alpha/tint over life, normal or additive) on
+  one pooled `ParticleContainer`, a shared `ParticleBudget` that thins under `reducedFx`/`batterySaver`, culled off
+  screen; pure `ParticleSim` and curves.
+- **Navigation**: A* `findPath` on any tile grid or `CollisionGrid` (reach radius, extra cost, end-only tiles, no
+  corner cutting), `straightenPath`, `simplifyPath`, `floodFill`, `nearestOpen`, `MinHeap`.
+- **Saves**: `SaveStore` (versioned slots over a pluggable `SaveBackend`, a migration chain, a checksum, the last good
+  copy kept), `Autosaver`.
+- **Scene transitions**: `transitionTo(engine, next, transition, mode)` with `FadeTransition`,
+  `CrossfadeTransition`, `DitherWipeTransition`; `Letterbox`.
+- **Localisation**: `Translator` (English source as key, `|context`, plurals, missing-key callback, runtime switching),
+  `extractStrings`.
+- **Ambient**: `DayClock`, deterministic `weatherAt`, `WeatherLayer`, `ColorGrade`; pixel `NightShade`,
+  `paintWeatherArt`, `SwayProp` (sprites swaying by whole pixels), `DitherVignette`, `nineSlice`/`frameSvg` UI frames.
+- **Input**: `Keymap` (rebinding, reserved keys, saved sets), `AimGesture` (drag-to-aim), `TargetLock`.
+- **Diagnostics and debug**: `watchContextLoss`, `guardRender`, `bootWatch`, `maxTextureSize`, `FrameSampler`,
+  `captureErrors`; `DebugOverlay` (FPS graph, draw calls, entities, collision boxes, the last errors).
+- **`FloatingText`**: pooled bitmap labels for damage numbers and pickups, fonts baked ahead.
+
+## 0.5.3
+
+### Added
+
+- Music in layers: `music.channel(name)` plays one looping track per channel (a score and an ambience under it),
+  each crossfaded on its own at its own level; `music.play` is the `'music'` channel. `music.configure({ route,
+  pauseInBackground })`: the `<audio>` element's own volume by default, a Web Audio gain only where that volume is
+  read-only (iOS) or when asked, and the music stopped while the page is hidden. `MusicChannel`, `elementVolumeLocked`.
+- `paintLayer(stage, { at, duration, paint, depth, alive, every, fps, onCreate })` in `1681-engine/pixel`: one
+  effect as its own pixel layer redrawn at 12 fps, following its anchor, dithered away at the end and skipped off
+  screen.
+- `Footsteps`: steps and hooves by the surface under the feet, the surface named by the game (`setSurfaceAt`).
+- `detectTouch` and `TouchEnv` are exported; `setTouchOverrideKey` names the `localStorage` key that forces touch.
+
+### Changed
+
+- `MusicOptions` is now the player's configuration; a track's options are `MusicPlayOptions`.
+- Music plays on the element's own volume where it works, instead of always through Web Audio: a file from another
+  origin no longer plays silent there.
+
+## 0.5.2
+
+### Added
+
+- `registerMaterial(name, { light, factors })`: a game adds its own materials to the hue-shifted ramps, or changes a
+  built-in one. `Material` is the built-in set (`BuiltinMaterial`) or any registered name; `MATERIALS` and
+  `RAMP_FACTOR_SET` (now exported) include what is registered.
+- `registerHandRamps(…)`: ramps picked by hand for a game's own effect colours.
+- `1681-engine/pixel/tone` and `1681-engine/pixel/paint`: the pixel shapes and the colour/dither helpers as
+  named exports (`pixelPaint` and `pixelTone` remain namespaces of `1681-engine/pixel`).
+- `selectiveOutline(g, width, dark)` and `groundShadow(g, cx, cy, rx, ry, core, rim)` take their colours.
+- A test that fails on a game's names or language anywhere in the engine, and "The engine knows no game" in the
+  architecture guide.
+
+### Changed
+
+- `pixelTone.ramp` has no hand-picked ramps built in any more (they were one game's effect colours): every colour is
+  `derivedRamp` until a game registers its own.
+
+## 0.5.1
+
+### Changed
+
+- The library ships one file per source module (`dist/core/Stage.js`, `dist/pixel/pixel.js`…) behind the same two
+  entry points, and declares no side effects, so a game's bundler keeps only what it imports: a web worker that wants
+  the colour helpers no longer takes Pixi, the audio engine and every other module with it.
+
+## 0.5.0
+
+### Fixed
+
+- The bundled audio worker (`takeCleanerWorker`) is found again by a game's own bundler: 0.4.0 wrote its URL as an
+  absolute `/assets/…`, so Vite failed to build any game importing the engine (`Could not resolve entry module`). The
+  library is now built with a relative base and the worker sits beside the module that loads it.
+
+## 0.4.0
+
+### Changed
+
+- Node 22 or later (Node 20 reached its end of life; Pixi reads `navigator`, which Node 20 lacks, as it loads).
+
+### Added
+
+- A documentation site (VitePress): home, guide, an API reference generated from the source by TypeDoc, the changelog,
+  and the examples running live; `npm run docs:dev` / `docs:build`, published by a GitHub Pages workflow.
+- Examples `pixel-dungeon` (dithered torchlight, a carried light, evaporating slimes) and `ecs-stress` (tens of
+  thousands of bodies with the frame rate and step time).
+- Types the public API refers to are exported too: `ComponentValues`, `ArrayOf`, `SettingsListener`, `Tween`,
+  `TweenConfig`, `TweenTarget`, `EaseFn`, `Vec2`, `AtlasPlan`, `AtlasPage`, `CameraLike`, `SoundEngine`,
+  `SoundOptions`, `TiledPropertyValue`; `PackedPixels` is exported as a class from the pixel module.
+
+## 0.3.0
+
+### Added
+
+- Characters: `RigView` draws a rig from cut-out images or vector shapes (origin at the feet, mirrored by `facing`,
+  joints readable for held items); `PosePlayer` blends key poses with crossfades between clips; `HUMANOID_POSES` (72)
+  and `HUMANOID_CLIPS`.
+- `LightLayer`: smooth darkness with soft lights, colour washes and flicker.
+- `music` / `MusicPlayer`: streamed tracks, crossfaded, looping, at the music volume, iOS-safe.
+- Multiplayer: the netcode protocol, `PredictedMover` (prediction and reconciliation), `InterpolationBuffer`, an
+  authoritative `Room` with input validation and flood limits, `RoomHost` for any Node WebSocket library, and a
+  client `Connection` with batching, clock sync and reconnection. Tested end to end with simulated latency and jitter,
+  and through real sockets in the example.
+- Examples `night-garden` (smooth art, rig, lights) and `multiplayer` (`npm run example:server`).
+
+## 0.2.0
+
+The engine is now **1681 Engine** (`1681-engine`), for 2D games in any art style; the pixel-art tools moved to
+their own module, **Dither** (`1681-engine/pixel`).
+
+### Breaking
+
+- Pixel-art exports moved to `1681-engine/pixel`: `PixelLayer`, `pixelPaint`, `pixelTone`, the colour and pixel-grid
+  helpers, `PALETTE`, the prop kit, `ramp`/`selectiveOutline`, `Darkness` and the transient lights, `Evaporation`,
+  `spritePixels`.
+- `stage.add.pixels()` is gone: use `addPixelLayer(stage)` from the pixel module, or `stage.add.existing(obj)` for any
+  object made elsewhere.
+- `EngineOptions.pixelArt` (default on) is now `pixelPerfect` (default off). Off, textures are smooth, antialiased and
+  drawn at the screen's density; on, they are sharp, at one backing pixel per CSS pixel, and the camera lands on
+  whole pixels (`Camera.roundPixels`).
+- `createCollisionGrid`'s fifth argument is an options object (`ground`, `shotOverTiles`, `bodyHalfWidth`,
+  `bodyHalfHeight`); `setShotOverTiles` is gone.
+
+### Added
+
+- `AssetLoader`: images, sprite sheets, JSON, text and Tiled maps with their tileset images, progress, a concurrency
+  limit, errors that name the URL.
+- Tiled maps: `parseTiled` (CSV and base64 layers, groups, objects, properties, flips, tile animations; clear refusals
+  for what is not supported), `collisionFromTiled` (a layer or a tile property), `TilemapView` (layers drawn in culled
+  chunks, each at its own depth among the bodies).
+- `Animator` (fps or per-frame durations, loop or finish, speed) and `animationSystem` with `SpriteComponent` and
+  `AnimationComponent`.
+- `Actions`: named input bound to keys, gamepad buttons and sticks (with a dead zone), and virtual touch buttons; per-step
+  edges, analog values, rebinding.
+- `Camera.track`: a soft follow that is the same at any frame rate, a deadzone, an offset, the bounds kept.
+- Example `top-down` with a Tiled map, written by `examples/top-down/make-assets.mjs`.
+- `world.each(A, B, fn)`: walks without allocating a row per entity.
+- `defineFields(name, { x: 'f32', … })`: numeric components kept in typed-array columns (`world.columns`).
+- `world.slots(A, B)`: the matching slot indices as a cached `Int32Array`, rebuilt only when membership changes.
+  With field components a step over 50,000 bodies takes 0.1 ms, 200 times the first release.
+- `world.count(type)`, `entityIndex(e)`, `npm run bench`.
+
+### Changed
+
+- `World` stores components in sparse sets instead of maps: a query over 50,000 bodies went from 21 ms to 2 ms a
+  step, and spawning and destroying makes a third of the garbage. Entity ids are recycled with a generation, so a
+  stale id never matches the entity that reuses its slot. Entities are walked last-added first.
+- Removing a component while a walk is in progress is deferred like destroying an entity, so nothing is skipped.
+
+## 0.1.0 (as Dither Engine)
+
+First release, split out of a shipped game's client.
+
+### Added
+
+- `Engine`, `Scene`, `SceneManager` (replace, push, pop, async `onEnter`) and `FixedLoop` (fixed-step simulation with
+  interpolation and a cap on catch-up steps).
+- `World` ECS: typed components, queries, `fixed` and `frame` systems, deferred destruction, error isolation.
+- `EventBus` with `once`, `off`, `listenerCount` and listener error isolation.
+- Rendering core: `Stage`, `Camera`, `PixelLayer`, display objects, tweens, timers, bitmap labels, texture atlas.
+- Pixel effects: `pixelPaint`, `pixelTone`, `Evaporation`, hit-stop and recoil curves.
+- Lighting: `Darkness` with dithered lamps and transient lights.
+- Skeleton rig, pose blending, material ramps, selective outline and `HUMANOID_RIG`.
+- Audio: `sound`, synthesized recipes (`registerSounds`), recorded takes (`registerTakes`).
+- Input: `Keyboard`, stick maths, long press, touch detection.
+- Networking: deterministic `stepMover` with a configurable body box, binary snapshot codec, cadence rules, server
+  clock.
+- Example: `walk-room`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phadec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# 1681 Engine
 
-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.
+[![CI](https://github.com/Phadec/1681-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/Phadec/1681-engine/actions/workflows/ci.yml)
+[![Docs](https://github.com/Phadec/1681-engine/actions/workflows/docs.yml/badge.svg)](https://phadec.github.io/1681-engine/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A 2D game engine for the web, built on [PixiJS 8](https://pixijs.com) and written in TypeScript, for games in any
+art style: hand-drawn, HD, vector or pixel art. Pixel art gets a module of its own, **Dither**.
+
+It grew out of a shipped online action RPG, so its pieces were made for a real game under real load: a fast ECS,
+a fixed-step simulation a server can replay **bit for bit**, Tiled maps, input that works the same on keyboard,
+gamepad and touch, and for pixel art, effects painted on the world's own pixel grid and dithered lighting.
+
+```ts
+import { Engine, Scene, defineComponent, system } from '1681-engine';
+
+const Position = defineComponent<{ x: number; y: number }>('Position');
+
+class Level extends Scene {
+  override onEnter() {
+    this.world.spawn([Position, { x: 0, y: 0 }]);
+    this.world.addSystem(
+      system('drift', 'fixed', ({ world, dt }) => {
+        world.each(Position, (_e, p) => (p.x += 30 * dt));
+      }),
+    );
+  }
+}
+
+const engine = await Engine.create({ parent: document.body });
+await engine.scenes.replace(new Level());
+```
+
+> **Status: 0.x, early.** The API will change between minor versions until 1.0. See [CHANGELOG.md](CHANGELOG.md).
+
+## Entry points
+
+| Import | For | Holds |
+|---|---|---|
+| `1681-engine` | every 2D game | engine, scenes, ECS, rendering core, assets, Tiled maps, animation, input, camera, rig maths, audio, networking |
+| `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/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.
+React and React DOM (19) are optional peer dependencies needed only by `1681-engine/react`; nothing else imports React.
+Start a pixel-art game with `Engine.create({ pixelPerfect: true })`: sharp textures and a camera that lands on whole
+pixels. Without it, textures are smooth and drawn at the screen's own density.
+
+## Features
+
+| 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. |
+| **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) |
+| **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) |
+| **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) |
+| **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) |
+| **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
+
+```tsx
+import { createRoot } from 'react-dom/client';
+import { ConfirmDialog, Panel, TitleTips, UiProvider, askConfirm, injectBaseCss } from '1681-engine/react';
+
+injectBaseCss(); // the base stylesheet, first in <head>, so the game's own CSS wins
+// theme it with custom properties: frames are 9-slice border-images the game draws
+document.documentElement.style.cssText += `
+  --e1681-font: 'My Pixel Font'; --e1681-accent: #f0c060;
+  --e1681-frame: url(/ui/frame.svg); --e1681-frame-slice: 16 20 20 16 fill; --e1681-frame-width: 16px 20px 20px 16px;`;
+
+createRoot(document.getElementById('ui')!).render(
+  <UiProvider labels={{ cancel: 'Annuler', ok: 'OK' }}>
+    <Panel title="Inventory" onClose={close} width={420}>…</Panel>
+    <ConfirmDialog />
+    <TitleTips />
+  </UiProvider>,
+);
+if (await askConfirm('Drop the sword?')) drop();
+```
+
+Windows and dialogs are fitted into the screen by `fitToViewport` and placed in whole pixels; tooltips and the
+select's list by `placeTooltip` and `listWidth`. On a touch device (`isTouchUi`, or `UiProvider touch`) a `Panel` is a
+full-screen sheet and tooltips are off. Every word the kit prints is a prop or a `labels` entry with an English default.
+
+## Install
+
+```sh
+npm install 1681-engine pixi.js
+```
+
+`pixi.js` (8.6 or later) is a peer dependency. The package is ESM only and ships its TypeScript types. On a server
+(the multiplayer `Room`) it needs Node 22 or later.
+
+The engine renders with **WebGL 2** by default. `Engine.create({ preference: 'webgpu' })` opts into WebGPU, which
+is experimental here: it falls back to WebGL where the browser lacks it, but has not been profiled the way the WebGL
+path has.
+
+## Documentation
+
+**https://phadec.github.io/1681-engine/** — the guide, the API reference and the examples running live.
+
+The documentation site (guide, API reference generated from the source, live examples) is built with
+`npm run docs:build` and published to GitHub Pages by `.github/workflows/docs.yml`; `npm run docs:dev` serves it
+locally.
+
+- [Getting started](docs/guide/getting-started.md): an engine, a scene, entities and systems, assets, a Tiled map, input,
+  the camera, a rigged character, light and music, and multiplayer, step by step.
+- [Architecture](docs/guide/architecture.md): how the frame loop, scenes, ECS and rendering fit together, and the rules that keep it fast.
+- A page per module: [input](docs/guide/input.md), [physics](docs/guide/physics.md), [navigation](docs/guide/navigation.md),
+  [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).
+- [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
+    HUD and pause dialog, a versioned save, scene transitions, two languages, rebindable keys and a debug overlay.
+  - `night-garden`: smooth vector art, a rigged hero animated by blended poses, a lantern and fireflies in the dark.
+  - `pixel-dungeon`: the pixel module: dithered torchlight, a carried light, slimes that evaporate into their own pixels.
+  - `ecs-stress`: tens of thousands of bodies on typed-array components, with the frame rate and step time.
+  - `multiplayer`: `npm run example:server`, then two tabs: prediction, reconciliation and interpolation.
+  - `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.
+
+## Develop
+
+```sh
+npm install
+npm run dev        # examples at http://127.0.0.1:5180/
+npm test           # unit tests under node
+npm run typecheck  # sources and tests
+npm run bench      # ECS benchmark
+npm run build      # dist/: both ESM bundles and their .d.ts files
+npm run check      # typecheck, test and build, as CI runs it
+npm run docs:dev   # the documentation site, with the API reference and examples
+```
+
+Contributions are welcome: read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+## License
+
+[MIT](LICENSE)