Module builder 

CesBuilder — the terrain-builder resource.

A planet has ONE builder (its terrain source); when it is unset the planet renders a plain white sphere. The base CesBuilder is the SINGLE builder class: whether it is a built-in noise example or YOUR custom terrain is decided by two fields — device (GPU/CPU) and a hidden builtin_shader selector (None = custom, Terrain = the built-in noise). The four paths (BuilderRoute) are:

• builtin_shader == Terrain, device == GPU — built-in GPU noise (the rich inline shader, driven by the noise knobs). The auto-added default, shipped as the CesGPUNoiseExample GDScript (carries the knobs as its own @exports).
• builtin_shader == Terrain, device == CPU — the same noise baked on CPU worker threads (crate::noise_provider::NoiseProvider); shipped as CesCPUNoiseExample.
• builtin_shader == None, device == GPU — YOUR terrain: point shader_file at a .glsl defining terrain_height / terrain_color (compiled at runtime). May add @export var name: float knobs (surfaced to the GLSL as #define NAME).
• builtin_shader == None, device == CPU — YOUR terrain in GDScript: extends CesBuilder, define height / color / normal, and set the device to CPU. If it instead defines _bake_requested, the bake is ASYNCHRONOUS (CEL-86) — see BuilderRoute::CpuCustomAsync.

The planet routes on (device, builtin_shader) plus, for the CPU-custom pair, whether the script defines _bake_requested — see route_of. The noise knobs live on the example GDScripts (not this base); a custom builder simply doesn’t declare them.

Structs

BuilderParams

Plain, testable noise params (the Example builders’ knobs). Defaults MUST reproduce HeightGpu::default / TextureGpu::default so a default builder renders like the historical HQ terrain.

CesBuilder

The terrain source: a Resource you assign to Celestial::builder. It answers “what does this planet’s surface look like?” — height, colour, and (since it also owns the water_* group) the ocean.

Enums

BuilderDevice

Which device runs a builder — an exported dropdown on CesBuilder. Combined with BuiltinShader it selects the BuilderRoute.

BuilderRoute

The terrain paths the planet routes between. Derived from a builder’s CesBuilder::device and CesBuilder::builtin_shader, plus — for the CPU-custom pair — whether the GDScript defines BAKE_REQUESTED. NOT an exported field.

BuiltinShader

Which BUILT-IN library shader a builder runs — a hidden (STORAGE-only) selector on CesBuilder. None = a custom builder (user .glsl or GDScript); Terrain = the built-in noise example. Combined with BuilderDevice it selects the BuilderRoute.

Constants

BAKE_REQUESTED

The GDScript method whose presence selects the async CPU bake route.

BASE_READY

Optional GDScript method gating whether the baked surface is shown yet.

Functions

builder_height_gpu

Map the params onto the geometry (height) GPU struct (enabled always on — the planet’s builder SELECTION gates displacement, not this flag).

builder_texture_gpu

Map the params onto the surface (texture) GPU struct.

route_of

Resolve a builder’s routing path.