fix(game): repair seams in generated scrolling backgrounds (#5684)

Author: georgi

packages/image-nodes/src/nodes/game.ts

@@ -468,6 +468,38 @@ function meanEdgeDifference(
   return total / (length * 3);
 }
 
+function repairEdgeBand(
+  rgba: Buffer,
+  width: number,
+  height: number,
+  axis: "x" | "y"
+): void {
+  const extent = axis === "x" ? width : height;
+  const length = axis === "x" ? height : width;
+  const band = Math.min(Math.floor(extent / 2), Math.max(1, Math.ceil(extent * 0.1)));
+  for (let depth = 0; depth < band; depth++) {
+    const t = depth / band;
+    const weight = (1 - t * t * (3 - 2 * t)) / 2;
+    for (let i = 0; i < length; i++) {
+      const a = (axis === "x" ? i * width + depth : depth * width + i) * 4;
+      const b = (axis === "x" ? i * width + width - 1 - depth : (height - 1 - depth) * width + i) * 4;
+      // Blend premultiplied colors so invisible RGB cannot tint opaque pixels.
+      const alphaA = rgba[a + 3];
+      const alphaB = rgba[b + 3];
+      const blendedA = alphaA * (1 - weight) + alphaB * weight;
+      const blendedB = alphaB * (1 - weight) + alphaA * weight;
+      for (let c = 0; c < 3; c++) {
+        const colorA = rgba[a + c] * alphaA;
+        const colorB = rgba[b + c] * alphaB;
+        rgba[a + c] = blendedA === 0 ? 0 : Math.round((colorA * (1 - weight) + colorB * weight) / blendedA);
+        rgba[b + c] = blendedB === 0 ? 0 : Math.round((colorB * (1 - weight) + colorA * weight) / blendedB);
+      }
+      rgba[a + 3] = Math.round(blendedA);
+      rgba[b + 3] = Math.round(blendedB);
+    }
+  }
+}
+
 export class SeamlessImageNode extends BaseNode {
   static readonly nodeType = "nodetool.game.SeamlessImage";
   static readonly title = "Seamless Image";
@@ -477,7 +509,7 @@ export class SeamlessImageNode extends BaseNode {
     output: "image",
     fill: "dict"
   };
-  static readonly inlineFields = ["check_x", "check_y", "threshold"];
+  static readonly inlineFields = ["check_x", "check_y", "repair", "threshold"];
   static readonly inputFields = ["image", "slot"];
 
   @prop({
@@ -533,6 +565,15 @@ export class SeamlessImageNode extends BaseNode {
   })
   declare threshold: number;
 
+  @prop({
+    type: "bool",
+    default: false,
+    title: "Repair seams",
+    description:
+      "Blend the outer 10% on each checked axis before measuring. Preserves dimensions and the center, but softens detail near the edges."
+  })
+  declare repair: boolean;
+
   async process(context?: ProcessingContext): Promise<Record<string, unknown>> {
     const name = SeamlessImageNode.title;
     const fromSlot = slotOverrides(name, this.slot, "image");
@@ -553,11 +594,18 @@ export class SeamlessImageNode extends BaseNode {
         throw new Error(`${name}: ${SHARP_UNAVAILABLE_MESSAGE}`);
       }
       const rgba = await sharp(img.buf, { failOn: "none" })
+        .toColourspace("srgb")
         .ensureAlpha()
         .raw()
         .toBuffer();
       const { width, height } = img;
       const stride = width * 4;
+      if (this.repair) {
+        if (checkX) repairEdgeBand(rgba, width, height, "x");
+        if (checkY) repairEdgeBand(rgba, width, height, "y");
+        img.buf = await sharp(rgba, { raw: { width, height, channels: 4 } })
+          .png().toBuffer();
+      }
       if (checkX) {
         const diff = meanEdgeDifference(
           rgba,
@@ -588,12 +636,18 @@ export class SeamlessImageNode extends BaseNode {
     if (!parsed.success) {
       throw formatZodIssues(name, parsed.error);
     }
+    const stampedImage: Record<string, unknown> = stampFill(this.image, img, parsed.data);
+    if (this.repair && (checkX || checkY)) {
+      // The repaired bytes must not retain the original asset's identity.
+      stampedImage.uri = "";
+      stampedImage.asset_id = null;
+    }
     return {
       output: await persistStamped(
         context,
         name,
         parsed.data.slot_id,
-        stampFill(this.image, img, parsed.data)
+        stampedImage
       ),
       fill: parsed.data
     };

packages/image-nodes/tests/game.test.ts

@@ -243,6 +243,68 @@ describe("nodetool.game.Tileset", () => {
 });
 
 describe("nodetool.game.SeamlessImage", () => {
+  it.each([[true, false], [false, true], [true, true]])(
+    "repairs requested axes x=%s y=%s and preserves the center",
+    async (checkX, checkY) => {
+      const image = await makeImage(64, 64, (x, y) => [x * 4, y * 4, 80]);
+      const result = await runNode(".SeamlessImage", {
+        image, slot_id: "bg.space", check_x: checkX, check_y: checkY,
+        repair: true, threshold: 0
+      });
+      const output = result.output as { data: Uint8Array; uri: string; asset_id: string | null };
+      expect(output.uri).toBe("");
+      expect(output.asset_id).toBeNull();
+      const { data, info } = await sharp(output.data).ensureAlpha().raw()
+        .toBuffer({ resolveWithObject: true });
+      expect([info.width, info.height]).toEqual([64, 64]);
+      const pixel = (x: number, y: number) => [...data.subarray((y * 64 + x) * 4, (y * 64 + x) * 4 + 4)];
+      expect(pixel(32, 32)).toEqual([128, 128, 80, 255]);
+      for (let i = 0; i < 64; i++) {
+        if (checkX) expect(pixel(0, i)).toEqual(pixel(63, i));
+        if (checkY) expect(pixel(i, 0)).toEqual(pixel(i, 63));
+      }
+      expect(result.fill).toMatchObject({ seamless_x: checkX, seamless_y: checkY });
+      expect(stamped(result)).toEqual(result.fill);
+    }
+  );
+
+  it.each([[1, 1], [1, 7], [7, 1], [2, 2], [9, 11], [1920, 1080]])(
+    "repairs images sized %s by %s",
+    async (width, height) => {
+      const image = await makeImage(width, height, (x, y) => [x * 20, y * 20, 50]);
+      const result = await runNode(".SeamlessImage", {
+        image, slot_id: "bg.space", check_x: true, check_y: true,
+        repair: true, threshold: 0
+      });
+      expect(result.fill).toMatchObject({ size: [width, height], seamless_x: true, seamless_y: true });
+    }
+  );
+
+  it("does not alter artwork when neither axis requires tiling", async () => {
+    const image = await makeImage(16, 16, (x, y) => [x * 10, y * 10, 50]);
+    const result = await runNode(".SeamlessImage", {
+      image, slot_id: "title", check_x: false, check_y: false, repair: true
+    });
+    const output = result.output as { data: Uint8Array };
+    expect(Buffer.from(output.data)).toEqual(Buffer.from(image.data as string, "base64"));
+  });
+
+  it("blends transparency without leaking invisible colors into the edge", async () => {
+    const pixels = Buffer.alloc(16 * 16 * 4);
+    for (let i = 0; i < 16 * 16; i++) {
+      pixels.set(i < 128 ? [255, 0, 0, 0] : [0, 0, 255, 255], i * 4);
+    }
+    const data = await sharp(pixels, { raw: { width: 16, height: 16, channels: 4 } }).png().toBuffer();
+    const result = await runNode(".SeamlessImage", {
+      image: { type: "image", data }, slot_id: "bg.space",
+      check_x: false, check_y: true, repair: true, threshold: 0
+    });
+    const output = result.output as { data: Uint8Array };
+    const rgba = await sharp(output.data).ensureAlpha().raw().toBuffer();
+    expect([...rgba.subarray(0, 4)]).toEqual([0, 0, 255, 128]);
+    expect([...rgba.subarray(15 * 16 * 4, 15 * 16 * 4 + 4)]).toEqual([0, 0, 255, 128]);
+  });
+
   const bgFar = slot("bg.far");
   if (bgFar.kind !== "image") throw new Error("bg.far is an image");
   const [w, h] = bgFar.size;

packages/protocol/src/game-graph.ts

@@ -263,7 +263,8 @@ function checkerPropertiesFor(slot: GameSlotSpec): Record<string, unknown> {
       return {
         slot_id: slot.id,
         check_x: slot.seamless_x,
-        check_y: slot.seamless_y
+        check_y: slot.seamless_y,
+        repair: slot.seamless_x || slot.seamless_y
       };
     case "sfx":
       return { slot_id: slot.id, seconds: slot.seconds };

packages/protocol/tests/game-graph.test.ts

@@ -105,6 +105,7 @@ const SHAPES: Record<string, PlanNodeShape> = {
       { name: "slot_id", type: "str" },
       { name: "check_x", type: "bool" },
       { name: "check_y", type: "bool" },
+      { name: "repair", type: "bool" },
       { name: "threshold", type: "float" }
     ],
     outputs: [
@@ -244,6 +245,15 @@ const typesOf = (placement: WorkflowPlacement, slotId: string): string[] =>
     .map((node) => node.type);
 
 describe("gameGraphPlacement", () => {
+  it("repairs scrolling backgrounds but leaves title artwork untouched", () => {
+    const placement = gameGraphPlacement(manifestOf("shmup"), chipDesign("shmup"), choices(), lookup);
+    const checkers = placement.nodes.filter((node) => node.type === GAME_SEAMLESS_IMAGE_NODE_TYPE);
+    expect(checkers.find((node) => node.setupStepId === "bg.space")?.properties)
+      .toMatchObject({ check_x: false, check_y: true, repair: true });
+    expect(checkers.find((node) => node.setupStepId === "title")?.properties)
+      .toMatchObject({ check_x: false, check_y: false, repair: false });
+  });
+
   it("builds one chain per slot kind, with nothing left to report", () => {
     const placement = gameGraphPlacement(platformer, design, choices(), lookup);
     expect(placement.issues).toEqual([]);