Add basic 3D movement and collision primitives<BUILD_PR_LEVEL_17_4_MOVEMENT_COLLISION_BASE>

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,8 +2,8 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Implement minimal 3D camera:
-- create camera state (position, rotation)
-- integrate into scene safely
-- ensure no impact to 2D camera
-- validate all samples still pass
+Implement basic 3D movement + collision:
+- add velocity-based position updates
+- implement simple collision bounds (AABB or sphere)
+- isolate from 2D systems
+- validate no regression across samples

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Introduce minimal 3D camera foundation<BUILD_PR_LEVEL_17_3_CAMERA_FOUNDATION>
+Add basic 3D movement and collision primitives<BUILD_PR_LEVEL_17_4_MOVEMENT_COLLISION_BASE>

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-15T19:11:35.746Z
+Generated: 2026-04-15T19:21:48.819Z
 
 Filters: games=false, samples=true, tools=false, sampleRange=all
 

docs/dev/reports/validation_report.txt

@@ -1 +1 @@
-Post-run: verify camera init + no regression
+Post-run: verify movement + collision + no regression

docs/pr/BUILD_PR_LEVEL_17_4_MOVEMENT_COLLISION_BASE.md

@@ -0,0 +1,18 @@
+# BUILD PR: 17.4 Movement + Collision Base (3D)
+
+## Purpose
+Introduce minimal 3D movement and collision primitives.
+
+## Scope
+- Basic position update (velocity integration)
+- Simple collision bounds (AABB or sphere)
+- No physics engine yet (foundation only)
+
+## Testability
+- 2D systems remain unaffected
+- 3D entities can move and collide in isolation
+
+## Acceptance
+- [ ] Movement updates correctly
+- [ ] Collision detection triggers
+- [ ] No regression in 2D or networking

src/engine/core/Engine.js

@@ -196,6 +196,16 @@ export default class Engine {
 
     const updateStart = performance.now();
     const tickerResult = this.fixedTicker.advance(deltaMs, (stepSeconds) => {
+      if (this.scene && typeof this.scene.step3DPhysics === 'function') {
+        try {
+          this.scene.step3DPhysics(stepSeconds, this);
+        } catch (error) {
+          this.logger?.warn?.('Engine scene step3DPhysics hook failed.', {
+            error: error?.message || String(error),
+          });
+        }
+      }
+
       if (this.scene && typeof this.scene.update === 'function') {
         this.scene.update(stepSeconds, this);
       }

src/engine/physics/collision3d.js

@@ -0,0 +1,123 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/15/2026
+collision3d.js
+*/
+function toFinite(value, fallback = 0) {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function getAabb3D(bounds) {
+  return {
+    x: toFinite(bounds?.x, 0),
+    y: toFinite(bounds?.y, 0),
+    z: toFinite(bounds?.z, 0),
+    width: Math.max(0, toFinite(bounds?.width, 0)),
+    height: Math.max(0, toFinite(bounds?.height, 0)),
+    depth: Math.max(0, toFinite(bounds?.depth, 0)),
+  };
+}
+
+export function isAabbColliding3D(a, b) {
+  const left = getAabb3D(a);
+  const right = getAabb3D(b);
+
+  return (
+    left.x < right.x + right.width &&
+    left.x + left.width > right.x &&
+    left.y < right.y + right.height &&
+    left.y + left.height > right.y &&
+    left.z < right.z + right.depth &&
+    left.z + left.depth > right.z
+  );
+}
+
+export function resolveAabbCollision3D(body, obstacle) {
+  if (!body || !obstacle || body === obstacle) {
+    return {
+      collided: false,
+      axis: null,
+      overlap: 0,
+    };
+  }
+
+  const moving = getAabb3D(body);
+  const fixed = getAabb3D(obstacle);
+
+  if (!isAabbColliding3D(moving, fixed)) {
+    return {
+      collided: false,
+      axis: null,
+      overlap: 0,
+    };
+  }
+
+  const movingCenterX = moving.x + moving.width / 2;
+  const movingCenterY = moving.y + moving.height / 2;
+  const movingCenterZ = moving.z + moving.depth / 2;
+  const fixedCenterX = fixed.x + fixed.width / 2;
+  const fixedCenterY = fixed.y + fixed.height / 2;
+  const fixedCenterZ = fixed.z + fixed.depth / 2;
+
+  const deltaX = movingCenterX - fixedCenterX;
+  const deltaY = movingCenterY - fixedCenterY;
+  const deltaZ = movingCenterZ - fixedCenterZ;
+  const overlapX = (moving.width + fixed.width) / 2 - Math.abs(deltaX);
+  const overlapY = (moving.height + fixed.height) / 2 - Math.abs(deltaY);
+  const overlapZ = (moving.depth + fixed.depth) / 2 - Math.abs(deltaZ);
+
+  let axis = 'x';
+  let overlap = overlapX;
+
+  if (overlapY < overlap) {
+    axis = 'y';
+    overlap = overlapY;
+  }
+
+  if (overlapZ < overlap) {
+    axis = 'z';
+    overlap = overlapZ;
+  }
+
+  if (axis === 'x') {
+    body.x += deltaX < 0 ? -overlap : overlap;
+    body.velocityX = 0;
+  } else if (axis === 'y') {
+    body.y += deltaY < 0 ? -overlap : overlap;
+    body.velocityY = 0;
+  } else {
+    body.z += deltaZ < 0 ? -overlap : overlap;
+    body.velocityZ = 0;
+  }
+
+  return {
+    collided: true,
+    axis,
+    overlap,
+  };
+}
+
+export function resolveAabbCollisions3D(body, obstacles = []) {
+  if (!Array.isArray(obstacles) || obstacles.length === 0) {
+    return {
+      collided: false,
+      collisionCount: 0,
+      axes: [],
+    };
+  }
+
+  const axes = [];
+  for (const obstacle of obstacles) {
+    const result = resolveAabbCollision3D(body, obstacle);
+    if (result.collided) {
+      axes.push(result.axis);
+    }
+  }
+
+  return {
+    collided: axes.length > 0,
+    collisionCount: axes.length,
+    axes,
+  };
+}

src/engine/physics/index.js

@@ -7,4 +7,6 @@ index.js
 export { applyDrag } from './drag.js';
 export { stepArcadeBody } from './arcadeBody.js';
 export { integrateVelocity2D } from './integration.js';
-
+export { integrateVelocity3D } from './integration3d.js';
+export { isAabbColliding3D, resolveAabbCollision3D, resolveAabbCollisions3D } from './collision3d.js';
+export { stepSceneBodies3D } from './scene3d.js';

src/engine/physics/integration3d.js

@@ -0,0 +1,21 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/15/2026
+integration3d.js
+*/
+function toFinite(value, fallback = 0) {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+export function integrateVelocity3D(body, dtSeconds) {
+  if (!body || typeof body !== 'object') {
+    return body;
+  }
+
+  const dt = toFinite(dtSeconds, 0);
+  body.x = toFinite(body.x, 0) + toFinite(body.velocityX, 0) * dt;
+  body.y = toFinite(body.y, 0) + toFinite(body.velocityY, 0) * dt;
+  body.z = toFinite(body.z, 0) + toFinite(body.velocityZ, 0) * dt;
+  return body;
+}

src/engine/physics/scene3d.js

@@ -0,0 +1,43 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/15/2026
+scene3d.js
+*/
+import { integrateVelocity3D } from './integration3d.js';
+import { resolveAabbCollisions3D } from './collision3d.js';
+
+export function stepSceneBodies3D(
+  scene,
+  dtSeconds,
+  {
+    bodiesKey = 'bodies3D',
+    collidersKey = 'staticColliders3D',
+  } = {},
+) {
+  if (!scene || typeof scene !== 'object') {
+    return {
+      movedBodies: 0,
+      resolvedCollisions: 0,
+    };
+  }
+
+  const bodies = Array.isArray(scene[bodiesKey]) ? scene[bodiesKey] : [];
+  const staticColliders = Array.isArray(scene[collidersKey]) ? scene[collidersKey] : [];
+  let movedBodies = 0;
+  let resolvedCollisions = 0;
+
+  for (const body of bodies) {
+    integrateVelocity3D(body, dtSeconds);
+    movedBodies += 1;
+
+    const colliders = Array.isArray(body?.colliders3D) ? body.colliders3D : staticColliders;
+    const collisionResult = resolveAabbCollisions3D(body, colliders);
+    resolvedCollisions += collisionResult.collisionCount;
+  }
+
+  return {
+    movedBodies,
+    resolvedCollisions,
+  };
+}