@datamoc/mw_games 0.7.6 → 0.7.8

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

@@ -1,4 +1,6 @@
 import { ColorMatrixFilter, Sprite, Texture } from 'pixi.js';
+import type { PaletteMapping, RecolorProbe } from './PaletteRemap.ts';
+import type { Texture2D } from './Types2D.ts';
 /** A parsed `image~MOD(args)` path, usable by any MWG game content format. */
 export interface ImageModifier {
     readonly name: string;
@@ -35,6 +37,52 @@ export declare function imageModifier(path: ParsedImagePath, name: string): Imag
  * ```
  */
 export declare function colorShiftMatrix(red: number, green: number, blue: number): ColorMatrixFilter['matrix'];
+/**
+ * Build the matrix for `~R`/`~G`/`~B(percent)`: scales one or more channels by a percentage
+ * (100 = unchanged), leaving any channel not passed at 100%.
+ *
+ * @example
+ * ```ts
+ * import { channelScaleMatrix } from '@datamoc/mw_games/two-d/render';
+ * const matrix = channelScaleMatrix({ red: 150 }); // ~R(150), a 50% brighter red channel
+ * console.log(matrix[0]); // 1.5
+ * ```
+ */
+export declare function channelScaleMatrix(scale: {
+    red?: number;
+    green?: number;
+    blue?: number;
+}): ColorMatrixFilter['matrix'];
+/**
+ * A live, per-frame colour-matrix approximation of a blend towards `color` (0xRRGGBB) by
+ * `ratio`, the same shape `TintedSprite.lerpTint` gives an additive-capable sprite, expressed
+ * here as a plain matrix so a bare Pixi `Sprite` can use it too. This is *not* what
+ * `applyTextureModifiers` uses for `~BLEND` itself (that bakes an exact per-pixel blend once,
+ * via `blendPixels`, rather than attaching a runtime filter) - kept as its own export for a
+ * game that wants a cheap, adjustable-at-runtime approximation instead of a baked texture, the
+ * tradeoff `~CS`'s `colorShiftMatrix` already makes for an additive shift.
+ *
+ * @example
+ * ```ts
+ * import { blendMatrix } from '@datamoc/mw_games/two-d/render';
+ * const matrix = blendMatrix(0xff0000, 0.5); // half-way to red
+ * ```
+ */
+export declare function blendMatrix(color: number, ratio: number): ColorMatrixFilter['matrix'];
+/** One `~CHAN` output-channel source: a named input channel, or a constant 0/1. */
+export type ChannelSource = 'R' | 'G' | 'B' | 'A' | '0' | '1';
+/**
+ * Build the matrix for `~CHAN(r,g,b,a)`: each output channel is fed by whichever named input
+ * channel (or constant black/white) is given for it, missing trailing entries left as the
+ * output channel's own identity source (`R,G,B,A`).
+ *
+ * @example
+ * ```ts
+ * import { channelSwapMatrix } from '@datamoc/mw_games/two-d/render';
+ * const matrix = channelSwapMatrix(['B', 'G', 'R']); // swap the red and blue channels
+ * ```
+ */
+export declare function channelSwapMatrix(sources: readonly ChannelSource[]): ColorMatrixFilter['matrix'];
 /** Apply the renderer-neutral subset supported by the Pixi backend. */
 /**
  * @example
@@ -55,4 +103,130 @@ export declare function applyImageModifiers(sprite: Sprite, parsed: ParsedImageP
  * ```
  */
 export declare function croppedTexture(texture: Texture, parsed: ParsedImagePath): Texture;
+/**
+ * `~RC(src>dst,src>dst,...)`'s pairs, each side hex (`#c0ffee`, `c0ffee`) or, when `resolve` is
+ * given, a named colour (`~RC(magenta>red)`) it resolves. A pair whose either side is neither
+ * hex nor resolvable is dropped rather than aborting the whole list.
+ *
+ * @example
+ * ```ts
+ * import { parseColorPairs, parseImagePath, imageModifier } from '@datamoc/mw_games/two-d/render';
+ *
+ * const rc = imageModifier(parseImagePath('unit.png~RC(magenta>ff0000)'), 'RC')!;
+ * const mapping = parseColorPairs(rc.args, (name) => (name === 'magenta' ? 0xff00ff : undefined));
+ * console.log(mapping); // { from: [0xff00ff], to: [0xff0000] }
+ * ```
+ */
+export declare function parseColorPairs(args: readonly string[], resolve?: (name: string) => number | undefined): PaletteMapping;
+/**
+ * `~PAL(a,b,c>x,y,z)`'s two comma-separated colour lists, one per side of a single `>`. The
+ * modifier's own args have already been comma-split by `parseImagePath` before this runs (the
+ * same naive split every modifier's argument list goes through), so `a,b,c>x,y,z` arrives as
+ * the four separate tokens `['a', 'b', 'c>x', 'y', 'z']` - rejoining them with `,` recovers the
+ * original text before this does its own split on `>` and then `,`, rather than assuming the
+ * list boundary landed on an argument boundary the way a naive `args[0]`/`args[1]` read would.
+ *
+ * @example
+ * ```ts
+ * import { parsePaletteLists, parseImagePath, imageModifier } from '@datamoc/mw_games/two-d/render';
+ *
+ * const pal = imageModifier(parseImagePath('unit.png~PAL(ff0000,00ff00>0000ff,ffff00)'), 'PAL')!;
+ * console.log(parsePaletteLists(pal.args)); // { from: [0xff0000, 0x00ff00], to: [0x0000ff, 0xffff00] }
+ * ```
+ */
+export declare function parsePaletteLists(args: readonly string[], resolve?: (name: string) => number | undefined): PaletteMapping;
+/**
+ * Resolves a nested `~BLIT`/`~MASK` image path to a texture already loaded by the caller, and
+ * (`~RC`/`~PAL`) a named colour that is not hex. `resolveTexture` receives the raw argument text
+ * exactly as written, nested modifiers included (`unit.png~RC(magenta>red)`, not stripped down
+ * to `unit.png`) - parsing and applying those is the caller's own recursive call into
+ * `parseImagePath`/`applyImageModifiers`/`applyTextureModifiers`, not something this function
+ * does on the caller's behalf, since a caller with no sibling asset resolver has nothing to
+ * recurse into anyway.
+ */
+export interface ImageTextureProbe extends RecolorProbe {
+    resolveTexture?(pathWithModifiers: string): Texture2D | undefined;
+    resolveColor?(name: string): number | undefined;
+}
+/**
+ * Applies the modifiers that need real pixel access or a sibling texture rather than a sprite
+ * property or a Pixi filter: `~RC` (exact palette swap, `src>dst` hex or named-colour pairs -
+ * see `resolveColor`/`parseColorPairs`), `~PAL` (the same swap from two comma-separated colour
+ * lists either side of one `>` - see `parsePaletteLists`), `~BLIT` (composite another image on
+ * top at an offset), `~MASK` (take alpha from another image at an offset, keeping this image's
+ * own colour), `~BLEND` (an exact per-pixel lerp towards a colour, via `blendPixels`) and
+ * `~ROTATE` (rotates the source pixels themselves and expands the surface, via `rotatePixels` -
+ * this is why `~ROTATE` lives here rather than as a sprite transform: it has to be right for
+ * terrain and anything else that must keep tiling after the rotation). `~BLIT`/`~MASK` need
+ * `probe.resolveTexture` to find the sibling image; without it they are skipped rather than
+ * treated as an error, since a caller that only wants `~RC`/`~PAL` has no sibling image to
+ * resolve. `resolveTexture` receives the argument exactly as written, nested modifiers included
+ * (`~BLIT(claws.png~FL(horiz),4,4)` calls it with `'claws.png~FL(horiz)'`, not `'claws.png'`) -
+ * parsing and applying those recursively is the caller's own job, this function composites
+ * whatever texture it is handed back.
+ *
+ * @example
+ * ```ts
+ * import { Texture } from 'pixi.js';
+ * import { applyTextureModifiers, parseImagePath } from '@datamoc/mw_games/two-d/render';
+ * const recolored = applyTextureModifiers(Texture.EMPTY, parseImagePath('unit.png~RC(ff00ff>ff0000)'));
+ * ```
+ */
+export declare function applyTextureModifiers(texture: Texture, parsed: ParsedImagePath, probe?: ImageTextureProbe): Texture;
+/**
+ * The renderer-free core of `~MASK`: `base`'s alpha channel is multiplied by `mask`'s alpha at
+ * the given offset (a pixel the mask does not cover keeps zero alpha), `base`'s own colour
+ * left untouched. Exported so the masking logic is testable without a canvas.
+ *
+ * @example
+ * ```ts
+ * import { maskPixels } from '@datamoc/mw_games/two-d/render';
+ * const base = new Uint8ClampedArray([10, 20, 30, 255]); // one opaque pixel
+ * const mask = new Uint8ClampedArray([0, 0, 0, 128]); // half-alpha mask, same 1x1 size
+ * const out = maskPixels(base, 1, 1, mask, 1, 1, 0, 0);
+ * console.log([...out]); // [10, 20, 30, 128]
+ * ```
+ */
+export declare function maskPixels(base: Uint8ClampedArray, baseWidth: number, baseHeight: number, mask: Uint8ClampedArray, maskWidth: number, maskHeight: number, offsetX: number, offsetY: number): Uint8ClampedArray;
+/**
+ * The renderer-free core of `~BLEND`: every pixel's RGB is lerped `ratio` of the way towards
+ * `color` (0xRRGGBB), an exact per-pixel blend rather than `blendMatrix`'s runtime
+ * approximation - this is what `applyTextureModifiers` bakes into the texture once. Alpha is
+ * untouched; a fully transparent pixel is skipped entirely, matching `remapPixels`.
+ *
+ * @example
+ * ```ts
+ * import { blendPixels } from '@datamoc/mw_games/two-d/render';
+ *
+ * const pixels = new Uint8ClampedArray([0, 0, 0, 255]); // one opaque black pixel
+ * const out = blendPixels(pixels, 0xff0000, 0.5);
+ * console.log([...out]); // [128, 0, 0, 255] - half-way to red
+ * ```
+ */
+export declare function blendPixels(pixels: Uint8ClampedArray, color: number, ratio: number): Uint8ClampedArray;
+export interface RotatedPixels {
+    readonly data: Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * The renderer-free core of `~ROTATE`: rotates the source pixels themselves by `degrees`
+ * (clockwise) around their centre and expands the surface to fit the rotated bounds, rather
+ * than turning a sprite's own transform - `applyImageModifiers`'s `sprite.rotation` leaves the
+ * art unrotated and does not grow the surface, which is wrong for terrain and anything else
+ * that has to keep tiling after the rotation. A destination pixel outside the source once
+ * rotated back is fully transparent. Sampling is nearest-neighbour, so an exact multiple of 90
+ * degrees round-trips pixel-for-pixel; other angles show the aliasing any nearest-neighbour
+ * rotation does.
+ *
+ * @example
+ * ```ts
+ * import { rotatePixels } from '@datamoc/mw_games/two-d/render';
+ *
+ * const pixels = new Uint8ClampedArray([255, 0, 0, 255, 0, 255, 0, 255]); // 2x1: red, green
+ * const rotated = rotatePixels(pixels, 2, 1, 90);
+ * console.log(rotated.width, rotated.height); // 1, 2 - the surface expanded to fit
+ * ```
+ */
+export declare function rotatePixels(pixels: Uint8ClampedArray, width: number, height: number, degrees: number): RotatedPixels;
 //# sourceMappingURL=ImageModifiers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ImageModifiers.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/ImageModifiers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAa,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAyB7D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAuBtG;AAED,uEAAuE;AACvE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,SAAI,GAAG,IAAI,CA0B5F;AAED,sEAAsE;AACtE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAYjF"}
+{"version":3,"file":"ImageModifiers.d.ts","sourceRoot":"","sources":["../../../src/two-d/render/ImageModifiers.ts"],"names":[],"mappings":"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"}