nova64 0.2.5 → 0.2.7

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

@@ -0,0 +1,73 @@
+// runtime/api-3d/camera.js
+// Camera controls, fog, and scene lighting helpers
+
+import * as THREE from 'three';
+
+export function cameraModule({ scene, camera, gpu }) {
+  function setCameraPosition(x, y, z) {
+    gpu.setCameraPosition(x, y, z);
+  }
+  function setCameraTarget(x, y, z) {
+    gpu.setCameraTarget(x, y, z);
+  }
+  function setCameraFOV(fov) {
+    gpu.setCameraFOV(fov);
+  }
+
+  function setCameraLookAt(direction) {
+    if (Array.isArray(direction) && direction.length >= 3) {
+      camera.lookAt(
+        camera.position.x + direction[0],
+        camera.position.y + direction[1],
+        camera.position.z + direction[2]
+      );
+    } else if (typeof direction === 'object' && direction.x !== undefined) {
+      camera.lookAt(
+        camera.position.x + direction.x,
+        camera.position.y + direction.y,
+        camera.position.z + direction.z
+      );
+    }
+  }
+
+  function setFog(color, near = 10, far = 50) {
+    gpu.setFog(color, near, far);
+  }
+  function clearFog() {
+    if (scene) scene.fog = null;
+  }
+  function setLightDirection(x, y, z) {
+    gpu.setLightDirection(x, y, z);
+  }
+  function setLightColor(color) {
+    if (gpu.setLightColor) gpu.setLightColor(color);
+  }
+  function setAmbientLight(color, intensity) {
+    if (gpu.setAmbientLight) gpu.setAmbientLight(color, intensity);
+  }
+
+  function setDirectionalLight(direction, color = 0xffffff, intensity = 1.0) {
+    const toRemove = scene.children.filter(c => c.type === 'DirectionalLight');
+    toRemove.forEach(l => scene.remove(l));
+    const light = new THREE.DirectionalLight(color, intensity);
+    if (Array.isArray(direction) && direction.length >= 3) {
+      light.position.set(direction[0], direction[1], direction[2]);
+    } else {
+      light.position.set(1, 2, 1);
+    }
+    scene.add(light);
+  }
+
+  return {
+    setCameraPosition,
+    setCameraTarget,
+    setCameraFOV,
+    setCameraLookAt,
+    setFog,
+    clearFog,
+    setLightDirection,
+    setLightColor,
+    setAmbientLight,
+    setDirectionalLight,
+  };
+}

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

@@ -0,0 +1,180 @@
+// runtime/api-3d/instancing.js
+// GPU instancing (InstancedMesh) and LOD (Level of Detail) system
+
+import * as THREE from 'three';
+
+export function instancingModule({
+  scene,
+  camera,
+  gpu,
+  instancedMeshes,
+  lodObjects,
+  counters,
+  getCachedMaterial,
+}) {
+  const _iDummy = new THREE.Object3D();
+
+  // --- Instancing ---
+
+  function createInstancedMesh(shape = 'cube', count = 100, color = 0xffffff, options = {}) {
+    let geometry;
+    switch (shape) {
+      case 'sphere':
+        geometry = gpu.createSphereGeometry(options.size || 1, options.segments || 6);
+        break;
+      case 'plane':
+        geometry = gpu.createPlaneGeometry(options.width || 1, options.height || 1);
+        break;
+      case 'cylinder':
+        geometry = gpu.createCylinderGeometry(
+          options.size || 0.5,
+          options.size || 0.5,
+          options.height || 2,
+          8
+        );
+        break;
+      default:
+        geometry = gpu.createBoxGeometry(options.size || 1, options.size || 1, options.size || 1);
+    }
+    const material = getCachedMaterial({ color, ...options });
+    const mesh = new THREE.InstancedMesh(geometry, material, count);
+    mesh.castShadow = mesh.receiveShadow = true;
+    mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    scene.add(mesh);
+    const id = ++counters.instance;
+    instancedMeshes.set(id, { mesh, count });
+    return id;
+  }
+
+  function setInstanceTransform(
+    instancedId,
+    index,
+    x = 0,
+    y = 0,
+    z = 0,
+    rx = 0,
+    ry = 0,
+    rz = 0,
+    sx = 1,
+    sy = 1,
+    sz = 1
+  ) {
+    const entry = instancedMeshes.get(instancedId);
+    if (!entry || index < 0 || index >= entry.count) return false;
+    _iDummy.position.set(x, y, z);
+    _iDummy.rotation.set(rx, ry, rz);
+    _iDummy.scale.set(sx, sy, sz);
+    _iDummy.updateMatrix();
+    entry.mesh.setMatrixAt(index, _iDummy.matrix);
+    return true;
+  }
+
+  function setInstanceColor(instancedId, index, color) {
+    const entry = instancedMeshes.get(instancedId);
+    if (!entry) return false;
+    entry.mesh.setColorAt(index, new THREE.Color(color));
+    if (entry.mesh.instanceColor) entry.mesh.instanceColor.needsUpdate = true;
+    return true;
+  }
+
+  function finalizeInstances(instancedId) {
+    const entry = instancedMeshes.get(instancedId);
+    if (!entry) return false;
+    entry.mesh.instanceMatrix.needsUpdate = true;
+    try {
+      entry.mesh.computeBoundingSphere();
+    } catch {
+      /* mock or incomplete geometry — skip */
+    }
+    return true;
+  }
+
+  function removeInstancedMesh(instancedId) {
+    const entry = instancedMeshes.get(instancedId);
+    if (!entry) return false;
+    scene.remove(entry.mesh);
+    entry.mesh.geometry?.dispose();
+    entry.mesh.material?.dispose();
+    instancedMeshes.delete(instancedId);
+    return true;
+  }
+
+  // --- LOD ---
+
+  function createLODMesh(levels = [], position = [0, 0, 0]) {
+    const lod = new THREE.LOD();
+    for (const {
+      shape = 'cube',
+      size = 1,
+      color = 0xffffff,
+      distance = 0,
+      options = {},
+    } of levels) {
+      let geometry;
+      switch (shape) {
+        case 'sphere':
+          geometry = gpu.createSphereGeometry(size, options.segments || 8);
+          break;
+        case 'plane':
+          geometry = gpu.createPlaneGeometry(size, options.height || size);
+          break;
+        case 'cylinder':
+          geometry = gpu.createCylinderGeometry(
+            size * 0.5,
+            size * 0.5,
+            options.height || size * 2,
+            options.segments || 8
+          );
+          break;
+        default:
+          geometry = gpu.createBoxGeometry(size, size, size);
+      }
+      const mat = getCachedMaterial({ color, ...options });
+      const mesh = new THREE.Mesh(geometry, mat);
+      mesh.castShadow = mesh.receiveShadow = true;
+      lod.addLevel(mesh, distance);
+    }
+    if (Array.isArray(position) && position.length >= 3) {
+      lod.position.set(position[0], position[1], position[2]);
+    }
+    scene.add(lod);
+    const id = ++counters.lod;
+    lodObjects.set(id, lod);
+    return id;
+  }
+
+  function setLODPosition(lodId, x, y, z) {
+    const lod = lodObjects.get(lodId);
+    if (!lod) return false;
+    lod.position.set(x, y, z);
+    return true;
+  }
+
+  function removeLODMesh(lodId) {
+    const lod = lodObjects.get(lodId);
+    if (!lod) return false;
+    scene.remove(lod);
+    for (const { object } of lod.levels) {
+      object.geometry?.dispose();
+      object.material?.dispose();
+    }
+    lodObjects.delete(lodId);
+    return true;
+  }
+
+  function updateLODs() {
+    for (const lod of lodObjects.values()) lod.update(camera);
+  }
+
+  return {
+    createInstancedMesh,
+    setInstanceTransform,
+    setInstanceColor,
+    finalizeInstances,
+    removeInstancedMesh,
+    createLODMesh,
+    setLODPosition,
+    removeLODMesh,
+    updateLODs,
+  };
+}

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

@@ -0,0 +1,51 @@
+// runtime/api-3d/lights.js
+// Dynamic point lights created by carts at runtime
+
+import * as THREE from 'three';
+
+export function lightsModule({ scene, cartLights, counters }) {
+  /**
+   * Creates a dynamic point light in the 3D scene.
+   * @param {number} [color=0xffffff] - Hex color
+   * @param {number} [intensity=2] - Brightness multiplier
+   * @param {number} [distance=20] - Max range (0 = infinite)
+   * @param {number} [x=0] - World X position
+   * @param {number} [y=0] - World Y position
+   * @param {number} [z=0] - World Z position
+   * @returns {number} Light ID
+   */
+  function createPointLight(color = 0xffffff, intensity = 2, distance = 20, x = 0, y = 0, z = 0) {
+    const light = new THREE.PointLight(color, intensity, distance);
+    light.position.set(x, y, z);
+    scene.add(light);
+    const id = ++counters.light;
+    cartLights.set(id, light);
+    return id;
+  }
+
+  function setPointLightPosition(lightId, x, y, z) {
+    const light = cartLights.get(lightId);
+    if (!light) return false;
+    light.position.set(x, y, z);
+    return true;
+  }
+
+  function setPointLightColor(lightId, color) {
+    const light = cartLights.get(lightId);
+    if (!light) return false;
+    light.color.setHex(color);
+    return true;
+  }
+
+  function removeLight(lightId) {
+    const light = cartLights.get(lightId);
+    if (!light) return false;
+    scene.remove(light);
+    if (light.shadow?.map) light.shadow.map.dispose();
+    if (light.dispose) light.dispose();
+    cartLights.delete(lightId);
+    return true;
+  }
+
+  return { createPointLight, setPointLightPosition, setPointLightColor, removeLight };
+}

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

@@ -0,0 +1,47 @@
+// runtime/api-3d/materials.js
+// Material cache and full disposal utility
+
+export function materialsModule({ gpu, materialCache }) {
+  function getMaterialKey(options) {
+    return JSON.stringify({
+      material: options.material || 'standard',
+      color: options.color || 0xffffff,
+      emissive: options.emissive || 0x000000,
+      metalness: options.metalness,
+      roughness: options.roughness,
+      transparent: options.transparent,
+      opacity: options.opacity,
+      wireframe: options.wireframe,
+    });
+  }
+
+  function getCachedMaterial(options) {
+    const key = getMaterialKey(options);
+    if (materialCache.has(key)) return materialCache.get(key);
+    const material = gpu.createN64Material(options);
+    materialCache.set(key, material);
+    return material;
+  }
+
+  function disposeMaterial(material) {
+    const textureProps = [
+      'map',
+      'normalMap',
+      'roughnessMap',
+      'metalnessMap',
+      'aoMap',
+      'emissiveMap',
+      'bumpMap',
+      'displacementMap',
+      'alphaMap',
+      'lightMap',
+      'envMap',
+    ];
+    textureProps.forEach(prop => {
+      if (material[prop]?.dispose) material[prop].dispose();
+    });
+    material.dispose();
+  }
+
+  return { getMaterialKey, getCachedMaterial, disposeMaterial };
+}

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

@@ -0,0 +1,84 @@
+// runtime/api-3d/models.js
+// GLTF model loading, skeletal animation, and texture loading
+
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+export function modelsModule({ scene, gpu, meshes, mixers, modelAnimations, counters }) {
+  async function loadModel(url, position = [0, 0, 0], scale = 1) {
+    return new Promise((resolve, reject) => {
+      const loader = new GLTFLoader();
+      loader.load(
+        url,
+        gltf => {
+          const model = gltf.scene;
+          model.position.set(...position);
+          model.scale.setScalar(scale);
+          model.traverse(child => {
+            if (child.isMesh) {
+              child.castShadow = true;
+              child.receiveShadow = true;
+              if (child.material) {
+                child.material = gpu.createN64Material({
+                  color: child.material.color,
+                  texture: child.material.map,
+                });
+              }
+            }
+          });
+          scene.add(model);
+          const id = ++counters.mesh;
+          meshes.set(id, model);
+          if (gltf.animations?.length > 0) {
+            const mixer = new THREE.AnimationMixer(model);
+            mixers.set(id, mixer);
+            modelAnimations.set(id, gltf.animations);
+            mixer.clipAction(gltf.animations[0]).play();
+          }
+          resolve(id);
+        },
+        undefined,
+        reject
+      );
+    });
+  }
+
+  function playAnimation(meshId, nameOrIndex = 0, loop = true, timeScale = 1.0) {
+    const mixer = mixers.get(meshId);
+    const animations = modelAnimations.get(meshId);
+    if (!mixer || !animations) return;
+    const clip =
+      typeof nameOrIndex === 'number'
+        ? animations[nameOrIndex]
+        : THREE.AnimationClip.findByName(animations, nameOrIndex);
+    if (clip) {
+      mixer.stopAllAction();
+      const action = mixer.clipAction(clip);
+      action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce);
+      action.timeScale = timeScale;
+      action.play();
+    }
+  }
+
+  function updateAnimations(dt) {
+    mixers.forEach(mixer => mixer.update(dt));
+  }
+
+  function loadTexture(url) {
+    return new Promise((resolve, reject) => {
+      new THREE.TextureLoader().load(
+        url,
+        tex => {
+          tex.magFilter = THREE.NearestFilter;
+          tex.minFilter = THREE.NearestFilter;
+          tex.generateMipmaps = false;
+          resolve(tex);
+        },
+        undefined,
+        reject
+      );
+    });
+  }
+
+  return { loadModel, playAnimation, updateAnimations, loadTexture };
+}