GPU-accelerated boids flocking simulation with spatial grid optimization.

Features

• Classic boids rules: separation, alignment, cohesion with configurable weights
• Spatial grid acceleration (default) or naive O(N²) neighbor search
• 2D and 3D modes with boundary reflection
• Pointer-based interaction for user-driven steering
• Optional instanced mesh with automatic orientation from velocities
• Phase tracking for wing flapping animation sync
• Supports initialization from external samplers (e.g., ComputeBVHSampler)
• GPU culling support with custom instanceMatrix (Three.js r182+)

Architecture

• Compute passes: GPU init → velocity (neighbor influence) → position (integration)
• Spatial grid reduces neighbor search from O(N²) to O(N) via cell hashing
• Three behavioral zones: separation (repel), alignment (match velocity), cohesion (attract)
• Node-based instancing helper provides per-boid transform matrices for rendering

import { Boids, ComputeBVHSampler, ComputeInstanceCulling, instanceCullingIndex } from '@three-blocks/core';
import { ConeGeometry, InstancedMesh, MeshPhysicalNodeMaterial } from 'three/webgpu';

// Advanced: Initialize from ComputeBVHSampler with GPU culling (Three.js r182+)
const sampler = new ComputeBVHSampler(sdfGenerator, renderer, count);
await sampler.compute();

const boids = new Boids({
  count,
  is3D: true,
  domainDimensions: new THREE.Vector3(100, 100, 100),
  separation: 0.035,
  alignment: 0.04,
  cohesion: 0.03,
  useRelativeParameters: true,
  useMatrices: true, // Enable instance matrices for GPU culling
  initialPositions: sampler.positionsBuffer // Initialize from sampler
});

// Create mesh with custom instanceMatrix for GPU culling
const geometry = new ConeGeometry(0.15, 0.6, 4);
const material = new MeshPhysicalNodeMaterial({ color: 0xffffff });
const mesh = new InstancedMesh(geometry, material, count);
mesh.instanceMatrix = boids.buffers.instanceMatrices.value;
mesh.frustumCulled = true;
scene.add(mesh);

// Use culling index in material
const instanceCulling = new ComputeInstanceCulling(mesh, renderer);
const culledIndex = instanceCullingIndex(instanceCulling);
material.colorNode = boids.buffers.velocities.element(culledIndex).xyz.length()...;