nova64 0.2.1

package/runtime/api-3d/primitives.js

@@ -0,0 +1,304 @@
+// runtime/api-3d/primitives.js
+// Mesh creation (createMesh) and all shape primitives
+
+import * as THREE from 'three';
+import { logger } from '../logger.js';
+
+export function primitivesModule({
+  scene,
+  gpu,
+  meshes,
+  mixers,
+  modelAnimations,
+  counters,
+  getCachedMaterial,
+}) {
+  function createMesh(geometry, material, position = [0, 0, 0]) {
+    if (!geometry || !material) {
+      logger.error('createMesh: geometry and material are required');
+      return null;
+    }
+
+    let mesh;
+    if (geometry.type && !geometry.isBufferGeometry) {
+      // Mock object path (used in tests)
+      mesh = {
+        type: 'Mesh',
+        geometry,
+        material,
+        position: {
+          x: 0,
+          y: 0,
+          z: 0,
+          set(x, y, z) {
+            this.x = x;
+            this.y = y;
+            this.z = z;
+          },
+        },
+        rotation: {
+          x: 0,
+          y: 0,
+          z: 0,
+          set(x, y, z) {
+            this.x = x;
+            this.y = y;
+            this.z = z;
+          },
+        },
+        scale: {
+          x: 1,
+          y: 1,
+          z: 1,
+          set(x, y, z) {
+            this.x = x;
+            this.y = y;
+            this.z = z;
+          },
+          setScalar(s) {
+            this.x = s;
+            this.y = s;
+            this.z = s;
+          },
+        },
+        castShadow: true,
+        receiveShadow: true,
+      };
+    } else {
+      mesh = new THREE.Mesh(geometry, material);
+      mesh.castShadow = true;
+      mesh.receiveShadow = true;
+    }
+
+    if (Array.isArray(position) && position.length >= 3) {
+      mesh.position.set(position[0], position[1], position[2]);
+    } else if (typeof position === 'object' && position.x !== undefined) {
+      mesh.position.set(position.x, position.y || 0, position.z || 0);
+    } else {
+      mesh.position.set(0, 0, 0);
+    }
+
+    if (scene.add) scene.add(mesh);
+    if (material?.userData?.animated && gpu.registerAnimatedMesh) {
+      gpu.registerAnimatedMesh(mesh);
+    }
+
+    const id = ++counters.mesh;
+    meshes.set(id, mesh);
+    return id;
+  }
+
+  function destroyMesh(id) {
+    const mesh = meshes.get(id);
+    if (mesh) {
+      scene.remove(mesh);
+      mesh.geometry?.dispose();
+      if (mesh.material?.map) mesh.material.map.dispose();
+      mesh.material?.dispose();
+      meshes.delete(id);
+      mixers.delete(id);
+      modelAnimations.delete(id);
+    }
+  }
+
+  function getMesh(id) {
+    return meshes.get(id);
+  }
+
+  function createCube(size = 1, color = 0xffffff, position = [0, 0, 0], options = {}) {
+    try {
+      if (typeof size !== 'number' || size <= 0) {
+        logger.warn('createCube: invalid size, using default');
+        size = 1;
+      }
+      if (typeof color !== 'number') {
+        logger.warn('createCube: invalid color, using white');
+        color = 0xffffff;
+      }
+      return createMesh(
+        gpu.createBoxGeometry(size, size, size),
+        getCachedMaterial({ color, ...options }),
+        position
+      );
+    } catch (e) {
+      logger.error('createCube failed:', e);
+      return null;
+    }
+  }
+
+  function createAdvancedCube(size = 1, materialOptions = {}, position = [0, 0, 0]) {
+    try {
+      if (typeof size !== 'number' || size <= 0) size = 1;
+      return createMesh(
+        gpu.createBoxGeometry(size, size, size),
+        getCachedMaterial(materialOptions),
+        position
+      );
+    } catch (e) {
+      logger.error('createAdvancedCube failed:', e);
+      return null;
+    }
+  }
+
+  function createSphere(
+    radius = 1,
+    color = 0xffffff,
+    position = [0, 0, 0],
+    segments = 8,
+    options = {}
+  ) {
+    try {
+      if (typeof radius !== 'number' || radius <= 0) {
+        logger.warn('createSphere: invalid radius, using default');
+        radius = 1;
+      }
+      if (typeof segments !== 'number' || segments < 3) {
+        logger.warn('createSphere: invalid segments, using default');
+        segments = 8;
+      }
+      return createMesh(
+        gpu.createSphereGeometry(radius, segments),
+        getCachedMaterial({ color, ...options }),
+        position
+      );
+    } catch (e) {
+      logger.error('createSphere failed:', e);
+      return null;
+    }
+  }
+
+  function createAdvancedSphere(
+    radius = 1,
+    materialOptions = {},
+    position = [0, 0, 0],
+    segments = 16
+  ) {
+    try {
+      if (typeof radius !== 'number' || radius <= 0) radius = 1;
+      if (typeof segments !== 'number' || segments < 3) segments = 16;
+      return createMesh(
+        gpu.createSphereGeometry(radius, segments),
+        getCachedMaterial(materialOptions),
+        position
+      );
+    } catch (e) {
+      logger.error('createAdvancedSphere failed:', e);
+      return null;
+    }
+  }
+
+  function createPlane(width = 1, height = 1, color = 0xffffff, position = [0, 0, 0]) {
+    try {
+      if (typeof width !== 'number' || width <= 0) {
+        logger.warn('createPlane: invalid width, using default');
+        width = 1;
+      }
+      if (typeof height !== 'number' || height <= 0) {
+        logger.warn('createPlane: invalid height, using default');
+        height = 1;
+      }
+      return createMesh(
+        gpu.createPlaneGeometry(width, height),
+        getCachedMaterial({ color }),
+        position
+      );
+    } catch (e) {
+      logger.error('createPlane failed:', e);
+      return null;
+    }
+  }
+
+  function createCylinder(
+    radiusTop = 1,
+    radiusBottom = 1,
+    height = 1,
+    color = 0xffffff,
+    position = [0, 0, 0],
+    options = {}
+  ) {
+    try {
+      const geom = gpu.createCylinderGeometry
+        ? gpu.createCylinderGeometry(radiusTop, radiusBottom, height, options.segments || 16)
+        : gpu.createBoxGeometry(radiusTop, height, radiusTop);
+      return createMesh(geom, getCachedMaterial({ ...options, color }), position);
+    } catch (e) {
+      logger.error('createCylinder err', e);
+      return createCube(radiusTop * 2, color, position);
+    }
+  }
+
+  function createTorus(
+    radius = 1,
+    tube = 0.3,
+    color = 0xffffff,
+    position = [0, 0, 0],
+    options = {}
+  ) {
+    try {
+      const geometry = new THREE.TorusGeometry(
+        radius,
+        tube,
+        options.radialSegments || 8,
+        options.tubularSegments || 16
+      );
+      return createMesh(geometry, gpu.createN64Material({ color, ...options }), position);
+    } catch (e) {
+      logger.error('createTorus failed:', e);
+      return null;
+    }
+  }
+
+  function createCone(
+    radius = 1,
+    height = 2,
+    color = 0xffffff,
+    position = [0, 0, 0],
+    options = {}
+  ) {
+    try {
+      return createMesh(
+        gpu.createConeGeometry(radius, height, options.segments || 16),
+        getCachedMaterial({ color, ...options }),
+        position
+      );
+    } catch (e) {
+      logger.error('createCone failed:', e);
+      return null;
+    }
+  }
+
+  function createCapsule(
+    radius = 0.5,
+    height = 1,
+    color = 0xffffff,
+    position = [0, 0, 0],
+    options = {}
+  ) {
+    try {
+      return createMesh(
+        gpu.createCapsuleGeometry(radius, height, options.segments || 8),
+        getCachedMaterial({ color, ...options }),
+        position
+      );
+    } catch (e) {
+      logger.error('createCapsule failed:', e);
+      return null;
+    }
+  }
+
+  return {
+    createMesh,
+    destroyMesh,
+    getMesh,
+    removeMesh: destroyMesh,
+    createCube,
+    createAdvancedCube,
+    createSphere,
+    createAdvancedSphere,
+    createPlane,
+    createCylinder,
+    createTorus,
+    createCone,
+    createCapsule,
+  };
+}

package/runtime/api-3d/scene.js

@@ -0,0 +1,169 @@
+// runtime/api-3d/scene.js
+// clearScene, setupScene, raycasting, stats, N64 effects
+
+import * as THREE from 'three';
+import { logger } from '../logger.js';
+
+export function sceneModule(ctx) {
+  const {
+    scene,
+    camera,
+    renderer,
+    gpu,
+    meshes,
+    cartLights,
+    materialCache,
+    instancedMeshes,
+    lodObjects,
+  } = ctx;
+
+  // These come from other modules — resolved at call-time via ctx
+  function getDisposeMaterial() {
+    return ctx.disposeMaterial;
+  }
+  function getRemoveLight() {
+    return ctx.removeLight;
+  }
+
+  function clearScene() {
+    const disposeMaterial = getDisposeMaterial();
+    const removeLight = getRemoveLight();
+
+    logger.info(
+      '🧹 Clearing 3D scene... meshes:',
+      meshes.size,
+      'lights:',
+      cartLights.size,
+      'materials:',
+      materialCache.size
+    );
+
+    // Dispose all cart meshes
+    for (const [, mesh] of meshes) {
+      scene.remove(mesh);
+      if (mesh.geometry) mesh.geometry.dispose();
+      if (mesh.material) {
+        if (Array.isArray(mesh.material)) mesh.material.forEach(disposeMaterial);
+        else disposeMaterial(mesh.material);
+      }
+    }
+    meshes.clear();
+
+    // Remove dynamic lights
+    cartLights.forEach((_, id) => removeLight(id));
+    cartLights.clear();
+
+    // Flush material cache
+    materialCache.forEach(disposeMaterial);
+    materialCache.clear();
+
+    // Remove any remaining scene children (e.g. from loadModel / direct additions)
+    while (scene.children.length > 0) {
+      const child = scene.children[0];
+      scene.remove(child);
+      if (child.geometry) child.geometry.dispose();
+      if (child.material) {
+        if (Array.isArray(child.material)) child.material.forEach(disposeMaterial);
+        else disposeMaterial(child.material);
+      }
+    }
+
+    // Re-add minimal default lighting so scenes aren't black
+    scene.add(new THREE.AmbientLight(0xffffff, 0.5));
+    const dir = new THREE.DirectionalLight(0xffffff, 0.8);
+    dir.position.set(5, 10, 7.5);
+    scene.add(dir);
+
+    // Reset animated mesh registry in GPU backend
+    if (gpu.clearAnimatedMeshes) gpu.clearAnimatedMeshes();
+
+    // Dispose instanced meshes
+    for (const { mesh } of instancedMeshes.values()) {
+      scene.remove(mesh);
+      mesh.geometry?.dispose();
+      mesh.material?.dispose();
+    }
+    instancedMeshes.clear();
+
+    // Dispose LOD objects
+    for (const lod of lodObjects.values()) {
+      scene.remove(lod);
+      for (const { object } of lod.levels) {
+        object.geometry?.dispose();
+        object.material?.dispose();
+      }
+    }
+    lodObjects.clear();
+
+    logger.info('✅ Scene cleared completely');
+  }
+
+  /**
+   * setupScene(opts) — One-call scene configuration.
+   * opts: { camera, light, fog, skybox, effects }
+   */
+  function setupScene(opts = {}) {
+    const cam = opts.camera ?? {};
+    ctx.setCameraPosition(cam.x ?? 0, cam.y ?? 5, cam.z ?? 10);
+    ctx.setCameraTarget(cam.targetX ?? 0, cam.targetY ?? 0, cam.targetZ ?? 0);
+    if (cam.fov) ctx.setCameraFOV(cam.fov);
+
+    const light = opts.light ?? {};
+    if (light.direction) {
+      const d = light.direction;
+      ctx.setLightDirection(d[0] ?? -0.3, d[1] ?? -1, d[2] ?? -0.5);
+    }
+    if (light.color !== undefined) ctx.setLightColor(light.color);
+    if (light.ambient !== undefined) ctx.setAmbientLight(light.ambient);
+
+    if (opts.fog && opts.fog !== false) {
+      ctx.setFog(opts.fog.color ?? 0x000000, opts.fog.near ?? 10, opts.fog.far ?? 50);
+    }
+
+    if (opts.skybox && typeof globalThis.createSpaceSkybox === 'function') {
+      globalThis.createSpaceSkybox(opts.skybox);
+    }
+
+    if (opts.effects && typeof globalThis.enableRetroEffects === 'function') {
+      globalThis.enableRetroEffects(typeof opts.effects === 'object' ? opts.effects : {});
+    }
+  }
+
+  function raycastFromCamera(x, y) {
+    const raycaster = new THREE.Raycaster();
+    const mouse = new THREE.Vector2(
+      (x / renderer.domElement.clientWidth) * 2 - 1,
+      -(y / renderer.domElement.clientHeight) * 2 + 1
+    );
+    raycaster.setFromCamera(mouse, camera);
+    const objects = Array.from(meshes.values()).filter(m => m.type === 'Mesh');
+    const hits = raycaster.intersectObjects(objects);
+    if (hits.length > 0) {
+      for (const [id, mesh] of meshes) {
+        if (mesh === hits[0].object) {
+          return { meshId: id, point: hits[0].point, distance: hits[0].distance };
+        }
+      }
+    }
+    return null;
+  }
+
+  function get3DStats() {
+    return gpu.getStats();
+  }
+  function enablePixelation(factor = 2) {
+    gpu.enablePixelation(factor);
+  }
+  function enableDithering(enabled = true) {
+    gpu.enableDithering(enabled);
+  }
+
+  return {
+    clearScene,
+    setupScene,
+    raycastFromCamera,
+    get3DStats,
+    enablePixelation,
+    enableDithering,
+  };
+}

package/runtime/api-3d/transforms.js

@@ -0,0 +1,161 @@
+// runtime/api-3d/transforms.js
+// Mesh position, rotation, scale, visibility, and shadow controls
+
+import { logger } from '../logger.js';
+
+export function transformsModule({ getMesh }) {
+  function setPosition(meshId, x, y, z) {
+    try {
+      const mesh = getMesh(meshId);
+      if (!mesh) {
+        logger.warn(`setPosition: mesh with id ${meshId} not found`);
+        return false;
+      }
+      mesh.position.set(
+        typeof x === 'number' ? x : 0,
+        typeof y === 'number' ? y : 0,
+        typeof z === 'number' ? z : 0
+      );
+      return true;
+    } catch (e) {
+      logger.error('setPosition failed:', e);
+      return false;
+    }
+  }
+
+  function setRotation(meshId, x, y, z) {
+    try {
+      const mesh = getMesh(meshId);
+      if (!mesh) {
+        logger.warn(`setRotation: mesh with id ${meshId} not found`);
+        return false;
+      }
+      mesh.rotation.set(
+        typeof x === 'number' ? x : 0,
+        typeof y === 'number' ? y : 0,
+        typeof z === 'number' ? z : 0
+      );
+      return true;
+    } catch (e) {
+      logger.error('setRotation failed:', e);
+      return false;
+    }
+  }
+
+  function setScale(meshId, x, y, z) {
+    try {
+      const mesh = getMesh(meshId);
+      if (!mesh) {
+        logger.warn(`setScale: mesh with id ${meshId} not found`);
+        return false;
+      }
+      x = typeof x === 'number' && x > 0 ? x : 1;
+      if (typeof y === 'undefined') {
+        mesh.scale.setScalar(x);
+      } else {
+        mesh.scale.set(
+          x,
+          typeof y === 'number' && y > 0 ? y : 1,
+          typeof z === 'number' && z > 0 ? z : 1
+        );
+      }
+      return true;
+    } catch (e) {
+      logger.error('setScale failed:', e);
+      return false;
+    }
+  }
+
+  function getPosition(meshId) {
+    const mesh = getMesh(meshId);
+    return mesh ? [mesh.position.x, mesh.position.y, mesh.position.z] : null;
+  }
+
+  function getRotation(meshId) {
+    const mesh = getMesh(meshId);
+    return mesh ? [mesh.rotation.x, mesh.rotation.y, mesh.rotation.z] : null;
+  }
+
+  function rotateMesh(meshId, dX, dY, dZ) {
+    try {
+      const mesh = getMesh(meshId);
+      if (!mesh) {
+        logger.warn(`rotateMesh: mesh with id ${meshId} not found`);
+        return false;
+      }
+      mesh.rotation.x += typeof dX === 'number' ? dX : 0;
+      mesh.rotation.y += typeof dY === 'number' ? dY : 0;
+      mesh.rotation.z += typeof dZ === 'number' ? dZ : 0;
+      return true;
+    } catch (e) {
+      logger.error('rotateMesh failed:', e);
+      return false;
+    }
+  }
+
+  function moveMesh(meshId, x, y, z) {
+    const mesh = getMesh(meshId);
+    if (mesh) {
+      mesh.position.x += x;
+      mesh.position.y += y;
+      mesh.position.z += z;
+    }
+  }
+
+  function setFlatShading(meshId, enabled = true) {
+    const mesh = getMesh(meshId);
+    if (!mesh) return false;
+    if (mesh.material) {
+      mesh.material.flatShading = enabled;
+      mesh.material.needsUpdate = true;
+    }
+    return true;
+  }
+
+  function setMeshVisible(meshId, visible) {
+    const mesh = getMesh(meshId);
+    if (!mesh) return false;
+    mesh.visible = visible;
+    return true;
+  }
+
+  function setMeshOpacity(meshId, opacity) {
+    const mesh = getMesh(meshId);
+    if (!mesh) return false;
+    if (mesh.material) {
+      mesh.material.transparent = opacity < 1;
+      mesh.material.opacity = opacity;
+      mesh.material.needsUpdate = true;
+    }
+    return true;
+  }
+
+  function setCastShadow(meshId, cast) {
+    const mesh = getMesh(meshId);
+    if (!mesh) return false;
+    mesh.castShadow = cast;
+    return true;
+  }
+
+  function setReceiveShadow(meshId, receive) {
+    const mesh = getMesh(meshId);
+    if (!mesh) return false;
+    mesh.receiveShadow = receive;
+    return true;
+  }
+
+  return {
+    setPosition,
+    setRotation,
+    setScale,
+    getPosition,
+    getRotation,
+    rotateMesh,
+    moveMesh,
+    setFlatShading,
+    setMeshVisible,
+    setMeshOpacity,
+    setCastShadow,
+    setReceiveShadow,
+  };
+}