Procedural Planets

quad-sphere terrain built from layered noise and shaded by a biome ramp.

▶ Run in browser

Upstream: https://github.com/SebLague/Procedural-Planets

Licence: this port's own code is offered under MIT, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-2

Procedural Planets: SimVX Port

A SimVX port of SebLague/Procedural-Planets (E07, the 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

# from the repo root
uv run python examples/ports/procedural_planets/main.py            # interactive
uv run python examples/ports/procedural_planets/main.py --test     # headless capture (8 staged screenshots in screenshots/)
uv run python examples/ports/procedural_planets/harness.py         # CPU-only noise + mesh smoke test (no Vulkan)
uv run simvx export web examples/ports/procedural_planets/main.py \
    -o /tmp/procedural_planets.html

Controls

The port opens on a title card: click, or press Space / Enter, to dismiss it and bring up the slider panel. The bottom strip then summarises the drag, scroll and key controls while you play.

• Drag anywhere off the UI (the slider panel and the bottom strip): orbit the camera (yaw + pitch)

• Mouse wheel, or a two-finger pinch on touch: zoom in/out

• A / D or Left / Right: orbit camera horizontally

• W / S or Up / Down: zoom in/out

• 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

• nodes/title.py: TitleOverlay title card

• 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

Deviations from upstream

• The noise filters are evaluated a whole cube face at a time with NumPy rather than per vertex, which is what makes editing the planet interactively viable at all. A full six-face rebuild is still far too slow to hide inside one frame in pure Python (of the order of 100 ms at the default resolution of 64, and close to a second at the slider’s 192 maximum), which is why slider drags coalesce their rebuilds. Run harness.py to time it on your machine.

• Elevation min/max is locked by a pre-flight pass over all six faces before any mesh is built, so the biome ramp lines up across face seams.

• Slider drags request a regenerate rather than performing one: the request is coalesced to at most one rebuild every few frames.

Source files

File	Summary	Lines
main.py	Procedural Planets: quad-sphere terrain built from layered noise and shaded by a biome ramp.	460
harness.py	Procedural Planets: CPU-only harness.	89
nodes/__init__.py	Procedural Planets: port nodes.	44
nodes/colour.py	Biome colour ramp generator: port of Lague’s ColourGenerator.	252
nodes/controls.py	SliderPanel: bottom-left anchored noise sliders.	177
nodes/planet.py	Planet: root 3D node owning 6 cube-face MeshInstance3D children.	133
nodes/shape.py	Shape generator: vectorised numpy port of Lague’s ShapeGenerator + noise filters.	236
nodes/terrain_face.py	Single quad-sphere face: vectorised port of Lague’s TerrainFace.	139
nodes/title.py	TitleOverlay: the title card the port opens on, before the planet is interactive.	73

Source

"""Procedural Planets: quad-sphere terrain built from layered noise and shaded by a biome ramp.

# /// simvx
# tags = ["port", "tier-2"]
# upstream = "https://github.com/SebLague/Procedural-Planets"
# web = { width = 1280, height = 720, responsive = true }
# ///

A SimVX port of Sebastian Lague's Procedural Planets series. Six cube faces are
normalised onto a sphere and displaced by a stack of multi-octave Perlin and
ridge noise filters, evaluated a whole face at a time with NumPy on top of
SimVX's `FastNoiseLite`. Elevation drives a per-biome colour ramp texture, and
the planet is lit by a directional sun inside a `WorldEnvironment` sky with
bloom. Drag the sliders to reshape the world while it turns: slider changes are
coalesced so a drag does not queue a rebuild per pixel. Each rebuild is still a
blocking numpy pass on the main thread, so expect a visible hitch that grows
with mesh resolution, from a fraction of a second at the default up to a few
seconds at the slider's maximum.

Drag anywhere outside the slider panel to orbit, scroll or pinch to zoom, `R`
rebuilds the mesh, `Q` or `Escape` quits.

Run:
    uv run python examples/ports/procedural_planets/main.py            # interactive
    uv run python examples/ports/procedural_planets/main.py --test     # headless capture
"""

from __future__ import annotations

import math
import sys
from collections.abc import Callable
from pathlib import Path

_PORT_DIR = Path(__file__).parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes.controls import SliderPanel, apply_slider_value  # noqa: E402
from nodes.planet import Planet  # noqa: E402
from nodes.title import TitleOverlay  # noqa: E402

from simvx.core import (  # noqa: E402
    DirectionalLight3D,
    GestureRecognizer,
    Input,
    Key,
    MouseButton,
    Node,
    OrbitCamera3D,
    Vec3,
    WorldEnvironment,
)
from simvx.core.ui import BottomControlsStrip  # noqa: E402
from simvx.graphics import App  # noqa: E402

WIDTH = 1280
HEIGHT = 720

MIN_DISTANCE = 2.4
MAX_DISTANCE = 20.0
STRIP_HEIGHT = 32.0

CONTROL_HINTS = [
    "DRAG to orbit",
    "SCROLL or PINCH to zoom",
    "A/D W/S to orbit and zoom",
    "R to regenerate",
    "Q to quit",
]


# ---------------------------------------------------------------------------
# HDR skybox helper: falls back to procedural blue if no .hdr is present
# ---------------------------------------------------------------------------


def _make_environment_map() -> dict:
    """Return the environment_map spec for WorldEnvironment.

    If `assets/sky.hdr` exists, load it as an equirectangular HDR cubemap;
    otherwise return a procedural gradient (deep blue) that the renderer
    converts to a cubemap on first install.
    """
    hdr_path = _PORT_DIR / "assets" / "sky.hdr"
    if hdr_path.exists():
        return {"path": str(hdr_path)}
    return {"colour": (0.05, 0.07, 0.15)}


# ---------------------------------------------------------------------------
# Root scene
# ---------------------------------------------------------------------------


class PlanetRoot(Node):
    """Root: WorldEnvironment + OrbitCamera3D + DirectionalLight3D + Planet + UI.

    Args:
        headless: Skip the title card and the slider panel so `--test` captures
            render the planet alone.
        show_panel: Force the slider panel on or off; defaults to "on once the
            title card is dismissed".
    """

    # The canonical registration path: the scene tree consumes this at mount,
    # which also covers the web export (it never calls `main()`).
    input_actions = {
        "orbit": [MouseButton.LEFT, MouseButton.RIGHT],
        "orbit_left": [Key.A, Key.LEFT],
        "orbit_right": [Key.D, Key.RIGHT],
        "zoom_in": [Key.W, Key.UP],
        "zoom_out": [Key.S, Key.DOWN],
        "start": [Key.SPACE, Key.ENTER],
        "regen": [Key.R],
        "quit": [Key.ESCAPE, Key.Q],
    }

    def __init__(self, *, headless: bool = False, show_panel: bool | None = None, **kwargs) -> None:
        super().__init__(**kwargs)
        self._headless = headless
        self._show_panel = (not headless) if show_panel is None else show_panel
        self._panel: SliderPanel | None = None
        self._strip: BottomControlsStrip | None = None
        self._menu: TitleOverlay | None = None
        # True while a pointer drag that began off the UI is orbiting the camera.
        self._dragging = False
        # Coalesce slider changes: regenerate at most once every K frames.
        self._regen_pending = False
        self._regen_cooldown = 0
        self._regen_pending_resolution: int | None = None

    def on_ready(self) -> None:
        # Environment + IBL: gradient skybox unless an HDR is sitting in
        # assets/sky.hdr. Bloom helps the specular highlight pop.
        env = WorldEnvironment(
            environment_map=_make_environment_map(),
        )
        env.bloom_enabled = True
        env.bloom_threshold = 1.05
        env.bloom_intensity = 0.5
        env.tonemap_exposure = 1.05
        self.add_child(env)

        # OrbitCamera3D derives its position from pivot/distance/yaw/pitch, so
        # the port never touches camera trigonometry. Angles are radians and a
        # negative pitch places the camera above the planet, looking down.
        self._cam = OrbitCamera3D(
            name="Camera",
            fov=55.0,
            near=0.05,
            far=200.0,
            distance=5.5,
            yaw=math.radians(25.0),
            pitch=math.radians(-18.0),
        )
        self.add_child(self._cam)

        # Sun.
        sun = DirectionalLight3D(name="Sun", intensity=1.6)
        sun.colour = (1.0, 0.97, 0.92)
        sun.position = Vec3(4.0, 3.0, 2.5)
        sun.look_at(Vec3(0.0, 0.0, 0.0))
        self.add_child(sun)

        # Planet.
        self.planet = Planet(resolution=64)
        self.add_child(self.planet)

        if self._headless:
            if self._show_panel:
                self.show_slider_panel()
            return

        # Two-finger pinch is the touch equivalent of the scroll wheel.
        gestures = GestureRecognizer(name="Gestures")
        gestures.pinch.connect(self._on_pinch)
        self.add_child(gestures)

        self._strip = BottomControlsStrip(hints=CONTROL_HINTS)
        self._strip.place_bottom_strip(STRIP_HEIGHT)
        self.add_child(self._strip)

        self._menu = TitleOverlay(self._start, controls=CONTROL_HINTS)
        self.add_child(self._menu)

    # ------------------------------------------------------------------
    # Title card
    # ------------------------------------------------------------------

    def _start(self) -> None:
        """Dismiss the title card and bring up the slider panel."""
        if self._menu is None:
            return
        self.remove_child(self._menu)
        self._menu = None
        if self._show_panel:
            self.show_slider_panel()

    def show_slider_panel(self) -> SliderPanel:
        """Add the noise-slider panel if it is not up already, and return it."""
        if self._panel is None:
            self._panel = SliderPanel(
                self.planet.shape_settings,
                self._on_slider,
                bottom_margin=STRIP_HEIGHT + 8.0,
            )
            self.add_child(self._panel)
        return self._panel

    def hide_slider_panel(self) -> None:
        """Remove the noise-slider panel if it is up."""
        if self._panel is not None:
            self.remove_child(self._panel)
            self._panel = None

    # ------------------------------------------------------------------
    # Camera
    # ------------------------------------------------------------------

    def set_view(self, yaw_deg: float, pitch_deg: float, distance: float) -> None:
        """Frame the planet from a fixed angle (used by the capture stages)."""
        self._cam.yaw = math.radians(yaw_deg)
        self._cam.pitch = math.radians(pitch_deg)
        self._cam.distance = max(MIN_DISTANCE, min(MAX_DISTANCE, distance))
        self._cam.update_transform()

    def _zoom(self, delta: float) -> None:
        """Move the camera `delta` units closer, clamped to the framing range."""
        self._cam.distance = max(MIN_DISTANCE, min(MAX_DISTANCE, self._cam.distance - delta))
        self._cam.update_transform()

    def _on_pinch(self, scale: float, _cx: float, _cy: float) -> None:
        self._zoom((scale - 1.0) * self._cam.distance)

    def _update_drag(self) -> None:
        """Orbit the camera while a pointer drag that began off the UI is held."""
        if Input.is_action_just_pressed("orbit"):
            self._dragging = not self._pointer_over_ui()
        if Input.is_action_just_released("orbit") or len(Input.touches) >= 2:
            # A second finger means the gesture is a pinch, not an orbit drag.
            self._dragging = False
        if not self._dragging:
            return
        delta = Input.mouse_delta
        if delta.x or delta.y:
            self._cam.orbit(math.radians(-delta.x * 0.4), math.radians(-delta.y * 0.3))

    def _pointer_over_ui(self) -> bool:
        """True when the cursor sits on the slider panel or the controls strip."""
        pos = Input.mouse_position
        return any(ctl is not None and ctl.is_point_inside(pos) for ctl in (self._panel, self._strip))

    # ------------------------------------------------------------------
    # Per-frame update
    # ------------------------------------------------------------------

    def on_update(self, dt: float) -> None:
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return

        # Idle planet rotation (slow, like upstream demo).
        self.planet.rotate_y(0.05 * dt)

        if self._menu is not None:
            # Any click or key starts, not just the button: touch users should
            # not have to find a 260 px target.
            if Input.is_action_just_pressed("start") or Input.is_action_just_pressed("orbit"):
                self._start()
            return

        # Keyboard orbit + zoom.
        if Input.is_action_pressed("orbit_left"):
            self._cam.orbit(math.radians(80.0 * dt), 0.0)
        if Input.is_action_pressed("orbit_right"):
            self._cam.orbit(math.radians(-80.0 * dt), 0.0)
        if Input.is_action_pressed("zoom_in"):
            self._zoom(4.0 * dt)
        if Input.is_action_pressed("zoom_out"):
            self._zoom(-4.0 * dt)
        if Input.is_action_just_pressed("regen"):
            self.planet.regenerate()

        self._update_drag()

        # Mouse-wheel zoom.
        wheel = Input.mouse_wheel_y
        if wheel:
            self._zoom(wheel * 0.5)

        # Coalesced regen.
        if self._regen_cooldown > 0:
            self._regen_cooldown -= 1
        if self._regen_pending and self._regen_cooldown <= 0:
            self._regen_pending = False
            self._regen_cooldown = 4
            if self._regen_pending_resolution is not None:
                self.planet.set_resolution(self._regen_pending_resolution)
                self._regen_pending_resolution = None
            else:
                self.planet.regenerate()

    # ------------------------------------------------------------------
    # Slider handling
    # ------------------------------------------------------------------

    def _on_slider(self, key: str, value: float) -> None:
        if key == "resolution":
            new_res = max(2, int(round(value)))
            if new_res != self.planet.resolution:
                # Resolution changes are heavier: defer with a 4-frame cooldown.
                self._regen_pending_resolution = new_res
                self._regen_pending = True
            return
        apply_slider_value(self.planet.shape_settings, key, value)
        self._regen_pending = True


# ---------------------------------------------------------------------------
# Headless capture mode
# ---------------------------------------------------------------------------


def _run_headless() -> None:
    """Capture 8 staged screenshots in a single run_headless invocation.

    Strategy: schedule each stage's mutator at a specific frame index. The
    mutator runs in `on_frame` (BEFORE the engine ticks/renders that frame),
    so by the time `capture_frame()` fires at the *end* of that frame, the
    scene reflects the new shape. We use 4 frames per stage so the
    mesh-rebuild cost amortises and we don't capture a half-built planet.
    """
    from nodes.controls import apply_slider_value as _apply
    from nodes.shape import default_shape_settings

    from simvx.graphics import save_png

    out_dir = _PORT_DIR / "screenshots"
    out_dir.mkdir(exist_ok=True)

    Mutator = Callable[[PlanetRoot], None]
    stages: list[tuple[str, Mutator]] = []

    def stage(name: str, fn: Mutator) -> None:
        stages.append((name, fn))

    stage("01_boot.png", lambda root: None)

    def smooth(root: PlanetRoot) -> None:
        s = default_shape_settings()
        s.layers[1].enabled = False
        root.planet.update_shape(s)

    stage("02_smooth.png", smooth)

    def ridged(root: PlanetRoot) -> None:
        s = default_shape_settings()
        _apply(s, "ridge_strength", 0.85)
        _apply(s, "base_strength", 0.25)
        root.planet.update_shape(s)

    stage("03_ridged.png", ridged)

    def low_elev(root: PlanetRoot) -> None:
        s = default_shape_settings()
        _apply(s, "base_strength", 0.05)
        _apply(s, "ridge_strength", 0.02)
        root.planet.update_shape(s)

    stage("04_low_elev.png", low_elev)

    def high_elev(root: PlanetRoot) -> None:
        s = default_shape_settings()
        _apply(s, "base_strength", 0.95)
        _apply(s, "ridge_strength", 0.85)
        root.planet.update_shape(s)

    stage("05_high_elev.png", high_elev)

    def mid_drag(root: PlanetRoot) -> None:
        # Mid-drag stage: slider panel is included so this screenshot doubles
        # as proof the UI renders (sized + anchored).
        s = default_shape_settings()
        _apply(s, "base_strength", 0.55)
        _apply(s, "ridge_strength", 0.45)
        _apply(s, "base_freq", 1.6)
        root.planet.update_shape(s)
        root.planet.set_resolution(48)
        # Only this stage shows the panel; the rest stay clean for the
        # planet-only beauty shots. queue_redraw forces a layout pass so the
        # panel is positioned this frame.
        root.show_slider_panel().queue_redraw()

    stage("06_dragging.png", mid_drag)

    def high_res(root: PlanetRoot) -> None:
        # Final high-detail render with moderately exaggerated terrain so the
        # extra resolution is visually obvious at framing distance.
        root.hide_slider_panel()
        s = default_shape_settings()
        _apply(s, "base_strength", 0.45)
        _apply(s, "ridge_strength", 0.7)
        _apply(s, "base_freq", 1.4)
        root.planet.update_shape(s)
        root.planet.set_resolution(160)

    stage("07_high_res.png", high_res)

    def cinematic(root: PlanetRoot) -> None:
        root.set_view(yaw_deg=90.0, pitch_deg=-28.0, distance=5.0)

    stage("08_orbit.png", cinematic)

    # Per-stage budget: 4 frames (mutate, settle, render, capture).
    settle_frames = 4
    capture_indices: list[int] = []
    boot_frames = 4  # let the planet build before the first capture
    capture_indices.append(boot_frames - 1)
    next_frame = boot_frames
    schedule: dict[int, Mutator] = {}
    for _name, mutator in stages[1:]:
        schedule[next_frame] = mutator
        capture_indices.append(next_frame + settle_frames - 1)
        next_frame += settle_frames
    total_frames = next_frame + 1

    app = App(width=WIDTH, height=HEIGHT, title="Procedural Planets (test)", visible=False)
    root = PlanetRoot(headless=True)

    def on_frame(idx, _t):
        if idx in schedule:
            try:
                schedule[idx](root)
            except Exception as e:  # don't crash the capture sweep
                print(f"[--test] stage at frame {idx} failed: {e!r}")
        return None

    captured = app.run_headless(
        root,
        frames=total_frames,
        capture_frames=capture_indices,
        on_frame=on_frame,
    )

    for (name, _), img in zip(stages, captured, strict=False):
        save_png(img, out_dir / name)
        print(f"saved {out_dir / name}")


def main() -> None:
    if "--test" in sys.argv:
        _run_headless()
        return
    app = App(width=WIDTH, height=HEIGHT, title="Procedural Planets (SimVX)")
    app.run(PlanetRoot())


if __name__ == "__main__":
    main()