nova64 0.2.6 → 0.2.7

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

@@ -0,0 +1,296 @@
+// runtime/api-3d/particles.js
+// GPU particle system: typed-array physics simulation, single InstancedMesh draw call
+//
+// API:
+//   createParticleSystem(maxParticles, options) → systemId
+//   setParticleEmitter(systemId, emitter)          configure emission
+//   emitParticle(systemId, overrides?)             fire one particle
+//   burstParticles(systemId, count, overrides?)    fire N particles at once
+//   updateParticles(dt)                            step all systems (call each frame)
+//   removeParticleSystem(systemId)                 cleanup
+
+import * as THREE from 'three';
+
+export function particlesModule({ scene, counters }) {
+  // Per-particle typed arrays layout (indices into Float32Array pools):
+  //   px py pz  — position
+  //   vx vy vz  — velocity
+  //   age life  — lifetime tracking
+  //   r g b     — color (0-1)
+  //   size      — scale
+  //   active    — 1 = alive, 0 = dead
+
+  const STRIDE = 13; // slots per particle
+
+  const particleSystems = new Map();
+  let psCounter = 0;
+
+  const _dummy = new THREE.Object3D();
+  const _color = new THREE.Color();
+
+  function createParticleSystem(maxParticles = 200, options = {}) {
+    const {
+      shape = 'sphere',
+      size = 0.15,
+      segments = 4,
+      color = 0xffaa00,
+      emissive = 0xff6600,
+      emissiveIntensity = 2.0,
+      gravity = -9.8,
+      drag = 0.95,
+      // Emitter defaults
+      emitterX = 0,
+      emitterY = 0,
+      emitterZ = 0,
+      emitRate = 20, // particles per second
+      minLife = 0.8,
+      maxLife = 2.0,
+      minSpeed = 2,
+      maxSpeed = 8,
+      spread = Math.PI, // half-angle cone spread (PI = hemisphere)
+      minSize = 0.05,
+      maxSize = 0.3,
+      startColor = color,
+      endColor = 0x000000,
+    } = options;
+
+    // Geometry
+    let geometry;
+    if (shape === 'cube') {
+      geometry = new THREE.BoxGeometry(size, size, size);
+    } else {
+      geometry = new THREE.SphereGeometry(size, segments, segments);
+    }
+
+    const material = new THREE.MeshBasicMaterial({ color, vertexColors: false });
+    material.emissive = new THREE.Color(emissive);
+    // MeshBasicMaterial doesn't have emissive — use MeshStandardMaterial instead
+    const stdMat = new THREE.MeshStandardMaterial({
+      color,
+      emissive: new THREE.Color(emissive),
+      emissiveIntensity,
+      roughness: 0.8,
+      metalness: 0.0,
+    });
+
+    const mesh = new THREE.InstancedMesh(geometry, stdMat, maxParticles);
+    mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    mesh.castShadow = false;
+    mesh.receiveShadow = false;
+
+    // Hide all instances initially by scaling to zero
+    _dummy.position.set(0, -9999, 0);
+    _dummy.scale.set(0, 0, 0);
+    _dummy.updateMatrix();
+    for (let i = 0; i < maxParticles; i++) {
+      mesh.setMatrixAt(i, _dummy.matrix);
+    }
+    mesh.instanceMatrix.needsUpdate = true;
+
+    // Enable per-instance color
+    mesh.instanceColor = new THREE.InstancedBufferAttribute(new Float32Array(maxParticles * 3), 3);
+
+    scene.add(mesh);
+
+    // Typed-array particle state pool
+    const pool = new Float32Array(maxParticles * STRIDE);
+    // All start inactive (age = life = 0, active slot = 0)
+
+    const id = ++psCounter;
+    particleSystems.set(id, {
+      mesh,
+      pool,
+      maxParticles,
+      freeList: Array.from({ length: maxParticles }, (_, i) => i),
+      activeCount: 0,
+      emitAccum: 0,
+      emitter: {
+        x: emitterX,
+        y: emitterY,
+        z: emitterZ,
+        emitRate,
+        minLife,
+        maxLife,
+        minSpeed,
+        maxSpeed,
+        spread,
+        minSize,
+        maxSize,
+      },
+      config: {
+        gravity,
+        drag,
+        startColor: new THREE.Color(startColor),
+        endColor: new THREE.Color(endColor),
+      },
+    });
+
+    counters.particle = (counters.particle || 0) + 1;
+    return id;
+  }
+
+  function setParticleEmitter(systemId, emitter = {}) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return;
+    Object.assign(sys.emitter, emitter);
+  }
+
+  function _spawnParticle(sys, overrides = {}) {
+    if (sys.freeList.length === 0) return; // pool full
+    const idx = sys.freeList.pop();
+    const base = idx * STRIDE;
+    const { pool, emitter } = sys;
+
+    const ex = overrides.x ?? emitter.x;
+    const ey = overrides.y ?? emitter.y;
+    const ez = overrides.z ?? emitter.z;
+
+    // Random direction within spread cone (pointing up by default)
+    const phi = Math.random() * Math.PI * 2;
+    const theta = Math.random() * (overrides.spread ?? emitter.spread);
+    const ct = Math.cos(theta);
+    const st = Math.sin(theta);
+    const speed = emitter.minSpeed + Math.random() * (emitter.maxSpeed - emitter.minSpeed);
+    const vx = overrides.vx ?? st * Math.cos(phi) * speed;
+    const vy = overrides.vy ?? ct * speed;
+    const vz = overrides.vz ?? st * Math.sin(phi) * speed;
+
+    const life = emitter.minLife + Math.random() * (emitter.maxLife - emitter.minLife);
+    const sz = emitter.minSize + Math.random() * (emitter.maxSize - emitter.minSize);
+
+    // position
+    pool[base + 0] = ex;
+    pool[base + 1] = ey;
+    pool[base + 2] = ez;
+    // velocity
+    pool[base + 3] = vx;
+    pool[base + 4] = vy;
+    pool[base + 5] = vz;
+    // age, life
+    pool[base + 6] = 0;
+    pool[base + 7] = life > 0 ? life : 1;
+    // color (start)
+    const sc = sys.config.startColor;
+    pool[base + 8] = overrides.r ?? sc.r;
+    pool[base + 9] = overrides.g ?? sc.g;
+    pool[base + 10] = overrides.b ?? sc.b;
+    // size
+    pool[base + 11] = sz;
+    // active
+    pool[base + 12] = 1;
+
+    sys.activeCount++;
+  }
+
+  function emitParticle(systemId, overrides = {}) {
+    const sys = particleSystems.get(systemId);
+    if (sys) _spawnParticle(sys, overrides);
+  }
+
+  function burstParticles(systemId, count = 10, overrides = {}) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return;
+    for (let i = 0; i < count; i++) _spawnParticle(sys, overrides);
+  }
+
+  function updateParticles(dt) {
+    particleSystems.forEach(sys => {
+      const { pool, maxParticles, mesh, config, emitter } = sys;
+
+      // Auto-emit based on rate
+      sys.emitAccum += emitter.emitRate * dt;
+      while (sys.emitAccum >= 1 && sys.freeList.length > 0) {
+        _spawnParticle(sys);
+        sys.emitAccum -= 1;
+      }
+
+      let needsUpdate = false;
+
+      for (let i = 0; i < maxParticles; i++) {
+        const base = i * STRIDE;
+        if (pool[base + 12] === 0) continue; // inactive
+
+        // Step age
+        pool[base + 6] += dt;
+        const age = pool[base + 6];
+        const life = pool[base + 7];
+
+        if (age >= life) {
+          // Kill particle
+          pool[base + 12] = 0;
+          sys.freeList.push(i);
+          sys.activeCount--;
+
+          // Scale to zero
+          _dummy.position.set(0, -9999, 0);
+          _dummy.scale.set(0, 0, 0);
+          _dummy.updateMatrix();
+          mesh.setMatrixAt(i, _dummy.matrix);
+          needsUpdate = true;
+          continue;
+        }
+
+        // Physics integration
+        pool[base + 3] *= config.drag; // drag on vx
+        pool[base + 5] *= config.drag; // drag on vz
+        pool[base + 4] += config.gravity * dt; // gravity on vy
+
+        pool[base + 0] += pool[base + 3] * dt; // px
+        pool[base + 1] += pool[base + 4] * dt; // py
+        pool[base + 2] += pool[base + 5] * dt; // pz
+
+        // Interpolate color start→end
+        const t = age / life;
+        const r = pool[base + 8] * (1 - t) + config.endColor.r * t;
+        const g = pool[base + 9] * (1 - t) + config.endColor.g * t;
+        const b = pool[base + 10] * (1 - t) + config.endColor.b * t;
+        _color.setRGB(r, g, b);
+        mesh.setColorAt(i, _color);
+
+        // Shrink as particle ages
+        const sz = pool[base + 11] * (1 - t * 0.8);
+
+        _dummy.position.set(pool[base + 0], pool[base + 1], pool[base + 2]);
+        _dummy.scale.set(sz, sz, sz);
+        _dummy.updateMatrix();
+        mesh.setMatrixAt(i, _dummy.matrix);
+        needsUpdate = true;
+      }
+
+      if (needsUpdate) {
+        mesh.instanceMatrix.needsUpdate = true;
+        if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
+      }
+    });
+  }
+
+  function removeParticleSystem(systemId) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return false;
+    scene.remove(sys.mesh);
+    sys.mesh.geometry?.dispose();
+    sys.mesh.material?.dispose();
+    particleSystems.delete(systemId);
+    return true;
+  }
+
+  function getParticleStats(systemId) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return null;
+    return {
+      active: sys.activeCount,
+      max: sys.maxParticles,
+      free: sys.freeList.length,
+    };
+  }
+
+  return {
+    createParticleSystem,
+    setParticleEmitter,
+    emitParticle,
+    burstParticles,
+    updateParticles,
+    removeParticleSystem,
+    getParticleStats,
+  };
+}

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

@@ -0,0 +1,113 @@
+// runtime/api-3d/pbr.js
+// Normal maps, PBR roughness/metalness/AO maps
+
+import * as THREE from 'three';
+
+export function pbrModule({ meshes }) {
+  const _texLoader = new THREE.TextureLoader();
+
+  function loadNormalMap(url) {
+    return new Promise((resolve, reject) => {
+      _texLoader.load(
+        url,
+        texture => {
+          texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+          resolve(texture);
+        },
+        undefined,
+        err => reject(err)
+      );
+    });
+  }
+
+  function _upgradeToStandard(mesh) {
+    if (!mesh?.material) return;
+    if (mesh.material.isMeshStandardMaterial) return;
+    const old = mesh.material;
+    const standard = new THREE.MeshStandardMaterial({
+      color: old.color?.clone() ?? new THREE.Color(0xffffff),
+      map: old.map ?? null,
+      metalness: 0.0,
+      roughness: 0.6,
+      transparent: old.transparent ?? false,
+      opacity: old.opacity ?? 1.0,
+    });
+    old.dispose();
+    mesh.material = standard;
+  }
+
+  function setNormalMap(meshId, texture) {
+    const mesh = meshes.get(meshId);
+    if (!mesh) return false;
+    _upgradeToStandard(mesh);
+    mesh.material.normalMap = texture;
+    mesh.material.needsUpdate = true;
+    return true;
+  }
+
+  function setPBRMaps(meshId, maps = {}) {
+    const mesh = meshes.get(meshId);
+    if (!mesh) return false;
+    _upgradeToStandard(mesh);
+    const mat = mesh.material;
+    if (maps.normalMap) {
+      mat.normalMap = maps.normalMap;
+    }
+    if (maps.roughnessMap) {
+      mat.roughnessMap = maps.roughnessMap;
+    }
+    if (maps.aoMap) {
+      mat.aoMap = maps.aoMap;
+    }
+    if (maps.metalness !== undefined) mat.metalness = maps.metalness;
+    if (maps.roughness !== undefined) mat.roughness = maps.roughness;
+    mat.needsUpdate = true;
+    return true;
+  }
+
+  /**
+   * Set PBR scalar properties on a mesh without requiring texture maps.
+   * Clones the material so the change only affects this specific mesh.
+   *
+   * @param {number} meshId - ID returned by createSphere / createCube etc.
+   * @param {object} [opts]
+   * @param {number} [opts.metalness]        - 0 (dielectric) → 1 (fully metallic)
+   * @param {number} [opts.roughness]        - 0 (mirror-smooth) → 1 (fully rough)
+   * @param {number} [opts.envMapIntensity]  - Strength of environment reflections
+   * @param {number} [opts.color]            - Override surface colour (hex)
+   * @returns {boolean} true on success
+   */
+  function setPBRProperties(meshId, opts = {}) {
+    const mesh = meshes.get(meshId);
+    if (!mesh) return false;
+
+    // Replace with a fresh MeshStandardMaterial so we own it exclusively
+    // (avoids mutating a shared cached material that other meshes may use)
+    const old = mesh.material;
+    mesh.material = new THREE.MeshStandardMaterial({
+      color:
+        opts.color !== undefined
+          ? new THREE.Color(opts.color)
+          : (old.color?.clone() ?? new THREE.Color(0xffffff)),
+      map: old.map ?? null,
+      metalness:
+        opts.metalness !== undefined
+          ? Math.max(0, Math.min(1, opts.metalness))
+          : (old.metalness ?? 0.0),
+      roughness:
+        opts.roughness !== undefined
+          ? Math.max(0, Math.min(1, opts.roughness))
+          : (old.roughness ?? 0.6),
+      envMapIntensity: opts.envMapIntensity ?? old.envMapIntensity ?? 1.0,
+      emissive: old.emissive?.clone() ?? new THREE.Color(0),
+      emissiveIntensity: old.emissiveIntensity ?? 0,
+      transparent: old.transparent ?? false,
+      opacity: old.opacity ?? 1.0,
+      side: old.side ?? THREE.FrontSide,
+    });
+    mesh.material.needsUpdate = true;
+    return true;
+  }
+
+  return { loadNormalMap, setNormalMap, setPBRMaps, setPBRProperties };
+}

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