# Procedural Planets

Lague's quad-sphere tutorial, multi-octave noise, biome ramp, IBL.

```{raw} html
<a class="example-run-button" href="../demos/ports_procedural_planets.html">▶ Run in browser</a>
<p><strong>Upstream:</strong> <a href="https://github.com/SebLague/Procedural-Planets">https://github.com/SebLague/Procedural-Planets</a></p>
```

**Tags:** `port` `tier-2`

# Procedural Planets: SimVX Port

A SimVX port of [SebLague/Procedural-Planets](https://github.com/SebLague/Procedural-Planets) (E07 final episode). Builds a quad-sphere planet from 6 cube faces, displaces vertices with a stack of multi-octave Perlin (Simple FBM) and ridge noise filters, and shades the surface with a per-biome elevation ramp texture.

## Run

Interactive (Vulkan window, slider UI):

```
uv run python ported_games/procedural_planets/simvx_port/main.py
```

Headless screenshot capture (no GPU window: saves 8 staged screenshots
under `screenshots/`):

```
uv run python ported_games/procedural_planets/simvx_port/main.py --test
```

CPU-only smoke test (no Vulkan, no window: exercises the noise and mesh
build pipeline + sanity-checks performance budgets):

```
uv run python ported_games/procedural_planets/simvx_port/harness.py
```

Web export (WebGPU 3D pipeline, single standalone HTML):

```
uv run simvx export web ported_games/procedural_planets/simvx_port/main.py \
    -o ported_games/procedural_planets/simvx_port/web/index.html
```

## Controls

- `A` / `D` or `Left` / `Right`: orbit camera horizontally
- `W` / `S` or `Up` / `Down`: zoom in/out
- Mouse wheel: zoom in/out
- Right-click drag: orbit camera (yaw + pitch)
- `R`: force planet regenerate
- `Q` / `Esc`: quit
- Slider panel (bottom-left): drag to deform the planet in real time

## Files

- `main.py`: `PlanetRoot` scene + `--test` headless mode
- `nodes/shape.py`: `ShapeGenerator` (vectorised numpy port of upstream's noise filters)
- `nodes/terrain_face.py`: single quad-sphere face mesh builder
- `nodes/colour.py`: biome ramp texture + biome% sampler
- `nodes/planet.py`: `Planet(Node3D)` root with 6 face children + `regenerate()`
- `nodes/controls.py`: `SliderPanel` bottom-left UI
- `harness.py`: CPU-only smoke / perf test
- `assets/sky.hdr` (optional): equirectangular HDR skybox; falls back to a procedural blue gradient if absent
- `screenshots/`: `--test` output

See `../NOTES.md` for the engine-friction log and design deviations.


## Source

```{literalinclude} ../../examples/ports/procedural_planets/main.py
:language: python
:linenos:
```