refactor(voxel-renderer): implement inverted shape using rotation flipY (#235)

Author: fraxken

.changeset/eleven-tires-doubt.md

@@ -0,0 +1,5 @@
+---
+"@jolly-pixel/voxel.renderer": minor
+---
+
+Implement inverted shape using flipY rotatation

packages/voxel-renderer/docs/Blocks.md

@@ -50,17 +50,11 @@ type BlockShapeID =
   | "poleZ"
   | "poleCross"
   | "ramp"
-  | "rampFlip"
   | "rampCornerInner"
   | "rampCornerOuter"
-  | "rampCornerInnerFlip"
-  | "rampCornerOuterFlip"
   | "stair"
   | "stairCornerInner"
   | "stairCornerOuter"
-  | "stairFlip"
-  | "stairCornerInnerFlip"
-  | "stairCornerOuterFlip"
   | (string & {}); // custom shapes registered at runtime
 ```
 

packages/voxel-renderer/docs/BuiltInShapes.md

@@ -49,11 +49,8 @@ All ramp shapes use **collisionHint**: [trimesh](./Collision.md).
 | Shape ID | Occludes |
 |---:|---|
 | `ramp` | `-Y`, `+Z` |
-| `rampFlip` | `+Y`, `-Y`, `+Z` |
 | `rampCornerInner` | `-Y`, `+Z`, `+X` |
 | `rampCornerOuter` | `-Y` |
-| `rampCornerInnerFlip` | `+Y`, `+Z`, `+X` |
-| `rampCornerOuterFlip` | `+Y` |
 
 ### Stairs
 
@@ -64,9 +61,32 @@ All stair shapes use **collisionHint**: [trimesh](./Collision.md).
 | `stair` | `-Y`, `+Z` |
 | `stairCornerInner` | `-Y`, `+Z`, `+X` |
 | `stairCornerOuter` | `-Y` |
-| `stairFlip` | `+Y`, `+Z` |
-| `stairCornerInnerFlip` | `+Y`, `+Z`, `+X` |
-| `stairCornerOuterFlip` | `+Y` |
+
+### Inverted / Upside-Down Shapes (`flipY`)
+
+Ceiling ramps, inverted stairs, and similar shapes are produced by setting `flipY: true`
+on any voxel rather than using a dedicated shape class. `flipY` mirrors the block geometry
+around `y = 0.5`, reverses face winding to preserve correct lighting, and swaps
+the `+Y`/`-Y` occlusion directions so face culling against neighbours remains accurate.
+
+```ts
+// Ceiling ramp — same geometry as "ramp" but mounted upside-down
+vr.setVoxel("Ceiling", {
+  position: { x: 2, y: 4, z: 0 },
+  blockId: myRampBlock,
+  flipY: true
+});
+
+// Inverted inner-corner stair
+vr.setVoxel("Ceiling", {
+  position: { x: 3, y: 4, z: 0 },
+  blockId: myStairBlock,
+  rotation: VoxelRotation.CW90,
+  flipY: true
+});
+```
+
+`flipY` can be combined freely with `rotation`, `flipX`, and `flipZ`.
 
 ---
 

packages/voxel-renderer/docs/VoxelRenderer.md

@@ -10,7 +10,7 @@ const vr = actor.addComponentAndGet(VoxelRenderer, {
     {
       id: 1,
       name: "Grass",
-      shapeId: "fullCube",
+      shapeId: "cube",
       collidable: true,
       faceTextures: {},
       defaultTexture: {
@@ -40,6 +40,12 @@ vr.setVoxel("Ground", {
   flipZ: false
 });
 
+vr.setVoxel("Ground", {
+  position: { x: 2, y: 0, z: 0 },
+  blockId: 1,
+  flipY: true
+});
+
 const entry = vr.getVoxel({
   x: 0, y: 0, z: 0
 });
@@ -208,6 +214,8 @@ interface VoxelSetOptions {
   flipX?: boolean;
   /** Mirror the block on the Z axis. Default: `false`. */
   flipZ?: boolean;
+  /** Mirror the block geometry around y = 0.5 (upside-down). */
+  flipY?: boolean;
 }
 ```
 

packages/voxel-renderer/examples/scripts/demo-shapes.ts

@@ -19,20 +19,14 @@ import { PoleY } from "../../src/blocks/shapes/PoleY.ts";
 import { Pole } from "../../src/blocks/shapes/Pole.ts";
 import { PoleCross } from "../../src/blocks/shapes/PoleCross.ts";
 import { Ramp } from "../../src/blocks/shapes/Ramp.ts";
-import { RampFlip } from "../../src/blocks/shapes/RampFlip.ts";
 import {
   RampCornerInner,
-  RampCornerOuter,
-  RampCornerInnerFlip,
-  RampCornerOuterFlip
+  RampCornerOuter
 } from "../../src/blocks/shapes/RampCorner.ts";
 import {
   Stair,
   StairCornerInner,
-  StairCornerOuter,
-  StairFlip,
-  StairCornerInnerFlip,
-  StairCornerOuterFlip
+  StairCornerOuter
 } from "../../src/blocks/shapes/Stair.ts";
 
 // CONSTANTS
@@ -91,11 +85,6 @@ const kShapes: ShapeEntry[] = [
     label: "ramp",
     color: "#f5a623"
   },
-  {
-    shape: new RampFlip(),
-    label: "rampFlip",
-    color: "#f9a825"
-  },
   {
     shape: new RampCornerInner(),
     label: "rampCornerInner",
@@ -106,16 +95,6 @@ const kShapes: ShapeEntry[] = [
     label: "rampCornerOuter",
     color: "#9c27b0"
   },
-  {
-    shape: new RampCornerInnerFlip(),
-    label: "rampCornerInnerFlip",
-    color: "#c62828"
-  },
-  {
-    shape: new RampCornerOuterFlip(),
-    label: "rampCornerOuterFlip",
-    color: "#6a1b9a"
-  },
 
   // ── Stair ───────────────────────────────────────────────────────────────────
   {
@@ -132,21 +111,6 @@ const kShapes: ShapeEntry[] = [
     shape: new StairCornerOuter(),
     label: "stairCornerOuter",
     color: "#00897b"
-  },
-  {
-    shape: new StairFlip(),
-    label: "stairFlip",
-    color: "#3949ab"
-  },
-  {
-    shape: new StairCornerInnerFlip(),
-    label: "stairCornerInnerFlip",
-    color: "#bf360c"
-  },
-  {
-    shape: new StairCornerOuterFlip(),
-    label: "stairCornerOuterFlip",
-    color: "#00695c"
   }
 ];
 

packages/voxel-renderer/src/VoxelRenderer.ts

@@ -74,6 +74,8 @@ export interface VoxelSetOptions {
   flipX?: boolean;
   /** Mirror the block around z = 0.5. Default: false */
   flipZ?: boolean;
+  /** Mirror the block around y = 0.5. Default: false */
+  flipY?: boolean;
 }
 
 export interface VoxelRemoveOptions {
@@ -316,9 +318,10 @@ export class VoxelRenderer extends ActorComponent {
       blockId,
       rotation = 0,
       flipX = false,
-      flipZ = false
+      flipZ = false,
+      flipY = false
     } = options;
-    const transform = packTransform(rotation, flipX, flipZ);
+    const transform = packTransform(rotation, flipX, flipZ, flipY);
 
     this.world.setVoxelAt(
       layerName,
@@ -328,7 +331,7 @@ export class VoxelRenderer extends ActorComponent {
     this.#onLayerUpdated?.({
       action: "voxel-set",
       layerName,
-      metadata: { position, blockId, rotation, flipX, flipZ }
+      metadata: { position, blockId, rotation, flipX, flipZ, flipY }
     });
   }
 
@@ -353,12 +356,13 @@ export class VoxelRenderer extends ActorComponent {
       blockId,
       rotation = 0,
       flipX = false,
-      flipZ = false
+      flipZ = false,
+      flipY = false
     } of entries) {
       this.world.setVoxelAt(
         layerName,
         position,
-        { blockId, transform: packTransform(rotation, flipX, flipZ) }
+        { blockId, transform: packTransform(rotation, flipX, flipZ, flipY) }
       );
     }
   }

packages/voxel-renderer/src/blocks/BlockShape.ts

@@ -31,17 +31,11 @@ export type BlockShapeID =
   | "poleZ"
   | "poleCross"
   | "ramp"
-  | "rampFlip"
   | "rampCornerInner"
   | "rampCornerOuter"
-  | "rampCornerInnerFlip"
-  | "rampCornerOuterFlip"
   | "stair"
   | "stairCornerInner"
   | "stairCornerOuter"
-  | "stairFlip"
-  | "stairCornerInnerFlip"
-  | "stairCornerOuterFlip"
   | (string & {});
 
 /**

packages/voxel-renderer/src/blocks/BlockShapeRegistry.ts

@@ -3,18 +3,14 @@ import type { BlockShape } from "./BlockShape.ts";
 import { Cube } from "./shapes/Cube.ts";
 import { Slab } from "./shapes/Slab.ts";
 import { Ramp } from "./shapes/Ramp.ts";
-import { RampCornerInner, RampCornerOuter, RampCornerInnerFlip, RampCornerOuterFlip } from "./shapes/RampCorner.ts";
+import { RampCornerInner, RampCornerOuter } from "./shapes/RampCorner.ts";
 import { PoleY } from "./shapes/PoleY.ts";
 import { Pole } from "./shapes/Pole.ts";
 import { PoleCross } from "./shapes/PoleCross.ts";
-import { RampFlip } from "./shapes/RampFlip.ts";
 import {
   Stair,
   StairCornerInner,
-  StairCornerOuter,
-  StairFlip,
-  StairCornerInnerFlip,
-  StairCornerOuterFlip
+  StairCornerOuter
 } from "./shapes/Stair.ts";
 
 /**
@@ -56,17 +52,11 @@ export class BlockShapeRegistry {
       .register(new Pole("z"))
       .register(new PoleCross())
       .register(new Ramp())
-      .register(new RampFlip())
       .register(new RampCornerInner())
       .register(new RampCornerOuter())
-      .register(new RampCornerInnerFlip())
-      .register(new RampCornerOuterFlip())
       .register(new Stair())
       .register(new StairCornerInner())
-      .register(new StairCornerOuter())
-      .register(new StairFlip())
-      .register(new StairCornerInnerFlip())
-      .register(new StairCornerOuterFlip());
+      .register(new StairCornerOuter());
 
     return registry;
   }

packages/voxel-renderer/src/blocks/shapes/RampCorner.ts

@@ -7,8 +7,6 @@ import type {
   FaceDefinition
 } from "../BlockShape.ts";
 import {
-  type Vec2,
-  type Vec3,
   FACE
 } from "../../utils/math.ts";
 import {
@@ -174,79 +172,3 @@ export class RampCornerOuter implements BlockShape {
   }
 }
 
-// -- Reverse variants (Y-flipped) -------------------------------------------
-
-function yFlipFace(fd: FaceDefinition): FaceDefinition {
-  const flippedAndReversed = fd.vertices
-    .map(([x, y, z]) => [x, 1 - y, z] as Vec3)
-    .reverse() as Vec3[];
-  const reversedUvs = [...fd.uvs].reverse() as Vec2[];
-
-  let flippedFace: FACE;
-  if (fd.face === FACE.NegY) {
-    flippedFace = FACE.PosY;
-  }
-  else if (fd.face === FACE.PosY) {
-    flippedFace = FACE.NegY;
-  }
-  else {
-    flippedFace = fd.face;
-  }
-
-  const flippedNormal: Vec3 = [fd.normal[0], -fd.normal[1], fd.normal[2]];
-
-  return { face: flippedFace, normal: flippedNormal, vertices: flippedAndReversed, uvs: reversedUvs };
-}
-
-const kRampCornerInnerFlipFaces = new RampCornerInner().faces.map(yFlipFace);
-const kRampCornerOuterFlipFaces = new RampCornerOuter().faces.map(yFlipFace);
-
-/**
- * RampCornerInnerFlip — Y-flipped RampCornerInner (hangs from ceiling).
- * Flat ceiling at PosY, full walls PosZ + PosX, diagonal slope descends downward.
- *
- * Occludes: PosY, PosZ, PosX.
- */
-export class RampCornerInnerFlip implements BlockShape {
-  readonly id: BlockShapeID;
-  readonly collisionHint: BlockCollisionHint = "trimesh";
-
-  constructor(
-    id: BlockShapeID = "rampCornerInnerFlip"
-  ) {
-    this.id = id;
-  }
-
-  readonly faces: readonly FaceDefinition[] = kRampCornerInnerFlipFaces;
-
-  occludes(
-    face: FACE
-  ): boolean {
-    return face === FACE.PosY || face === FACE.PosZ || face === FACE.PosX;
-  }
-}
-
-/**
- * RampCornerOuterFlip — Y-flipped RampCornerOuter (quarter-pyramid hanging from ceiling).
- * Flat ceiling at PosY, slope descends downward.
- *
- * Occludes: PosY only.
- */
-export class RampCornerOuterFlip implements BlockShape {
-  readonly id: BlockShapeID;
-  readonly collisionHint: BlockCollisionHint = "trimesh";
-
-  constructor(
-    id: BlockShapeID = "rampCornerOuterFlip"
-  ) {
-    this.id = id;
-  }
-
-  readonly faces: readonly FaceDefinition[] = kRampCornerOuterFlipFaces;
-
-  occludes(
-    face: FACE
-  ): boolean {
-    return face === FACE.PosY;
-  }
-}