Skip to content
Download

Levels (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. 41 functions, the newest from API 1.13.

Explanations and examples: World access. Every function of the level 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_level_get_block cl.level.get_block both TICK 1.0
cl_level_set_block cl.level.set_block server TICK 1.0
cl_level_dimension cl.level.dimension both ANY 1.0
cl_level_game_time cl.level.game_time both TICK 1.0
cl_level_day_time cl.level.day_time both TICK 1.0
cl_level_is_client cl.level.is_client both ANY 1.0
cl_server_overworld cl.level.server_overworld server TICK 1.0
cl_client_level cl.level.client_level client ANY 1.0
cl_level_spawn cl.level.spawn server TICK 1.8
cl_level_raycast cl.level.raycast both TICK 1.11
cl_level_get_blocks cl.level.get_blocks both TICK 1.11
cl_level_snapshot cl.level.snapshot both TICK 1.11
cl_snapshot_retain cl.level.snapshot_retain both ANY 1.11
cl_snapshot_release cl.level.snapshot_release both ANY 1.11
cl_snapshot_get_info cl.level.snapshot_get_info both ANY 1.11
cl_snapshot_get cl.level.snapshot_get both ANY 1.11
cl_snapshot_copy cl.level.snapshot_copy both ANY 1.11
cl_level_light cl.level.light both TICK 1.11
cl_level_can_see_sky cl.level.can_see_sky both TICK 1.11
cl_level_heightmap cl.level.heightmap both TICK 1.11
cl_level_set_block_property cl.level.set_block_property server TICK 1.11
cl_level_container_size cl.level.container_size server TICK 1.11
cl_level_container_get cl.level.container_get server TICK 1.11
cl_level_container_set cl.level.container_set server TICK 1.11
cl_level_block_entity_type cl.level.block_entity_type server TICK 1.11
cl_level_block_entity_get cl.level.block_entity_get server TICK 1.11
cl_level_block_entity_merge cl.level.block_entity_merge server TICK 1.11
cl_level_chunk_data_get cl.level.chunk_data_get server TICK 1.12
cl_level_chunk_data_set cl.level.chunk_data_set server TICK 1.12
cl_level_chunk_data_get_nbt cl.level.chunk_data_get_nbt server TICK 1.12
cl_level_chunk_data_set_nbt cl.level.chunk_data_set_nbt server TICK 1.12
cl_level_chunk_data_remove cl.level.chunk_data_remove server TICK 1.12
cl_level_chunk_data_keys cl.level.chunk_data_keys server TICK 1.12
cl_level_saved_data_get cl.level.saved_data_get server TICK 1.12
cl_level_saved_data_set cl.level.saved_data_set server TICK 1.12
cl_level_saved_data_get_nbt cl.level.saved_data_get_nbt server TICK 1.12
cl_level_saved_data_set_nbt cl.level.saved_data_set_nbt server TICK 1.12
cl_level_saved_data_remove cl.level.saved_data_remove server TICK 1.12
cl_level_particle cl.level.particle both TICK 1.13
cl_level_decal cl.level.decal both TICK 1.13
cl_level_clear_decals cl.level.clear_decals both TICK 1.13

cl_level_get_block

cl_result cl_level_get_block(cl_level level, cl_block_pos pos, cl_block_state* out);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.level.get_block, level:get_block(...)
  • C++: Level::get_block(cl_block_pos pos) → Expected<cl_block_state>; clight::level::get_block(Level level, cl_block_pos pos) → Expected<cl_block_state>
  • 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_level_set_block

cl_result cl_level_set_block(cl_level level, cl_block_pos pos, cl_block_state state, cl_set_block_flags flags);
  • Side: server. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.level.set_block, level:set_block(...)
  • C++: Level::set_block(cl_block_pos pos, cl_block_state state, cl_set_block_flags flags) → Expected<void>; clight::level::set_block(Level level, cl_block_pos pos, cl_block_state state, cl_set_block_flags flags) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_dimension

cl_result cl_level_dimension(cl_level level, char* buf, size_t cap, size_t* out_len);

“minecraft:overworld”

  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.level.dimension, level:dimension(...)
  • C++: Level::dimension() → Expected<std::string>; clight::level::dimension(Level level) → 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_level_game_time

int64_t cl_level_game_time(cl_level level);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.level.game_time, level:game_time(...)
  • C++: Level::game_time() → int64_t; clight::level::game_time(Level level) → int64_t

cl_level_day_time

int64_t cl_level_day_time(cl_level level);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.level.day_time, level:day_time(...)
  • C++: Level::day_time() → int64_t; clight::level::day_time(Level level) → int64_t

cl_level_is_client

bool cl_level_is_client(cl_level level);
  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.level.is_client, level:is_client(...)
  • C++: Level::is_client() → bool; clight::level::is_client(Level level) → bool

cl_server_overworld

cl_level cl_server_overworld(void);

The overworld of the running logical server (null if none).

  • Side: server. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.level.server_overworld
  • C++: clight::level::server_overworld() → Level

cl_client_level

cl_level cl_client_level(void);

The client’s current level (null when not in a world).

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.level.client_level
  • C++: clight::level::client_level() → Level

cl_level_spawn

cl_result cl_level_spawn(cl_level level, cl_str type, cl_vec3 pos, const cl_spawn_opts* opts, cl_entity* out);

Spawns any entity type (vanilla or mod) at a position in a loaded chunk. Players can’t be spawned.

  • Side: server. Context: TICK (tick thread). Since: API 1.8.
  • Lua: cl.level.spawn, level:spawn(...)
  • C++: Level::spawn(std::string_view type, cl_vec3 pos, const cl_spawn_opts* opts) → Expected<Entity>; clight::level::spawn(Level level, std::string_view type, cl_vec3 pos, const cl_spawn_opts* opts) → Expected<Entity>
  • 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_level_raycast

cl_result cl_level_raycast(cl_level level, cl_vec3 from, cl_vec3 to, const cl_raycast_opts* opts, cl_raycast_hit* out);

The first block, fluid or entity on the straight line from from to to (Level#clip, BlockGetter#traverseBlocks; the same code the game uses for the crosshair, projectiles and line of sight). Unloaded chunks read as air. The line is at most 1024 blocks long. On a client: the client’s world and entity copies.

  • Side: both. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.raycast, level:raycast(...)
  • C++: Level::raycast(cl_vec3 from, cl_vec3 to, const cl_raycast_opts* opts) → Expected<cl_raycast_hit>; clight::level::raycast(Level level, cl_vec3 from, cl_vec3 to, const cl_raycast_opts* opts) → Expected<cl_raycast_hit>
  • 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_level_get_blocks

cl_result cl_level_get_blocks(cl_level level, cl_block_pos min, cl_block_pos max, cl_block_state* out, size_t cap, size_t* out_count);

Every block state in the box from min to max (corners included, any order), x fastest, then z, then y: index = ((y - min.y) * size_z + (z - min.z)) * size_x + (x - min.x). One call instead of thousands of level_get_block. Mod blocks report their own state, unloaded positions CL_BLOCK_UNLOADED. At most 2,097,152 blocks (128 x 128 x 128). A buffer smaller than the box gets nothing (out_count says how many states the box has; WASM: up to 262,144 per call).

  • Side: both. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.get_blocks, level:get_blocks(...)
  • C++: Level::get_blocks(cl_block_pos min, cl_block_pos max) → Expected<std::vector<cl_block_state>>; clight::level::get_blocks(Level level, cl_block_pos min, cl_block_pos max) → Expected<std::vector<cl_block_state>>
  • Fills an array: pointer / cap / out_count. Lua returns a list, C++ a std::vector.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_snapshot

cl_snapshot cl_level_snapshot(cl_level level, cl_block_pos min, cl_block_pos max);

A copy of the block states in a box (the same layout and limit as level_get_blocks), taken now. Reading it is safe from any thread and never sees later changes; for workers, acoustics and path planning off the tick thread. Release it with snapshot_release. Null on failure (cl_last_error).

  • Side: both. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.snapshot, level:snapshot(...)
  • C++: Level::snapshot(cl_block_pos min, cl_block_pos max) → Snapshot; clight::level::snapshot(Level level, cl_block_pos min, cl_block_pos max) → Snapshot
  • The returned handle is owned: release it ©, or let the RAII class do it (C++). Lua releases it when it is collected (or at once with local s <close> = ...).

cl_snapshot_retain

void cl_snapshot_retain(cl_snapshot s);
  • Side: both. Context: ANY (any thread). Since: API 1.11.
  • Lua: cl.level.snapshot_retain, snapshot:retain(...)
  • C++: Snapshot::retain() → void; clight::level::snapshot_retain(cl_snapshot s) → void

cl_snapshot_release

void cl_snapshot_release(cl_snapshot s);
  • Side: both. Context: ANY (any thread). Since: API 1.11.
  • Lua: cl.level.snapshot_release, snapshot:release(...)
  • C++: Snapshot::release() → void; clight::level::snapshot_release(cl_snapshot s) → void

cl_snapshot_get_info

cl_result cl_snapshot_get_info(cl_snapshot s, cl_snapshot_info* out);
  • Side: both. Context: ANY (any thread). Since: API 1.11.
  • Lua: cl.level.snapshot_get_info, snapshot:get_info(...)
  • C++: Snapshot::get_info() → Expected<cl_snapshot_info>; clight::level::snapshot_get_info(cl_snapshot s) → Expected<cl_snapshot_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_snapshot_get

cl_block_state cl_snapshot_get(cl_snapshot s, cl_block_pos pos);

The state at a world position (CL_BLOCK_UNLOADED outside the box or in an unloaded chunk).

  • Side: both. Context: ANY (any thread). Since: API 1.11.
  • Lua: cl.level.snapshot_get, snapshot:get(...)
  • C++: Snapshot::get(cl_block_pos pos) → cl_block_state; clight::level::snapshot_get(cl_snapshot s, cl_block_pos pos) → cl_block_state

cl_snapshot_copy

cl_result cl_snapshot_copy(cl_snapshot s, int32_t offset, cl_block_state* out, size_t cap, size_t* out_count);

Copies states from index offset on into out (count: how many there are from offset). WASM reads big snapshots in slices of up to 262,144 states.

  • Side: both. Context: ANY (any thread). Since: API 1.11.
  • Lua: cl.level.snapshot_copy, snapshot:copy(...)
  • C++: Snapshot::copy(int32_t offset) → Expected<std::vector<cl_block_state>>; clight::level::snapshot_copy(cl_snapshot s, int32_t offset) → Expected<std::vector<cl_block_state>>
  • Fills an array: pointer / cap / out_count. Lua returns a list, C++ a std::vector.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_light

cl_result cl_level_light(cl_level level, cl_block_pos pos, cl_light_info* out);
  • Side: both. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.light, level:light(...)
  • C++: Level::light(cl_block_pos pos) → Expected<cl_light_info>; clight::level::light(Level level, cl_block_pos pos) → Expected<cl_light_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_level_can_see_sky

bool cl_level_can_see_sky(cl_level level, cl_block_pos pos);

Level#canSeeSky: no block that stops sky light above the position.

  • Side: both. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.can_see_sky, level:can_see_sky(...)
  • C++: Level::can_see_sky(cl_block_pos pos) → bool; clight::level::can_see_sky(Level level, cl_block_pos pos) → bool

cl_level_heightmap

cl_result cl_level_heightmap(cl_level level, int32_t x, int32_t z, cl_heightmap kind, int32_t* out);

Level#getHeight(type, x, z): the y just above the highest block of the kind in the column (the level’s minimum y for an empty column). CL_E_NOT_LOADED: the chunk is not loaded. Clients only have WORLD_SURFACE and MOTION_BLOCKING (CL_E_UNSUPPORTED for the others).

  • Side: both. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.heightmap, level:heightmap(...)
  • C++: Level::heightmap(int32_t x, int32_t z, cl_heightmap kind) → Expected<int32_t>; clight::level::heightmap(Level level, int32_t x, int32_t z, cl_heightmap kind) → Expected<int32_t>
  • 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_level_set_block_property

cl_result cl_level_set_block_property(cl_level level, cl_block_pos pos, cl_str name, cl_str value, cl_set_block_flags flags);

Sets one property of the block at pos (BlockState#setValue; Level#setBlock with flags). CL_E_NOT_FOUND: the block has no such property; CL_E_INVALID_ARGUMENT: not one of its values.

  • Side: server. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.set_block_property, level:set_block_property(...)
  • C++: Level::set_block_property(cl_block_pos pos, std::string_view name, std::string_view value, cl_set_block_flags flags) → Expected<void>; clight::level::set_block_property(Level level, cl_block_pos pos, std::string_view name, std::string_view value, cl_set_block_flags flags) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_container_size

cl_result cl_level_container_size(cl_level level, cl_block_pos pos, int32_t* out);

The container block at pos (chests, barrels, shulker boxes, hoppers, furnaces, dispensers, droppers, brewing stands, crafters, …; a double chest is one container of 54 slots): its slot count. CL_E_NOT_FOUND: no container there.

  • Side: server. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.container_size, level:container_size(...)
  • C++: Level::container_size(cl_block_pos pos) → Expected<int32_t>; clight::level::container_size(Level level, cl_block_pos pos) → Expected<int32_t>
  • 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_level_container_get

cl_item_stack cl_level_container_get(cl_level level, cl_block_pos pos, int32_t slot);

The stack in a container slot (0-based), with all its data components (null for an empty slot). Owned.

  • Side: server. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.container_get, level:container_get(...)
  • C++: Level::container_get(cl_block_pos pos, int32_t slot) → ItemStack; clight::level::container_get(Level level, cl_block_pos pos, int32_t slot) → ItemStack
  • The returned handle is owned: release it ©, or let the RAII class do it (C++). Lua releases it when it is collected (or at once with local s <close> = ...).

cl_level_container_set

cl_result cl_level_container_set(cl_level level, cl_block_pos pos, int32_t slot, cl_item_stack stack);

Puts a copy of the stack into a slot (null or empty clears it), like Container#setItem: furnaces restart, hoppers and comparators see it, players with the container open see it at once.

  • Side: server. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.container_set, level:container_set(...)
  • C++: Level::container_set(cl_block_pos pos, int32_t slot, cl_item_stack stack) → Expected<void>; clight::level::container_set(Level level, cl_block_pos pos, int32_t slot, cl_item_stack stack) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_block_entity_type

cl_result cl_level_block_entity_type(cl_level level, cl_block_pos pos, char* buf, size_t cap, size_t* out_len);

The block entity type at pos (“minecraft:chest”). CL_E_NOT_FOUND: no block entity.

  • Side: server. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.block_entity_type, level:block_entity_type(...)
  • C++: Level::block_entity_type(cl_block_pos pos) → Expected<std::string>; clight::level::block_entity_type(Level level, cl_block_pos pos) → 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_level_block_entity_get

cl_result cl_level_block_entity_get(cl_level level, cl_block_pos pos, char* buf, size_t cap, size_t* out_len);

The block entity’s data as SNBT, exactly what /data get block shows (with id, x, y, z).

  • Side: server. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.block_entity_get, level:block_entity_get(...)
  • C++: Level::block_entity_get(cl_block_pos pos) → Expected<std::string>; clight::level::block_entity_get(Level level, cl_block_pos pos) → 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_level_block_entity_merge

cl_result cl_level_block_entity_merge(cl_level level, cl_block_pos pos, cl_str snbt);

Merges SNBT into the block entity’s data like /data merge block (id and position are ignored), then saves and sends the update to the players who see it. CL_E_PARSE: bad SNBT.

  • Side: server. Context: TICK (tick thread). Since: API 1.11.
  • Lua: cl.level.block_entity_merge, level:block_entity_merge(...)
  • C++: Level::block_entity_merge(cl_block_pos pos, std::string_view snbt) → Expected<void>; clight::level::block_entity_merge(Level level, cl_block_pos pos, std::string_view snbt) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_chunk_data_get

cl_result cl_level_chunk_data_get(cl_level level, int32_t chunk_x, int32_t chunk_z, cl_str key, char* buf, size_t cap, size_t* out_len);

Chunk data: NBT values under namespaced keys on a loaded chunk (chunk coordinates: block >> 4), saved in the chunk under “clight:data”. Same formats and limits as entity data. CL_E_NOT_LOADED: the chunk is not loaded.

  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.chunk_data_get, level:chunk_data_get(...)
  • C++: Level::chunk_data_get(int32_t chunk_x, int32_t chunk_z, std::string_view key) → Expected<std::string>; clight::level::chunk_data_get(Level level, int32_t chunk_x, int32_t chunk_z, std::string_view key) → 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_level_chunk_data_set

cl_result cl_level_chunk_data_set(cl_level level, int32_t chunk_x, int32_t chunk_z, cl_str key, cl_str snbt);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.chunk_data_set, level:chunk_data_set(...)
  • C++: Level::chunk_data_set(int32_t chunk_x, int32_t chunk_z, std::string_view key, std::string_view snbt) → Expected<void>; clight::level::chunk_data_set(Level level, int32_t chunk_x, int32_t chunk_z, std::string_view key, std::string_view snbt) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_chunk_data_get_nbt

cl_buf cl_level_chunk_data_get_nbt(cl_level level, int32_t chunk_x, int32_t chunk_z, cl_str key);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.chunk_data_get_nbt, level:chunk_data_get_nbt(...)
  • C++: Level::chunk_data_get_nbt(int32_t chunk_x, int32_t chunk_z, std::string_view key) → Buf; clight::level::chunk_data_get_nbt(Level level, int32_t chunk_x, int32_t chunk_z, std::string_view key) → Buf
  • The returned handle is owned: release it ©, or let the RAII class do it (C++). Lua releases it when it is collected (or at once with local s <close> = ...).

cl_level_chunk_data_set_nbt

cl_result cl_level_chunk_data_set_nbt(cl_level level, int32_t chunk_x, int32_t chunk_z, cl_str key, cl_buf data);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.chunk_data_set_nbt, level:chunk_data_set_nbt(...)
  • C++: Level::chunk_data_set_nbt(int32_t chunk_x, int32_t chunk_z, std::string_view key, cl_buf data) → Expected<void>; clight::level::chunk_data_set_nbt(Level level, int32_t chunk_x, int32_t chunk_z, std::string_view key, cl_buf data) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_chunk_data_remove

cl_result cl_level_chunk_data_remove(cl_level level, int32_t chunk_x, int32_t chunk_z, cl_str key);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.chunk_data_remove, level:chunk_data_remove(...)
  • C++: Level::chunk_data_remove(int32_t chunk_x, int32_t chunk_z, std::string_view key) → Expected<void>; clight::level::chunk_data_remove(Level level, int32_t chunk_x, int32_t chunk_z, std::string_view key) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_chunk_data_keys

cl_result cl_level_chunk_data_keys(cl_level level, int32_t chunk_x, int32_t chunk_z, char* buf, size_t cap, size_t* out_len);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.chunk_data_keys, level:chunk_data_keys(...)
  • C++: Level::chunk_data_keys(int32_t chunk_x, int32_t chunk_z) → Expected<std::string>; clight::level::chunk_data_keys(Level level, int32_t chunk_x, int32_t chunk_z) → 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_level_saved_data_get

cl_result cl_level_saved_data_get(cl_level level, cl_str key, char* buf, size_t cap, size_t* out_len);

Saved data (SavedData): one NBT value per key and level, saved with the world in data/<namespace>/<path>.dat (every level of a key in one file; vanilla never reads it). Use the overworld for world-wide data. At most 16 MiB per value.

  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.saved_data_get, level:saved_data_get(...)
  • C++: Level::saved_data_get(std::string_view key) → Expected<std::string>; clight::level::saved_data_get(Level level, std::string_view key) → 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_level_saved_data_set

cl_result cl_level_saved_data_set(cl_level level, cl_str key, cl_str snbt);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.saved_data_set, level:saved_data_set(...)
  • C++: Level::saved_data_set(std::string_view key, std::string_view snbt) → Expected<void>; clight::level::saved_data_set(Level level, std::string_view key, std::string_view snbt) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_saved_data_get_nbt

cl_buf cl_level_saved_data_get_nbt(cl_level level, cl_str key);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.saved_data_get_nbt, level:saved_data_get_nbt(...)
  • C++: Level::saved_data_get_nbt(std::string_view key) → Buf; clight::level::saved_data_get_nbt(Level level, std::string_view key) → Buf
  • The returned handle is owned: release it ©, or let the RAII class do it (C++). Lua releases it when it is collected (or at once with local s <close> = ...).

cl_level_saved_data_set_nbt

cl_result cl_level_saved_data_set_nbt(cl_level level, cl_str key, cl_buf data);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.saved_data_set_nbt, level:saved_data_set_nbt(...)
  • C++: Level::saved_data_set_nbt(std::string_view key, cl_buf data) → Expected<void>; clight::level::saved_data_set_nbt(Level level, std::string_view key, cl_buf data) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_saved_data_remove

cl_result cl_level_saved_data_remove(cl_level level, cl_str key);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.level.saved_data_remove, level:saved_data_remove(...)
  • C++: Level::saved_data_remove(std::string_view key) → Expected<void>; clight::level::saved_data_remove(Level level, std::string_view key) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_particle

cl_result cl_level_particle(cl_level level, cl_str type, const cl_particle_spawn* s);

Spawns particles of a mod type (render_particle_type) or a vanilla one (“minecraft:flame”, “dust{…}”). Server: the Celestial clients with CLight get the mod particle, vanilla clients the type’s fallback (vanilla types: everyone gets the vanilla packet). Client: this client only.

  • Side: both. Context: TICK (tick thread). Since: API 1.13.
  • Lua: cl.level.particle, level:particle(...)
  • C++: Level::particle(std::string_view type, const cl_particle_spawn* s) → Expected<void>; clight::level::particle(Level level, std::string_view type, const cl_particle_spawn* s) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_decal

cl_result cl_level_decal(cl_level level, const cl_decal_desc* desc);

A decal projected on the blocks at desc.pos (blood, scorch marks, footprints). Drawn by the client; at most 1024 decals (the oldest go first). Server: sent to the Celestial clients with CLight near it.

  • Side: both. Context: TICK (tick thread). Since: API 1.13.
  • Lua: cl.level.decal, level:decal(...)
  • C++: Level::decal(const cl_decal_desc* desc) → Expected<void>; clight::level::decal(Level level, const cl_decal_desc* desc) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_clear_decals

cl_result cl_level_clear_decals(cl_level level, cl_vec3 pos, double radius);

Removes the calling mod’s decals within radius of pos (radius <= 0: all of them). Server: on the clients near pos.

  • Side: both. Context: TICK (tick thread). Since: API 1.13.
  • Lua: cl.level.clear_decals, level:clear_decals(...)
  • C++: Level::clear_decals(cl_vec3 pos, double radius) → Expected<void>; clight::level::clear_decals(Level level, cl_vec3 pos, double radius) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.