@directivegames/genesys.js 3.1.28 → 3.1.30

package/src/components/visual/SplineMeshComponent.ts

@@ -0,0 +1,421 @@
+/**
+ * SplineMeshComponent generates a flat ribbon mesh along a Catmull-Rom spline.
+ *
+ * Use cases include roads, paths, rivers, and any geometry that follows a curved path.
+ * The component samples points along the spline and creates a ribbon with proper
+ * UV mapping for texture tiling based on world distance.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Provide an array of control points defining the path
+ * - Adjust width, segments, and tension for desired appearance
+ * - Use uvScale to control texture tiling density
+ * - Enable showDebug to visualize control points and spline curve
+ */
+import * as THREE from 'three';
+
+import { MaterialUtils } from '../../materials.js';
+import { EngineClass } from '../../systems/ClassRegistry.js';
+import { resourceManager } from '../../utils/ResourceManager.js';
+import { isNode } from '../../utils/Utils.js';
+import { PrimitiveComponent } from '../PrimitiveComponent.js';
+
+import type { GenericMaterialType } from '../../materials.js';
+import type { EditorClassMeta, EditorPropertyChangedResult } from '../../utils/EditorClassMeta.js';
+import type { PrimitiveComponentOptions } from '../PrimitiveComponent.js';
+
+export interface SplineMeshComponentOptions extends PrimitiveComponentOptions {
+  /** Control points defining the spline path */
+  points?: THREE.Vector3[];
+  /** Width of the ribbon mesh (default: 1) */
+  width?: number;
+  /** Number of segments along the spline (default: 50) */
+  segments?: number;
+  /** Whether the spline forms a closed loop (default: false) */
+  closed?: boolean;
+  /** Catmull-Rom tension parameter (default: 0.5) */
+  tension?: number;
+  /** UV tiles per world unit along the spline (default: 1) */
+  uvScale?: number;
+  /** Material for the mesh (path to material JSON or THREE.Material instance) */
+  material?: GenericMaterialType;
+  /** Show debug visualization of control points and spline (default: false) */
+  showDebug?: boolean;
+}
+
+@EngineClass('SplineMeshComponent')
+export class SplineMeshComponent extends PrimitiveComponent<SplineMeshComponentOptions> {
+  private mesh: THREE.Mesh | null = null;
+  private curve: THREE.CatmullRomCurve3 | null = null;
+  private debugGroup: THREE.Group | null = null;
+
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    ...PrimitiveComponent.EDITOR_CLASS_META,
+    points: { array: { child: { type: THREE.Vector3 } } },
+    width: { number: { min: 0.1, max: 100, step: 0.1, decimals: 2 } },
+    segments: { integer: { min: 2, max: 500, step: 1 } },
+    tension: { number: { min: 0, max: 1, step: 0.05, decimals: 2 } },
+    uvScale: { number: { min: 0.01, max: 10, step: 0.1, decimals: 2 } },
+    closed: { boolean: {} },
+    showDebug: { boolean: {} },
+    material: { type: ['material'] },
+  } as const;
+
+  static override get DEFAULT_OPTIONS(): SplineMeshComponentOptions {
+    return {
+      ...PrimitiveComponent.DEFAULT_OPTIONS,
+      // Provide default starter points so the spline is visible when created
+      points: [
+        new THREE.Vector3(-2, 0, 0),
+        new THREE.Vector3(0, 0, 1),
+        new THREE.Vector3(2, 0, 0),
+      ],
+      width: 1,
+      segments: 50,
+      closed: false,
+      tension: 0.5,
+      uvScale: 1,
+      material: '',  // Asset path to material JSON file
+      showDebug: false,
+      physicsOptions: {
+        ...PrimitiveComponent.DEFAULT_PHYSICS_OPTIONS,
+        enabled: false,
+      },
+    };
+  }
+
+  constructor(options: SplineMeshComponentOptions = {}) {
+    super(options);
+    this.rebuildMesh();
+  }
+
+  /**
+   * Returns the THREE.Mesh object associated with this component
+   */
+  public getMesh(): THREE.Mesh | null {
+    return this.mesh;
+  }
+
+  /**
+   * Returns the underlying Catmull-Rom curve
+   */
+  public getCurve(): THREE.CatmullRomCurve3 | null {
+    return this.curve;
+  }
+
+  /**
+   * Sets new control points and rebuilds the mesh
+   */
+  public setPoints(points: THREE.Vector3[]): void {
+    this.options.points = points;
+    this.rebuildMesh();
+  }
+
+  /**
+   * Sets the ribbon width and rebuilds the mesh
+   */
+  public setWidth(width: number): void {
+    this.options.width = width;
+    this.rebuildMesh();
+  }
+
+  /**
+   * Sets the segment count and rebuilds the mesh
+   */
+  public setSegments(segments: number): void {
+    this.options.segments = segments;
+    this.rebuildMesh();
+  }
+
+  /**
+   * Sets the Catmull-Rom tension and rebuilds the mesh
+   */
+  public setTension(tension: number): void {
+    this.options.tension = tension;
+    this.rebuildMesh();
+  }
+
+  /**
+   * Sets the UV scale and rebuilds the mesh
+   */
+  public setUvScale(uvScale: number): void {
+    this.options.uvScale = uvScale;
+    this.rebuildMesh();
+  }
+
+  /**
+   * Sets whether the spline is closed and rebuilds the mesh
+   */
+  public setClosed(closed: boolean): void {
+    this.options.closed = closed;
+    this.rebuildMesh();
+  }
+
+  /**
+   * Sets the material for the mesh
+   */
+  public setMaterial(material: GenericMaterialType): void {
+    this.options.material = material;
+    if (this.mesh) {
+      resourceManager.loadGenericMaterial(material).then((loadedMaterial) => {
+        if (loadedMaterial && this.mesh) {
+          this.mesh.material = loadedMaterial;
+        }
+      });
+    } else {
+      // Mesh doesn't exist yet - rebuild to create it with the new material
+      this.rebuildMesh();
+    }
+  }
+
+  /**
+   * Toggles debug visualization
+   */
+  public setShowDebug(show: boolean): void {
+    this.options.showDebug = show;
+    this.updateDebugVisualization();
+  }
+
+  /**
+   * Rebuilds the ribbon mesh based on current options
+   */
+  public rebuildMesh(): void {
+    // Filter out null/undefined points and ensure they are Vector3 instances
+    // (points may be plain {x,y,z} objects after deserialization)
+    const rawPoints = this.options.points ?? [];
+    const points = rawPoints
+      .filter((p): p is THREE.Vector3 => p != null)
+      .map(p => p instanceof THREE.Vector3 ? p : new THREE.Vector3((p as any).x, (p as any).y, (p as any).z));
+    if (points.length < 2) {
+      this.clearMesh();
+      return;
+    }
+
+    // Create the Catmull-Rom curve
+    this.curve = new THREE.CatmullRomCurve3(
+      points,
+      this.options.closed ?? false,
+      'catmullrom',
+      this.options.tension ?? 0.5
+    );
+
+    const segments = this.options.segments ?? 50;
+    const width = this.options.width ?? 1;
+    const uvScale = this.options.uvScale ?? 1;
+    const halfWidth = width / 2;
+
+    // Generate geometry
+    const geometry = this.generateRibbonGeometry(this.curve, segments, halfWidth, uvScale);
+
+    // Remove old mesh if exists
+    if (this.mesh) {
+      this.mesh.removeFromParent();
+      this.mesh.geometry.dispose();
+    }
+
+    // Create new mesh with default material initially
+    this.mesh = new THREE.Mesh(geometry, MaterialUtils.DefaultMaterial);
+    this.mesh.setTransient(true);
+    this.bindObject3DProperties(this.mesh, ['castShadow', 'receiveShadow']);
+    this.add(this.mesh);
+
+    // Load material if specified
+    if (!isNode() && this.options.material) {
+      resourceManager.loadGenericMaterial(this.options.material).then((loadedMaterial) => {
+        if (loadedMaterial && this.mesh) {
+          this.mesh.material = loadedMaterial;
+        }
+      });
+    }
+
+    // Update debug visualization
+    this.updateDebugVisualization();
+  }
+
+  /**
+   * Generates a ribbon geometry along the curve
+   */
+  private generateRibbonGeometry(
+    curve: THREE.CatmullRomCurve3,
+    segments: number,
+    halfWidth: number,
+    uvScale: number
+  ): THREE.BufferGeometry {
+    const vertices: number[] = [];
+    const normals: number[] = [];
+    const uvs: number[] = [];
+    const indices: number[] = [];
+
+    const totalLength = curve.getLength();
+    const up = new THREE.Vector3(0, 1, 0);
+    const tempTangent = new THREE.Vector3();
+    const tempNormal = new THREE.Vector3();
+    const tempBinormal = new THREE.Vector3();
+
+    // Sample points along the curve
+    for (let i = 0; i <= segments; i++) {
+      const t = i / segments;
+      const point = curve.getPointAt(t);
+      const tangent = curve.getTangentAt(t).normalize();
+
+      // Calculate binormal (perpendicular to tangent and up)
+      tempBinormal.crossVectors(up, tangent).normalize();
+
+      // Handle degenerate case when tangent is parallel to up
+      if (tempBinormal.lengthSq() < 0.001) {
+        tempBinormal.set(1, 0, 0);
+      }
+
+      // Calculate normal (perpendicular to tangent and binormal)
+      tempNormal.crossVectors(tangent, tempBinormal).normalize();
+
+      // Create two vertices at this point (left and right edges)
+      const leftPoint = point.clone().addScaledVector(tempBinormal, -halfWidth);
+      const rightPoint = point.clone().addScaledVector(tempBinormal, halfWidth);
+
+      vertices.push(leftPoint.x, leftPoint.y, leftPoint.z);
+      vertices.push(rightPoint.x, rightPoint.y, rightPoint.z);
+
+      // Normals point up
+      normals.push(tempNormal.x, tempNormal.y, tempNormal.z);
+      normals.push(tempNormal.x, tempNormal.y, tempNormal.z);
+
+      // UVs: U tiles along length based on world distance, V is 0-1 across width
+      const distanceAlongCurve = t * totalLength;
+      const u = distanceAlongCurve * uvScale;
+      uvs.push(u, 0); // Left edge
+      uvs.push(u, 1); // Right edge
+    }
+
+    // Generate indices for triangle strip (CCW winding for upward-facing normals)
+    for (let i = 0; i < segments; i++) {
+      const baseIndex = i * 2;
+
+      // First triangle: left[i] -> left[i+1] -> right[i]
+      indices.push(baseIndex, baseIndex + 2, baseIndex + 1);
+      // Second triangle: right[i] -> left[i+1] -> right[i+1]
+      indices.push(baseIndex + 1, baseIndex + 2, baseIndex + 3);
+    }
+
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute('position', new THREE.Float32BufferAttribute(vertices, 3));
+    geometry.setAttribute('normal', new THREE.Float32BufferAttribute(normals, 3));
+    geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2));
+    geometry.setIndex(indices);
+
+    return geometry;
+  }
+
+  /**
+   * Clears the current mesh
+   */
+  private clearMesh(): void {
+    if (this.mesh) {
+      this.mesh.removeFromParent();
+      this.mesh.geometry.dispose();
+      this.mesh = null;
+    }
+    this.curve = null;
+    this.clearDebugVisualization();
+  }
+
+  /**
+   * Updates debug visualization showing control points and spline
+   */
+  private updateDebugVisualization(): void {
+    this.clearDebugVisualization();
+
+    if (!this.options.showDebug || !this.curve) {
+      return;
+    }
+
+    this.debugGroup = new THREE.Group();
+    this.debugGroup.setTransient(true);
+
+    // Filter out null/undefined points and ensure they are Vector3 instances
+    const rawPoints = this.options.points ?? [];
+    const points = rawPoints
+      .filter((p): p is THREE.Vector3 => p != null)
+      .map(p => p instanceof THREE.Vector3 ? p : new THREE.Vector3((p as any).x, (p as any).y, (p as any).z));
+
+    // Draw control point spheres
+    const sphereGeometry = new THREE.SphereGeometry(0.15);
+    const sphereMaterial = new THREE.MeshBasicMaterial({ color: 0xff0000 });
+
+    for (let i = 0; i < points.length; i++) {
+      const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
+      sphere.position.copy(points[i]);
+      this.debugGroup.add(sphere);
+    }
+
+    // Draw spline curve line
+    const curvePoints = this.curve.getPoints(100);
+    const lineGeometry = new THREE.BufferGeometry().setFromPoints(curvePoints);
+    const lineMaterial = new THREE.LineBasicMaterial({ color: 0x00ff00 });
+    const line = new THREE.Line(lineGeometry, lineMaterial);
+    this.debugGroup.add(line);
+
+    // Draw tangent indicators at control points
+    const arrowMaterial = new THREE.LineBasicMaterial({ color: 0x0000ff });
+    for (let i = 0; i < points.length; i++) {
+      const t = this.options.closed ? i / points.length : i / (points.length - 1);
+      const tangent = this.curve.getTangentAt(Math.min(t, 1)).normalize();
+      const arrowPoints = [
+        points[i].clone(),
+        points[i].clone().addScaledVector(tangent, 0.5)
+      ];
+      const arrowGeometry = new THREE.BufferGeometry().setFromPoints(arrowPoints);
+      const arrow = new THREE.Line(arrowGeometry, arrowMaterial);
+      this.debugGroup.add(arrow);
+    }
+
+    this.add(this.debugGroup);
+  }
+
+  /**
+   * Clears debug visualization
+   */
+  private clearDebugVisualization(): void {
+    if (this.debugGroup) {
+      this.debugGroup.removeFromParent();
+      this.debugGroup.traverse((child) => {
+        if (child instanceof THREE.Mesh || child instanceof THREE.Line) {
+          child.geometry.dispose();
+          if (Array.isArray(child.material)) {
+            child.material.forEach(m => m.dispose());
+          } else {
+            child.material.dispose();
+          }
+        }
+      });
+      this.debugGroup = null;
+    }
+  }
+
+  public override calcBoundingBox(): void {
+    if (this.mesh) {
+      this.mesh.geometry.computeBoundingBox();
+      this._boundingBox.copy(this.mesh.geometry.boundingBox!).applyMatrix4(this.mesh.matrixWorld);
+    }
+  }
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_Path';
+  }
+
+  public override onEditorPropertyChanged(path: string, value: any, result: EditorPropertyChangedResult): void {
+    super.onEditorPropertyChanged(path, value, result);
+
+    // Rebuild mesh when any spline-related property changes
+    if (result.isOptions) {
+      if (path === 'material') {
+        this.setMaterial(value);
+      } else if (path === 'points' || path.startsWith('points[') || path.startsWith('points.')) {
+        // Handle array changes: full replacement, element changes, or property changes
+        this.rebuildMesh();
+      } else if (['width', 'segments', 'tension', 'uvScale', 'closed', 'showDebug'].includes(path)) {
+        this.rebuildMesh();
+      }
+    }
+  }
+}
+

package/src/components/visual/index.ts

@@ -21,3 +21,4 @@ export * from './TerrainMeshComponent.js';
 export * from './SkyboxComponent.js';
 export * from './FogComponent.js';
 export * from './UI3DComponent.js';
+export * from './SplineMeshComponent.js';