zx-kit 0.9.2 → 0.11.0

package/dist/animation.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Time-based easing curve. Maps progress `t` (0..1) to eased value (typically 0..1).
+ * Pass to `createTween` via the `ease` option.
+ */
+export type Easing = (t: number) => number;
+/**
+ * Built-in easing curves for `Tween`. Pass to `createTween({ ease: Easings.easeOut })`.
+ * Roll your own by writing any `(t: number) => number` function.
+ */
+export declare const Easings: {
+    /** Constant velocity. */
+    readonly linear: Easing;
+    /** Slow start, fast end (quadratic in). */
+    readonly easeIn: Easing;
+    /** Fast start, slow end (quadratic out). */
+    readonly easeOut: Easing;
+};
+/**
+ * A frame-index timer for sprite-strip animations.
+ * Holds no bitmaps — just counts time and reports which frame index should be shown.
+ * Use the index to look up your own sprite table (lets one timer drive multi-direction
+ * sprites: `SPRITES[playerDir][tickAnimation(walkAnim, dt)]`).
+ */
+export interface Animation {
+    /** Number of frames in the cycle. */
+    frameCount: number;
+    /** Duration of each frame in milliseconds. */
+    frameMs: number;
+    /** When `true` the animation wraps; when `false` it stops on the last frame. */
+    loop: boolean;
+    /** Internal: accumulated time since last reset. */
+    elapsed: number;
+    /** `true` once a non-looping animation has reached its last frame. */
+    done: boolean;
+    /** Optional callback fired exactly once when a non-looping animation completes. */
+    onComplete?: () => void;
+}
+/**
+ * Creates an `Animation` frame timer at frame 0.
+ *
+ * @param frameCount - Number of distinct frames (e.g. `2` for a walk cycle, `4` for an explosion)
+ * @param frameMs    - Milliseconds per frame
+ * @param opts.loop  - When `true` (default) the animation wraps; when `false` it stops on the last frame
+ * @param opts.onComplete - Fired exactly once when a non-looping animation reaches its last frame
+ *
+ * @example
+ * const walkAnim = createAnimation(2, 60)                          // looping 2-frame cycle
+ * const explosion = createAnimation(4, 50, { loop: false,
+ *   onComplete: () => state.phase = 'gameover' })
+ */
+export declare function createAnimation(frameCount: number, frameMs: number, opts?: {
+    loop?: boolean;
+    onComplete?: () => void;
+}): Animation;
+/**
+ * Advances the animation by `dt` milliseconds and returns the current frame index (`0..frameCount-1`).
+ * Call once per frame. For non-looping animations, fires `onComplete` once on completion.
+ *
+ * @param anim - Animation to tick
+ * @param dt   - Frame delta in milliseconds
+ * @returns Current frame index — use to look up your sprite bitmap
+ *
+ * @example
+ * const idx = tickAnimation(walkAnim, dt)
+ * const sprite = PLAYER_FRAMES[playerDir][idx]
+ * drawSprite(ctx, sprite, x, y, C.B_WHITE, C.BLACK)
+ */
+export declare function tickAnimation(anim: Animation, dt: number): number;
+/**
+ * Returns the current frame index without advancing time.
+ * Useful when reading the index outside the tick (e.g. inside a renderer).
+ */
+export declare function getAnimationFrame(anim: Animation): number;
+/**
+ * Resets the animation to frame 0 and clears `done`.
+ * Call before re-using a non-looping animation, or to restart a loop from the beginning.
+ */
+export declare function resetAnimation(anim: Animation): void;
+/**
+ * A time-based linear interpolation between two 2D points.
+ * Use to slide a sprite from one cell to another, drop a mine in an arc (with `easeIn`),
+ * or animate any pair of pixel coordinates.
+ *
+ * Read `tween.x` / `tween.y` after `tickTween` to draw at the current position.
+ */
+export interface Tween {
+    /** Starting X in game pixels. */
+    fromX: number;
+    /** Starting Y in game pixels. */
+    fromY: number;
+    /** Ending X in game pixels. */
+    toX: number;
+    /** Ending Y in game pixels. */
+    toY: number;
+    /** Total duration in milliseconds. */
+    durationMs: number;
+    /** Internal: time elapsed since creation. */
+    elapsed: number;
+    /** Current interpolated X — updated each `tickTween`. */
+    x: number;
+    /** Current interpolated Y — updated each `tickTween`. */
+    y: number;
+    /** Easing curve mapping linear progress `t` to eased value. */
+    ease: Easing;
+    /** `true` once the tween has reached its end. */
+    done: boolean;
+    /** Optional callback fired exactly once on completion. */
+    onComplete?: () => void;
+}
+/**
+ * Creates a `Tween` from `(fromX, fromY)` to `(toX, toY)` over `durationMs`.
+ * Initial `x`/`y` are set to the starting point.
+ *
+ * @param fromX, fromY - Starting position in game pixels
+ * @param toX, toY     - Ending position in game pixels
+ * @param durationMs   - Total duration in milliseconds
+ * @param opts.ease    - Easing curve (default `Easings.linear`)
+ * @param opts.onComplete - Fired exactly once when the tween reaches its end
+ *
+ * @example
+ * // Slide player from one cell to the next over 120ms
+ * state.walkTween = createTween(
+ *   state.playerCol * 8, state.playerRow * 8,
+ *   newCol * 8, newRow * 8,
+ *   120,
+ *   { onComplete: () => commitMove(state) },
+ * )
+ */
+export declare function createTween(fromX: number, fromY: number, toX: number, toY: number, durationMs: number, opts?: {
+    ease?: Easing;
+    onComplete?: () => void;
+}): Tween;
+/**
+ * Advances the tween by `dt` milliseconds and updates `tween.x` / `tween.y`.
+ * Returns `true` once the tween has finished (also fires `onComplete` exactly once).
+ * Subsequent calls after completion are no-ops and return `true`.
+ *
+ * @param tween - Tween to advance
+ * @param dt    - Frame delta in milliseconds
+ * @returns `true` when the tween has reached its end this frame or earlier
+ *
+ * @example
+ * if (state.walkTween) {
+ *   tickTween(state.walkTween, dt)
+ *   // renderer reads state.walkTween.x / .y
+ * }
+ */
+export declare function tickTween(tween: Tween, dt: number): boolean;
+//# sourceMappingURL=animation.d.ts.map

package/dist/animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.d.ts","sourceRoot":"","sources":["../src/animation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AAE1C;;;GAGG;AACH,eAAO,MAAM,OAAO;IAClB,yBAAyB;qBACH,MAAM;IAC5B,2CAA2C;qBACjB,MAAM;IAChC,4CAA4C;sBACD,MAAM;CACzC,CAAA;AAIV;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,IAAI,EAAE,OAAO,CAAA;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAA;IACb,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GACrD,SAAS,CASX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAWjE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAKzD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAGpD;AAID;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAA;IACT,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAA;IACT,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,IAAI,EAAE,OAAO,CAAA;IACb,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAC5B,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GACpD,KAAK,CASP;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAc3D"}

package/dist/animation.js

@@ -0,0 +1,141 @@
+/**
+ * Built-in easing curves for `Tween`. Pass to `createTween({ ease: Easings.easeOut })`.
+ * Roll your own by writing any `(t: number) => number` function.
+ */
+export const Easings = {
+    /** Constant velocity. */
+    linear: ((t) => t),
+    /** Slow start, fast end (quadratic in). */
+    easeIn: ((t) => t * t),
+    /** Fast start, slow end (quadratic out). */
+    easeOut: ((t) => 1 - (1 - t) * (1 - t)),
+};
+/**
+ * Creates an `Animation` frame timer at frame 0.
+ *
+ * @param frameCount - Number of distinct frames (e.g. `2` for a walk cycle, `4` for an explosion)
+ * @param frameMs    - Milliseconds per frame
+ * @param opts.loop  - When `true` (default) the animation wraps; when `false` it stops on the last frame
+ * @param opts.onComplete - Fired exactly once when a non-looping animation reaches its last frame
+ *
+ * @example
+ * const walkAnim = createAnimation(2, 60)                          // looping 2-frame cycle
+ * const explosion = createAnimation(4, 50, { loop: false,
+ *   onComplete: () => state.phase = 'gameover' })
+ */
+export function createAnimation(frameCount, frameMs, opts = {}) {
+    return {
+        frameCount,
+        frameMs,
+        loop: opts.loop ?? true,
+        elapsed: 0,
+        done: false,
+        onComplete: opts.onComplete,
+    };
+}
+/**
+ * Advances the animation by `dt` milliseconds and returns the current frame index (`0..frameCount-1`).
+ * Call once per frame. For non-looping animations, fires `onComplete` once on completion.
+ *
+ * @param anim - Animation to tick
+ * @param dt   - Frame delta in milliseconds
+ * @returns Current frame index — use to look up your sprite bitmap
+ *
+ * @example
+ * const idx = tickAnimation(walkAnim, dt)
+ * const sprite = PLAYER_FRAMES[playerDir][idx]
+ * drawSprite(ctx, sprite, x, y, C.B_WHITE, C.BLACK)
+ */
+export function tickAnimation(anim, dt) {
+    if (anim.done)
+        return anim.frameCount - 1;
+    anim.elapsed += dt;
+    const totalMs = anim.frameCount * anim.frameMs;
+    if (!anim.loop && anim.elapsed >= totalMs) {
+        anim.done = true;
+        anim.onComplete?.();
+        return anim.frameCount - 1;
+    }
+    const t = anim.loop ? anim.elapsed % totalMs : anim.elapsed;
+    return Math.min(anim.frameCount - 1, Math.floor(t / anim.frameMs));
+}
+/**
+ * Returns the current frame index without advancing time.
+ * Useful when reading the index outside the tick (e.g. inside a renderer).
+ */
+export function getAnimationFrame(anim) {
+    if (anim.done)
+        return anim.frameCount - 1;
+    const totalMs = anim.frameCount * anim.frameMs;
+    const t = anim.loop ? anim.elapsed % totalMs : Math.min(anim.elapsed, totalMs);
+    return Math.min(anim.frameCount - 1, Math.floor(t / anim.frameMs));
+}
+/**
+ * Resets the animation to frame 0 and clears `done`.
+ * Call before re-using a non-looping animation, or to restart a loop from the beginning.
+ */
+export function resetAnimation(anim) {
+    anim.elapsed = 0;
+    anim.done = false;
+}
+/**
+ * Creates a `Tween` from `(fromX, fromY)` to `(toX, toY)` over `durationMs`.
+ * Initial `x`/`y` are set to the starting point.
+ *
+ * @param fromX, fromY - Starting position in game pixels
+ * @param toX, toY     - Ending position in game pixels
+ * @param durationMs   - Total duration in milliseconds
+ * @param opts.ease    - Easing curve (default `Easings.linear`)
+ * @param opts.onComplete - Fired exactly once when the tween reaches its end
+ *
+ * @example
+ * // Slide player from one cell to the next over 120ms
+ * state.walkTween = createTween(
+ *   state.playerCol * 8, state.playerRow * 8,
+ *   newCol * 8, newRow * 8,
+ *   120,
+ *   { onComplete: () => commitMove(state) },
+ * )
+ */
+export function createTween(fromX, fromY, toX, toY, durationMs, opts = {}) {
+    return {
+        fromX, fromY, toX, toY, durationMs,
+        elapsed: 0,
+        x: fromX, y: fromY,
+        ease: opts.ease ?? Easings.linear,
+        done: false,
+        onComplete: opts.onComplete,
+    };
+}
+/**
+ * Advances the tween by `dt` milliseconds and updates `tween.x` / `tween.y`.
+ * Returns `true` once the tween has finished (also fires `onComplete` exactly once).
+ * Subsequent calls after completion are no-ops and return `true`.
+ *
+ * @param tween - Tween to advance
+ * @param dt    - Frame delta in milliseconds
+ * @returns `true` when the tween has reached its end this frame or earlier
+ *
+ * @example
+ * if (state.walkTween) {
+ *   tickTween(state.walkTween, dt)
+ *   // renderer reads state.walkTween.x / .y
+ * }
+ */
+export function tickTween(tween, dt) {
+    if (tween.done)
+        return true;
+    tween.elapsed += dt;
+    const t = Math.min(1, tween.elapsed / tween.durationMs);
+    const eased = tween.ease(t);
+    tween.x = tween.fromX + (tween.toX - tween.fromX) * eased;
+    tween.y = tween.fromY + (tween.toY - tween.fromY) * eased;
+    if (t >= 1) {
+        tween.done = true;
+        tween.x = tween.toX;
+        tween.y = tween.toY;
+        tween.onComplete?.();
+    }
+    return tween.done;
+}
+//# sourceMappingURL=animation.js.map

package/dist/animation.js.map

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

package/dist/ay.d.ts

@@ -0,0 +1,89 @@
+/** ZX Spectrum 128K / Melodik AY-3-8912 master clock. */
+export declare const AY_CLOCK = 1773400;
+/**
+ * Hardware-accurate logarithmic amplitude table.
+ * The real chip uses ≈ √2 steps per level (≈ 3 dB).
+ * Index 0 = silence, index 15 = full amplitude.
+ */
+export declare const AY_VOL: readonly number[];
+export type AYChannel = 'A' | 'B' | 'C';
+/** One note in an AY sequencer pattern. */
+export interface AYNote {
+    /** Frequency in Hz. 0 = rest (silence). */
+    freq: number;
+    /** Duration in milliseconds. */
+    dur: number;
+    /** Amplitude 0–15.  Default 15.  Ignored when envShape is set. */
+    vol?: number;
+    /** Mix LFSR noise alongside the tone. Default false. */
+    noise?: boolean;
+    /** Noise period 1–31 (maps to R6). Higher = darker texture. Default 8. */
+    noisePeriod?: number;
+    /** Envelope shape 0–15 (R13). When set, vol is ignored. */
+    envShape?: number;
+    /** Envelope cycle duration in ms (one ramp: 0→15 or 15→0). Default = note duration. */
+    envCycleDurMs?: number;
+}
+/** Real-time AY chip handle returned by `createAY()`. */
+export interface AYChip {
+    /** Set channel tone + volume (vol 0–15). freq ≤ 0 silences the tone generator. */
+    tone(ch: AYChannel, freq: number, vol?: number): void;
+    /** Enable LFSR noise on a channel.  period 1–31 (R6): higher = darker texture. */
+    enableNoise(ch: AYChannel, period?: number): void;
+    /** Disable noise on a channel. */
+    disableNoise(ch: AYChannel): void;
+    /**
+     * Apply an AY envelope to a channel's amplitude.
+     * shape 0–15 maps to the 16 AY-3-8912 envelope shapes (see `AY_ENVELOPE_SHAPES`).
+     * cycleDurMs: time in ms for one ramp (15→0 or 0→15).
+     * Repeating shapes are pre-scheduled for 32 cycles — call again to extend.
+     */
+    envelope(ch: AYChannel, shape: number, cycleDurMs: number): void;
+    /** Fade out a channel (tone + noise). */
+    mute(ch: AYChannel): void;
+    /** Fade out all three channels. */
+    muteAll(): void;
+    /** Stop all oscillators / sources and release Web Audio nodes. */
+    stop(): void;
+}
+/**
+ * Human-readable names for the 16 AY envelope shapes.
+ * Index = R13 value.  Useful for documentation and tooling.
+ */
+export declare const AY_ENVELOPE_SHAPES: readonly ["\\_ ", "\\_ ", "\\_ ", "\\_ ", "/_ ", "/_ ", "/_ ", "/_ ", "\\\\", "\\_", "\\/\\/", "\\‾", "//", "/‾", "/\\/\\", "/_"];
+/**
+ * Creates three persistent AY channels wired to the zx-kit master gain.
+ * Each channel has independent tone (square wave), noise (LFSR), and envelope.
+ *
+ * Must be called inside a user-gesture handler due to browser autoplay policy.
+ *
+ * @example
+ * button.addEventListener('click', () => {
+ *   const ay = createAY()
+ *   ay.tone('A', 440, 12)
+ *   ay.enableNoise('B', 16)
+ *   ay.envelope('C', 10, 400)  // shape 10 = \/\/ triangle
+ *   ay.tone('C', 220, 0)       // tone silent; only envelope-modulated noise
+ * })
+ */
+export declare function createAY(): AYChip;
+/**
+ * Pre-schedules up to three independent AY note arrays on the shared AudioContext.
+ * All channels start at the same wall-clock time; shorter channels finish earlier.
+ * Fire-and-forget — no handle returned.
+ *
+ * Each `AYNote` may optionally mix in LFSR noise and/or apply an envelope shape.
+ *
+ * @example
+ * playAY({
+ *   a: [{ freq: 440, dur: 300 }, { freq: 523, dur: 300, envShape: 12, envCycleDurMs: 150 }],
+ *   b: [{ freq: 110, dur: 200, noise: true, noisePeriod: 16 }],
+ *   c: [{ freq: 0,   dur: 600, noise: true, noisePeriod: 4, envShape: 8, envCycleDurMs: 100 }],
+ * })
+ */
+export declare function playAY(pattern: {
+    a?: AYNote[];
+    b?: AYNote[];
+    c?: AYNote[];
+}, startDelay?: number): void;
+//# sourceMappingURL=ay.d.ts.map

package/dist/ay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ay.d.ts","sourceRoot":"","sources":["../src/ay.ts"],"names":[],"mappings":"AAIA,yDAAyD;AACzD,eAAO,MAAM,QAAQ,UAAY,CAAA;AAEjC;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EAGnC,CAAA;AAWD,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;AAEvC,2CAA2C;AAC3C,MAAM,WAAW,MAAM;IACrB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,MAAM;IACrB,kFAAkF;IAClF,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrD,kFAAkF;IAClF,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjD,kCAAkC;IAClC,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAChE,yCAAyC;IACzC,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAA;IACzB,mCAAmC;IACnC,OAAO,IAAI,IAAI,CAAA;IACf,kEAAkE;IAClE,IAAI,IAAI,IAAI,CAAA;CACb;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,mIAWrB,CAAA;AAwFV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CA6GjC;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EACrD,UAAU,SAAI,GACb,IAAI,CA+EN"}