Core types

Status: Implemented. Every type here is generated from client/clight/idl/clight.idl. Random sources, NBT, chunk and box types and Java-semantics maths helpers are Planned.

Everything is declared in clight.h. The complete lists (every handle, enum value, struct field and callback type) are on the generated page Types, enums and constants.

Version

#define CLIGHT_API_VERSION_MAJOR 1
#define CLIGHT_API_VERSION_MINOR 4
#define CLIGHT_API_VERSION ((CLIGHT_API_VERSION_MAJOR << 16) | CLIGHT_API_VERSION_MINOR)

uint32_t cl_api_version(void);      // the engine's version, e.g. 0x00010004 = 1.4
cl_str   cl_game_version(void);     // "26.3"
cl_str   cl_engine_build(void);     // "seecraft 0.x (git abc1234)"
bool     cl_core_has(cl_str name);  // optional modules, functions and features

Lua: cl.version ("1.4.0"), cl.api_major (1), cl.has("level.set_block"). C++: clight::core::api_version(), clight::core::has("...").

Basic types

C	C++	Lua	Description
`cl_result` (`int32_t`)	`clight::Expected<T>`	raised `cl.Error`, or `ok, err` from `cl.try`	0 = OK, < 0 = error
`cl_str`	`std::string_view`	string	UTF-8 slice (`ptr`, `len`)
`cl_ident` (`uint32_t`)	`cl_ident`	string	Interned `namespace:path`
`cl_holder` (`uint32_t`)	`cl_holder`	holder table	Registry reference from `cl_*_register`
`cl_block_state` (`uint32_t`)	`cl_block_state`	number, or a block id string as input	Global block-state id
`cl_block_id`, `cl_item_id`, `cl_entity_type_id` (`uint32_t`)	the same	number, or an id string as input	Raw registry ids (session only)
`cl_block_pos`	`cl_block_pos`	`cl.pos(x, y, z)`	`int32` x, y, z
`cl_vec3`	`cl_vec3`	`cl.vec(x, y, z)`	double x, y, z
`cl_direction`	`cl_direction`	`"down"`, `"up"`, `"north"`, `"south"`, `"west"`, `"east"`	Vanilla `Direction` order
`cl_uuid` (`uint64_t hi, lo`)	`cl_uuid`	`player.uuid` is the string `"xxxxxxxx-..."`	Entity and player UUIDs
`cl_color` (`uint32_t`)	`cl_color`	number	`0xAARRGGBB` for drawing, `0xRRGGBB` for text

Handles

Each handle is typedef struct cl_<name> { uint64_t h; } cl_<name>;, null when h == 0 (CL_IS_NULL(handle)).

C	C++ class	Owned
`cl_level`	`clight::Level`
`cl_entity`	`clight::Entity` (players too)
`cl_item_stack`	`clight::ItemStack` (RAII, copy = retain)	yes
`cl_text`	`clight::Text` (RAII, copy = retain)	yes
`cl_buf`	`clight::Buf` (RAII, move-only)	yes
`cl_sub`	`clight::Subscription` (RAII)
`cl_task`	`clight::Task`
`cl_keybind`	`clight::Keybind`
`cl_config`	`clight::Config`
`cl_cmd_ctx`, `cl_cmd_node`	`clight::CmdCtx`, `clight::CmdNode`
`cl_gui`, `cl_hud_layer`	`clight::Gui`, `clight::HudLayer`
`cl_screen`, `cl_widget`, `cl_rml_doc`	`clight::Screen`, `clight::Widget`, `clight::RmlDoc`
`cl_menu`, `cl_sound`, `cl_mixin`	`clight::Menu`, `clight::Sound`, `clight::mixin::Handle` (RAII)

cl_entity covers every entity, including players. Functions in the cl_player_* family take a cl_entity and return CL_E_WRONG_TYPE (or a default) when it isn’t a player.

Owned values

Type	Create	Add a reference	Release
`cl_item_stack`	`cl_stack_create`, `cl_stack_create_by_name`, `cl_player_inventory_get`, `cl_menu_get_item`	`cl_stack_retain`	`cl_stack_release`
`cl_text`	`cl_text_literal`, `cl_text_translatable`	`cl_text_retain`	`cl_text_release`
`cl_buf`	`cl_buf_create`	(none)	`cl_buf_release`

Values passed into an event payload or a callback are borrowed: valid until the callback returns. Retain them if you keep them.

Memory

void* cl_alloc(size_t size, size_t align);   // in a WASM mod: the guest's own allocator
void  cl_free(void* p);

WASM mods allocate in their own linear memory (limit: limits.memory_mb, default 256). The host never frees mod memory and the mod never frees host memory.

Time

uint64_t cl_time_now_ns(void);                // monotonic; profiling and UI animation only
int64_t  cl_level_game_time(cl_level level);  // gameplay ticks
int64_t  cl_level_day_time(cl_level level);

Logging

typedef enum cl_log_level { CL_LOG_TRACE, CL_LOG_DEBUG, CL_LOG_INFO, CL_LOG_WARN, CL_LOG_ERROR } cl_log_level;
void cl_log(cl_log_level level, cl_str message);
#define CL_LOGF(level, ...)   /* printf-style, formats into a 1 KB stack buffer */
#define CL_LOG(...)           /* clight_easy.h: CL_LOGF(CL_LOG_INFO, ...) */

C	C++	Lua
`CL_LOG("x=%d", x)`	`clight::log::info("x={}", x)` (`std::format`)	`cl.log("x =", x)`, `cl.log.info("x=%d", x)`

Output goes to logs/latest.log with the [modid] prefix. See Logging, profiling and debugging.

Planned

Random sources (level random, Xoroshiro and legacy generators, positional forks), NBT values, chunk and section positions, boxes, frame timing for render callbacks, and Java-semantics maths helpers (Mth.sin, floorDiv, String#hashCode). See Determinism and vanilla parity.