Struct Celestial

Source

pub struct Celestial {Show 16 fields
    pub radius: f32,
    pub screen_error: f32,
    pub chunk_res: i64,
    pub tile_res: i64,
    pub max_depth: i64,
    pub vram_budget_gib: f32,
    pub geomorph: bool,
    pub lod_colors: bool,
    pub debug_log: bool,
    pub horizon_cull: bool,
    pub cull_height_margin: f32,
    pub max_bakes_per_frame: i64,
    pub recompute_every_frame: bool,
    pub scatter_layers: Array<Gd<CesScatterLayer>>,
    pub builder: Option<Gd<CesBuilder>>,
    pub auto_add_builder: bool,
    /* private fields */
}

Expand description

A procedural planet: the Node3D you add to a Godot scene.

It owns the whole terrain pipeline — every frame it selects a screen-space-error cut of the quadtree around the active camera, realizes the newly-visible chunks on the GPU, and draws them from an indirect MultiMesh child. What the surface looks like comes from the CesBuilder resource in builder (terrain + ocean); vegetation and props come from the CesScatterLayer resources in scatter_layers.

The exported properties below are all live: editing one in the inspector (or from GDScript) reshades or rebuilds as needed, with no scene reload.

Fields§

§radius: f32

Radius of the undisplaced sphere, in world units — the scale of the whole planet. Terrain displaces around it, so the rendered ground can sit above or below this radius (see ground_radius_at). Changing it re-realizes every resident chunk. Default 1000.

§screen_error: f32

Target screen-space error, in normalized screen units (chunk edge over distance): the LOD cut is chosen so no chunk exceeds it. Lower = sharper terrain, but more resident chunks, more bakes and more VRAM pressure; higher = coarser and cheaper. Default 0.02 (range 0.005–0.5).

§chunk_res: i64

Geometry grid of one chunk: chunk_res segments per chunk edge, so each chunk carries chunk_res² triangles. Raising it makes each chunk denser (fewer, larger chunks reach the same screen_error) at a higher per-slot vertex-pool cost. Default 16 (range 2–32).

§tile_res: i64

Phase 4: per-chunk detail-tile resolution. Colour + normal detail is baked at tile_res × tile_res per chunk (independent of chunk_res) and sampled per-pixel, so surface shading is crisper than the geometry grid. NOTE: the detail atlas costs tile_res² × 16 B per resident chunk (detail atlases + surface buffers), so a larger tile_res means fewer chunks fit in vram_budget_gib (see effective_budget).

§max_depth: i64

Hard cap on quadtree subdivision, i.e. the finest terrain the camera can ever reach: below this depth the cut stops refining even if screen_error is not met, so the ground goes blocky as you get close. 0 = no subdivision (the 20 base icosphere faces only — “LOD 0”). Default 16 (range 0–20).

§vram_budget_gib: f32

GPU VRAM budget for the resident chunk pools, in GiB. You set the gigabytes, not a slot count: the number of resident chunk slots is derived as vram / per-chunk bytes, where per-chunk = verts_per_chunk×48 B (geometry) + tile_res²×16 B (detail atlases + surface buffers). So a bigger tile_res simply means fewer chunks fit in the same budget — no manual rebalancing. (Also clamped so the atlas texture height stays within the GPU’s limit.)

§geomorph: bool

Geomorphing (Phase 5): smoothly blend each chunk between its full-detail grid and its coarser (parent-resolution) sublattice as the camera distance crosses the LOD band, so detail fades in/out instead of popping when the quadtree subdivides/merges. The per-chunk morph factor rides in the per-frame instance buffer (INSTANCE_CUSTOM.g) and is applied in the surface vertex shader, so the realize/bake cache is untouched. When off, every chunk gets morph = 1 (full detail, no blend) and the instance buffer is NOT re-uploaded on camera movement.

§lod_colors: bool

Debug view: tint each chunk by its pool slot so the chunk tiling (and the LOD cut) is visible on the surface. Off by default; purely visual.

§debug_log: bool

Print a one-line status (chunks in the cut, resident, realized, graph executes, selection time) to the Godot output every ~5 seconds. Default on.

§horizon_cull: bool

Horizon (back-of-planet) culling: skip selecting/realizing/baking/drawing chunks that are fully beyond the planet’s horizon. Removes the entire far hemisphere; and because the horizon is close when the camera is near the surface, it also drops distant near-ground chunks — shrinking the resident set (and the VRAM/tile_res it can afford).

§cull_height_margin: f32

Terrain-height slack for horizon culling, as a fraction of radius: a patch is kept if terrain up to radius × cull_height_margin above the surface could peek over the horizon. Raise if tall terrain pops in at the horizon; lower to cull more aggressively. (HQ max displacement ≈ 0.3·r.)

§max_bakes_per_frame: i64

Max NEW chunks to realize+bake per frame. A large influx (teleport, fast turn, first fill) otherwise bakes every newly-visible chunk in one frame and spikes frame time; capping it spreads the work over frames (the rest pop in over the next few frames). Lower = smoother under influx, slower fill-in. Dirty re-bakes (streamed-tile arrivals) share this cap; already-resident chunks are always drawn (stale until their re-bake turn). Default 48.

§recompute_every_frame: bool

TEST (temporary): bypass the per-chunk cache and re-realize + re-bake every VISIBLE chunk EVERY frame (no persistence, no eviction). Lets you probe the raw per-frame realize+bake cost at high tile_res/chunk_res without the cache size limiting things. Off = normal cached path.

§scatter_layers: Array<Gd<CesScatterLayer>>

Scatter layers (CEL-73): each layer scatters one mesh over the planet on a stable world lattice, with LIVE density + min_height/max_height sliders — edits re-run only the scatter-compact dispatch. A layer with no mesh is INACTIVE (for grass assign addons/celestialsim/grass_blade.tres). lod_level sets density/reach; adding/removing layers (or changing instances_per_cell/max_instances) rebuilds the GPU job.

§builder: Option<Gd<CesBuilder>>

The terrain builder (one active at a time). Its TYPE (a CesBuilder subclass) decides how the surface is produced. A new planet starts with a GPU-example builder (added when the node is first readied); clear it to render a plain white sphere. Swapping or editing the builder reshades/rebuilds live.

§auto_add_builder: bool

Hidden, storage-only guard: add the default builder the first time a builder-less planet is readied, then never again (so clearing the builder stays white). Not shown in the inspector — see on_validate_property.

Implementations§

Source §