Three.js Voxel Builder Development

Expert guidance for working with a modern Vue 3 + Three.js Voxel Builder application featuring WebGPU support, natural lighting, and urban planning visualization tools.

Project Overview

This skill provides specialized knowledge for developing and maintaining a sophisticated voxel building system with:

Development Commands

When starting work or building the project:

1. **Install dependencies**: `npm install`

2. **Start dev server**: `npm run dev`

3. **Build for production**: `npm run build` (includes TypeScript compilation)

4. **Preview production**: `npm run preview`

Core Architecture Understanding

Three View System

The application uses single-page navigation with three core views:

Navigation is handled in `src/App.vue` with reactive view switching.

WebGPU Support (October 2025)

ThreejsScene uses WebGPU for modern GPU-accelerated rendering:

**When working with WebGPU components:**

```typescript

// Import from three/webgpu

import * as THREE from 'three/webgpu'

// Use NodeMaterial variants

const material = new THREE.MeshStandardNodeMaterial({ color: 0x70f39e });

// Async renderer initialization

const renderer = new THREE.WebGPURenderer({ antialias: true });

await renderer.init();

// Use setAnimationLoop

renderer.setAnimationLoop(animate);

// Check WebGPU support

import { detectWebGPU } from './utils/webgpuDetector';

const support = await detectWebGPU();

```

Voxel Builder System

**Architecture approach**: One mesh per block for simplicity and reliability

**Key features:**

**Tool system:**

Component Architecture

**ThreejsScene** (`src/components/ThreejsScene.vue`) - WebGPU ⚡

**CityJSONViewer** (`src/components/CityJSONViewer.vue`)

**VoxelEngine** (`src/components/VoxelEngine.vue`)

Key Utility Classes

**CityJSONIntegration** (`src/utils/cityJsonIntegration.ts`)

```typescript

import { CityJSONIntegration } from './utils/cityJsonIntegration';

const integration = new CityJSONIntegration({

chunkSize: 2000,

onComplete: () => console.log('Loaded!')

});

const scene = await integration.loadCityJSON('/path/to/data.json');

```

**VoxelEngine System** (`src/utils/voxelEngine.ts`)

**Touch Interface** (`src/utils/touchInterface.ts`)

File Organization

```

src/

├── components/

│ ├── ThreejsScene.vue # Three.js WebGPU demo with animations

│ ├── CityJSONViewer.vue # Urban data visualization

│ └── VoxelEngine.vue # Minecraft-style editor

├── utils/

│ ├── geometryGenerator.ts # Three.js WebGPU geometry utilities

│ ├── webgpuDetector.ts # WebGPU browser compatibility detector

│ ├── cityJsonIntegration.ts # CityJSON wrapper class

│ ├── voxelEngine.ts # Voxel engine core systems

│ └── touchInterface.ts # Mobile gesture handling

├── App.vue # Main router with view switching

└── main.ts # Vue app entry point

```

Development Guidelines

TypeScript Configuration

Three.js Version Compatibility

**Current version**: Three.js 0.180.0 with WebGPU support

**Key changes from previous versions:**

Local Fork Strategy

**cityjson-threejs-loader:**

Voxel Engine Development

When working with the voxel system:

Performance Considerations

Implemented Features (January 2025)

3D Preview System ⭐

Complete Export/Import System

Advanced Voxel Engine

Testing Urban Data

The CityJSONViewer includes demo data generation for testing without external files. Use the built-in generator when developing new visualization features.

Migration History

When to Use This Skill

Use this skill when:

Constraints