Fix Sample 1610 mini map orientation and clarify hybrid 2D vs 3D visualization

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-COMMAND: Implement samples 1615-1617, integrate into index, package to <project folder>/tmp/BUILD_PR_LEVEL_17_27_ADVANCED_3D_SAMPLES_BATCH_3.zip
+COMMAND: Fix Sample 1610 hybrid demo by correcting mini map Y-axis inversion and adding clear visual distinction between 2D overlay and 3D world. Package results to <project folder>/tmp/BUILD_PR_LEVEL_17_29_SAMPLE_1610_HYBRID_FIX.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Add Advanced 3D Samples batch 3 (1615-1617)
+Fix Sample 1610 mini map orientation and clarify hybrid 2D vs 3D visualization

docs/dev/reports/validation_checklist.txt

@@ -1,2 +1,5 @@
-- [ ] samples load
-- [ ] no errors
+
+- [ ] mini map orientation correct (forward = up)
+- [ ] no inversion artifacts
+- [ ] 2D vs 3D clearly labeled or visually distinct
+- [ ] sample remains simple and functional

docs/pr/BUILD_PR_LEVEL_17_29_SAMPLE_1610_HYBRID_FIX.md

@@ -0,0 +1,29 @@
+# BUILD_PR_LEVEL_17_29_SAMPLE_1610_HYBRID_FIX
+
+Implement:
+
+1. Mini Map Fix
+- invert Y-axis mapping so world forward aligns with upward direction on mini map
+- ensure consistent coordinate transform between world and mini map
+
+2. Hybrid Clarity
+Add explicit differentiation:
+- 2D layer:
+  - top-down mini map or UI overlay
+  - clearly labeled "2D Layer"
+- 3D layer:
+  - main camera world
+  - clearly labeled "3D World"
+
+3. Visual Indicators
+- add label overlays or color coding
+- optional toggle to highlight layers
+
+Constraints:
+- minimal changes
+- no engine refactor
+- sample must remain simple and educational
+
+Validation:
+- moving forward = moves up on mini map
+- user can clearly identify what is 2D vs 3D

docs/pr/PLAN_PR_LEVEL_17_29_SAMPLE_1610_HYBRID_FIX.md

@@ -0,0 +1,16 @@
+# PLAN_PR_LEVEL_17_29_SAMPLE_1610_HYBRID_FIX
+
+Purpose:
+Fix clarity and correctness issues in Sample 1610 (Hybrid 2D/3D World).
+
+Problems Identified:
+- Mini map is vertically inverted (upside down)
+- Hybrid concept is not visually clear (2D vs 3D not distinguishable)
+
+Scope:
+- correct mini map coordinate orientation
+- make 2D vs 3D distinction explicit and visible
+
+Out of Scope:
+- engine changes
+- new features beyond clarity and correctness

samples/phase-16/1610/Hybrid2D3DWorldScene.js

@@ -101,37 +101,49 @@ export default class Hybrid2D3DWorldScene extends Scene {
     const zRatio = (point.z - this.worldBounds.minZ) / Math.max(0.0001, this.worldBounds.maxZ - this.worldBounds.minZ);
     return {
       x: viewport.x + xRatio * viewport.width,
-      y: viewport.y + zRatio * viewport.height,
+      y: viewport.y + (1 - zRatio) * viewport.height,
     };
   }
 
   drawTopdown(renderer) {
     const map = this.topdownViewport;
-    renderer.drawRect(map.x, map.y, map.width, map.height, 'rgba(15, 23, 42, 0.86)');
-    renderer.strokeRect(map.x, map.y, map.width, map.height, '#60a5fa', 1.5);
+    renderer.drawRect(map.x - 6, map.y - 28, map.width + 12, map.height + 34, 'rgba(8, 42, 64, 0.54)');
+    renderer.drawRect(map.x, map.y, map.width, map.height, 'rgba(15, 23, 42, 0.92)');
+    renderer.strokeRect(map.x, map.y, map.width, map.height, '#22d3ee', 2);
+    renderer.drawRect(map.x + 8, map.y + 8, 94, 18, 'rgba(8, 145, 178, 0.35)');
+    renderer.drawText('2D Layer', map.x + 15, map.y + 21, { color: '#67e8f9', font: '12px monospace' });
 
     this.props.forEach((prop) => {
       const topLeft = this.worldToMap({ x: prop.transform3D.x, z: prop.transform3D.z }, map);
       const bottomRight = this.worldToMap({ x: prop.transform3D.x + prop.size3D.width, z: prop.transform3D.z + prop.size3D.depth }, map);
+      const left = Math.min(topLeft.x, bottomRight.x);
+      const top = Math.min(topLeft.y, bottomRight.y);
+      const width = Math.max(2, Math.abs(bottomRight.x - topLeft.x));
+      const height = Math.max(2, Math.abs(bottomRight.y - topLeft.y));
       renderer.drawRect(
-        topLeft.x,
-        topLeft.y,
-        Math.max(2, bottomRight.x - topLeft.x),
-        Math.max(2, bottomRight.y - topLeft.y),
+        left,
+        top,
+        width,
+        height,
         prop.color
       );
     });
 
     const playerTopLeft = this.worldToMap({ x: this.player.x, z: this.player.z }, map);
     const playerBottomRight = this.worldToMap({ x: this.player.x + this.player.width, z: this.player.z + this.player.depth }, map);
+    const playerLeft = Math.min(playerTopLeft.x, playerBottomRight.x);
+    const playerTop = Math.min(playerTopLeft.y, playerBottomRight.y);
+    const playerWidth = Math.max(3, Math.abs(playerBottomRight.x - playerTopLeft.x));
+    const playerHeight = Math.max(3, Math.abs(playerBottomRight.y - playerTopLeft.y));
     renderer.drawRect(
-      playerTopLeft.x,
-      playerTopLeft.y,
-      Math.max(3, playerBottomRight.x - playerTopLeft.x),
-      Math.max(3, playerBottomRight.y - playerTopLeft.y),
-      '#f8fafc'
+      playerLeft,
+      playerTop,
+      playerWidth,
+      playerHeight,
+      '#22d3ee'
     );
-    renderer.drawText('2D Tactical View', map.x + 10, map.y + 18, { color: '#cbd5e1', font: '12px monospace' });
+    renderer.strokeRect(playerLeft - 1, playerTop - 1, playerWidth + 2, playerHeight + 2, '#ecfeff', 1);
+    renderer.drawText('Forward ^', map.x + map.width - 74, map.y + 18, { color: '#a5f3fc', font: '12px monospace' });
   }
 
   render(renderer) {
@@ -144,7 +156,10 @@ export default class Hybrid2D3DWorldScene extends Scene {
     this.drawTopdown(renderer);
 
     const viewport = this.viewport3d;
+    renderer.drawRect(viewport.x - 6, viewport.y - 28, viewport.width + 12, viewport.height + 34, 'rgba(56, 29, 92, 0.34)');
     renderer.strokeRect(viewport.x, viewport.y, viewport.width, viewport.height, '#d8d5ff', 2);
+    renderer.drawRect(viewport.x + 10, viewport.y + 8, 94, 18, 'rgba(109, 40, 217, 0.35)');
+    renderer.drawText('3D World', viewport.x + 17, viewport.y + 21, { color: '#ddd6fe', font: '12px monospace' });
     drawDepthBackdrop(renderer, viewport);
 
     const cameraState = this.camera3D?.getState?.() ?? {

tests/runtime/Phase16AdvancedBatch1Sanity.test.mjs

@@ -42,14 +42,18 @@ function makeInput(keys = []) {
 
 function createRendererProbe(width = 960, height = 540) {
   const lines = [];
+  const texts = [];
   return {
     lines,
+    texts,
     getCanvasSize() {
       return { width, height };
     },
     clear() {},
     strokeRect() {},
-    drawText() {},
+    drawText(text) {
+      texts.push(String(text));
+    },
     drawRect() {},
     drawLine(x1, y1, x2, y2, color) {
       lines.push({ x1, y1, x2, y2, color });
@@ -104,10 +108,16 @@ function assertHybridDemo() {
   scene.step3DPhysics(1 / 60, { input: makeInput(['KeyD']) });
   assert.equal(scene.player.x > startX, true, 'Hybrid demo should move player in shared world state.');
 
+  const mapNear = scene.worldToMap({ x: scene.player.x, z: scene.worldBounds.minZ + 1 }, scene.topdownViewport);
+  const mapFar = scene.worldToMap({ x: scene.player.x, z: scene.worldBounds.maxZ - 1 }, scene.topdownViewport);
+  assert.equal(mapFar.y < mapNear.y, true, 'Hybrid mini map should map forward world depth toward upward screen direction.');
+
   const renderer = createRendererProbe();
   scene.render(renderer);
   const visibleLines = countVisibleLinesInViewport(renderer.lines, scene.viewport3d);
   assert.equal(visibleLines > 0, true, 'Hybrid demo should render visible 3D wireframe output.');
+  assert.equal(renderer.texts.includes('2D Layer'), true, 'Hybrid demo should clearly label the 2D layer.');
+  assert.equal(renderer.texts.includes('3D World'), true, 'Hybrid demo should clearly label the 3D world layer.');
 }
 
 function assertMultiplayerDemo() {