Enhance Terrain System Documentation and Editor Functionality

jonit-dev · jonit-dev · commit b86fa2a44bd3 · 2025-06-11T23:35:14.000-07:00
- Expanded the terrain system implementation document to include context, goals, current pain points, and a proposed solution with detailed architecture and directory structure.
- Introduced a new lighting category in the Enhanced Add Object Menu, allowing users to add various light types (Directional, Point, Spot, Ambient) to the scene.
- Updated the entity creation handlers to support new light types, enhancing the editor's capabilities for 3D scene development.
- Improved the geometry generation for spiral stairs, optimizing the creation process and ensuring better performance.

This commit aims to provide a comprehensive guide for the terrain system while enriching the editor's functionality for lighting and geometry creation.
diff --git a/docs/implementation/terrain-system.md b/docs/implementation/terrain-system.md
@@ -2,19 +2,70 @@
 
 ## Overview
 
-This document outlines the implementation plan for a comprehensive terrain system in Vibe Coder 3D. The terrain system will integrate seamlessly with the existing Unity-like editor architecture while providing specialized capabilities for large-scale landscape creation and editing.
+### Context & Goals
 
-## Architecture Decision: Hybrid Approach
+- **Landscape Creation Need**: Vibe Coder 3D currently lacks specialized tools for creating large-scale natural landscapes and environmental terrain, limiting users to basic geometric shapes for ground surfaces
+- **Unity-like Workflow**: Users expect familiar terrain creation tools similar to Unity's terrain system, with heightmap support, multi-layer texturing, and performance-optimized rendering
+- **Performance Requirements**: Large terrain systems need specialized LOD (Level of Detail) management and chunk-based rendering to maintain 60+ FPS with complex landscapes spanning hundreds of square kilometers
+- **Physics Integration**: Terrain must integrate seamlessly with the existing Rapier3D physics system using optimized `HeightfieldCollider` for realistic collision detection without performance degradation
 
-After analyzing the current Vibe Coder 3D architecture, we've chosen a **hybrid approach** that leverages the existing shape system while introducing specialized terrain subsystems. This approach provides the best balance of integration and performance optimization.
+### Current Pain Points
 
-### Why Hybrid Approach?
+- **Limited Ground Creation**: Users must create ground surfaces using scaled cubes or planes, which don't support natural landscape features like hills, valleys, or complex terrain topology
+- **No Heightmap Support**: The current system lacks ability to import real-world elevation data or create procedural terrain using noise functions and heightmaps
+- **Performance Issues with Large Surfaces**: Creating large ground areas using multiple primitive shapes causes performance bottlenecks due to excessive draw calls and physics calculations
+- **Missing Terrain Tools**: No specialized editing tools for terrain sculpting, texture blending, or environmental detail placement that are standard in modern 3D engines
 
-1. **Seamless Editor Integration**: Works with existing hierarchy, inspector, and entity management
-2. **Performance Optimization**: Enables terrain-specific optimizations without affecting other systems
-3. **Physics Compatibility**: Integrates with existing Rapier3D physics system
-4. **Familiar Workflow**: Maintains Unity-like entity creation and property editing patterns
-5. **Future Extensibility**: Clear path for advanced terrain features
+## Proposed Solution
+
+### High-level Summary
+
+- **Hybrid Integration Approach**: Extend the existing ECS component system with a specialized `Terrain` component that leverages current architecture while adding terrain-specific optimizations
+- **HeightfieldCollider Physics**: Utilize Rapier3D's native `HeightfieldCollider` for memory-efficient, high-performance terrain physics without requiring additional dependencies
+- **Multi-layer Texture System**: Implement custom shader-based texture blending supporting up to 8 terrain layers with height-based and slope-based automatic blending rules
+- **Chunk-based LOD Rendering**: Develop a streaming LOD system that dynamically loads/unloads terrain chunks based on camera distance, supporting massive terrains (1000x1000+ world units)
+- **Editor Tool Integration**: Create intuitive terrain creation and editing tools within the existing Unity-like editor interface, including heightmap import and basic sculpting capabilities
+
+### Architecture & Directory Structure
+
+```typescript
+src/
+├── core/
+│   ├── lib/
+│   │   ├── ecs/
+│   │   │   ├── components/
+│   │   │   │   ├── definitions/
+│   │   │   │   │   └── TerrainComponent.ts          # New terrain ECS component
+│   │   │   │   └── ComponentDefinitions.ts          # Register terrain component
+│   │   └── terrain/                                 # New terrain subsystem
+│   │       ├── TerrainGeometry.ts                   # Heightmap-based geometry generation
+│   │       ├── TerrainMaterial.ts                   # Multi-layer texture blending
+│   │       ├── TerrainPhysics.ts                    # HeightfieldCollider integration
+│   │       ├── TerrainLOD.ts                        # Level-of-detail management
+│   │       └── TerrainStreaming.ts                  # Chunk-based streaming system
+├── editor/
+│   ├── components/
+│   │   ├── menus/
+│   │   │   └── EnhancedAddObjectMenu.tsx            # Add terrain to menu
+│   │   ├── panels/
+│   │   │   ├── ViewportPanel/
+│   │   │   │   ├── components/
+│   │   │   │   │   ├── TerrainGeometry.tsx          # React Three Fiber integration
+│   │   │   │   │   ├── TerrainMaterial.tsx          # Material rendering component
+│   │   │   │   │   └── TerrainCollider.tsx          # Physics visualization
+│   │   │   └── InspectorPanel/
+│   │   │       └── Terrain/                         # New terrain inspector sections
+│   │   │           ├── TerrainSection.tsx           # Basic terrain properties
+│   │   │           ├── HeightmapSection.tsx         # Heightmap import/export
+│   │   │           ├── TextureSection.tsx           # Multi-layer texturing
+│   │   │           └── LODSection.tsx               # Performance settings
+│   │   └── terrain/                                 # New terrain-specific UI
+│   │       ├── HeightmapImporter.tsx                # Heightmap file handling
+│   │       ├── TextureLayerEditor.tsx               # Layer configuration
+│   │       └── TerrainPreview.tsx                   # Real-time preview
+│   └── types/
+│       └── shapes.ts                                # Add Terrain to ShapeType enum
+```
 
 ## Implementation Phases
 
diff --git a/src/editor/components/menus/EnhancedAddObjectMenu.tsx b/src/editor/components/menus/EnhancedAddObjectMenu.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-import { FiBox, FiFolder } from 'react-icons/fi';
+import { FiBox, FiFolder, FiSun, FiZap } from 'react-icons/fi';
 import {
   TbBox,
   TbBuildingBridge,
@@ -10,6 +10,7 @@ import {
   TbDiamond,
   TbHeart,
   TbHexagon,
+  TbLamp,
   TbMath,
   TbOctagon,
   TbPlus,
@@ -30,7 +31,7 @@ import { IMenuCategory, IMenuItemOption, NestedDropdownMenu } from './NestedDrop
 
 export interface IEnhancedAddObjectMenuProps {
   anchorRef: React.RefObject<HTMLElement>;
-  onAdd: (type: ShapeType) => void;
+  onAdd: (type: ShapeType | string) => void;
   onCustomModel?: () => void;
 }
 
@@ -203,6 +204,32 @@ const OBJECT_CATEGORIES: IMenuCategory[] = [
       },
     ],
   },
+  {
+    label: 'Lighting',
+    icon: <FiSun size={18} />,
+    items: [
+      {
+        type: 'DirectionalLight',
+        label: 'Directional Light',
+        icon: <TbLamp size={18} />,
+      },
+      {
+        type: 'PointLight',
+        label: 'Point Light',
+        icon: <FiZap size={18} />,
+      },
+      {
+        type: 'SpotLight',
+        label: 'Spot Light',
+        icon: <TbLamp size={18} />,
+      },
+      {
+        type: 'AmbientLight',
+        label: 'Ambient Light',
+        icon: <FiSun size={18} />,
+      },
+    ],
+  },
   {
     label: 'Assets',
     icon: <FiFolder size={18} />,
@@ -230,6 +257,13 @@ export const EnhancedAddObjectMenu: React.FC<IEnhancedAddObjectMenuProps> = ({
       return;
     }
 
+    // Handle light types
+    const lightTypes = ['DirectionalLight', 'PointLight', 'SpotLight', 'AmbientLight'];
+    if (lightTypes.includes(item.type as string)) {
+      onAdd(item.type as string);
+      return;
+    }
+
     // Handle all primitive shapes
     const validTypes: ShapeType[] = [
       ShapeType.Cube,
diff --git a/src/editor/components/panels/ViewportPanel/components/CustomGeometries.tsx b/src/editor/components/panels/ViewportPanel/components/CustomGeometries.tsx
@@ -342,66 +342,73 @@ export const SpiralStairsGeometry: React.FC<{
 
     let vertexOffset = 0;
 
-    // Create central pole - complete cylinder with caps
+    // --- Create Central Pole ---
+    // This creates a complete, solid cylinder with correct normals and caps.
     const poleSegments = 8;
+    const poleVertices: number[] = [];
+    const poleIndices: number[] = [];
+    const poleUvs: number[] = [];
+    let poleVertexCount = 0;
+
+    // Helper to add a vertex
+    const addVertex = (x: number, y: number, z: number, u: number, v: number) => {
+      poleVertices.push(x, y, z);
+      poleUvs.push(u, v);
+      return poleVertexCount++;
+    };
 
-    // Center vertices for caps
-    vertices.push(0, 0, 0); // Bottom center
-    vertices.push(0, height, 0); // Top center
-    uvs.push(0.5, 0.5);
-    uvs.push(0.5, 0.5);
-
-    const bottomCenterIndex = vertexOffset;
-    const topCenterIndex = vertexOffset + 1;
-    vertexOffset += 2;
-
-    // Create circle vertices for both top and bottom
-    const bottomVertices: number[] = [];
-    const topVertices: number[] = [];
-
-    for (let i = 0; i < poleSegments; i++) {
+    // --- Side Vertices ---
+    const sideVertexStartIndex = poleVertexCount;
+    for (let i = 0; i <= poleSegments; i++) {
       const angle = (i / poleSegments) * 2 * Math.PI;
       const x = Math.cos(angle) * innerRadius;
       const z = Math.sin(angle) * innerRadius;
-
-      // Bottom circle
-      vertices.push(x, 0, z);
-      uvs.push(0.5 + 0.5 * Math.cos(angle), 0.5 + 0.5 * Math.sin(angle));
-      bottomVertices.push(vertexOffset);
-      vertexOffset++;
-
-      // Top circle
-      vertices.push(x, height, z);
-      uvs.push(0.5 + 0.5 * Math.cos(angle), 0.5 + 0.5 * Math.sin(angle));
-      topVertices.push(vertexOffset);
-      vertexOffset++;
+      addVertex(x, 0, z, i / poleSegments, 0); // Bottom vertex
+      addVertex(x, height, z, i / poleSegments, 1); // Top vertex
     }
 
-    // Create side faces
+    // --- Side Faces ---
     for (let i = 0; i < poleSegments; i++) {
-      const next = (i + 1) % poleSegments;
+      const bl = sideVertexStartIndex + i * 2;
+      const tl = sideVertexStartIndex + i * 2 + 1;
+      const br = sideVertexStartIndex + (i + 1) * 2;
+      const tr = sideVertexStartIndex + (i + 1) * 2 + 1;
+      poleIndices.push(bl, br, tl, br, tr, tl);
+    }
 
-      const bottom1 = bottomVertices[i];
-      const bottom2 = bottomVertices[next];
-      const top1 = topVertices[i];
-      const top2 = topVertices[next];
+    // --- Cap Vertices & Faces ---
+    const createCap = (isTop: boolean) => {
+      const y = isTop ? height : 0;
+      const centerIdx = addVertex(0, y, 0, 0.5, 0.5);
+      const ringStartIndex = poleVertexCount;
+
+      for (let i = 0; i <= poleSegments; i++) {
+        const angle = (i / poleSegments) * 2 * Math.PI;
+        const x = Math.cos(angle) * innerRadius;
+        const z = Math.sin(angle) * innerRadius;
+        addVertex(x, y, z, 0.5 + Math.cos(angle) * 0.5, 0.5 + Math.sin(angle) * 0.5);
+      }
 
-      // Side quad (two triangles)
-      indices.push(bottom1, top1, bottom2);
-      indices.push(bottom2, top1, top2);
-    }
+      for (let i = 0; i < poleSegments; i++) {
+        const p1 = ringStartIndex + i;
+        const p2 = ringStartIndex + i + 1;
+        if (isTop) {
+          poleIndices.push(centerIdx, p1, p2);
+        } else {
+          poleIndices.push(centerIdx, p2, p1); // Flip winding for bottom cap
+        }
+      }
+    };
 
-    // Create bottom cap
-    for (let i = 0; i < poleSegments; i++) {
-      const next = (i + 1) % poleSegments;
-      indices.push(bottomCenterIndex, bottomVertices[next], bottomVertices[i]);
-    }
+    createCap(false); // Bottom cap
+    createCap(true); // Top cap
 
-    // Create top cap
-    for (let i = 0; i < poleSegments; i++) {
-      const next = (i + 1) % poleSegments;
-      indices.push(topCenterIndex, topVertices[i], topVertices[next]);
-    }
+    // --- Add pole to the main geometry ---
+    const baseVertexIndex = vertexOffset;
+    vertices.push(...poleVertices);
+    uvs.push(...poleUvs);
+    poleIndices.forEach((i) => indices.push(i + baseVertexIndex));
+    vertexOffset += poleVertexCount;
 
     // Create steps - simple rectangular treads
     for (let step = 0; step < steps; step++) {
diff --git a/src/editor/hooks/useEditorHandlers.ts b/src/editor/hooks/useEditorHandlers.ts
@@ -60,6 +60,10 @@ export const useEditorHandlers = ({
     createTube,
     createCross,
     createCustomModel,
+    createDirectionalLight,
+    createPointLight,
+    createSpotLight,
+    createAmbientLight,
   } = useEntityCreation();
 
   // Scene action hooks - get both new and legacy methods
@@ -80,7 +84,7 @@ export const useEditorHandlers = ({
 
   // Entity creation handler
   const handleAddObject = useCallback(
-    async (type: ShapeType, modelPath?: string) => {
+    async (type: ShapeType | string, modelPath?: string) => {
       try {
         let entity;
         switch (type) {
@@ -172,8 +176,20 @@ export const useEditorHandlers = ({
               throw new Error('CustomModel requires a modelPath');
             }
             break;
+          case 'DirectionalLight':
+            entity = createDirectionalLight();
+            break;
+          case 'PointLight':
+            entity = createPointLight();
+            break;
+          case 'SpotLight':
+            entity = createSpotLight();
+            break;
+          case 'AmbientLight':
+            entity = createAmbientLight();
+            break;
           default:
-            entity = createEntity(type);
+            entity = createEntity(type as string);
             break;
         }
 
@@ -218,6 +234,10 @@ export const useEditorHandlers = ({
       createCross,
       createCamera,
       createCustomModel,
+      createDirectionalLight,
+      createPointLight,
+      createSpotLight,
+      createAmbientLight,
       setSelectedId,
       setStatusMessage,
       setShowAddMenu,
