@datamoc/mw_games 0.44.2 → 0.45.0

package/dist/two-d/render/PaletteRemap.js

@@ -1,217 +0,0 @@
-import { Texture } from 'pixi.js';
-function hexToRgb(hex) {
-    return [(hex >> 16) & 0xff, (hex >> 8) & 0xff, hex & 0xff];
-}
-/** a colour's brightness, as the integer average of its channels - the engine's own ruler */
-function brightnessOf(color) {
-    const [r, g, b] = hexToRgb(color);
-    return Math.floor((r + g + b) / 3);
-}
-/**
- * One channel of `ratio * a + (1 - ratio) * b`, truncated rather than rounded, because that is
- * the arithmetic a palette range's shades are defined in: rounding instead of truncating puts
- * every shade up to a whole step brighter, and the difference shows wherever art is painted
- * from the shades. No clamp goes on top of it, and none is needed: a ratio never leaves 0..1
- * and both ends are channels, so a value between them is already a channel.
- */
-function blendedChannel(a, b, ratio) {
-    return Math.trunc(ratio * a + (1 - ratio) * b);
-}
-/** `ratio` of the way from `b` to `a`, per channel, as a packed `0xRRGGBB` */
-function blend(a, b, ratio) {
-    const [ar, ag, ab] = hexToRgb(a);
-    const [br, bg, bb] = hexToRgb(b);
-    return (blendedChannel(ar, br, ratio) << 16) | (blendedChannel(ag, bg, ratio) << 8) | blendedChannel(ab, bb, ratio);
-}
-/**
- * Builds a `PaletteMapping` that recolours every entry of `reference` into a shade of the
- * `min -> mid -> max` gradient, the shape a team colour or any other `[color_range]`-style
- * remap is defined by. `reference` is the exact list of colours the art was painted with, so
- * pixels outside it - anti-aliased edges, shading, outlines - are left alone by an `'exact'`
- * remap, which is the mode this pairs with.
- *
- * The reference's *first* entry is its anchor, and it is the one colour whose shade is fixed by
- * the range alone: it becomes `mid`. Every other entry is placed by its own brightness rather
- * than by its position, so the *rest* of the list needs no order - a darker entry blends towards
- * `min` and a brighter one towards `max`, each in proportion to how its average compares with
- * the anchor's. That is what lets one mapping reproduce art as shaded as the reference it was
- * painted from, and what the first entry has to be: the base shade the art was built around.
- *
- * Brightness and the blend are computed the way the engine they mirror does, a floored integer
- * average and a truncated blend, which is what makes the shades equal the engine's byte for byte
- * rather than merely close. The engine's own black-and-white special cases fall out of the two
- * branches here rather than being spelled out: an anchor with an average of 0 has no ratio to
- * divide by, so every entry takes the brighter branch and `mid` is the top of the scale instead
- * of the middle of it, and a white anchor is at least as bright as everything, so every entry
- * takes the darker one.
- *
- * @example
- * ```ts
- * import { paletteRangeMapping, recolorTexture } from '@datamoc/mw_games/two-d/render';
- * import type { Texture2D } from '@datamoc/mw_games/two-d/render';
- *
- * declare const texture: Texture2D;
- * declare const magentaReference: readonly number[]; // the exact colours the art was painted with
- *
- * const redTeam = paletteRangeMapping(magentaReference, { min: 0x000000, mid: 0xff0000, max: 0xffffff });
- * const recolored = recolorTexture(texture, redTeam); // 'exact': only those pixels are repainted
- * ```
- */
-export function paletteRangeMapping(reference, range) {
-    const anchor = reference.length > 0 ? brightnessOf(reference[0]) : 255;
-    const to = reference.map((color) => {
-        const brightness = brightnessOf(color);
-        if (anchor !== 0 && brightness <= anchor)
-            return blend(range.mid, range.min, brightness / anchor);
-        return blend(range.mid, range.max, (255 - brightness) / (255 - anchor));
-    });
-    return { from: reference, to };
-}
-/**
- * The renderer-free core of a palette remap. In `'exact'` mode (the default) a pixel is
- * repainted only when it exactly matches one of `mapping.from`; every other pixel, including
- * one close but not identical to a `from` colour, passes through unchanged. In `'nearest'` mode
- * every opaque pixel is repainted with the `to` colour of whichever `from` entry it is nearest
- * to in RGB space. Alpha and fully transparent pixels are always left untouched. Exported on
- * its own so the remap logic is unit-testable without a canvas or a texture.
- *
- * @example
- * ```ts
- * import { remapPixels } from '@datamoc/mw_games/two-d/render';
- *
- * const pixels = new Uint8ClampedArray([255, 0, 255, 255, 10, 10, 10, 255]); // magenta, then dark grey
- * const out = remapPixels(pixels, { from: [0xff00ff], to: [0xff0000] }); // 'exact' by default
- * console.log([...out.slice(0, 4)]); // [255, 0, 0, 255] - the exact match repainted
- * console.log([...out.slice(4, 8)]); // [10, 10, 10, 255] - not a match, left alone
- * ```
- */
-export function remapPixels(pixels, mapping, mode = 'exact') {
-    const from = mapping.from.map(hexToRgb);
-    const out = new Uint8ClampedArray(pixels.length);
-    for (let index = 0; index < pixels.length; index += 4) {
-        const alpha = pixels[index + 3];
-        const r = pixels[index];
-        const g = pixels[index + 1];
-        const b = pixels[index + 2];
-        out[index] = r;
-        out[index + 1] = g;
-        out[index + 2] = b;
-        out[index + 3] = alpha;
-        if (alpha === 0 || from.length === 0)
-            continue;
-        if (mode === 'exact') {
-            const match = from.findIndex(([fr, fg, fb]) => fr === r && fg === g && fb === b);
-            if (match < 0)
-                continue;
-            const [tr, tg, tb] = hexToRgb(mapping.to[match] ?? mapping.from[match]);
-            out[index] = tr;
-            out[index + 1] = tg;
-            out[index + 2] = tb;
-            continue;
-        }
-        let nearest = 0;
-        let nearestDistance = Infinity;
-        for (let paletteIndex = 0; paletteIndex < from.length; paletteIndex += 1) {
-            const [fr, fg, fb] = from[paletteIndex];
-            const dr = r - fr;
-            const dg = g - fg;
-            const db = b - fb;
-            const distance = dr * dr + dg * dg + db * db;
-            if (distance < nearestDistance) {
-                nearestDistance = distance;
-                nearest = paletteIndex;
-            }
-        }
-        const [tr, tg, tb] = hexToRgb(mapping.to[nearest] ?? mapping.from[nearest]);
-        out[index] = tr;
-        out[index + 1] = tg;
-        out[index + 2] = tb;
-    }
-    return out;
-}
-/**
- * Opens a canvas the size of `texture`, draws it in, and hands the 2D context to `paint` to
- * make whatever further edits it needs (a palette remap, a composited overlay, a rewritten
- * alpha channel); the result becomes the returned `Texture`. Shared by every texture-level
- * image modifier (`recolorTexture` here, `~BLIT`/`~MASK`/`~BLEND` in `ImageModifiers.ts`) so
- * each one only has to write its own pixel or compositing logic, not the canvas bookkeeping.
- * Returns `texture` unchanged if there is no usable 2D canvas.
- *
- * @example
- * ```ts
- * import { withTextureCanvas } from '@datamoc/mw_games/two-d/render';
- * import type { Texture2D } from '@datamoc/mw_games/two-d/render';
- *
- * declare const texture: Texture2D;
- *
- * // a minimal custom modifier: invert every pixel's RGB, alpha untouched
- * const inverted = withTextureCanvas(texture, {}, (context, width, height) => {
- * 	const { data } = context.getImageData(0, 0, width, height);
- * 	for (let i = 0; i < data.length; i += 4) {
- * 		data[i] = 255 - data[i];
- * 		data[i + 1] = 255 - data[i + 1];
- * 		data[i + 2] = 255 - data[i + 2];
- * 	}
- * 	context.putImageData({ data, width, height }, 0, 0);
- * });
- * ```
- */
-export function withTextureCanvas(texture, probe, paint) {
-    const width = texture.width;
-    const height = texture.height;
-    if (width <= 0 || height <= 0 || !texture.source)
-        return texture;
-    const usingRealCanvas = !probe.createCanvas;
-    const canvas = probe.createCanvas?.(width, height) ??
-        (typeof document === 'undefined' ? null : document.createElement('canvas'));
-    if (!canvas)
-        return texture;
-    canvas.width = width;
-    canvas.height = height;
-    const context = canvas.getContext('2d');
-    if (!context)
-        return texture;
-    //a real `CanvasRenderingContext2D.putImageData` throws on a plain `{data,width,height}` -
-    //it needs an actual `ImageData` - so every pixel-level modifier can write the plain object
-    //`RemapCanvasContext` declares and this is the one place that makes it real
-    const paintContext = usingRealCanvas
-        ? {
-            drawImage: context.drawImage.bind(context),
-            getImageData: context.getImageData.bind(context),
-            putImageData: (imageData, dx, dy) => context.putImageData(new ImageData(new Uint8ClampedArray(imageData.data), imageData.width, imageData.height), dx, dy),
-        }
-        : context;
-    context.drawImage(texture.source.resource, 0, 0);
-    paint(paintContext, width, height);
-    return Texture.from(canvas);
-}
-/**
- * Recolours a texture by palette remap: draws it to a canvas, runs `remapPixels` over the raw
- * pixel data, and returns a new `Texture` wrapping the result. The source texture is never
- * mutated, so the same base art recolours per team without extra copies kept around by the
- * caller. Needs a real 2D canvas context (unlike `remapPixels` itself), so pass `probe` in a
- * test or host integration with no DOM; omitting it uses `document.createElement('canvas')`.
- *
- * `mode` defaults to `'exact'`, correct for a discrete swap (`~RC`/`~PAL`'s short, specific
- * `from` list); a `paletteRangeMapping` gradient, meant to cover the whole reference palette a
- * team's art is drawn against, wants `'nearest'` instead - see `PaletteRemapMode`'s own doc for
- * why the wrong choice silently recolours far more of the image than intended.
- *
- * @example
- * ```ts
- * import { paletteRangeMapping, recolorTexture } from '@datamoc/mw_games/two-d/render';
- * import type { Texture2D } from '@datamoc/mw_games/two-d/render';
- *
- * declare const texture: Texture2D;
- * const mapping = paletteRangeMapping([0xffffff, 0x808080, 0x000000], { min: 0xffe0e0, mid: 0xc00000, max: 0x400000 });
- * const redTeam = recolorTexture(texture, mapping, {}, 'nearest');
- * ```
- */
-export function recolorTexture(texture, mapping, probe = {}, mode = 'exact') {
-    return withTextureCanvas(texture, probe, (context, width, height) => {
-        const imageData = context.getImageData(0, 0, width, height);
-        const remapped = remapPixels(imageData.data, mapping, mode);
-        context.putImageData({ data: remapped, width, height }, 0, 0);
-    });
-}
-//# sourceMappingURL=PaletteRemap.js.map

package/dist/two-d/render/PaletteRemap.js.map

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

package/dist/two-d/render/Particles.d.ts

@@ -1,262 +0,0 @@
-import { Container } from 'pixi.js';
-import type { Texture2D } from './Types2D.ts';
-/**
- * One live particle. Exposed as plain readable state rather than hidden inside the emitter,
- * because that is what makes the simulation testable without a renderer at all: an emitter
- * given no `texture` runs the whole physics step and draws nothing, so a test drives
- * `update(dt)` and reads positions directly, the same split `Level` and `TileMap` already
- * draw between what a thing *is* and how it is drawn.
- */
-export interface Particle {
-    x: number;
-    y: number;
-    vx: number;
-    vy: number;
-    /** seconds since birth */
-    age: number;
-    /** seconds this particle lives for */
-    life: number;
-    rotation: number;
-    spin: number;
-    /** current interpolated values, recomputed every step from the emitter's range or curve */
-    scale: number;
-    alpha: number;
-    /** this particle's own tint, picked once at birth from the emitter's range */
-    tint: number;
-    /**
-     * Index into the emitter's `frames` for this particle's own age, or 0 without a frame
-     * sequence. Readable here for the same reason the rest of this interface is: a frame
-     * sequence is simulation state (which frame a flame is on), so a test asserts it without a
-     * renderer.
-     */
-    frame: number;
-    /** false for a pooled particle waiting to be reused */
-    active: boolean;
-}
-/** a `[min, max]` range picked per particle; a bare number means that value exactly */
-export type ParticleRange = number | readonly [number, number];
-/**
- * A value driven by a particle's own age, `t` running 0 at birth to 1 at death. What a pair
- * of endpoints cannot say: a smoke puff whose alpha falls fast and then lingers, a spark that
- * shrinks by halves, anything that curves.
- */
-export type ParticleCurve = (t: number) => number;
-/**
- * Where in the emitter's local space a particle is born. Without one every particle starts at
- * the emitter's origin, which is right for a hit spark and wrong for anything with an extent:
- * the width of a forge, the mouth of a flame column, rain across a room.
- *
- * A `rect` spreads births uniformly across `width` x `height`; an `ellipse` spreads them
- * uniformly inside it (the square-root of the radius, so they do not bunch at the centre).
- * Both are centred on the emitter and move with it, since this is local space.
- */
-export interface ParticleSpawnArea {
-    shape: 'rect' | 'ellipse';
-    /** full width of the area, in world units */
-    width: number;
-    /** full height; defaults to `width`, so a square rectangle or a circle */
-    height?: number;
-}
-export interface ParticleEmitterOptions {
-    /** drawn per particle; omit for a pure simulation that renders nothing (tests, headless) */
-    texture?: Texture2D;
-    /**
-     * A texture sequence each particle walks across its own life - the four frames of a flame,
-     * the puff of smoke - taken in preference to `texture`, whose place it takes. Chosen by the
-     * particle's age rather than the emitter's, so a burst does not flick through the frames in
-     * lockstep.
-     */
-    frames?: readonly Texture2D[];
-    /** how many particles can live at once. The pool is allocated once at this size and never grows */
-    max?: number;
-    /** particles emitted per second while `start()`ed; 0 makes the emitter burst-only */
-    rate?: number;
-    /** seconds a particle lives */
-    life?: ParticleRange;
-    /** initial speed, world units per second */
-    speed?: ParticleRange;
-    /** emission direction in radians; the default sprays in every direction */
-    angle?: ParticleRange;
-    /** constant acceleration, world units per second squared - the default falls nowhere */
-    gravity?: {
-        x: number;
-        y: number;
-    };
-    /** scale at birth and at death, interpolated across a particle's life, or a curve of it */
-    scale?: readonly [number, number] | ParticleCurve;
-    /** alpha at birth and at death, or a curve of the particle's age - see `scale` */
-    alpha?: readonly [number, number] | ParticleCurve;
-    /**
-     * A per-frame wobble on the scale, between 0 and 1: each frame every particle's scale is
-     * multiplied by a seeded draw in `[1 - flicker, 1]`, so a flame's size jumps instead of
-     * sliding. 1 lets it drop to nothing, which with a `scale` curve of `(t) => 1 - t` is a
-     * torch spark. Dropped under reduced motion, like the travel and the spin.
-     */
-    flicker?: number;
-    /** rotation change in radians per second */
-    spin?: ParticleRange;
-    /** where in local space particles are born; without one they all start at the origin */
-    spawn?: ParticleSpawnArea;
-    /**
-     * Multiplied into every particle sprite, either one colour for the whole emitter or a
-     * `[from, to]` pair each particle draws its own colour from, channel by channel - water
-     * with a depth to it rather than one flat tint. Ignored without a `texture`.
-     */
-    tint?: ParticleRange;
-}
-/** what an attached emitter follows: a display object, or a thunk reading live position */
-export type FollowTarget = Container | (() => {
-    x: number;
-    y: number;
-});
-/** options for {@link ParticleEmitter.attach} */
-export interface FollowOptions {
-    /** added to the target position on every sync */
-    offsetX?: number;
-    offsetY?: number;
-    /**
-     * Consulted on every update tick; a false return pauses emission while the target
-     * is off-screen or paused, without consumer bookkeeping. Particles already alive
-     * still finish their lives, and an explicit `burst()` always fires - the callback
-     * gates the tick, not the call.
-     */
-    enabled?: () => boolean;
-    /**
-     * Consulted on every update tick; a false return hides the emitter and every particle
-     * it has in the air, so a fog-of-war gate keeps an aura's spray out of unexplored
-     * space without the consumer re-placing `visible` every frame. Drawing only: the
-     * simulation keeps stepping behind the invisibility, emission keeps following
-     * `enabled`, and `detach()` stops consulting the hook and leaves the emitter visible.
-     */
-    visible?: () => boolean;
-}
-/**
- * A pooled particle emitter: sparks off a sword hit, dust under a footstep, rain over a map.
- *
- * Pooled rather than allocating per particle, because this is the one primitive in the
- * framework that can be asked to create and discard thousands of short-lived things per
- * second, and a garbage collector pause is exactly the frame-time cost this project's own
- * performance priority cares about. The pool is allocated once at `max` and reused forever
- * after; asking for more particles than that while `max` are already alive drops the request
- * rather than growing, so a runaway emitter degrades visibly instead of eating memory.
- *
- * Every random draw goes through `mwg/core`'s seeded `Random`, so a replayed or
- * seeded run produces the same spray, rather than particles being the one thing on screen
- * that a deterministic replay cannot reproduce.
- *
- * @example
- * ```ts
- * import { ParticleEmitter, type Texture2D } from '@datamoc/mw_games/two-d/render';
- *
- * declare const sparkTexture: Texture2D;
- *
- * const sparks = new ParticleEmitter({
- * 	texture: sparkTexture,
- * 	max: 64,
- * 	life: [0.2, 0.4],
- * 	speed: [80, 160],
- * 	gravity: { x: 0, y: 300 },
- * 	scale: [1, 0.2],
- * 	alpha: [1, 0],
- * });
- * sparks.x = 100;
- * sparks.y = 60;
- *
- * sparks.burst(12); // a sword hit: 12 particles at once, fewer if the pool is nearly full
- * sparks.update(1 / 60); // steps physics and, since a texture was given, the sprites too
- * console.log(sparks.activeCount); // 12 - still alive right after the burst
- * ```
- */
-export declare class ParticleEmitter extends Container {
-    private readonly pool;
-    private readonly sprites;
-    private readonly rate;
-    private readonly life;
-    private readonly speed;
-    private readonly angleRange;
-    private readonly gravityX;
-    private readonly gravityY;
-    private readonly scaleOf;
-    private readonly alphaOf;
-    private readonly flicker;
-    private readonly spin;
-    private readonly tintRange;
-    /** set once a burst brings its own tint, after which the sprites take each particle's */
-    private tintOverridden;
-    /** the frame sequence to walk, if one was given - `texture` is ignored in its favour */
-    private readonly frames?;
-    /** where in local space births happen, or null for a single point at the origin */
-    private readonly spawnArea;
-    private emitting;
-    private followTarget;
-    private followOffsetX;
-    private followOffsetY;
-    private followEnabled;
-    private followVisible;
-    /** where the next pool search starts, so reuse stays O(1) amortised rather than O(pool) */
-    private poolCursor;
-    /** fractional particles owed from previous frames, so a low rate still emits accurately */
-    private debt;
-    constructor(options?: ParticleEmitterOptions);
-    /** begins continuous emission at `rate` particles per second */
-    start(): void;
-    /** stops emitting; particles already alive still finish their lives */
-    stop(): void;
-    /**
-     * Follows `target`, repositioning on every update tick and every `burst()`, plus
-     * once right now so the position is fresh before the first tick. A second `attach`
-     * replaces the first; `detach()` stops following and keeps the last position. A
-     * destroyed `Container` target cannot move again, so it auto-detaches (thunk
-     * targets are read unconditionally - their liveness is the caller's).
-     *
-     * @example
-     * ```ts
-     * import { ParticleEmitter } from '@datamoc/mw_games/two-d/render';
-     *
-     * const aura = new ParticleEmitter({ rate: 20 });
-     * const hero = { x: 100, y: 200 };
-     * aura.attach(() => hero, { offsetY: -10 });
-     * aura.start();
-     * aura.update(1 / 60);
-     * aura.detach();
-     * ```
-     */
-    attach(target: FollowTarget, options?: FollowOptions): void;
-    /** stops following; the emitter keeps its last position and its emitting state */
-    detach(): void;
-    /** the current follow target, or null when detached */
-    get attachedTo(): FollowTarget | null;
-    private syncFollow;
-    private followEmissionAllowed;
-    get isEmitting(): boolean;
-    /** how many particles are alive right now */
-    get activeCount(): number;
-    /** the pool, live: a renderer or a test reads `active` particles straight off it */
-    get particles(): readonly Particle[];
-    /**
-     * Emits `count` particles at once - a hit spark, an explosion.
-     *
-     * @param at where this burst happens and what colour it is, in the emitter's parent space,
-     * instead of the emitter's own position and tint - one emitter can then throw sparks of a
-     * different colour from each broken part without being moved or duplicated.
-     * @returns how many were actually emitted, which is fewer than asked when the pool is full
-     */
-    burst(count: number, at?: {
-        x?: number;
-        y?: number;
-        tint?: number;
-    }): number;
-    private spawn;
-    /**
-     * One seeded draw for where in local space this birth happens. A point emitter draws
-     * nothing here, which is what keeps an emitter without a spawn area on exactly the random
-     * sequence it had before, so an existing seeded replay does not shift.
-     */
-    private spawnOffset;
-    update(dt: number): void;
-    /** mirrors the pool onto the sprites; a no-op for a textureless emitter */
-    private draw;
-    /** kills every live particle at once, without emitting anything further */
-    clear(): void;
-}
-//# sourceMappingURL=Particles.d.ts.map

package/dist/two-d/render/Particles.d.ts.map

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