Models (function list)

Status: Implemented (API 1.24). Generated from client/clight/idl/clight_api.json by tools/docs/gen_api_reference.py; do not edit by hand. 11 functions, the newest from API 1.15.

Explanations and examples: Rendering, Guide: Entity models and animation. Every function of the model module is listed here in table order. The details of each function follow the table, in the same order. Side: where the function works (server, client, both). Context: the thread it may be called on (Conventions). Since: the API version that added it.

C function	Lua	Side	Context	Since
`cl_model_load`	`cl.model.load`	both	MAIN	1.9
`cl_model_get_info`	`cl.model.get_info`	both	ANY	1.9
`cl_model_clip_name`	`cl.model.clip_name`	both	ANY	1.9
`cl_model_clip_length`	`cl.model.clip_length`	both	ANY	1.9
`cl_model_bone_name`	`cl.model.bone_name`	both	ANY	1.9
`cl_model_morph_name`	`cl.model.morph_name`	both	ANY	1.9
`cl_model_add_event`	`cl.model.add_event`	both	MAIN	1.9
`cl_model_variants`	`cl.model.variants`	both	ANY	1.13
`cl_model_set_shader`	`cl.model.set_shader`	client	MAIN	1.13
`cl_model_set_lod_distances`	`cl.model.set_lod_distances`	both	MAIN	1.15
`cl_model_lod_levels`	`cl.model.lod_levels`	both	ANY	1.15

cl_model_load

cl_result cl_model_load(cl_str path, cl_model* out);

Loads a glTF 2.0 model (.glb or .gltf) from a mod’s assets: “my_mod:models/entity/x.glb” is assets/my_mod/models/entity/x.glb of the mod my_mod. A clip file next to it (“x_clips.json”) adds clip lengths, loop flags and events. Loading the same path again gives the same model. On a dedicated server only the skeleton and the clips load (events, root motion and bone positions work there too). Errors: CL_E_NOT_FOUND, CL_E_PARSE (the message says what is wrong), CL_E_PERMISSION_DENIED (a path outside the mod’s assets).

Side: both. Context: MAIN (startup (main thread)). Since: API 1.9.
Lua: cl.model.load
C++: clight::model::load(std::string_view path) → Expected<Model>
The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_get_info

cl_result cl_model_get_info(cl_model m, cl_model_info* out);

Side: both. Context: ANY (any thread). Since: API 1.9.
Lua: cl.model.get_info, model:get_info(...)
C++: Model::get_info() → Expected<cl_model_info>; clight::model::get_info(Model m) → Expected<cl_model_info>
The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_clip_name

cl_result cl_model_clip_name(cl_model m, int32_t index, char* buf, size_t cap, size_t* out_len);

Side: both. Context: ANY (any thread). Since: API 1.9.
Lua: cl.model.clip_name, model:clip_name(...)
C++: Model::clip_name(int32_t index) → Expected<std::string>; clight::model::clip_name(Model m, int32_t index) → Expected<std::string>
Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_clip_length

float cl_model_clip_length(cl_model m, cl_str clip);

The clip’s length in seconds (-1: no such clip).

Side: both. Context: ANY (any thread). Since: API 1.9.
Lua: cl.model.clip_length, model:clip_length(...)
C++: Model::clip_length(std::string_view clip) → float; clight::model::clip_length(Model m, std::string_view clip) → float

cl_model_bone_name

cl_result cl_model_bone_name(cl_model m, int32_t index, char* buf, size_t cap, size_t* out_len);

Side: both. Context: ANY (any thread). Since: API 1.9.
Lua: cl.model.bone_name, model:bone_name(...)
C++: Model::bone_name(int32_t index) → Expected<std::string>; clight::model::bone_name(Model m, int32_t index) → Expected<std::string>
Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_morph_name

cl_result cl_model_morph_name(cl_model m, int32_t index, char* buf, size_t cap, size_t* out_len);

Side: both. Context: ANY (any thread). Since: API 1.9.
Lua: cl.model.morph_name, model:morph_name(...)
C++: Model::morph_name(int32_t index) → Expected<std::string>; clight::model::morph_name(Model m, int32_t index) → Expected<std::string>
Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_add_event

cl_result cl_model_add_event(cl_model m, cl_str clip, float time, cl_str name);

An event marker from code (besides the file’s): entity.anim_event fires with name when the clip passes time.

Side: both. Context: MAIN (startup (main thread)). Since: API 1.9.
Lua: cl.model.add_event, model:add_event(...)
C++: Model::add_event(std::string_view clip, float time, std::string_view name) → Expected<void>; clight::model::add_event(Model m, std::string_view clip, float time, std::string_view name) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_variants

cl_result cl_model_variants(cl_model m, char* buf, size_t cap, size_t* out_len);

The model’s material variants (KHR_materials_variants), one name per line.

Side: both. Context: ANY (any thread). Since: API 1.13.
Lua: cl.model.variants, model:variants(...)
C++: Model::variants() → Expected<std::string>; clight::model::variants(Model m) → Expected<std::string>
Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_set_shader

cl_result cl_model_set_shader(cl_model m, const cl_model_shader_opts* opts);

A custom fragment shader for every material of the model (client). The engine compiles the GLSL to SPIR-V and checks it first: no resource declarations, extensions, buffers, images, atomics or engine bindings; the shader only sees what the cl_* functions give it, so it cannot reach other GPU memory. CL_E_PARSE: the shader did not compile (the message has the compiler log). Shader packs draw the model with their own entity program instead.

Side: client. Context: MAIN (startup (main thread)). Since: API 1.13.
Lua: cl.model.set_shader, model:set_shader(...)
C++: Model::set_shader(const cl_model_shader_opts* opts) → Expected<void>; clight::model::set_shader(Model m, const cl_model_shader_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_set_lod_distances

cl_result cl_model_set_lod_distances(cl_model m, cl_str distances, float cull);

LOD switch distances in blocks, comma separated (“12,32”: level 1 from 12 blocks, level 2 from 32), and the distance beyond which the model is not drawn at all (<= 0: never culled, or the file’s last MSFT_screencoverage). Empty distances: the file’s MSFT_screencoverage (for scale 1), else 16, 32, 64, … blocks. Only the world uses LOD; the hand and the GUI draw full detail. CL_E_INVALID_ARGUMENT: a distance that is not a number >= 0.

Side: both. Context: MAIN (startup (main thread)). Since: API 1.15.
Lua: cl.model.set_lod_distances, model:set_lod_distances(...)
C++: Model::set_lod_distances(std::string_view distances, float cull) → Expected<void>; clight::model::set_lod_distances(Model m, std::string_view distances, float cull) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_model_lod_levels

int32_t cl_model_lod_levels(cl_model m);

The model’s LOD levels (1: no simplified meshes).

Side: both. Context: ANY (any thread). Since: API 1.15.
Lua: cl.model.lod_levels, model:lod_levels(...)
C++: Model::lod_levels() → int32_t; clight::model::lod_levels(Model m) → int32_t