home / skills / bbeierle12 / skill-mcp-claude / particles-gpu
This skill helps you render thousands to millions of particles efficiently using GPU instancing, custom shaders, and Points geometry for high-performance
npx playbooks add skill bbeierle12/skill-mcp-claude --skill particles-gpuReview the files below or copy the command above to add this skill to your agents.
---
name: particles-gpu
description: GPU-based particle systems using instanced rendering, buffer attributes, Points geometry, and custom shaders. Use when rendering thousands to millions of particles efficiently, creating particle effects like snow, rain, stars, or abstract visualizations.
---
# GPU Particles
Render massive particle counts (10k-1M+) efficiently using GPU instancing and custom shaders.
## Quick Start
```tsx
import { useRef, useMemo } from 'react';
import { useFrame } from '@react-three/fiber';
import * as THREE from 'three';
function Particles({ count = 10000 }) {
const points = useRef<THREE.Points>(null!);
const positions = useMemo(() => {
const pos = new Float32Array(count * 3);
for (let i = 0; i < count; i++) {
pos[i * 3] = (Math.random() - 0.5) * 10;
pos[i * 3 + 1] = (Math.random() - 0.5) * 10;
pos[i * 3 + 2] = (Math.random() - 0.5) * 10;
}
return pos;
}, [count]);
return (
<points ref={points}>
<bufferGeometry>
<bufferAttribute
attach="attributes-position"
count={count}
array={positions}
itemSize={3}
/>
</bufferGeometry>
<pointsMaterial size={0.05} color="#ffffff" />
</points>
);
}
```
## Rendering Approaches
| Approach | Particle Count | Complexity | Use Case |
|----------|---------------|------------|----------|
| Points | 10k - 500k | Low | Simple particles, stars |
| Instanced Mesh | 1k - 100k | Medium | 3D geometry particles |
| Custom Shader | 100k - 10M | High | Maximum control |
## Points Geometry
Simplest approach—each particle is a screen-facing point sprite.
### Basic Points
```tsx
function BasicPoints({ count = 5000 }) {
const positions = useMemo(() => {
const pos = new Float32Array(count * 3);
for (let i = 0; i < count; i++) {
const theta = Math.random() * Math.PI * 2;
const phi = Math.acos(2 * Math.random() - 1);
const r = Math.cbrt(Math.random()) * 5;
pos[i * 3] = r * Math.sin(phi) * Math.cos(theta);
pos[i * 3 + 1] = r * Math.sin(phi) * Math.sin(theta);
pos[i * 3 + 2] = r * Math.cos(phi);
}
return pos;
}, [count]);
return (
<points>
<bufferGeometry>
<bufferAttribute
attach="attributes-position"
count={count}
array={positions}
itemSize={3}
/>
</bufferGeometry>
<pointsMaterial
size={0.1}
sizeAttenuation={true}
transparent={true}
opacity={0.8}
depthWrite={false}
blending={THREE.AdditiveBlending}
/>
</points>
);
}
```
### Points with Texture
```tsx
function TexturedPoints({ count = 5000 }) {
const texture = useTexture('/particle.png');
return (
<points>
<bufferGeometry>
{/* ... positions ... */}
</bufferGeometry>
<pointsMaterial
size={0.5}
map={texture}
transparent={true}
alphaTest={0.01}
depthWrite={false}
blending={THREE.AdditiveBlending}
/>
</points>
);
}
```
## Custom Attributes
Add per-particle data like color, size, velocity:
```tsx
function ColoredParticles({ count = 10000 }) {
const { positions, colors, sizes } = useMemo(() => {
const pos = new Float32Array(count * 3);
const col = new Float32Array(count * 3);
const siz = new Float32Array(count);
for (let i = 0; i < count; i++) {
// Position
pos[i * 3] = (Math.random() - 0.5) * 10;
pos[i * 3 + 1] = (Math.random() - 0.5) * 10;
pos[i * 3 + 2] = (Math.random() - 0.5) * 10;
// Color (HSL to RGB)
const color = new THREE.Color();
color.setHSL(Math.random(), 0.8, 0.5);
col[i * 3] = color.r;
col[i * 3 + 1] = color.g;
col[i * 3 + 2] = color.b;
// Size
siz[i] = 0.05 + Math.random() * 0.1;
}
return { positions: pos, colors: col, sizes: siz };
}, [count]);
return (
<points>
<bufferGeometry>
<bufferAttribute
attach="attributes-position"
count={count}
array={positions}
itemSize={3}
/>
<bufferAttribute
attach="attributes-color"
count={count}
array={colors}
itemSize={3}
/>
<bufferAttribute
attach="attributes-size"
count={count}
array={sizes}
itemSize={1}
/>
</bufferGeometry>
<pointsMaterial
vertexColors
size={0.1}
sizeAttenuation
transparent
depthWrite={false}
/>
</points>
);
}
```
## Custom Shader Particles
Maximum control over particle appearance and animation:
```tsx
const vertexShader = `
attribute float aSize;
attribute vec3 aColor;
attribute float aAlpha;
uniform float uTime;
uniform float uPixelRatio;
varying vec3 vColor;
varying float vAlpha;
void main() {
vColor = aColor;
vAlpha = aAlpha;
vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
// Size attenuation
gl_PointSize = aSize * uPixelRatio * (300.0 / -mvPosition.z);
gl_Position = projectionMatrix * mvPosition;
}
`;
const fragmentShader = `
varying vec3 vColor;
varying float vAlpha;
void main() {
// Circular particle
float dist = length(gl_PointCoord - 0.5);
if (dist > 0.5) discard;
// Soft edge
float alpha = 1.0 - smoothstep(0.4, 0.5, dist);
gl_FragColor = vec4(vColor, alpha * vAlpha);
}
`;
function ShaderParticles({ count = 50000 }) {
const points = useRef<THREE.Points>(null!);
const { positions, sizes, colors, alphas } = useMemo(() => {
const pos = new Float32Array(count * 3);
const siz = new Float32Array(count);
const col = new Float32Array(count * 3);
const alp = new Float32Array(count);
for (let i = 0; i < count; i++) {
pos[i * 3] = (Math.random() - 0.5) * 20;
pos[i * 3 + 1] = (Math.random() - 0.5) * 20;
pos[i * 3 + 2] = (Math.random() - 0.5) * 20;
siz[i] = 10 + Math.random() * 20;
const color = new THREE.Color();
color.setHSL(0.6 + Math.random() * 0.2, 0.8, 0.5);
col[i * 3] = color.r;
col[i * 3 + 1] = color.g;
col[i * 3 + 2] = color.b;
alp[i] = 0.3 + Math.random() * 0.7;
}
return { positions: pos, sizes: siz, colors: col, alphas: alp };
}, [count]);
useFrame(({ clock }) => {
points.current.material.uniforms.uTime.value = clock.elapsedTime;
});
return (
<points ref={points}>
<bufferGeometry>
<bufferAttribute attach="attributes-position" count={count} array={positions} itemSize={3} />
<bufferAttribute attach="attributes-aSize" count={count} array={sizes} itemSize={1} />
<bufferAttribute attach="attributes-aColor" count={count} array={colors} itemSize={3} />
<bufferAttribute attach="attributes-aAlpha" count={count} array={alphas} itemSize={1} />
</bufferGeometry>
<shaderMaterial
vertexShader={vertexShader}
fragmentShader={fragmentShader}
uniforms={{
uTime: { value: 0 },
uPixelRatio: { value: Math.min(window.devicePixelRatio, 2) }
}}
transparent
depthWrite={false}
blending={THREE.AdditiveBlending}
/>
</points>
);
}
```
## Animated Particles
### Position Animation in Shader
```glsl
// Vertex shader with animation
attribute vec3 aVelocity;
attribute float aPhase;
uniform float uTime;
void main() {
vec3 pos = position;
// Simple oscillation
pos.y += sin(uTime * 2.0 + aPhase) * 0.5;
// Velocity-based movement
pos += aVelocity * uTime;
// Wrap around bounds
pos = mod(pos + 10.0, 20.0) - 10.0;
vec4 mvPosition = modelViewMatrix * vec4(pos, 1.0);
gl_PointSize = 10.0 * (300.0 / -mvPosition.z);
gl_Position = projectionMatrix * mvPosition;
}
```
### CPU Animation (for dynamic systems)
```tsx
function AnimatedParticles({ count = 10000 }) {
const points = useRef<THREE.Points>(null!);
const velocities = useMemo(() => {
const vel = new Float32Array(count * 3);
for (let i = 0; i < count; i++) {
vel[i * 3] = (Math.random() - 0.5) * 0.02;
vel[i * 3 + 1] = (Math.random() - 0.5) * 0.02;
vel[i * 3 + 2] = (Math.random() - 0.5) * 0.02;
}
return vel;
}, [count]);
useFrame(() => {
const positions = points.current.geometry.attributes.position.array as Float32Array;
for (let i = 0; i < count; i++) {
positions[i * 3] += velocities[i * 3];
positions[i * 3 + 1] += velocities[i * 3 + 1];
positions[i * 3 + 2] += velocities[i * 3 + 2];
// Wrap around
for (let j = 0; j < 3; j++) {
if (positions[i * 3 + j] > 5) positions[i * 3 + j] = -5;
if (positions[i * 3 + j] < -5) positions[i * 3 + j] = 5;
}
}
points.current.geometry.attributes.position.needsUpdate = true;
});
// ... geometry setup
}
```
## Instanced Mesh Particles
For 3D geometry particles (not just points):
```tsx
function InstancedParticles({ count = 1000 }) {
const mesh = useRef<THREE.InstancedMesh>(null!);
const dummy = useMemo(() => new THREE.Object3D(), []);
useEffect(() => {
for (let i = 0; i < count; i++) {
dummy.position.set(
(Math.random() - 0.5) * 10,
(Math.random() - 0.5) * 10,
(Math.random() - 0.5) * 10
);
dummy.rotation.set(
Math.random() * Math.PI,
Math.random() * Math.PI,
0
);
dummy.scale.setScalar(0.05 + Math.random() * 0.1);
dummy.updateMatrix();
mesh.current.setMatrixAt(i, dummy.matrix);
}
mesh.current.instanceMatrix.needsUpdate = true;
}, [count, dummy]);
useFrame(({ clock }) => {
for (let i = 0; i < count; i++) {
mesh.current.getMatrixAt(i, dummy.matrix);
dummy.matrix.decompose(dummy.position, dummy.quaternion, dummy.scale);
dummy.rotation.x += 0.01;
dummy.rotation.y += 0.01;
dummy.updateMatrix();
mesh.current.setMatrixAt(i, dummy.matrix);
}
mesh.current.instanceMatrix.needsUpdate = true;
});
return (
<instancedMesh ref={mesh} args={[undefined, undefined, count]}>
<icosahedronGeometry args={[1, 0]} />
<meshStandardMaterial color="#ff6b6b" />
</instancedMesh>
);
}
```
## Buffer Geometry Patterns
### Sphere Distribution
```tsx
function spherePositions(count: number, radius: number) {
const positions = new Float32Array(count * 3);
for (let i = 0; i < count; i++) {
const theta = Math.random() * Math.PI * 2;
const phi = Math.acos(2 * Math.random() - 1);
const r = Math.cbrt(Math.random()) * radius; // Cube root for uniform volume
positions[i * 3] = r * Math.sin(phi) * Math.cos(theta);
positions[i * 3 + 1] = r * Math.sin(phi) * Math.sin(theta);
positions[i * 3 + 2] = r * Math.cos(phi);
}
return positions;
}
```
### Galaxy Spiral
```tsx
function galaxyPositions(count: number, arms: number, spin: number) {
const positions = new Float32Array(count * 3);
for (let i = 0; i < count; i++) {
const armIndex = i % arms;
const armAngle = (armIndex / arms) * Math.PI * 2;
const radius = Math.random() * 5;
const spinAngle = radius * spin;
const angle = armAngle + spinAngle;
// Add randomness
const randomX = (Math.random() - 0.5) * 0.5 * radius;
const randomY = (Math.random() - 0.5) * 0.2;
const randomZ = (Math.random() - 0.5) * 0.5 * radius;
positions[i * 3] = Math.cos(angle) * radius + randomX;
positions[i * 3 + 1] = randomY;
positions[i * 3 + 2] = Math.sin(angle) * radius + randomZ;
}
return positions;
}
```
### Grid Distribution
```tsx
function gridPositions(countPerAxis: number, spacing: number) {
const count = countPerAxis ** 3;
const positions = new Float32Array(count * 3);
const offset = (countPerAxis - 1) * spacing * 0.5;
let index = 0;
for (let x = 0; x < countPerAxis; x++) {
for (let y = 0; y < countPerAxis; y++) {
for (let z = 0; z < countPerAxis; z++) {
positions[index * 3] = x * spacing - offset;
positions[index * 3 + 1] = y * spacing - offset;
positions[index * 3 + 2] = z * spacing - offset;
index++;
}
}
}
return positions;
}
```
## Performance Tips
| Technique | Impact |
|-----------|--------|
| Use Points over InstancedMesh | 5-10x faster for simple particles |
| GPU animation (shader) vs CPU | 10-100x faster at scale |
| Disable depthWrite | Faster blending |
| Use Float32Array | Required for buffers |
| Frustum culling (default on) | Skip off-screen |
### Optimal Settings
```tsx
<pointsMaterial
transparent
depthWrite={false} // Faster blending
blending={THREE.AdditiveBlending} // Good for glowing particles
sizeAttenuation // Perspective-correct size
/>
```
## File Structure
```
particles-gpu/
├── SKILL.md
├── references/
│ ├── buffer-patterns.md # Distribution patterns
│ └── shader-examples.md # Complete shader examples
└── scripts/
├── particles/
│ ├── basic-points.tsx # Simple points setup
│ ├── shader-points.tsx # Custom shader particles
│ └── instanced.tsx # Instanced mesh particles
└── distributions/
├── sphere.ts # Sphere distribution
├── galaxy.ts # Galaxy spiral
└── grid.ts # Grid distribution
```
## Reference
- `references/buffer-patterns.md` — Position distribution patterns
- `references/shader-examples.md` — Complete particle shaders
This skill implements GPU-based particle systems using instanced rendering, buffer attributes, Points geometry, and custom shaders to render thousands to millions of particles efficiently. It provides patterns for positioning, per-particle attributes (color, size, velocity), and both CPU- and GPU-driven animation approaches. The goal is high-performance visual effects like snow, rain, starfields, and abstract generative visuals.
Particles are represented as BufferGeometry attributes and rendered with Points, InstancedMesh, or custom ShaderMaterial depending on needs. Per-particle data (position, color, size, velocity, alpha, etc.) is uploaded as Float32Array buffer attributes and can be animated either on the CPU by updating buffers or on the GPU via vertex/fragment shaders. The shader approach uses uniforms (time, pixel ratio) and varying values to control appearance, size attenuation, soft edges, and movement entirely on the GPU for maximum scale.
When should I animate on the CPU vs the GPU?
Use GPU animation for large counts (100k+) to avoid heavy CPU per-frame work. CPU animation is fine for smaller, highly interactive systems where you need per-particle logic on the CPU.
How do I keep particle sizes consistent across screens?
Apply size attenuation in the vertex shader and pass a uPixelRatio uniform (clamped) so gl_PointSize scales properly with device pixel ratio.