nova64 0.2.6 → 0.2.7

package/dist/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/dist/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,
+  };
+}

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

@@ -0,0 +1,166 @@
+// runtime/api-3d.js
+// Thin orchestrator — delegates to runtime/api-3d/*.js sub-modules
+import * as THREE from 'three';
+globalThis.THREE = THREE;
+import { materialsModule } from './api-3d/materials.js';
+import { primitivesModule } from './api-3d/primitives.js';
+import { transformsModule } from './api-3d/transforms.js';
+import { cameraModule } from './api-3d/camera.js';
+import { lightsModule } from './api-3d/lights.js';
+import { modelsModule } from './api-3d/models.js';
+import { instancingModule } from './api-3d/instancing.js';
+import { pbrModule } from './api-3d/pbr.js';
+import { sceneModule } from './api-3d/scene.js';
+import { particlesModule } from './api-3d/particles.js';
+
+export function threeDApi(gpu) {
+  if (!gpu.getScene) return { exposeTo: () => {} };
+
+  const scene = gpu.getScene();
+  const camera = gpu.getCamera();
+  const renderer = gpu.getRenderer();
+
+  // Shared state — passed by reference into every sub-module
+  const meshes = new Map();
+  const mixers = new Map();
+  const modelAnimations = new Map();
+  const materialCache = new Map();
+  const cartLights = new Map();
+  const instancedMeshes = new Map();
+  const lodObjects = new Map();
+  const counters = { mesh: 0, light: 0, instance: 0, lod: 0 };
+
+  // Build context — each module appends its exports so later modules can call earlier ones
+  const ctx = {
+    scene,
+    camera,
+    renderer,
+    gpu,
+    meshes,
+    mixers,
+    modelAnimations,
+    materialCache,
+    cartLights,
+    instancedMeshes,
+    lodObjects,
+    counters,
+  };
+
+  Object.assign(ctx, materialsModule(ctx));
+  Object.assign(ctx, primitivesModule(ctx));
+  Object.assign(ctx, transformsModule(ctx));
+  Object.assign(ctx, cameraModule(ctx));
+  Object.assign(ctx, lightsModule(ctx));
+  Object.assign(ctx, modelsModule(ctx));
+  Object.assign(ctx, instancingModule(ctx));
+  Object.assign(ctx, pbrModule(ctx));
+  Object.assign(ctx, particlesModule(ctx));
+  Object.assign(ctx, sceneModule(ctx)); // last: uses late binding to call other modules
+
+  return {
+    exposeTo(target) {
+      Object.assign(target, {
+        // Primitive creation
+        createCube: ctx.createCube,
+        createSphere: ctx.createSphere,
+        createCylinder: ctx.createCylinder,
+        createPlane: ctx.createPlane,
+        createAdvancedCube: ctx.createAdvancedCube,
+        createAdvancedSphere: ctx.createAdvancedSphere,
+        createTorus: ctx.createTorus,
+        createCone: ctx.createCone,
+        createCapsule: ctx.createCapsule,
+
+        // Mesh management
+        destroyMesh: ctx.destroyMesh,
+        removeMesh: ctx.removeMesh,
+
+        // Model and texture loading
+        loadModel: ctx.loadModel,
+        playAnimation: ctx.playAnimation,
+        updateAnimations: ctx.updateAnimations,
+        loadTexture: ctx.loadTexture,
+
+        // Transforms
+        setPosition: ctx.setPosition,
+        setRotation: ctx.setRotation,
+        setScale: ctx.setScale,
+        getPosition: ctx.getPosition,
+        getRotation: ctx.getRotation,
+        rotateMesh: ctx.rotateMesh,
+        moveMesh: ctx.moveMesh,
+
+        // Mesh helpers
+        setFlatShading: ctx.setFlatShading,
+        setMeshVisible: ctx.setMeshVisible,
+        setMeshOpacity: ctx.setMeshOpacity,
+        setCastShadow: ctx.setCastShadow,
+        setReceiveShadow: ctx.setReceiveShadow,
+
+        // Camera
+        setCameraPosition: ctx.setCameraPosition,
+        setCameraTarget: ctx.setCameraTarget,
+        setCameraLookAt: ctx.setCameraLookAt,
+        setCameraFOV: ctx.setCameraFOV,
+
+        // Scene / atmosphere
+        setFog: ctx.setFog,
+        clearFog: ctx.clearFog,
+        setLightDirection: ctx.setLightDirection,
+        setLightColor: ctx.setLightColor,
+        setAmbientLight: ctx.setAmbientLight,
+        setDirectionalLight: ctx.setDirectionalLight,
+        clearScene: ctx.clearScene,
+
+        // Effects
+        enablePixelation: ctx.enablePixelation,
+        enableDithering: ctx.enableDithering,
+
+        // Dynamic lights
+        createPointLight: ctx.createPointLight,
+        setPointLightPosition: ctx.setPointLightPosition,
+        setPointLightColor: ctx.setPointLightColor,
+        removeLight: ctx.removeLight,
+
+        // GPU instancing
+        createInstancedMesh: ctx.createInstancedMesh,
+        setInstanceTransform: ctx.setInstanceTransform,
+        setInstanceColor: ctx.setInstanceColor,
+        finalizeInstances: ctx.finalizeInstances,
+        removeInstancedMesh: ctx.removeInstancedMesh,
+
+        // LOD system
+        createLODMesh: ctx.createLODMesh,
+        setLODPosition: ctx.setLODPosition,
+        removeLODMesh: ctx.removeLODMesh,
+        updateLODs: ctx.updateLODs,
+
+        // Normal / PBR maps
+        loadNormalMap: ctx.loadNormalMap,
+        setNormalMap: ctx.setNormalMap,
+        setPBRMaps: ctx.setPBRMaps,
+        setPBRProperties: ctx.setPBRProperties,
+
+        // GPU particle system
+        createParticleSystem: ctx.createParticleSystem,
+        setParticleEmitter: ctx.setParticleEmitter,
+        emitParticle: ctx.emitParticle,
+        burstParticles: ctx.burstParticles,
+        updateParticles: ctx.updateParticles,
+        removeParticleSystem: ctx.removeParticleSystem,
+        getParticleStats: ctx.getParticleStats,
+
+        // Interaction / stats / convenience
+        raycastFromCamera: ctx.raycastFromCamera,
+        get3DStats: ctx.get3DStats,
+        setupScene: ctx.setupScene,
+
+        // Direct Three.js access for advanced users
+        getScene: () => scene,
+        getCamera: () => camera,
+        getRenderer: () => renderer,
+        getMesh: ctx.getMesh,
+      });
+    },
+  };
+}