Render stages, shaders and post effects

Status: Partly implemented (API 1.13). Post-processing passes from mod GLSL, shader-pack uniforms and MOD_<ID> defines, custom fragment shaders for glTF models, the render.frame and render.fog events, sky / lightmap / ambient darkness overrides and camera effects are implemented. Callbacks at other render stages, extra render targets, depth input for post passes and compute passes are Planned; their names may still change. Guide: Post-processing, Fog, Sky and Camera.

Function tables: render, camera, model, events.

Mod shaders

Mods write GLSL 4.60 functions; the engine adds everything else, checks the source and compiles it to SPIR-V on the client (never raw Vulkan, see GPU access). Refused: layout, uniform, buffer, shared, images, samplers, atomics, #extension, #include, #version, #line, while / do, ##, main, the engine’s resource names and names starting with sc_ / gl_ (except gl_FragCoord, gl_FrontFacing); at most 64 KiB. Compile errors return CL_E_PARSE with the compiler log (line numbers of your file).

Post passes

cl_result cl_render_post_pass(const cl_post_pass_desc* desc, cl_post_pass* out);     // MAIN, client
cl_result cl_post_pass_set_uniform(cl_post_pass p, cl_str name, float value);       // ANY
cl_result cl_post_pass_set_enabled(cl_post_pass p, bool enabled);
bool      cl_post_pass_is_enabled(cl_post_pass p);
cl_result cl_post_pass_remove(cl_post_pass p);

cl_post_pass_desc: id, shader (a GLSL file of a mod defining vec4 cl_post(vec2 uv)), uniforms (up to 16 float names, comma separated; each name becomes a macro of cl_uniform(i)), order (lower first), enabled, textures (up to 4 PNGs of mods). In the shader: cl_scene(uv), cl_uniform(i), cl_texture(i, uv), cl_resolution(), cl_time(), cl_partial(). Passes run after the world and the hand, before the HUD; each enabled pass is one full-screen draw plus a copy. At most 32 passes.

Shader packs

cl_result cl_render_set_uniform(cl_str name, float value);   // a pack sees `uniform float <modid>_<name>;`

Every loaded mod also adds #define MOD_<MODID> (upper case) to every pack program. A pack may declare a mod’s uniform before the mod sets it (it reads 0 until then).

Model shaders, parameters and variants

cl_result cl_model_set_shader(cl_model m, const cl_model_shader_opts* opts);          // MAIN, client
cl_result cl_model_variants(cl_model m, char* buf, size_t cap, size_t* out_len);       // one name per line
cl_result cl_entity_set_render_param(cl_entity e, cl_str name, float value);           // TICK, both
float     cl_entity_render_param(cl_entity e, cl_str name);
cl_result cl_entity_clear_render_param(cl_entity e, cl_str name);
cl_result cl_entity_set_material_variant(cl_entity e, cl_str variant);                 // "" = default materials
cl_result cl_entity_material_variant(cl_entity e, char* buf, size_t cap, size_t* out_len);

cl_model_shader_opts: shader (defines vec4 cl_shade(); empty: the materials’ own shading again), params (up to 8 render parameter ids → cl_param(0..7)), textures (up to 4 → cl_texture(0..3, uv)). Further functions: cl_albedo(), cl_tint(), cl_uv(), cl_normal(), cl_view_pos(), cl_lightmap(), cl_time(), cl_light(color), cl_fog(color), cl_cutout(). Up to 32 models with shaders. Render parameters are the entity’s synced numbers (server: every Celestial client with CLight; client: a local value that wins until cleared); the variant is the synced string clight:material_variant. Shader packs draw shaded models with their own entity program.

Fog, sky and light

Event	Payload	Context
render.frame	partial, delta (s), time (s)	RENDER, client
render.fog	fog_type, mutable environmental_start, environmental_end, render_distance_start, render_distance_end, sky_end, cloud_end, red, green, blue, alpha; partial	RENDER, client

cl_result cl_render_set_sky_color(cl_color rgb, float strength);      // 0 = vanilla
cl_result cl_render_set_lightmap_tint(cl_color rgb, float strength);
cl_result cl_render_set_ambient_darkness(float amount);               // 0..1
cl_result cl_render_clear_overrides(void);

Camera effects

cl_result cl_camera_set_effects(const cl_camera_effects* fx);   // per mod; mods combine
cl_result cl_camera_clear_effects(void);
cl_result cl_camera_get_effects(cl_camera_effects* out);        // what applies (after the player's settings)

cl_camera_effects: fov_mult (scaled by FOV Effects), roll (degrees, scaled by Distortion Effects), bob_scale (only with View Bobbing), vignette, vignette_color, shake, shake_speed (only with the player’s Mod Camera Shake option, off by default; scaled by Distortion Effects), smoothing (seconds).

cl.has: render.post, render.pack_uniforms, render.fog, render.sky, render.lightmap, camera.effects, camera.shake, model.shaders, model.variants, entity.render_params.