celestialsim/
lib.rs

1//! **CelestialSim** — a Godot GDExtension that renders planetary bodies with
2//! adaptive-LOD, chunked-quadtree terrain.
3//!
4//! Each frame the CPU selects a screen-space-error cut over a *fixed* triangular
5//! quadtree — its cost depends on the number of chunks in view, not on the
6//! triangle count — and Slang compute shaders realize each chunk's geometry and
7//! bake its surface-detail atlas straight into an indirect `MultiMesh` on Godot's
8//! main `RenderingDevice`. There is **no CPU readback**: geometry and colour never
9//! leave the GPU. Chunks are cached in stable pool slots
10//! (`celestial_algo::chunk_cache::ChunkCache`), so only newly-visible chunks are
11//! realized and revisited terrain costs nothing to redraw.
12//!
13//! # Most readers want the guide, not the API
14//!
15//! The user documentation — install, first planet, custom terrain, scatter — is at
16//! <https://celestialsim.github.io/CelestialSim/>. This page is the Rust reference
17//! for the extension's internals.
18//!
19//! # The three types you touch from Godot
20//!
21//! * [`celestial::Celestial`] — the planet `Node3D`. Add one to a scene, set its
22//!   radius / LOD knobs, and it streams terrain around the active camera.
23//! * [`builder::CesBuilder`] — a `Resource` assigned to the planet's `builder`
24//!   property: it *is* the terrain source (built-in GPU or CPU noise, your own
25//!   `.glsl`, or GDScript), and it also carries the planet's ocean settings.
26//! * [`scatter_layer::CesScatterLayer`] — a `Resource` per scattered mesh (grass,
27//!   trees, rocks), placed entirely on the GPU; layers go in the planet's
28//!   `scatter_layers` array.
29//!
30//! # Module map
31//!
32//! Pipeline (the render-thread GPU work):
33//! * [`chunk_pipeline`] — wires the `upload → realize → bake` computation graph and
34//!   runs it in one render-thread job.
35//! * [`chunk_nodes`] — one self-contained `PipelineNode` per operation.
36//! * [`gpu`] — thin helpers over Godot's main `RenderingDevice` (render thread only).
37//!
38//! CPU → GPU packing:
39//! * [`chunk_descriptors`] — std430 packing of chunk descriptors and per-instance data.
40//! * [`descriptors`] — the shared terrain-noise params (`HeightGpu` + `TextureGpu`).
41//! * [`scatter_descriptors`] — the scatter passes' params/aux/visibility buffers.
42//!
43//! Surface / terrain:
44//! * [`surface`] — the CPU-surface traits (a baked per-chunk colour/height/normal patch).
45//! * [`custom_surface`] — assembles a user `.glsl` into the realize/bake shaders.
46//! * [`noise_provider`] — the built-in noise evaluated on the CPU.
47//! * [`chunk_mesh`] — the reference chunk mesh the indirect `MultiMesh` instances.
48//!
49//! Scatter:
50//! * [`scatter_mesh`] — the procedural grass-blade mesh.
51//!
52//! Water:
53//! * [`water`] / [`water_runtime`] — the analytic ocean proxy and its per-frame update.
54//!
55//! Async CPU bake:
56//! * [`async_bake`] — the thread-safe hand-back queue behind `CesBuilder::submit_chunk`.
57//! * [`bake_pool`] — the worker pool that bakes chunk surfaces off the main thread.
58//!
59//! Debug-only (`#[cfg(debug_assertions)]`, excluded from release builds):
60//! [`chunk_gpu_test`], [`quadtree_debug`], [`tile_viewer`].
61//!
62//! The pure-CPU LOD math — quadtree selection and the chunk cache — lives in the
63//! sibling `celestial-algo` crate, and the engine-agnostic GPU computation graph in
64//! `celestial-graph`.
65//!
66//! # Shaders
67//!
68//! The compute shaders are Slang sources under `crates/celestialsim/shaders/`, with
69//! their SPIR-V **committed** and baked into the cdylib — a normal build needs no
70//! `slangc`. Regenerate with `SLANG_RECOMPILE=1 cargo build -p celestialsim` after
71//! editing a `.slang`.
72
73use godot::prelude::*;
74
75pub mod async_bake;
76/// Task 10 chunk-realize GPU verification node — debug-only; runs `ChunkRealize`
77/// on a local RenderingDevice and checks positions vs `chunk_subvertex_base`.
78#[cfg(debug_assertions)]
79pub mod chunk_gpu_test;
80pub mod chunk_descriptors;
81pub mod chunk_mesh;
82pub mod chunk_nodes;
83pub mod chunk_pipeline;
84pub mod custom_surface;
85pub mod bake_pool;
86pub mod descriptors;
87pub mod gpu;
88pub mod builder;
89pub mod noise_provider;
90#[cfg(debug_assertions)]
91pub mod quadtree_debug;
92pub mod celestial;
93pub mod scatter_descriptors;
94pub mod scatter_layer;
95pub mod scatter_mesh;
96pub mod surface;
97pub mod water;
98pub mod water_runtime;
99/// Debug-only standalone single-tile texture viewer (`CelestialTileViewer`):
100/// re-bakes one icosphere face's surface detail into a `W×W` texture as the user
101/// zooms/pans, isolated from the clipmap. Excluded from release builds.
102#[cfg(debug_assertions)]
103pub mod tile_viewer;
104
105struct CelestialExtension;
106
107#[gdextension]
108unsafe impl ExtensionLibrary for CelestialExtension {}
celestialsim/lib.rs

celestialsim/
lib.rs
