castle-web-cli 0.4.113 → 0.4.115

package/kits/physics-2d/behaviors/Sound.jsx

@@ -0,0 +1,152 @@
+import { resolveDeckFile } from 'castle-web-sdk';
+import React from 'react';
+import { mediaElement, playMedia, playOneShot, setMediaPan, stopMedia } from '../engine/media';
+import { mediaFilesOfKind } from '../engine/files';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+
+// Plays a sound file (.mp3 / .wav / .m4a) from an actor.
+//
+// Two ways to use it. Set `playOnStart` and it plays when the scene starts --
+// music, ambience, a jingle on a game-over screen. Or leave it off and trigger
+// it from a behavior, through the handle this puts on the actor:
+//
+//   scene.getActor('sfx').runtime.sound.play();   // from the top
+//   await actor.runtime.sound.play();             // ...and wait for it to end
+//   actor.runtime.sound.stop();
+//
+// `play()` on a `polyphonic` sound overlaps copies instead of cutting the last
+// one off, which is what a sound effect fired twice in a row should do. Without
+// it, a second play restarts the one element, which is what music wants.
+//
+// Sound only plays during play, never in the editor: `update` is what wires the
+// element up, and the editor doesn't run it. Pressing Stop silences everything,
+// as does `scene.sound.stopAll()` (see systems/media.js).
+//
+// Browsers refuse to play audio until the player has touched the page. A sound
+// that starts before that isn't lost -- it's queued and starts on the first tap
+// or key (engine/media.js), which for a game is usually the first input anyway.
+export class Sound {
+  static behaviorName = 'Sound';
+
+  static defaultProps = {
+    file: '',
+    volume: 1,
+    playbackRate: 1,
+    pan: 0,
+    loop: false,
+    polyphonic: false,
+    playOnStart: true,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor) {
+    if (!actor.runtime || actor.runtime.collected) return;
+    const file = resolveDeckFile(this.props.file);
+    const element = mediaElement(actor.id, 'audio', file);
+    if (!element) {
+      actor.runtime.sound = null;
+      return;
+    }
+    // Props are live: turning the volume down, the pitch up, or the loop on in
+    // the inspector takes effect on the sound already playing.
+    const settings = readSettings(this.props);
+    element.volume = settings.volume;
+    element.playbackRate = settings.playbackRate;
+    element.loop = settings.loop;
+    if (settings.pan !== 0) setMediaPan(element, settings.pan);
+
+    const handle = actor.runtime.sound;
+    if (!handle || handle.file !== file) {
+      actor.runtime.sound = makeHandle(file, element, () => readSettings(this.props));
+      if (this.props.playOnStart) void actor.runtime.sound.play();
+    } else {
+      handle.settings = settings;
+    }
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="Sound" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="File"
+          value={component.file}
+          onChange={(file) => setComponent({ file })}
+          options={mediaFilesOfKind('audio')}
+          {...overrideProps(override, 'file')}
+        />
+        <AutoFields
+          defaultProps={Sound.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          only={['volume', 'playbackRate', 'pan', 'loop', 'polyphonic', 'playOnStart']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+function clamp(value, min, max, fallback) {
+  return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+
+function readSettings(props) {
+  return {
+    volume: clamp(props.volume, 0, 1, 1),
+    // The same ceiling the classic editor used: past 10x a sound is a click.
+    playbackRate: clamp(props.playbackRate, 0.01, 10, 1),
+    pan: clamp(props.pan, -1, 1, 0),
+    loop: Boolean(props.loop),
+    polyphonic: Boolean(props.polyphonic),
+  };
+}
+
+// What a behavior gets at `actor.runtime.sound`. Plain methods over the element,
+// so game code never has to know an <audio> is involved.
+//
+// `play()` returns a promise that resolves when the sound ends, so a behavior
+// can `await` one before doing the next thing. A looping sound resolves right
+// away rather than never -- awaiting something that by definition doesn't end
+// would hang the caller forever, and that is never what was meant.
+function makeHandle(file, element, currentSettings) {
+  const handle = {
+    file,
+    element,
+    settings: currentSettings(),
+    play() {
+      const s = handle.settings;
+      if (s.polyphonic) {
+        return playOneShot(file, { volume: s.volume, playbackRate: s.playbackRate, pan: s.pan });
+      }
+      try {
+        element.currentTime = 0;
+      } catch {
+        // Not seekable yet (still loading) -- it plays from the start anyway.
+      }
+      playMedia(element);
+      if (s.loop) return Promise.resolve();
+      return new Promise((resolve) => {
+        const done = () => resolve();
+        element.addEventListener('ended', done, { once: true });
+        element.addEventListener('error', done, { once: true });
+      });
+    },
+    resume() {
+      playMedia(element);
+    },
+    pause() {
+      element.pause();
+    },
+    stop() {
+      stopMedia(element);
+    },
+    get playing() {
+      return !element.paused;
+    },
+  };
+  return handle;
+}

package/kits/physics-2d/behaviors/Sprite.jsx

@@ -1,15 +1,19 @@
 import { resolveDeckFile } from 'castle-web-sdk';
 import React from 'react';
-import { frameCount, renderSpriteFrame } from '../engine/pxart';
+import { artFrameCount, isImageArt, renderArtFrame } from '../engine/art';
 import { renderSmoothSpriteFrame } from '../engine/pxartSmooth';
 import { spriteDestRect } from '../engine/spriteGeometry';
 import { Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
-import { parseTint, tintImageData } from './tint';
+import { parseTint, tintCanvas } from './tint';
 
-// Runtime behavior for the pixel-art Sprite format (.pxart). It looks up the
-// parsed Sprite from the scene's sprite map, composites the current animation
-// frame into a cached offscreen canvas (tinted), and blits it into the actor's
+// Runtime behavior for a deck's 2D art: the pixel-art `.pxart` format, or an
+// image file (png / jpg / gif / webp / svg) the deck uploaded. Both come out of
+// the scene's sprite map the same way (see engine/art.js), so everything below
+// -- draw modes, tint, tiling, the collider's auto-fit -- works on either.
+//
+// It looks up the art, composites the current animation frame into a cached
+// offscreen canvas (tinted), and blits it into the actor's
 // Layout box with smoothing disabled — unless the FILE itself opts into a
 // `cornerRadius` (a property of the .pxart asset, not a Sprite prop) greater
 // than 0, in which case the cached canvas holds a corner-rounded vector
@@ -66,15 +70,21 @@ export class Sprite {
     if (!layout) return;
     const sprite = this.resolveSprite(scene);
     if (!sprite) return;
-    const total = frameCount(sprite);
+    const total = artFrameCount(sprite);
     const frameIndex = Math.min(Math.max(actor.runtime?.spriteAnim?.frameIndex ?? 0, 0), total - 1);
     const canvas = getSpriteCanvas(sprite, frameIndex, this.props.tint);
+    if (!canvas) return;
+    // `canvas` is a <canvas> for pixel art and may be the <img> itself for an
+    // untinted image, so size comes from the art rather than the element.
+    const artSize = sprite.resolution;
     const prevSmoothing = ctx.imageSmoothingEnabled;
     // File-level `cornerRadius > 0` sprites are pre-rendered as supersampled,
     // corner-rounded vector fills (see engine/pxartSmooth.js); blit those with
     // smoothing on so downscaling to the Layout box stays antialiased. Plain
     // pixel sprites (`cornerRadius === 0`) keep nearest-neighbor blitting.
-    const smoothing = sprite.cornerRadius > 0;
+    // Image files are resampled too -- nearest neighbour is right for pixel art
+    // and wrong for a photograph.
+    const smoothing = sprite.cornerRadius > 0 || isImageArt(sprite);
 
     // Snap the destination rect to whole device pixels so tiles that abut
     // exactly in card units (e.g. adjacent 100-unit-wide tiles) land on the
@@ -94,7 +104,7 @@ export class Sprite {
     // Everything downstream (snapping, tiling's clip box) works off `dest`: the
     // Layout box itself for every mode except `fit`/`cover`, which resize to the
     // art's own aspect ratio (see `spriteDestRect`).
-    const dest = spriteDestRect(this.props.mode, layout, canvas);
+    const dest = spriteDestRect(this.props.mode, layout, artSize);
     if (transform.b === 0 && transform.c === 0) {
       const x0 = dest.x * transform.a + transform.e;
       const y0 = dest.y * transform.d + transform.f;
@@ -108,7 +118,7 @@ export class Sprite {
       ctx.setTransform(1, 0, 0, 1, 0, 0);
       ctx.imageSmoothingEnabled = smoothing;
       if (tiling) {
-        drawTilesSnapped(ctx, canvas, this.props.tileSize, dest, transform, x0, y0, rx0, ry0, rx1, ry1);
+        drawTilesSnapped(ctx, canvas, artSize, this.props.tileSize, dest, transform, x0, y0, rx0, ry0, rx1, ry1);
       } else {
         // Clip cover's overflow to the snapped Layout box (undone by restore).
         if (covering) {
@@ -126,7 +136,7 @@ export class Sprite {
     } else {
       ctx.imageSmoothingEnabled = smoothing;
       if (tiling) {
-        drawTilesUnsnapped(ctx, canvas, this.props.tileSize, dest);
+        drawTilesUnsnapped(ctx, canvas, artSize, this.props.tileSize, dest);
       } else if (covering) {
         // Rotated: clip cover's overflow to the Layout box in card units.
         ctx.save();
@@ -142,8 +152,8 @@ export class Sprite {
     }
   }
 
-  static Inspector({ component, setComponent, files, override }) {
-    const spriteFiles = getSpriteFiles(files);
+  static Inspector({ component, setComponent, sprites, override }) {
+    const spriteFiles = getSpriteFiles(sprites);
     return (
       <Panel title="Sprite" overridden={override?.anyOverridden()}>
         <SelectField
@@ -183,9 +193,9 @@ function validTileSize(value) {
 // using the same per-edge-rounding discipline as the box snap in `draw`, so
 // neighboring tiles within this actor land on identical device pixels with
 // no hairline seams.
-function drawTilesSnapped(ctx, canvas, tileSize, layout, transform, x0, y0, rx0, ry0, rx1, ry1) {
+function drawTilesSnapped(ctx, canvas, artSize, tileSize, layout, transform, x0, y0, rx0, ry0, rx1, ry1) {
   const cellHeight = validTileSize(tileSize);
-  const cellWidth = cellHeight * (canvas.width / canvas.height);
+  const cellWidth = cellHeight * (artSize.width / artSize.height);
   const cellDeviceWidth = cellWidth * transform.a;
   const cellDeviceHeight = cellHeight * transform.d;
   const cols = Math.ceil(layout.width / cellWidth);
@@ -208,9 +218,9 @@ function drawTilesSnapped(ctx, canvas, tileSize, layout, transform, x0, y0, rx0,
 
 // Rotated actors have no axis-aligned device edges to snap to, so tile
 // unsnapped in card units, matching the unsnapped stretch fallback in `draw`.
-function drawTilesUnsnapped(ctx, canvas, tileSize, layout) {
+function drawTilesUnsnapped(ctx, canvas, artSize, tileSize, layout) {
   const cellHeight = validTileSize(tileSize);
-  const cellWidth = cellHeight * (canvas.width / canvas.height);
+  const cellWidth = cellHeight * (artSize.width / artSize.height);
   const cols = Math.ceil(layout.width / cellWidth);
   const rows = Math.ceil(layout.height / cellHeight);
   ctx.save();
@@ -232,7 +242,57 @@ function drawTilesUnsnapped(ctx, canvas, tileSize, layout) {
 // new object naturally misses the WeakMap and rebuilds.
 const spriteCanvasCache = new WeakMap();
 
+// Ceiling on a cached sprite bitmap's long side. Nothing is ever rasterized
+// larger than the card itself -- 500x700 card units, times the display's pixel
+// ratio -- so this is roughly the card at 3x, and a copy bigger than it holds
+// detail that no draw can show. It only ever bites uploaded photos: `.pxart`
+// caps at 512 (RESOLUTION_MAX), and a 4000x3000 photo goes from a 46 MB cached
+// canvas to 12 MB with nothing visibly different.
+const MAX_CACHE_LONG_SIDE = 2048;
+
+// The raster this frame is drawn from, at its own natural size: the decoded
+// <img> for an image, a freshly rendered canvas for pixel art. Null while an
+// image is still downloading.
+function frameSource(sprite, frameIndex) {
+  if (isImageArt(sprite)) return sprite.ready ? sprite.image : null;
+  const canvas = document.createElement('canvas');
+  if (sprite.cornerRadius > 0) {
+    renderSmoothSpriteFrame(sprite, frameIndex, canvas, { cornerRadius: sprite.cornerRadius });
+    return canvas;
+  }
+  return renderArtFrame(sprite, frameIndex, canvas) ? canvas : null;
+}
+
+function sourceSize(source) {
+  return {
+    width: source.naturalWidth || source.width,
+    height: source.naturalHeight || source.height,
+  };
+}
+
+// `size` shrunk to fit MAX_CACHE_LONG_SIDE, keeping the aspect ratio. Returned
+// unchanged when it already fits, which is the case for everything but a large
+// uploaded image (so no pixel art is ever resampled by this).
+function cappedSize({ width, height }) {
+  const longest = Math.max(width, height);
+  if (longest <= MAX_CACHE_LONG_SIDE) return { width, height };
+  const scale = MAX_CACHE_LONG_SIDE / longest;
+  return {
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale)),
+  };
+}
+
+// The drawable source for one frame: a cached offscreen canvas, or -- for an
+// untinted image -- the decoded <img> itself, since copying it into a canvas
+// would buy nothing and cost a full-resolution bitmap. Null while an image is
+// still downloading; the caller skips the draw and picks it up next frame.
 function getSpriteCanvas(sprite, frameIndex, tint) {
+  const tintRgba = parseTint(tint);
+  if (isImageArt(sprite)) {
+    if (!sprite.ready) return null;
+    if (!tintRgba) return sprite.image;
+  }
   const key = `${frameIndex}|${tint ?? ''}`;
   let byKey = spriteCanvasCache.get(sprite);
   if (!byKey) {
@@ -242,21 +302,24 @@ function getSpriteCanvas(sprite, frameIndex, tint) {
   const cached = byKey.get(key);
   if (cached) return cached;
 
-  const canvas = document.createElement('canvas');
-  if (sprite.cornerRadius > 0) {
-    renderSmoothSpriteFrame(sprite, frameIndex, canvas, { cornerRadius: sprite.cornerRadius });
-  } else {
-    renderSpriteFrame(sprite, frameIndex, canvas);
-  }
-  const tintRgba = parseTint(tint);
-  if (tintRgba) {
-    const octx = canvas.getContext('2d');
-    if (octx && canvas.width > 0 && canvas.height > 0) {
-      const image = octx.getImageData(0, 0, canvas.width, canvas.height);
-      tintImageData(image.data, tintRgba);
-      octx.putImageData(image, 0, 0);
-    }
+  const source = frameSource(sprite, frameIndex);
+  // Nothing to render yet -- don't cache the blank.
+  if (!source) return null;
+  const natural = sourceSize(source);
+  const size = cappedSize(natural);
+  // A copy is only worth making when it changes something: a tint to apply, or
+  // a bitmap too big to keep at full size. Otherwise the render IS the cache.
+  if (!tintRgba && size.width === natural.width) {
+    byKey.set(key, source);
+    return source;
   }
+  const canvas = document.createElement('canvas');
+  canvas.width = size.width;
+  canvas.height = size.height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return null;
+  ctx.drawImage(source, 0, 0, size.width, size.height);
+  if (tintRgba) tintCanvas(canvas, source, tintRgba);
   byKey.set(key, canvas);
   return canvas;
 }
@@ -272,7 +335,7 @@ function resolveTag(sprite, tagProp) {
 // The ordered list of frame indices to step through, honoring the tag range and
 // direction. No tag => the whole timeline, forward.
 function frameSequence(sprite, tag) {
-  const total = Math.max(frameCount(sprite), 1);
+  const total = Math.max(artFrameCount(sprite), 1);
   let from = 0;
   let to = total - 1;
   let direction = 'forward';
@@ -352,6 +415,8 @@ function advanceAnim(state, sprite, sequence, tag, dt) {
   state.frameIndex = sequence[state.pos];
 }
 
-function getSpriteFiles(files) {
-  return Object.keys(files).filter((path) => path.endsWith('.pxart'));
+// Everything the deck can point a Sprite at: `.pxart` drawings and image files
+// alike, which is exactly what the resolved art map holds.
+function getSpriteFiles(sprites) {
+  return Object.keys(sprites ?? {}).sort();
 }

package/kits/physics-2d/behaviors/Tone.jsx

@@ -0,0 +1,83 @@
+import React from 'react';
+import { playTone, WAVEFORMS } from '../engine/tone';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+
+// Plays a synthesized note -- no audio file involved. This is the cheapest sound
+// a deck can make: a blip on a pickup, a thud on a miss, a rising scale as a
+// counter climbs. Nothing is downloaded and nothing is stored.
+//
+//   actor.runtime.tone.play();          // the note as configured
+//   actor.runtime.tone.play({ note: 72 });  // ...or override it per play
+//   await actor.runtime.tone.play();    // wait for the release to finish
+//
+// `note` is a MIDI number: 60 is middle C, 72 an octave up, +1 a semitone. The
+// envelope is attack (silence up to full) then release (full down to silence),
+// so the note's whole length is attack + release seconds.
+export class Tone {
+  static behaviorName = 'Tone';
+
+  static defaultProps = {
+    note: 60,
+    waveform: 'square',
+    attack: 0,
+    release: 0.3,
+    volume: 0.5,
+    pan: 0,
+    playOnStart: false,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor) {
+    if (!actor.runtime || actor.runtime.collected) return;
+    const handle = actor.runtime.tone;
+    if (!handle) {
+      actor.runtime.tone = makeHandle(() => this.props);
+      if (this.props.playOnStart) void actor.runtime.tone.play();
+    } else {
+      handle.props = this.props;
+    }
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="Tone" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="Waveform"
+          value={component.waveform}
+          onChange={(waveform) => setComponent({ waveform })}
+          options={WAVEFORMS}
+          {...overrideProps(override, 'waveform')}
+        />
+        <AutoFields
+          defaultProps={Tone.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          only={['note', 'attack', 'release', 'volume', 'pan', 'playOnStart']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+// `actor.runtime.tone`. `play(overrides)` takes the same fields as the props, so
+// one Tone actor can cover a whole scale without a component per note.
+function makeHandle(currentProps) {
+  const handle = {
+    props: currentProps(),
+    voice: null,
+    play(overrides) {
+      handle.voice = playTone({ ...handle.props, ...overrides });
+      return handle.voice.finished;
+    },
+    stop() {
+      handle.voice?.stop();
+      handle.voice = null;
+    },
+  };
+  return handle;
+}

package/kits/physics-2d/behaviors/Video.jsx

@@ -0,0 +1,111 @@
+import { resolveDeckFile } from 'castle-web-sdk';
+import React from 'react';
+import { mediaElement, playMedia, stopMedia } from '../engine/media';
+import { mediaFilesOfKind } from '../engine/files';
+import { spriteDestRect } from '../engine/spriteGeometry';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+
+// Plays a video file (.mp4 / .webm / .mov / .m4v) inside the actor's Layout box.
+//
+// The video is decoded by the browser and blitted into the scene canvas every
+// frame, so it sits in the scene like any other actor: it moves with Layout,
+// rotates, draws in `z` order, and can have a Collider. `mode` frames it in the
+// box the same way a Sprite does (cover / fit / stretch).
+//
+// In the editor it holds its first frame -- `update` is what starts playback and
+// only play mode runs it -- so you can position it against the real picture.
+// Sound is muted by default: an autoplaying video with sound is blocked by
+// browsers, and a muted one isn't.
+export class Video {
+  static behaviorName = 'Video';
+
+  static defaultProps = {
+    file: '',
+    mode: 'cover',
+    playing: true,
+    loop: true,
+    muted: true,
+    volume: 1,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  element(actor) {
+    return mediaElement(actor.id, 'video', resolveDeckFile(this.props.file));
+  }
+
+  update(actor) {
+    if (!actor.runtime || actor.runtime.collected) return;
+    const element = this.element(actor);
+    if (!element) return;
+    element.loop = Boolean(this.props.loop);
+    element.muted = Boolean(this.props.muted);
+    element.volume = Number.isFinite(this.props.volume)
+      ? Math.min(1, Math.max(0, this.props.volume))
+      : 1;
+    if (this.props.playing) playMedia(element);
+    else if (!element.paused) element.pause();
+  }
+
+  draw(actor, scene, ctx) {
+    if (actor.runtime?.collected) return;
+    const layout = actor.components.Layout;
+    if (!layout) return;
+    const element = this.element(actor);
+    // HAVE_CURRENT_DATA: there is a frame to draw. Below it the element has
+    // nothing decoded yet and drawImage would throw.
+    if (!element || element.readyState < 2) return;
+    const size = { width: element.videoWidth, height: element.videoHeight };
+    if (!size.width || !size.height) return;
+    const dest = spriteDestRect(this.props.mode, layout, size);
+    const covering = this.props.mode === 'cover';
+    if (covering) {
+      // `cover` fills the box by overflowing it; the overflow is cropped.
+      ctx.save();
+      ctx.beginPath();
+      ctx.rect(layout.x, layout.y, layout.width, layout.height);
+      ctx.clip();
+    }
+    ctx.drawImage(element, dest.x, dest.y, dest.width, dest.height);
+    if (covering) ctx.restore();
+  }
+
+  // Used by the inspector's "stop" affordance and by game code that wants the
+  // element itself (`scene.getActor('clip').components.Video` is props; this is
+  // the live element).
+  static stop(actor) {
+    const element = mediaElement(actor.id, 'video', actor.components?.Video?.file);
+    if (element) stopMedia(element);
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="Video" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="File"
+          value={component.file}
+          onChange={(file) => setComponent({ file })}
+          options={mediaFilesOfKind('video')}
+          {...overrideProps(override, 'file')}
+        />
+        <SelectField
+          label="Mode"
+          value={component.mode}
+          onChange={(mode) => setComponent({ mode })}
+          options={['stretch', 'fit', 'cover']}
+          {...overrideProps(override, 'mode')}
+        />
+        <AutoFields
+          defaultProps={Video.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          only={['playing', 'loop', 'muted', 'volume']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}

package/kits/physics-2d/behaviors/tint.js

@@ -35,13 +35,28 @@ export function applyTint(color, tint) {
   return '#' + out.map((channel) => channel.toString(16).padStart(2, '0')).join('');
 }
 
-// Multiply an ImageData buffer's RGBA channels in place by the tint (0-255).
-// Used to tint an already-rendered offscreen canvas (the Sprite path).
-export function tintImageData(data, tint) {
-  for (let i = 0; i < data.length; i += 4) {
-    data[i] = Math.round((data[i] * tint[0]) / 255);
-    data[i + 1] = Math.round((data[i + 1] * tint[1]) / 255);
-    data[i + 2] = Math.round((data[i + 2] * tint[2]) / 255);
-    data[i + 3] = Math.round((data[i + 3] * tint[3]) / 255);
-  }
+// Multiply a tint into an already-drawn canvas, using the compositor rather
+// than a pixel loop. `source` is the untinted art the canvas was drawn from
+// (an <img> or a canvas), redrawn at the end to restore the alpha channel.
+//
+// Two steps, and the second is not optional: `multiply` blends alpha as well as
+// color, so the fill lands on the transparent pixels too and the sprite comes
+// out as a solid rectangle. `destination-in` with the original puts the shape
+// back. The tint's own alpha rides in on that same pass.
+//
+// This replaced a getImageData / multiply-in-JS / putImageData round trip, which
+// costs the same on a 16x16 pixel sprite and 3-5x more on an uploaded photo --
+// the bitmap has to leave the GPU and come back. Output is byte-identical,
+// checked at both opaque and translucent tints.
+export function tintCanvas(canvas, source, tint) {
+  const ctx = canvas.getContext('2d');
+  if (!ctx || canvas.width === 0 || canvas.height === 0) return;
+  ctx.globalCompositeOperation = 'multiply';
+  ctx.fillStyle = `rgb(${tint[0]},${tint[1]},${tint[2]})`;
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  ctx.globalCompositeOperation = 'destination-in';
+  ctx.globalAlpha = tint[3] / 255;
+  ctx.drawImage(source, 0, 0, canvas.width, canvas.height);
+  ctx.globalAlpha = 1;
+  ctx.globalCompositeOperation = 'source-over';
 }