castle-web-cli 0.4.83 → 0.4.85

package/kits/physics-2d/engine/pxartSmooth.js

@@ -0,0 +1,222 @@
+// ============================================================================
+// "Smooth" (Animal-Crossing-style) rendering for `.pxart` sprites.
+// ============================================================================
+//
+// Sprites with a file-level `cornerRadius` > 0 (see pxart.js /
+// docs/pxart-format.md) render through `renderSmoothSpriteFrame` instead of
+// the normal 1px/cell `renderSpriteFrame`.
+//
+// This is a LOCAL, per-pixel kernel filter — the same shape of algorithm as
+// Animal Crossing's actual smoothing (xBRZ-style template matching), not the
+// global boundary-trace-and-round approach this file used to implement. That
+// approach traced each region's FULL pixel-boundary loop and could detect
+// long straight/staircase runs across the whole loop; it looked fine on
+// blocky shapes but flattened organic curves it decided were "too regular",
+// which isn't fixable by tuning since the run detection itself is the
+// problem. This version never looks past a pixel's immediate 3x3
+// neighborhood, so there is no run/regularity detection to mis-fire — it
+// physically cannot flatten a curve, because it has no notion of a curve at
+// all, only of each corner in isolation.
+//
+// Approach, per source pixel P:
+//   1. Composite the frame normally (`renderSpriteFrame` — this already
+//      handles layer visibility/opacity/blend), then read back the native
+//      resolution raster. Regions are exact-RGBA-equality color runs, same as
+//      before.
+//   2. Supersample: P gets its own `scale` x `scale` block of the output
+//      canvas (plain grid subdivision — every output pixel belongs to
+//      exactly one source pixel's block, so there is no possibility of a
+//      gap or overlap between neighboring pixels' rendering).
+//   3. Fill P's whole block with its own color, then independently classify
+//      each of P's 4 corners against ONLY the 3 pixels touching that corner
+//      (2 edge-adjacent neighbors + 1 diagonal) and, for genuine convex
+//      corners, paint a `cornerRadius`-sized quarter-circle "cut" over that
+//      corner revealing the relevant neighbor's color (see `cornerFill`).
+// Because every pixel only ever paints within its OWN block, this recoloring
+// can never create a gap: it's the same guarantee a supersampled nearest-
+// neighbor render already has, just with a softened corner instead of a hard
+// one.
+//
+// Kept as a sibling of pxart.js (rather than inside it) so the format
+// parser/serializer stays focused on the on-disk shape.
+// ============================================================================
+
+import { MAX_CORNER_RADIUS, renderSpriteFrame } from './pxart';
+
+export const DEFAULT_SMOOTH_SCALE = 8;
+
+// Fallback only for a caller that omits `cornerRadius` entirely; every real
+// caller passes the sprite's own file-level `cornerRadius` value (see
+// docs/pxart-format.md and Sprite.jsx/PxArtEditor.jsx), which is how the
+// corner radius ends up being a portable, per-sprite part of the format
+// rather than a fixed constant every smooth sprite is stuck with.
+const FALLBACK_CORNER_RADIUS = 0.25;
+
+/** Render one frame of a Sprite with locally corner-rounded fills,
+ *  supersampled into `canvas` (sized to width*scale x height*scale). Reuses
+ *  `renderSpriteFrame` for compositing (layers, opacity, visibility, blend),
+ *  so those keep working unchanged. `cornerRadius` is in native-pixel units,
+ *  clamped to `MAX_CORNER_RADIUS` (two cuts on the same edge must not
+ *  overlap). */
+export function renderSmoothSpriteFrame(
+  sprite,
+  frameIndex,
+  canvas,
+  { scale = DEFAULT_SMOOTH_SCALE, cornerRadius = FALLBACK_CORNER_RADIUS } = {}
+) {
+  const clampedRadius = Math.min(MAX_CORNER_RADIUS, Math.max(0, cornerRadius));
+  const { width, height } = sprite.resolution;
+  canvas.width = Math.max(1, Math.round(width * scale));
+  canvas.height = Math.max(1, Math.round(height * scale));
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  if (width <= 0 || height <= 0) return;
+
+  const native = document.createElement('canvas');
+  renderSpriteFrame(sprite, frameIndex, native);
+  const nctx = native.getContext('2d');
+  const data = nctx?.getImageData(0, 0, width, height).data;
+  if (!data) return;
+
+  // null = out of canvas OR fully transparent; both read as "not this pixel's
+  // color" to every classification below, same as the old mask's treatment
+  // of out-of-canvas/transparent as background.
+  const colorAt = (x, y) => {
+    if (x < 0 || x >= width || y < 0 || y >= height) return null;
+    const i = (y * width + x) * 4;
+    const a = data[i + 3];
+    return a === 0 ? null : `${data[i]},${data[i + 1]},${data[i + 2]},${a}`;
+  };
+
+  ctx.save();
+  ctx.scale(scale, scale);
+  // Every pixel is processed, including transparent ones: a fully-enclosed
+  // transparent "hole" is, from its own corners' point of view, exactly the
+  // same kind of convex corner as an opaque pixel poking out of a
+  // background — it needs to cut (and round) its OWN corners the same way,
+  // or an enclosed 1px hole would stay a hard square forever (its opaque
+  // neighbors never round toward it, by the same-neighbor rule below).
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) drawPixelBlock(ctx, colorAt, x, y, colorAt(x, y), clampedRadius);
+  }
+  ctx.restore();
+}
+
+// ---------------------------------------------------------------------------
+// per-pixel local corner kernel
+// ---------------------------------------------------------------------------
+
+const NO_CUT = undefined;
+
+// Fill pixel (x, y)'s own unit square [x, x+1] x [y, y+1] with `color` (a
+// no-op when `color` is null — transparent, nothing to fill), then paint a
+// small rounded cut over each of its 4 corners that qualifies (see
+// `cornerFill`). Uses ONLY the 3x3 neighborhood of (x, y) — genuinely local,
+// unlike the old global loop trace.
+function drawPixelBlock(ctx, colorAt, x, y, color, cornerRadius) {
+  const north = colorAt(x, y - 1);
+  const south = colorAt(x, y + 1);
+  const west = colorAt(x - 1, y);
+  const east = colorAt(x + 1, y);
+
+  const cuts = [
+    ['TL', cornerFill(color, west, north, colorAt(x - 1, y - 1))],
+    ['TR', cornerFill(color, east, north, colorAt(x + 1, y - 1))],
+    ['BL', cornerFill(color, west, south, colorAt(x - 1, y + 1))],
+    ['BR', cornerFill(color, east, south, colorAt(x + 1, y + 1))],
+  ];
+
+  if (color) {
+    ctx.fillStyle = rgbaFillStyle(color);
+    ctx.fillRect(x, y, 1, 1);
+  }
+
+  if (cornerRadius <= 0) return;
+  for (const [corner, reveal] of cuts) {
+    if (reveal === NO_CUT) continue;
+    ctx.beginPath();
+    tracePixelWedge(ctx, corner, x, y, cornerRadius);
+    if (reveal === null) {
+      // Revealing transparency: clip to the wedge and clear it, rather than
+      // fill it, since there's no color to paint.
+      ctx.save();
+      ctx.clip();
+      ctx.clearRect(x, y, 1, 1);
+      ctx.restore();
+    } else {
+      ctx.fillStyle = rgbaFillStyle(reveal);
+      ctx.fill();
+    }
+  }
+}
+
+// Classify one corner of pixel `color`, given its two edge-adjacent
+// neighbors (`a`, `b`) and its diagonal neighbor (`g`). Returns the neighbor
+// color to reveal at that corner's rounded cut, or `NO_CUT` to leave the
+// corner sharp:
+//   - `a` or `b` matches `color`: either a flat/interior corner, or (when
+//     they don't BOTH match) a straight edge passing by rather than a real
+//     corner. Either way, nothing to round from P's side — a matching
+//     neighbor's OWN corner classification (evaluated independently, when
+//     IT is P) is what rounds the opposite case; the physical wedge that
+//     gets cut always lives entirely inside whichever pixel's corner is
+//     convex, so there's no double-handling.
+//   - neither `a` nor `b` matches, but `g` DOES: a diagonal touch between
+//     two same-colored pixels (the "checkerboard" case). Left uncut, so a
+//     smoothed diagonal stroke doesn't get visually pinched off at every
+//     step.
+//   - neither `a`, `b`, nor `g` matches, and `a` and `b` are THE SAME color:
+//     a genuine, unambiguous convex corner of P's own region touching one
+//     other region. Cut it, revealing that color.
+//   - neither `a`, `b`, nor `g` matches, and `a` and `b` DIFFER: three (or
+//     four, counting `g`) distinct colors meet at this exact point — e.g. a
+//     "T" where one region's straight edge is crossed by the boundary
+//     between two others. Left uncut. Rounding here would have to guess
+//     which of `a`/`b` "wins", and since the pixel on the OTHER side of
+//     that guess is classifying this same point independently — and would
+//     guess differently — a pair of pixels each revealing the OTHER's
+//     color produces a little criss-crossed notch instead of one clean
+//     curve. Leaving every pixel at a 3+-way point sharp keeps it a single
+//     consistent (if unrounded) vertex.
+function cornerFill(color, a, b, g) {
+  if (a === color || b === color) return NO_CUT;
+  if (g === color) return NO_CUT;
+  return a === b ? a : NO_CUT;
+}
+
+// `color` is always a `"r,g,b,a"` string (0-255 channels, alpha 0-255) —
+// see `colorAt` — never the transparent sentinel (only opaque colors ever
+// reach this function as `color`, only ever as `reveal`).
+function rgbaFillStyle(color) {
+  const [r, g, b, a] = color.split(',').map(Number);
+  return `rgba(${r}, ${g}, ${b}, ${a / 255})`;
+}
+
+// Trace the small corner wedge that gets cut from pixel (x, y)'s unit square
+// at `corner` (one of 'TL' | 'TR' | 'BL' | 'BR'): the sliver between the
+// exact corner point and the quarter-circle of radius `r` tangent to both
+// adjacent edges at distance `r` from the corner — i.e. exactly the piece a
+// standard rounded-rect corner removes from a sharp one. `ctx.arcTo`'s
+// corner-point-as-control-point form draws that same tangent arc without
+// hand-computed sweep angles.
+function tracePixelWedge(ctx, corner, x, y, r) {
+  if (corner === 'TL') {
+    ctx.moveTo(x, y);
+    ctx.lineTo(x + r, y);
+    ctx.arcTo(x, y, x, y + r, r);
+  } else if (corner === 'TR') {
+    ctx.moveTo(x + 1, y);
+    ctx.lineTo(x + 1, y + r);
+    ctx.arcTo(x + 1, y, x + 1 - r, y, r);
+  } else if (corner === 'BL') {
+    ctx.moveTo(x, y + 1);
+    ctx.lineTo(x, y + 1 - r);
+    ctx.arcTo(x, y + 1, x + r, y + 1, r);
+  } else {
+    ctx.moveTo(x + 1, y + 1);
+    ctx.lineTo(x + 1 - r, y + 1);
+    ctx.arcTo(x + 1, y + 1, x + 1, y + 1 - r, r);
+  }
+  ctx.closePath();
+}