Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 39 ยท Projects and Practice

Project: A Procedural Particle Galaxy

Generate a spiral galaxy with 100,000 GPU particles in Three.js: parametric arms, color gradients, a custom point shader, live sliders that rebuild geometry, and proper disposal.

This project is about scale. A galaxy is a hundred thousand tiny lights arranged in spiral arms, and you will build it with one Points object, one custom shader and about eighty lines of generator code. Along the way you practice the three skills that big Three.js scenes depend on: generating geometry from parameters, moving the animation work into the vertex shader, and rebuilding and disposing buffers safely when a slider changes.

The idea: a recipe for each star

Each star needs a position and a color. The recipe:

  1. Pick a radius r from the center, with more stars near the middle: r = random^k * maxRadius, where k > 1 pushes values toward 0.
  2. Pick an arm: with arms arms, star i belongs to arm i % arms, which sets a base angle arm / arms * 2ฯ€.
  3. Add a spin: the farther from the center, the more the angle is twisted: angle = baseAngle + r * spin. This turns straight spokes into spirals.
  4. Add randomness to the position, scaled by the radius and shaped with a power so that most stars sit close to the arm and a few drift away: offset = random^p * (random < 0.5 ? 1 : -1) * randomness * r.
  5. Color: blend from an inner color (hot, yellow-white) to an outer color (cool, blue) by r / maxRadius.

Galaxy generator parameters

arms, spin How many spirals and how tightly wound
randomness, power How far stars scatter from the arm
inner and outer color Gradient by radius
count, radius How many stars and how wide

Change one parameter and regenerate: you will understand each by seeing it.

1 / 2

Step 1: generate the geometry

A star's position is written straight into a Float32Array (three numbers per star), which becomes the position attribute. A second array holds colors. Using a seeded random function means the same parameters always produce the same galaxy, which is great for testing and for sharing a galaxy by its settings.

Step 1: the generator with PointsMaterial

Additive blending (AdditiveBlending) makes overlapping stars add their light, which creates the bright core without any extra work, and depthWrite: false stops stars from hiding each other. This version rotates the entire object on the CPU, which turns the galaxy like a rigid disc. Real galaxies rotate differentially: the inner stars go around faster than the outer ones. That needs per-star motion, which is the job of a vertex shader.

Step 2: a custom shader and live controls

Moving 100,000 stars on the CPU every frame would take real time. Instead the shader rotates each star around the Y axis by an angle that depends on its radius and uTime. The CPU only updates one number per frame. The same shader controls the star size (bigger when closer, with a per-star random scale attribute) and draws a soft round point.

The sliders change count, arms, spin and randomness. Moving a slider calls rebuild(), which creates new buffers and disposes the old geometry. This is the point of the exercise: forgetting geometry.dispose() there would leak GPU memory on every slider tick.

Step 2: a shader galaxy you can reshape

Drag the sliders and watch "geometries on GPU": it stays at 1, because every rebuild disposes the previous geometry. If you comment out the dispose() line it climbs with every change, which is exactly the leak the previous chapter warned about. The "draw calls" stay at 1 for 200,000 stars.

How the shader works

  • atan(p.x, p.z) and length(p.xz) convert the star from (x, z) to a polar angle and radius.
  • The angle advances by uTime * 0.6 / (1 + r * 0.6): the larger r, the slower the angular speed. This gives differential rotation, with a twist that never winds up because it is applied as a rotation of existing positions, not an accumulating offset.
  • gl_PointSize shrinks with distance (1 / -mv.z) and is multiplied by uPixelRatio, since point sizes are in device pixels.
  • vertexColors: true on ShaderMaterial makes Three.js declare the color attribute for you.

Ideas to extend it

  1. Mouse interaction: pass the pointer ray as a uniform and push nearby stars away (a vertex shader distance check) for a repelling effect.
  2. Bloom: add UnrealBloomPass from post-processing; the glow of the core becomes cinematic.
  3. A black hole at the center: a dark sphere with a bright accretion ring made with a ring geometry and a shader.
  4. Twinkle: add aPhase and modulate strength with sin(uTime * 3.0 + aPhase).
  5. Tween the parameters when the user changes a preset, by also passing the previous positions as an attribute and mixing them with uMix in the shader (morph between two galaxies on the GPU).
  6. Performance modes: detect low-end devices (renderer.capabilities, navigator.hardwareConcurrency) and default to 30,000 stars.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the generator use Math.pow(random, concentration) for the radius?

    random^k with k > 1 skews numbers toward zero, giving a dense core and sparser outer arms.
  2. 2. Why is rotation done in the vertex shader instead of on the CPU for each star?

    Per-star work on the CPU costs time every frame. In a vertex shader the GPU does it for every vertex in parallel.
  3. 3. What goes wrong if rebuild() forgets points.geometry.dispose()?

    GPU resources are released only by dispose(). Without it, memory grows each time you rebuild.
  4. 4. Why set frustumCulled = false on the Points object?

    Culling uses the original geometry's bounds. If the shader displaces vertices, those bounds may not match what is drawn.

Summary

  • A galaxy is a recipe: radius skewed to the center, arm angle plus spin, randomness shaped by a power, and a color gradient.
  • Points with additive blending draws huge star counts in one call; a seeded random function makes results repeatable.
  • A custom vertex shader performs differential rotation and size attenuation on the GPU with a single time uniform.
  • When parameters change, build new buffers, dispose the old geometry and debounce the rebuild.
  • Check renderer.info to confirm one draw call and a stable geometry count.

Next: Three.js Practice Challenges