Skip to main content

Crate celestialsim

Crate celestialsim 

Source
Expand description

CelestialSim — a Godot GDExtension that renders planetary bodies with adaptive-LOD, chunked-quadtree terrain.

Each frame the CPU selects a screen-space-error cut over a fixed triangular quadtree — its cost depends on the number of chunks in view, not on the triangle count — and Slang compute shaders realize each chunk’s geometry and bake its surface-detail atlas straight into an indirect MultiMesh on Godot’s main RenderingDevice. There is no CPU readback: geometry and colour never leave the GPU. Chunks are cached in stable pool slots (celestial_algo::chunk_cache::ChunkCache), so only newly-visible chunks are realized and revisited terrain costs nothing to redraw.

§Most readers want the guide, not the API

The user documentation — install, first planet, custom terrain, scatter — is at https://celestialsim.github.io/CelestialSim/. This page is the Rust reference for the extension’s internals.

§The three types you touch from Godot

  • celestial::Celestial — the planet Node3D. Add one to a scene, set its radius / LOD knobs, and it streams terrain around the active camera.
  • builder::CesBuilder — a Resource assigned to the planet’s builder property: it is the terrain source (built-in GPU or CPU noise, your own .glsl, or GDScript), and it also carries the planet’s ocean settings.
  • scatter_layer::CesScatterLayer — a Resource per scattered mesh (grass, trees, rocks), placed entirely on the GPU; layers go in the planet’s scatter_layers array.

§Module map

Pipeline (the render-thread GPU work):

  • chunk_pipeline — wires the upload → realize → bake computation graph and runs it in one render-thread job.
  • chunk_nodes — one self-contained PipelineNode per operation.
  • gpu — thin helpers over Godot’s main RenderingDevice (render thread only).

CPU → GPU packing:

Surface / terrain:

  • surface — the CPU-surface traits (a baked per-chunk colour/height/normal patch).
  • custom_surface — assembles a user .glsl into the realize/bake shaders.
  • noise_provider — the built-in noise evaluated on the CPU.
  • chunk_mesh — the reference chunk mesh the indirect MultiMesh instances.

Scatter:

Water:

Async CPU bake:

  • async_bake — the thread-safe hand-back queue behind CesBuilder::submit_chunk.
  • bake_pool — the worker pool that bakes chunk surfaces off the main thread.

Debug-only (#[cfg(debug_assertions)], excluded from release builds): chunk_gpu_test, quadtree_debug, tile_viewer.

The pure-CPU LOD math — quadtree selection and the chunk cache — lives in the sibling celestial-algo crate, and the engine-agnostic GPU computation graph in celestial-graph.

§Shaders

The compute shaders are Slang sources under crates/celestialsim/shaders/, with their SPIR-V committed and baked into the cdylib — a normal build needs no slangc. Regenerate with SLANG_RECOMPILE=1 cargo build -p celestialsim after editing a .slang.

Modules§

async_bake
The async GDScript bake contract (CEL-86): pure helpers + the submission queue a crate::builder::CesBuilder hands results back through.
bake_pool
Background chunk-surface baking (the fast-flight stutter fix), generic over any CpuSurfaceProvider.
builder
CesBuilder — the terrain-builder resource.
celestial
The Celestial node (Phase 2, CEL-62): a rendered, navigable chunked quadtree planet. Strictly additive to the clipmap.
chunk_descriptors
CPU → GPU packing of chunk descriptors for the Phase 2 chunked quadtree (CEL-62).
chunk_gpu_test
Task 10 chunk-realize GPU verification node — debug-only; runs ChunkRealize on a local RenderingDevice and checks positions vs chunk_subvertex_base. Task 10 verification: run the committed ChunkRealize.spv on a real Vulkan RenderingDevice and prove the realized vertex positions match the CPU reference quadtree::chunk_subvertex_base (terrain OFF), plus a terrain-ON envelope check.
chunk_mesh
Reference mesh for the per-chunk triangular grid (Phase 2, CEL-62).
chunk_nodes
Chunk pipeline nodes as self-contained units behind the ChunkNode trait.
chunk_pipeline
The chunk pipeline recording context + render-thread job.
custom_surface
Custom GPU surface layers: splice a user’s terrain GLSL into the library template and drive the per-slot surface buffers on the render device.
descriptors
CPU → GPU packing of the shared terrain-noise parameters.
gpu
Thin helpers over Godot’s main RenderingDevice.
noise_provider
NoiseProvider — a built-in CPU fBm-terrain CpuSurfaceProvider.
quadtree_debug
Phase 1 debug visualization of the CPU chunked-quadtree selection: turn a Vec<Chunk> into a per-LOD-coloured ArrayMesh (throwaway CPU mesh — Phase 2 replaces this with GPU realize through the nodes pipeline). The pure helpers (lod_color, build_debug_mesh) return plain Rust data so they unit-test without a running Godot engine; the Godot node converts them to engine-backed Packed*Array/Color and wires them to a MeshInstance3D each frame.
scatter_descriptors
CPU → GPU std430 packing for the scatter passes (CEL-73).
scatter_layer
CesScatterLayer — the editor-facing scatter layer resource (CEL-73).
scatter_mesh
Built-in procedural grass blade (CEL-73): the default scatter mesh when a CesScatterLayer has no mesh assigned. A tapered, quadratically-bent blade with a dark→light-green vertex-colour gradient, so a dense field reads as grass with zero committed assets.
surface
Neutral CPU-baked surface type + the provider trait that supplies it.
tile_viewer
Debug-only standalone single-tile texture viewer (CelestialTileViewer): re-bakes one icosphere face’s surface detail into a W×W texture as the user zooms/pans, isolated from the clipmap. Excluded from release builds. Debug-only standalone single-tile texture viewer (CelestialTileViewer).
water
Analytic water-surface geometry helpers.
water_runtime
Scene-side water surface: one transparent proxy sphere per planet driving the analytic water_surface.gdshader.