zx-kit 0.23.0 → 0.24.0

package/README.md

@@ -546,6 +546,9 @@ requestAnimationFrame(loop)
 | [`scene.ts`](#scenets--scene-manager) | Stack-based scene manager with onEnter/onExit/onPause/onResume hooks |
 | [`save.ts`](#savets--typed-save--load) | Typed save/load via callbacks, versioning + migrations, slot enumeration, throttling, Result types |
 | [`tilemap.ts`](#tilemapts--tile-map-engine) | Scrollable maps, solid tiles, O(1) id-index, background swap |
+| [`tilescroll.ts`](#tilescrollts--pixel-smooth-scrolling) | Pixel-smooth tile-map rendering at any camera position (sub-tile scroll) |
+| [`particles.ts`](#particlests--particle-pool) | Allocation-free particle pool for pixel effects: sparks, dust, puffs |
+| [`rng.ts`](#rngts--seeded-rng) | Seeded deterministic PRNG (mulberry32): int/range/float/chance/pick/shuffle/fork |
 | [`palette.ts`](#palettets--color-constants) | 15 Spectrum colors, `SpectrumColor` type, `CELL`, `SCALE` |
 | [`font.ts`](#fontts--rom-bitmap-font) | 96-character ROM font, raw bitmap access |
 | [`i18n.ts`](#i18nts--runtime-locale-selection) | Type-safe runtime locale selection for translated string packs |
@@ -2277,6 +2280,150 @@ The default language does not need its own `strings.en.ts` file. Keep the source
 
 ---
 
+## `tilescroll.ts` — Pixel-Smooth Scrolling
+
+[`tilemap.ts`](#tilemapts--tile-map-engine)'s `render(viewport)` takes a viewport in **whole tiles**, so a camera can only move in 8-pixel steps. That is perfect for grid games, but visibly steppy in a platformer where the player moves sub-pixel-smooth while jumping. `tilescroll.ts` renders the map at an **arbitrary pixel camera position** by drawing one overscan row/column and offsetting every tile by the camera remainder.
+
+Pair it with [`camera.ts`](#camerats--scrolling-camera): use `tileMapWorldSize` for the camera's `worldW` / `worldH`, then feed `cam.x` / `cam.y` straight into `drawTileMapAt`.
+
+### `tileMapWorldSize(map): { width, height }`
+
+Returns the map's full size in pixels (`cols × CELL`, `rows × CELL`) — handy for the camera's world bounds.
+
+```ts
+import { createCamera } from 'zx-kit'
+const cam = createCamera({ viewW: 256, viewH: 192, ...tileMapWorldSize(map) })
+```
+
+### `drawTileMapAt(ctx, map, camX, camY, viewW?, viewH?): void`
+
+Renders `map` with the viewport's top-left at world pixel `(camX, camY)`. The camera position is rounded to whole pixels for crisp output; off-screen and empty cells are skipped. `viewW` (default `256`) and `viewH` (default `192`) must be positive — throws otherwise. The leading/trailing partial tiles are drawn and naturally clipped by the canvas bounds, so keep the play area at the canvas origin (or render the map first) to avoid spilling under a status bar.
+
+```ts
+// game loop
+setCameraTarget(cam, player.x, player.y)
+tickCamera(cam, dt)
+drawTileMapAt(ctx, map, cam.x, cam.y)          // smooth background
+renderSprite(ctx, /* player drawn at (x - cam.x, y - cam.y) */)
+```
+
+---
+
+## `particles.ts` — Particle Pool
+
+An **allocation-free** particle pool for ZX-style pixel effects: carrot-shot sparks, landing dust, an enemy curling into a puff, glowing motes around a crystal. The pool is created once at startup with a fixed capacity; emitting and ticking never allocate, so it is safe to run every frame. Particles are plain coloured squares drawn in the Spectrum palette. Pass an `rng` for deterministic effects (replays, seeded worlds); otherwise it uses `Math.random`.
+
+### `Particle` / `ParticleSystem` interfaces
+
+```ts
+interface Particle {
+  x: number; y: number          // world pixels
+  vx: number; vy: number        // px per ms
+  life: number; maxLife: number // ms (fade with life / maxLife)
+  color: SpectrumColor
+  size: number                  // square side in px
+  active: boolean               // false slots are free for reuse
+}
+
+interface ParticleSystem {
+  readonly particles: Particle[]   // length === capacity
+  readonly capacity: number
+  activeCount: number
+}
+```
+
+### `createParticleSystem(capacity): ParticleSystem`
+
+Creates a pool of `capacity` particles, all inactive. Throws when `capacity` is not a positive integer.
+
+### `emitParticles(ps, opts): number`
+
+Emits up to `opts.count` particles and returns the number actually emitted (fewer when the pool is full). Throws when `count` is negative or non-integer.
+
+| Option | Type | Default | Meaning |
+|--------|------|---------|---------|
+| `x`, `y` | `number` | — | spawn position (world px) |
+| `count` | `number` | — | how many to emit |
+| `color` | `SpectrumColor \| SpectrumColor[]` | — | single colour, or palette to pick per particle |
+| `speed` | `number \| [min, max]` | `0.03` | px/ms |
+| `angle` | `number` | `0` | base direction in radians (`-π/2` = up) |
+| `spread` | `number` | `0` | angular jitter centred on `angle` |
+| `life` | `number \| [min, max]` | `300` | lifetime in ms |
+| `size` | `number` | `1` | square side in px |
+| `rng` | `() => number` | `Math.random` | deterministic source |
+
+```ts
+const sparks = createParticleSystem(128)
+
+// on carrot impact — a fan of yellow/white sparks shooting upward
+emitParticles(sparks, {
+  x: hit.x, y: hit.y, count: 12,
+  color: [C.B_YELLOW, C.B_WHITE],
+  speed: [0.02, 0.06], angle: -Math.PI / 2, spread: Math.PI,
+  life: [200, 400],
+})
+```
+
+### `tickParticles(ps, dtMs, gravity?): void`
+
+Advances every active particle by `dtMs`, applying optional `gravity` (px/ms², default `0`) to vertical velocity. Expired particles are deactivated and returned to the pool.
+
+### `renderParticles(ctx, ps, offsetX?, offsetY?): void`
+
+Draws every active particle as a filled square, rounding world coordinates to whole pixels. Subtract the camera world position via `offsetX` / `offsetY` to convert world → screen.
+
+### `clearParticles(ps): void`
+
+Deactivates all particles immediately (e.g. on room change).
+
+```ts
+// game loop
+tickParticles(sparks, dt, 0.0004)            // gentle gravity
+renderParticles(ctx, sparks, cam.x, cam.y)   // scrolled world
+```
+
+---
+
+## `rng.ts` — Seeded RNG
+
+A **seeded deterministic** pseudo-random generator: the same seed produces the same sequence on every machine and every run — exactly what procedural worlds need. Built on **mulberry32** (fast, allocation-free, good statistical quality for games). It is **not** cryptographically secure.
+
+The call order is part of the determinism contract: call the methods in the same order to reproduce a world.
+
+### `createRng(seed): Rng`
+
+Creates a generator from a `string` (hashed via `hashSeed`) or a finite `number` (coerced to uint32). Throws on a non-finite numeric seed.
+
+### `Rng` methods
+
+| Method | Returns | Throws when |
+|--------|---------|-------------|
+| `next()` | float `[0, 1)` | — |
+| `int(maxExclusive)` | int `[0, max)` | `max` not a positive integer |
+| `range(min, max)` | int `[min, max)` | bounds non-integer, or `max <= min` |
+| `float(min, max)` | float `[min, max)` | `max < min` |
+| `chance(p)` | boolean (`true` ~`p`) | `p` outside `[0, 1]` |
+| `pick(items)` | random element | `items` empty |
+| `shuffle(items)` | same array, shuffled in place | — |
+| `fork()` | independent `Rng` (advances parent one step) | — |
+
+```ts
+const rng = createRng('cave-level-7')
+const roomCount = rng.range(3, 7)
+const theme     = rng.pick(['spider', 'centipede', 'crystal'])
+if (rng.chance(0.15)) placeSecret()
+
+// independent sub-streams so adding enemies doesn't shift terrain layout
+const terrainRng = rng.fork()
+const enemyRng   = rng.fork()
+```
+
+### `hashSeed(seed): number`
+
+Hashes a string to an unsigned 32-bit integer (FNV-1a). Deterministic; exported for keying sub-streams by name.
+
+---
+
 ## Architecture
 
 ### Module structure
@@ -2304,9 +2451,13 @@ zx-kit/
 │   ├── ui.ts              # drawBox, drawFrame, drawPanelTitle,
 │   │                      # instrumentation widgets, progress bars
 │   ├── tilemap.ts         # createTileMap, Tile, Viewport, TileMap
+│   ├── tilescroll.ts      # drawTileMapAt, tileMapWorldSize (sub-pixel scroll)
 │   ├── sprite.ts          # createSprite, moveSprite, applyGravity,
 │   │                      # renderSprite, Sprite
 │   ├── collision.ts       # AABB, rect-vs-tile, pixel-precise masks
+│   ├── particles.ts       # createParticleSystem, emitParticles,
+│   │                      # tickParticles, renderParticles, clearParticles
+│   ├── rng.ts             # createRng, hashSeed (seeded mulberry32)
 │   ├── animation.ts       # frame timers, tweens, blinkers
 │   ├── camera.ts          # scrolling viewport, lerp, deadzone, bounds
 │   ├── scene.ts           # stack-based scene manager

package/dist/index.d.ts

@@ -6,8 +6,11 @@ export * from './audio.js';
 export * from './input.js';
 export * from './ui.js';
 export * from './tilemap.js';
+export * from './tilescroll.js';
 export * from './sprite.js';
 export * from './collision.js';
+export * from './particles.js';
+export * from './rng.js';
 export * from './animation.js';
 export * from './camera.js';
 export * from './scene.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}

package/dist/index.js

@@ -6,8 +6,11 @@ export * from './audio.js';
 export * from './input.js';
 export * from './ui.js';
 export * from './tilemap.js';
+export * from './tilescroll.js';
 export * from './sprite.js';
 export * from './collision.js';
+export * from './particles.js';
+export * from './rng.js';
 export * from './animation.js';
 export * from './camera.js';
 export * from './scene.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}

package/dist/particles.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @module particles
+ *
+ * **Allocation-free particle pool** for ZX-style pixel effects: carrot-shot
+ * sparks, landing dust, an enemy curling into a puff, glowing motes around a
+ * crystal. All particles live in a fixed-capacity pool created once at startup;
+ * emitting and ticking never allocates, so it is safe to run every frame.
+ *
+ * Particles are plain coloured squares drawn in the {@link "palette" | Spectrum
+ * palette}. For deterministic effects (replays, seeded worlds) pass an `rng`
+ * function to {@link emitParticles}; otherwise it uses `Math.random`.
+ *
+ * @example
+ * ```ts
+ * const sparks = createParticleSystem(128)
+ *
+ * // On carrot impact:
+ * emitParticles(sparks, {
+ *   x: hit.x, y: hit.y, count: 12,
+ *   color: [C.B_YELLOW, C.B_WHITE],
+ *   speed: [0.02, 0.06], angle: -Math.PI / 2, spread: Math.PI,
+ *   life: [200, 400], size: 1,
+ * })
+ *
+ * // Each frame:
+ * tickParticles(sparks, dt, 0.0004)            // gentle gravity
+ * renderParticles(ctx, sparks, cam.x, cam.y)   // world → screen offset
+ * ```
+ */
+import type { SpectrumColor } from './palette.js';
+/** A single pooled particle. `active === false` slots are free for reuse. */
+export interface Particle {
+    /** World X in pixels. */
+    x: number;
+    /** World Y in pixels. */
+    y: number;
+    /** Horizontal velocity in pixels per millisecond. */
+    vx: number;
+    /** Vertical velocity in pixels per millisecond. */
+    vy: number;
+    /** Remaining lifetime in milliseconds. */
+    life: number;
+    /** Lifetime the particle was spawned with (for fade math by the caller). */
+    maxLife: number;
+    /** Particle colour (Spectrum palette value). */
+    color: SpectrumColor;
+    /** Square side length in pixels (≥ 1). */
+    size: number;
+    /** Whether this slot is alive and should be ticked/rendered. */
+    active: boolean;
+}
+/** A fixed-capacity particle pool. Create once with {@link createParticleSystem}. */
+export interface ParticleSystem {
+    /** Backing pool. Length always equals {@link ParticleSystem.capacity}. */
+    readonly particles: Particle[];
+    /** Maximum number of simultaneously-alive particles. */
+    readonly capacity: number;
+    /** Number of currently-alive particles. */
+    activeCount: number;
+}
+/** A scalar value or an inclusive `[min, max]` range to sample uniformly. */
+export type Ranged = number | readonly [number, number];
+/** Options for a single {@link emitParticles} burst. */
+export interface EmitOptions {
+    /** Spawn X in world pixels. */
+    x: number;
+    /** Spawn Y in world pixels. */
+    y: number;
+    /** How many particles to emit (clamped to free pool slots). */
+    count: number;
+    /** Colour, or a palette to pick from per particle. */
+    color: SpectrumColor | readonly SpectrumColor[];
+    /** Speed in px/ms — scalar or `[min, max]`. Default `0.03`. */
+    speed?: Ranged;
+    /** Base emission direction in radians (0 = right, −π/2 = up). Default `0`. */
+    angle?: number;
+    /** Angular jitter in radians, centred on `angle`. Default `0` (no spread). */
+    spread?: number;
+    /** Lifetime in ms — scalar or `[min, max]`. Default `300`. */
+    life?: Ranged;
+    /** Square size in pixels. Default `1`. */
+    size?: number;
+    /** Random source for determinism. Default `Math.random`. */
+    rng?: () => number;
+}
+/**
+ * Creates a particle pool of fixed `capacity`. All slots start inactive.
+ * Throws when `capacity` is not a positive integer.
+ *
+ * @example
+ * const ps = createParticleSystem(256)
+ */
+export declare function createParticleSystem(capacity: number): ParticleSystem;
+/**
+ * Emits up to `opts.count` particles from the pool. Returns the number actually
+ * emitted — fewer than requested when the pool has no free slots left.
+ * Throws when `count` is negative or not an integer.
+ *
+ * @example
+ * const n = emitParticles(ps, { x, y, count: 10, color: C.B_WHITE })
+ */
+export declare function emitParticles(ps: ParticleSystem, opts: EmitOptions): number;
+/**
+ * Advances every active particle by `dtMs`, applying optional `gravity`
+ * (px/ms²) to vertical velocity. Particles whose lifetime expires are
+ * deactivated and returned to the pool.
+ *
+ * @param gravity - Downward acceleration in px/ms². Default `0` (no gravity).
+ *
+ * @example
+ * tickParticles(ps, dt)            // floaty
+ * tickParticles(ps, dt, 0.0006)   // falling sparks
+ */
+export declare function tickParticles(ps: ParticleSystem, dtMs: number, gravity?: number): void;
+/**
+ * Draws every active particle as a filled square. Subtract camera world
+ * position via `offsetX` / `offsetY` to convert world coords to screen coords.
+ * Coordinates are rounded to whole pixels for a crisp ZX look.
+ *
+ * @example
+ * renderParticles(ctx, ps)                 // world == screen
+ * renderParticles(ctx, ps, cam.x, cam.y)   // scrolled world
+ */
+export declare function renderParticles(ctx: CanvasRenderingContext2D, ps: ParticleSystem, offsetX?: number, offsetY?: number): void;
+/**
+ * Deactivates all particles immediately (e.g. on room change).
+ *
+ * @example
+ * clearParticles(ps)
+ */
+export declare function clearParticles(ps: ParticleSystem): void;
+//# sourceMappingURL=particles.d.ts.map

package/dist/particles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../src/particles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,yBAAyB;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAA;IACV,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAA;IACV,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf,gDAAgD;IAChD,KAAK,EAAE,aAAa,CAAA;IACpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,6EAA6E;AAC7E,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAEvD,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAA;IACT,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAA;IACT,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,KAAK,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE,CAAA;IAC/C,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAOrE;AAQD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CA6C3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,IAAI,CAcjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,wBAAwB,EAC7B,EAAE,EAAE,cAAc,EAClB,OAAO,SAAI,EACX,OAAO,SAAI,GACV,IAAI,CAQN;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAIvD"}

package/dist/particles.js

@@ -0,0 +1,138 @@
+function makeParticle() {
+    return { x: 0, y: 0, vx: 0, vy: 0, life: 0, maxLife: 0, color: '#000000', size: 1, active: false };
+}
+/**
+ * Creates a particle pool of fixed `capacity`. All slots start inactive.
+ * Throws when `capacity` is not a positive integer.
+ *
+ * @example
+ * const ps = createParticleSystem(256)
+ */
+export function createParticleSystem(capacity) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+        throw new Error(`createParticleSystem: capacity must be a positive integer, got ${capacity}`);
+    }
+    const particles = new Array(capacity);
+    for (let i = 0; i < capacity; i++)
+        particles[i] = makeParticle();
+    return { particles, capacity, activeCount: 0 };
+}
+function sampleRanged(v, fallback, rand) {
+    if (v === undefined)
+        return fallback;
+    if (typeof v === 'number')
+        return v;
+    return v[0] + rand() * (v[1] - v[0]);
+}
+/**
+ * Emits up to `opts.count` particles from the pool. Returns the number actually
+ * emitted — fewer than requested when the pool has no free slots left.
+ * Throws when `count` is negative or not an integer.
+ *
+ * @example
+ * const n = emitParticles(ps, { x, y, count: 10, color: C.B_WHITE })
+ */
+export function emitParticles(ps, opts) {
+    if (!Number.isInteger(opts.count) || opts.count < 0) {
+        throw new Error(`emitParticles: count must be a non-negative integer, got ${opts.count}`);
+    }
+    const rand = opts.rng ?? Math.random;
+    const colors = Array.isArray(opts.color)
+        ? opts.color
+        : [opts.color];
+    const angle = opts.angle ?? 0;
+    const spread = opts.spread ?? 0;
+    const size = opts.size ?? 1;
+    const pool = ps.particles;
+    let emitted = 0;
+    let cursor = 0;
+    for (let n = 0; n < opts.count; n++) {
+        // Find next free slot from where we left off.
+        let slot = -1;
+        while (cursor < ps.capacity) {
+            if (!pool[cursor].active) {
+                slot = cursor;
+                break;
+            }
+            cursor++;
+        }
+        if (slot === -1)
+            break;
+        const speed = sampleRanged(opts.speed, 0.03, rand);
+        const life = sampleRanged(opts.life, 300, rand);
+        const dir = angle + (rand() - 0.5) * spread;
+        const p = pool[slot];
+        p.x = opts.x;
+        p.y = opts.y;
+        p.vx = Math.cos(dir) * speed;
+        p.vy = Math.sin(dir) * speed;
+        p.life = life;
+        p.maxLife = life;
+        p.color = colors[Math.floor(rand() * colors.length)];
+        p.size = size;
+        p.active = true;
+        emitted++;
+        cursor++;
+    }
+    ps.activeCount += emitted;
+    return emitted;
+}
+/**
+ * Advances every active particle by `dtMs`, applying optional `gravity`
+ * (px/ms²) to vertical velocity. Particles whose lifetime expires are
+ * deactivated and returned to the pool.
+ *
+ * @param gravity - Downward acceleration in px/ms². Default `0` (no gravity).
+ *
+ * @example
+ * tickParticles(ps, dt)            // floaty
+ * tickParticles(ps, dt, 0.0006)   // falling sparks
+ */
+export function tickParticles(ps, dtMs, gravity = 0) {
+    const pool = ps.particles;
+    for (let i = 0; i < pool.length; i++) {
+        const p = pool[i];
+        if (!p.active)
+            continue;
+        p.vy += gravity * dtMs;
+        p.x += p.vx * dtMs;
+        p.y += p.vy * dtMs;
+        p.life -= dtMs;
+        if (p.life <= 0) {
+            p.active = false;
+            ps.activeCount--;
+        }
+    }
+}
+/**
+ * Draws every active particle as a filled square. Subtract camera world
+ * position via `offsetX` / `offsetY` to convert world coords to screen coords.
+ * Coordinates are rounded to whole pixels for a crisp ZX look.
+ *
+ * @example
+ * renderParticles(ctx, ps)                 // world == screen
+ * renderParticles(ctx, ps, cam.x, cam.y)   // scrolled world
+ */
+export function renderParticles(ctx, ps, offsetX = 0, offsetY = 0) {
+    const pool = ps.particles;
+    for (let i = 0; i < pool.length; i++) {
+        const p = pool[i];
+        if (!p.active)
+            continue;
+        ctx.fillStyle = p.color;
+        ctx.fillRect(Math.round(p.x - offsetX), Math.round(p.y - offsetY), p.size, p.size);
+    }
+}
+/**
+ * Deactivates all particles immediately (e.g. on room change).
+ *
+ * @example
+ * clearParticles(ps)
+ */
+export function clearParticles(ps) {
+    const pool = ps.particles;
+    for (let i = 0; i < pool.length; i++)
+        pool[i].active = false;
+    ps.activeCount = 0;
+}
+//# sourceMappingURL=particles.js.map

package/dist/particles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"particles.js","sourceRoot":"","sources":["../src/particles.ts"],"names":[],"mappings":"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"}

package/dist/rng.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module rng
+ *
+ * **Seeded deterministic pseudo-random number generator.** Same seed → same
+ * sequence, on every machine and every run — exactly what procedural world
+ * generation needs ("the same seed must create the same world").
+ *
+ * Built on **mulberry32**: a fast, allocation-free 32-bit generator with good
+ * statistical quality for games. It is *not* cryptographically secure — never
+ * use it for security tokens.
+ *
+ * @example
+ * ```ts
+ * const rng = createRng('cave-level-7')   // string or number seed
+ * rng.next()              // float in [0, 1)
+ * rng.int(8)              // int in [0, 8)
+ * rng.range(2, 6)         // int in [2, 6)
+ * rng.float(0.5, 1.5)     // float in [0.5, 1.5)
+ * rng.chance(0.25)        // true ~25% of the time
+ * rng.pick(['a','b','c']) // one element
+ * rng.shuffle([1,2,3,4])  // in-place Fisher–Yates
+ *
+ * const branch = rng.fork()  // independent deterministic sub-stream
+ * ```
+ */
+/**
+ * A seeded random source. All methods advance the same internal stream, so the
+ * order of calls is part of the determinism contract — call them in the same
+ * order to reproduce a world.
+ */
+export interface Rng {
+    /** Next float in `[0, 1)`. */
+    next(): number;
+    /** Next integer in `[0, maxExclusive)`. Throws when `maxExclusive` is not a positive integer. */
+    int(maxExclusive: number): number;
+    /** Next integer in `[minInclusive, maxExclusive)`. Throws when `maxExclusive <= minInclusive` or bounds are non-integer. */
+    range(minInclusive: number, maxExclusive: number): number;
+    /** Next float in `[min, max)`. Throws when `max < min`. */
+    float(min: number, max: number): number;
+    /** `true` with probability `p` (0–1). Throws when `p` is outside `[0, 1]`. */
+    chance(p: number): boolean;
+    /** Returns a random element of `items`. Throws when `items` is empty. */
+    pick<T>(items: readonly T[]): T;
+    /** Shuffles `items` in place (Fisher–Yates) and returns the same array. */
+    shuffle<T>(items: T[]): T[];
+    /** Derives an independent generator seeded from this stream (advances this stream by one step). */
+    fork(): Rng;
+}
+/**
+ * Hashes a string to an unsigned 32-bit integer using FNV-1a.
+ * Deterministic and dependency-free — used internally to turn string seeds
+ * into numeric state, but exported because it is handy for keying sub-streams.
+ *
+ * @example
+ * hashSeed('room:3')   // → stable uint32
+ */
+export declare function hashSeed(seed: string): number;
+/**
+ * Creates a seeded {@link Rng}. The seed may be a string (hashed via
+ * {@link hashSeed}) or a finite number (coerced to uint32).
+ *
+ * @param seed - String or finite number. Throws on a non-finite number.
+ *
+ * @example
+ * const a = createRng('alpha')
+ * const b = createRng('alpha')
+ * a.next() === b.next()   // → true (deterministic)
+ */
+export declare function createRng(seed: number | string): Rng;
+//# sourceMappingURL=rng.d.ts.map

package/dist/rng.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../src/rng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,GAAG;IAClB,8BAA8B;IAC9B,IAAI,IAAI,MAAM,CAAA;IACd,iGAAiG;IACjG,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;IACjC,4HAA4H;IAC5H,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;IACzD,2DAA2D;IAC3D,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;IACvC,8EAA8E;IAC9E,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1B,yEAAyE;IACzE,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAA;IAC/B,2EAA2E;IAC3E,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;IAC3B,mGAAmG;IACnG,IAAI,IAAI,GAAG,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,CA2EpD"}

package/dist/rng.js

@@ -0,0 +1,120 @@
+/**
+ * @module rng
+ *
+ * **Seeded deterministic pseudo-random number generator.** Same seed → same
+ * sequence, on every machine and every run — exactly what procedural world
+ * generation needs ("the same seed must create the same world").
+ *
+ * Built on **mulberry32**: a fast, allocation-free 32-bit generator with good
+ * statistical quality for games. It is *not* cryptographically secure — never
+ * use it for security tokens.
+ *
+ * @example
+ * ```ts
+ * const rng = createRng('cave-level-7')   // string or number seed
+ * rng.next()              // float in [0, 1)
+ * rng.int(8)              // int in [0, 8)
+ * rng.range(2, 6)         // int in [2, 6)
+ * rng.float(0.5, 1.5)     // float in [0.5, 1.5)
+ * rng.chance(0.25)        // true ~25% of the time
+ * rng.pick(['a','b','c']) // one element
+ * rng.shuffle([1,2,3,4])  // in-place Fisher–Yates
+ *
+ * const branch = rng.fork()  // independent deterministic sub-stream
+ * ```
+ */
+/**
+ * Hashes a string to an unsigned 32-bit integer using FNV-1a.
+ * Deterministic and dependency-free — used internally to turn string seeds
+ * into numeric state, but exported because it is handy for keying sub-streams.
+ *
+ * @example
+ * hashSeed('room:3')   // → stable uint32
+ */
+export function hashSeed(seed) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/**
+ * Creates a seeded {@link Rng}. The seed may be a string (hashed via
+ * {@link hashSeed}) or a finite number (coerced to uint32).
+ *
+ * @param seed - String or finite number. Throws on a non-finite number.
+ *
+ * @example
+ * const a = createRng('alpha')
+ * const b = createRng('alpha')
+ * a.next() === b.next()   // → true (deterministic)
+ */
+export function createRng(seed) {
+    let state;
+    if (typeof seed === 'string') {
+        state = hashSeed(seed);
+    }
+    else {
+        if (!Number.isFinite(seed)) {
+            throw new Error(`createRng: numeric seed must be finite, got ${seed}`);
+        }
+        state = seed >>> 0;
+    }
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    const rng = {
+        next,
+        int(maxExclusive) {
+            if (!Number.isInteger(maxExclusive) || maxExclusive <= 0) {
+                throw new Error(`Rng.int: maxExclusive must be a positive integer, got ${maxExclusive}`);
+            }
+            return Math.floor(next() * maxExclusive);
+        },
+        range(minInclusive, maxExclusive) {
+            if (!Number.isInteger(minInclusive) || !Number.isInteger(maxExclusive)) {
+                throw new Error(`Rng.range: bounds must be integers, got [${minInclusive}, ${maxExclusive})`);
+            }
+            if (maxExclusive <= minInclusive) {
+                throw new Error(`Rng.range: maxExclusive must be greater than minInclusive, got [${minInclusive}, ${maxExclusive})`);
+            }
+            return minInclusive + Math.floor(next() * (maxExclusive - minInclusive));
+        },
+        float(min, max) {
+            if (max < min) {
+                throw new Error(`Rng.float: max must be >= min, got [${min}, ${max})`);
+            }
+            return min + next() * (max - min);
+        },
+        chance(p) {
+            if (p < 0 || p > 1) {
+                throw new Error(`Rng.chance: probability must be in [0, 1], got ${p}`);
+            }
+            return next() < p;
+        },
+        pick(items) {
+            if (items.length === 0) {
+                throw new Error('Rng.pick: cannot pick from an empty array');
+            }
+            return items[Math.floor(next() * items.length)];
+        },
+        shuffle(items) {
+            for (let i = items.length - 1; i > 0; i--) {
+                const j = Math.floor(next() * (i + 1));
+                const tmp = items[i];
+                items[i] = items[j];
+                items[j] = tmp;
+            }
+            return items;
+        },
+        fork() {
+            return createRng((next() * 4294967296) >>> 0);
+        },
+    };
+    return rng;
+}
+//# sourceMappingURL=rng.js.map

package/dist/rng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.js","sourceRoot":"","sources":["../src/rng.ts"],"names":[],"mappings":"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"}

package/dist/tilescroll.d.ts

@@ -0,0 +1,27 @@
+import type { TileMap } from './tilemap.js';
+/**
+ * Returns the map's full size in pixels — handy for `worldW`/`worldH` when
+ * constructing a {@link "camera" | Camera}.
+ *
+ * @example
+ * const { width, height } = tileMapWorldSize(map)
+ */
+export declare function tileMapWorldSize(map: TileMap): {
+    width: number;
+    height: number;
+};
+/**
+ * Renders `map` with the viewport's top-left at world pixel `(camX, camY)`.
+ * The camera position is rounded to whole pixels for crisp output, then the
+ * visible tile range (plus one overscan row/column) is drawn at
+ * `tileX * CELL - camX`, giving smooth scrolling at any pixel offset.
+ *
+ * @param viewW - Visible width in pixels (default `256`). Must be positive.
+ * @param viewH - Visible height in pixels (default `192`). Must be positive.
+ *
+ * @example
+ * drawTileMapAt(ctx, map, cam.x, cam.y)            // standard 256×192
+ * drawTileMapAt(ctx, map, cam.x, cam.y, 256, 176)  // shorter play area
+ */
+export declare function drawTileMapAt(ctx: CanvasRenderingContext2D, map: TileMap, camX: number, camY: number, viewW?: number, viewH?: number): void;
+//# sourceMappingURL=tilescroll.d.ts.map

package/dist/tilescroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilescroll.d.ts","sourceRoot":"","sources":["../src/tilescroll.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAEhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,wBAAwB,EAC7B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,SAAM,EACX,KAAK,SAAM,GACV,IAAI,CAuBN"}

package/dist/tilescroll.js

@@ -0,0 +1,74 @@
+/**
+ * @module tilescroll
+ *
+ * **Pixel-smooth tile-map scrolling.** The built-in {@link "tilemap" |
+ * TileMap.render} takes a viewport in *whole tiles*, so a camera can only move
+ * in 8-pixel steps — fine for grid games, visibly steppy for a platformer where
+ * the player moves sub-pixel-smooth while jumping.
+ *
+ * {@link drawTileMapAt} renders the map at an arbitrary pixel camera position by
+ * drawing one extra row/column and offsetting every tile by `camX % CELL` /
+ * `camY % CELL`. Off-screen and empty cells are skipped; the leading/trailing
+ * partial tiles are drawn and naturally clipped by the canvas bounds.
+ *
+ * @example
+ * ```ts
+ * const cam = createCamera({ viewW: 256, viewH: 192, ...tileMapWorldSize(map) })
+ * // game loop:
+ * setCameraTarget(cam, player.x, player.y)
+ * tickCamera(cam, dt)
+ * drawTileMapAt(ctx, map, cam.x, cam.y)        // smooth background
+ * // …draw entities at (e.x - cam.x, e.y - cam.y)…
+ * ```
+ */
+import { CELL } from './palette.js';
+import { drawSprite } from './renderer.js';
+/**
+ * Returns the map's full size in pixels — handy for `worldW`/`worldH` when
+ * constructing a {@link "camera" | Camera}.
+ *
+ * @example
+ * const { width, height } = tileMapWorldSize(map)
+ */
+export function tileMapWorldSize(map) {
+    return { width: map.cols * CELL, height: map.rows * CELL };
+}
+/**
+ * Renders `map` with the viewport's top-left at world pixel `(camX, camY)`.
+ * The camera position is rounded to whole pixels for crisp output, then the
+ * visible tile range (plus one overscan row/column) is drawn at
+ * `tileX * CELL - camX`, giving smooth scrolling at any pixel offset.
+ *
+ * @param viewW - Visible width in pixels (default `256`). Must be positive.
+ * @param viewH - Visible height in pixels (default `192`). Must be positive.
+ *
+ * @example
+ * drawTileMapAt(ctx, map, cam.x, cam.y)            // standard 256×192
+ * drawTileMapAt(ctx, map, cam.x, cam.y, 256, 176)  // shorter play area
+ */
+export function drawTileMapAt(ctx, map, camX, camY, viewW = 256, viewH = 192) {
+    if (viewW <= 0 || viewH <= 0) {
+        throw new Error(`drawTileMapAt: viewW and viewH must be positive, got ${viewW}×${viewH}`);
+    }
+    const ox = Math.round(camX);
+    const oy = Math.round(camY);
+    const startCol = Math.floor(ox / CELL);
+    const startRow = Math.floor(oy / CELL);
+    const cols = Math.ceil(viewW / CELL) + 1;
+    const rows = Math.ceil(viewH / CELL) + 1;
+    for (let ry = 0; ry < rows; ry++) {
+        const ty = startRow + ry;
+        if (ty < 0 || ty >= map.rows)
+            continue;
+        for (let rx = 0; rx < cols; rx++) {
+            const tx = startCol + rx;
+            if (tx < 0 || tx >= map.cols)
+                continue;
+            const tile = map.getTile(tx, ty);
+            if (tile === null)
+                continue;
+            drawSprite(ctx, tile.sprite, tx * CELL - ox, ty * CELL - oy, tile.ink, tile.paper);
+        }
+    }
+}
+//# sourceMappingURL=tilescroll.js.map

package/dist/tilescroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilescroll.js","sourceRoot":"","sources":["../src/tilescroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAG1C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,EAAE,CAAA;AAC5D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,GAA6B,EAC7B,GAAY,EACZ,IAAY,EACZ,IAAY,EACZ,KAAK,GAAG,GAAG,EACX,KAAK,GAAG,GAAG;IAEX,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,wDAAwD,KAAK,IAAI,KAAK,EAAE,CAAC,CAAA;IAC3F,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAA;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAA;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;IAExC,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC;QACjC,MAAM,EAAE,GAAG,QAAQ,GAAG,EAAE,CAAA;QACxB,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI;YAAE,SAAQ;QACtC,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,QAAQ,GAAG,EAAE,CAAA;YACxB,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI;gBAAE,SAAQ;YACtC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;YAChC,IAAI,IAAI,KAAK,IAAI;gBAAE,SAAQ;YAC3B,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,IAAI,GAAG,EAAE,EAAE,EAAE,GAAG,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QACpF,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zx-kit",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/zrebec/zx-kit.git"