Entities and players (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. 139 functions, the newest from API 1.20.

Explanations and examples: Entities, Players. Every function of the entity 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_entity_is_valid`	`cl.entity.is_valid`	both	ANY	1.0
`cl_entity_is_player`	`cl.entity.is_player`	both	ANY	1.0
`cl_entity_id`	`cl.entity.id`	both	ANY	1.0
`cl_entity_uuid`	`cl.entity.uuid`	both	TICK	1.0
`cl_entity_type`	`cl.entity.type`	both	TICK	1.0
`cl_entity_level`	`cl.entity.level`	both	TICK	1.0
`cl_entity_position`	`cl.entity.position`	both	TICK	1.0
`cl_entity_teleport`	`cl.entity.teleport`	server	TICK	1.0
`cl_living_health`	`cl.living.health`	both	TICK	1.0
`cl_living_set_health`	`cl.living.set_health`	server	TICK	1.0
`cl_player_name`	`cl.player.name`	both	TICK	1.0
`cl_player_send_message`	`cl.player.send_message`	server	TICK	1.0
`cl_player_send_action_bar`	`cl.player.send_action_bar`	server	TICK	1.0
`cl_player_give`	`cl.player.give`	server	TICK	1.0
`cl_player_selected_slot`	`cl.player.selected_slot`	both	TICK	1.0
`cl_player_inventory_get`	`cl.player.inventory_get`	both	TICK	1.0
`cl_server_players`	`cl.entity.server_players`	server	TICK	1.0
`cl_client_player`	`cl.entity.client_player`	client	ANY	1.0
`cl_server_broadcast`	`cl.entity.server_broadcast`	server	TICK	1.0
`cl_player_take`	`cl.player.take`	server	TICK	1.3
`cl_player_count_item`	`cl.player.count_item`	both	TICK	1.3
`cl_player_inventory_shrink`	`cl.player.inventory_shrink`	server	TICK	1.3
`cl_player_inventory_set`	`cl.player.inventory_set`	server	TICK	1.3
`cl_player_game_mode`	`cl.player.game_mode`	both	TICK	1.4
`cl_player_inventory_consume`	`cl.player.inventory_consume`	server	TICK	1.4
`cl_player_send_title`	`cl.player.send_title`	server	TICK	1.4
`cl_player_clear_title`	`cl.player.clear_title`	server	TICK	1.4
`cl_player_kick`	`cl.player.kick`	server	TICK	1.6
`cl_entity_velocity`	`cl.entity.velocity`	both	TICK	1.8
`cl_entity_set_velocity`	`cl.entity.set_velocity`	server	TICK	1.8
`cl_entity_rotation`	`cl.entity.rotation`	both	TICK	1.8
`cl_entity_set_rotation`	`cl.entity.set_rotation`	server	TICK	1.8
`cl_entity_head_rotation`	`cl.entity.head_rotation`	both	TICK	1.8
`cl_entity_set_head_rotation`	`cl.entity.set_head_rotation`	server	TICK	1.8
`cl_entity_on_ground`	`cl.entity.on_ground`	both	TICK	1.8
`cl_entity_eye_position`	`cl.entity.eye_position`	both	TICK	1.8
`cl_entity_look_vector`	`cl.entity.look_vector`	both	TICK	1.8
`cl_entity_dimensions`	`cl.entity.dimensions`	both	TICK	1.8
`cl_entity_set_dimensions`	`cl.entity.set_dimensions`	server	TICK	1.8
`cl_entity_reset_dimensions`	`cl.entity.reset_dimensions`	server	TICK	1.8
`cl_entity_pose`	`cl.entity.pose`	both	TICK	1.8
`cl_entity_set_pose`	`cl.entity.set_pose`	server	TICK	1.8
`cl_entity_remove`	`cl.entity.remove`	server	TICK	1.8
`cl_entity_is_custom`	`cl.entity.is_custom`	both	TICK	1.8
`cl_entity_anim_play`	`cl.entity.anim_play`	both	TICK	1.9
`cl_entity_anim_layer`	`cl.entity.anim_layer`	both	TICK	1.9
`cl_entity_anim_stop`	`cl.entity.anim_stop`	both	TICK	1.9
`cl_entity_anim_clip`	`cl.entity.anim_clip`	both	TICK	1.9
`cl_entity_anim_state`	`cl.entity.anim_state`	both	TICK	1.9
`cl_entity_set_morph`	`cl.entity.set_morph`	both	TICK	1.9
`cl_entity_anim_look_at`	`cl.entity.anim_look_at`	both	TICK	1.9
`cl_entity_bone_transform`	`cl.entity.bone_transform`	both	TICK	1.9
`cl_entity_anim_root_motion`	`cl.entity.anim_root_motion`	both	TICK	1.9
`cl_entity_model`	`cl.entity.model`	both	TICK	1.9
`cl_level_entities_in_box`	`cl.entity.level_entities_in_box`	both	TICK	1.10
`cl_level_nearest_player`	`cl.entity.level_nearest_player`	both	TICK	1.10
`cl_level_entity_by_uuid`	`cl.entity.level_entity_by_uuid`	both	TICK	1.10
`cl_entity_by_uuid`	`cl.entity.by_uuid`	server	TICK	1.10
`cl_entity_category`	`cl.entity.category`	both	TICK	1.10
`cl_entity_has_tag`	`cl.entity.has_tag`	server	TICK	1.10
`cl_entity_add_tag`	`cl.entity.add_tag`	server	TICK	1.10
`cl_entity_remove_tag`	`cl.entity.remove_tag`	server	TICK	1.10
`cl_entity_attribute`	`cl.entity.attribute`	server	TICK	1.10
`cl_entity_attribute_base`	`cl.entity.attribute_base`	server	TICK	1.10
`cl_entity_set_attribute_base`	`cl.entity.set_attribute_base`	server	TICK	1.10
`cl_entity_add_attribute_modifier`	`cl.entity.add_attribute_modifier`	server	TICK	1.10
`cl_entity_remove_attribute_modifier`	`cl.entity.remove_attribute_modifier`	server	TICK	1.10
`cl_entity_has_attribute_modifier`	`cl.entity.has_attribute_modifier`	server	TICK	1.10
`cl_entity_add_effect`	`cl.entity.add_effect`	server	TICK	1.10
`cl_entity_remove_effect`	`cl.entity.remove_effect`	server	TICK	1.10
`cl_entity_has_effect`	`cl.entity.has_effect`	server	TICK	1.10
`cl_entity_effect`	`cl.entity.effect`	server	TICK	1.10
`cl_entity_clear_effects`	`cl.entity.clear_effects`	server	TICK	1.10
`cl_entity_set_synced_bool`	`cl.entity.set_synced_bool`	server	TICK	1.10
`cl_entity_set_synced_number`	`cl.entity.set_synced_number`	server	TICK	1.10
`cl_entity_set_synced_string`	`cl.entity.set_synced_string`	server	TICK	1.10
`cl_entity_clear_synced`	`cl.entity.clear_synced`	server	TICK	1.10
`cl_entity_synced_type`	`cl.entity.synced_type`	both	TICK	1.10
`cl_entity_synced_bool`	`cl.entity.synced_bool`	both	TICK	1.10
`cl_entity_synced_number`	`cl.entity.synced_number`	both	TICK	1.10
`cl_entity_synced_string`	`cl.entity.synced_string`	both	TICK	1.10
`cl_entity_hurt`	`cl.entity.hurt`	server	TICK	1.10
`cl_entity_knockback`	`cl.entity.knockback`	server	TICK	1.10
`cl_entity_set_passenger`	`cl.entity.set_passenger`	server	TICK	1.10
`cl_entity_dismount`	`cl.entity.dismount`	server	TICK	1.10
`cl_entity_eject_passengers`	`cl.entity.eject_passengers`	server	TICK	1.10
`cl_entity_vehicle`	`cl.entity.vehicle`	server	TICK	1.10
`cl_entity_passengers`	`cl.entity.passengers`	server	TICK	1.10
`cl_player_add_movement_modifier`	`cl.player.add_movement_modifier`	server	TICK	1.11
`cl_player_remove_movement_modifier`	`cl.player.remove_movement_modifier`	server	TICK	1.11
`cl_player_has_movement_modifier`	`cl.player.has_movement_modifier`	server	TICK	1.11
`cl_player_movement`	`cl.player.movement`	both	TICK	1.11
`cl_player_set_part_visible`	`cl.player.set_part_visible`	both	TICK	1.11
`cl_player_part_visible`	`cl.player.part_visible`	both	TICK	1.11
`cl_player_set_part_model`	`cl.player.set_part_model`	both	TICK	1.11
`cl_player_set_hand_disabled`	`cl.player.set_hand_disabled`	server	TICK	1.11
`cl_player_hand_disabled`	`cl.player.hand_disabled`	both	TICK	1.11
`cl_player_lock_slot`	`cl.player.lock_slot`	server	TICK	1.11
`cl_player_slot_locked`	`cl.player.slot_locked`	both	TICK	1.11
`cl_player_set_input_override`	`cl.player.set_input_override`	both	TICK	1.11
`cl_player_clear_input_override`	`cl.player.clear_input_override`	both	TICK	1.11
`cl_player_input_override`	`cl.player.input_override`	both	TICK	1.11
`cl_player_food`	`cl.player.food`	both	TICK	1.11
`cl_player_set_food`	`cl.player.set_food`	server	TICK	1.11
`cl_player_saturation`	`cl.player.saturation`	both	TICK	1.11
`cl_player_set_saturation`	`cl.player.set_saturation`	server	TICK	1.11
`cl_player_exhaustion`	`cl.player.exhaustion`	server	TICK	1.11
`cl_player_exhaust`	`cl.player.exhaust`	server	TICK	1.11
`cl_entity_air`	`cl.entity.air`	both	TICK	1.11
`cl_entity_max_air`	`cl.entity.max_air`	both	TICK	1.11
`cl_entity_set_air`	`cl.entity.set_air`	server	TICK	1.11
`cl_player_set_natural_regen`	`cl.player.set_natural_regen`	server	TICK	1.11
`cl_player_natural_regen`	`cl.player.natural_regen`	server	TICK	1.11
`cl_entity_path_to`	`cl.entity.path_to`	server	TICK	1.12
`cl_entity_follow_path`	`cl.entity.follow_path`	server	TICK	1.12
`cl_entity_path`	`cl.entity.path`	server	TICK	1.12
`cl_entity_path_state`	`cl.entity.path_state`	server	TICK	1.12
`cl_entity_path_done`	`cl.entity.path_done`	server	TICK	1.12
`cl_entity_path_stop`	`cl.entity.path_stop`	server	TICK	1.12
`cl_entity_look_at`	`cl.entity.look_at`	server	TICK	1.12
`cl_entity_look_at_entity`	`cl.entity.look_at_entity`	server	TICK	1.12
`cl_entity_data_get`	`cl.entity.data_get`	both	TICK	1.12
`cl_entity_data_set`	`cl.entity.data_set`	server	TICK	1.12
`cl_entity_data_get_nbt`	`cl.entity.data_get_nbt`	both	TICK	1.12
`cl_entity_data_set_nbt`	`cl.entity.data_set_nbt`	server	TICK	1.12
`cl_entity_data_remove`	`cl.entity.data_remove`	server	TICK	1.12
`cl_entity_data_keys`	`cl.entity.data_keys`	both	TICK	1.12
`cl_entity_set_render_param`	`cl.entity.set_render_param`	both	TICK	1.13
`cl_entity_render_param`	`cl.entity.render_param`	both	ANY	1.13
`cl_entity_clear_render_param`	`cl.entity.clear_render_param`	both	TICK	1.13
`cl_entity_set_material_variant`	`cl.entity.set_material_variant`	both	TICK	1.13
`cl_entity_material_variant`	`cl.entity.material_variant`	both	ANY	1.13
`cl_entity_path_to_entity`	`cl.entity.path_to_entity`	server	TICK	1.13
`cl_entity_set_casts_shadow`	`cl.entity.set_casts_shadow`	client	TICK	1.18
`cl_entity_casts_shadow`	`cl.entity.casts_shadow`	client	TICK	1.18
`cl_attachment_register`	`cl.entity.attachment_register`	both	ANY	1.20
`cl_entity_equipment`	`cl.entity.equipment`	both	TICK	1.20
`cl_entity_set_equipment`	`cl.entity.set_equipment`	server	TICK	1.20
`cl_entity_set_drop_chance`	`cl.entity.set_drop_chance`	server	TICK	1.20

cl_entity_is_valid

bool cl_entity_is_valid(cl_entity e);

Side: both. Context: ANY (any thread). Since: API 1.0.
Lua: cl.entity.is_valid, entity:is_valid(...)
C++: Entity::is_valid() → bool; clight::entity::is_valid(Entity e) → bool

cl_entity_is_player

bool cl_entity_is_player(cl_entity e);

Side: both. Context: ANY (any thread). Since: API 1.0.
Lua: cl.entity.is_player, entity:is_player(...)
C++: Entity::is_player() → bool; clight::entity::is_player(Entity e) → bool

cl_entity_id

int32_t cl_entity_id(cl_entity e);

Side: both. Context: ANY (any thread). Since: API 1.0.
Lua: cl.entity.id, entity:id(...)
C++: Entity::id() → int32_t; clight::entity::id(Entity e) → int32_t

cl_entity_uuid

cl_uuid cl_entity_uuid(cl_entity e);

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.entity.uuid, entity:uuid(...)
C++: Entity::uuid() → cl_uuid; clight::entity::uuid(Entity e) → cl_uuid

cl_entity_type

cl_result cl_entity_type(cl_entity e, char* buf, size_t cap, size_t* out_len);

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.entity.type, entity:type(...)
C++: Entity::type() → Expected<std::string>; clight::entity::type(Entity e) → 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_entity_level

cl_level cl_entity_level(cl_entity e);

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.entity.level, entity:level(...)
C++: Entity::level() → Level; clight::entity::level(Entity e) → Level

cl_entity_position

cl_result cl_entity_position(cl_entity e, cl_vec3* out);

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.entity.position, entity:position(...)
C++: Entity::position() → Expected<cl_vec3>; clight::entity::position(Entity e) → Expected<cl_vec3>
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_entity_teleport

cl_result cl_entity_teleport(cl_entity e, cl_vec3 pos);

Side: server. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.entity.teleport, entity:teleport(...)
C++: Entity::teleport(cl_vec3 pos) → Expected<void>; clight::entity::teleport(Entity e, cl_vec3 pos) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_living_health

float cl_living_health(cl_entity e);

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.living.health, entity:health(...), cl.entity.living_health (old name)
C++: Entity::health() → float; clight::entity::living_health(Entity e) → float

cl_living_set_health

cl_result cl_living_set_health(cl_entity e, float health);

Side: server. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.living.set_health, entity:set_health(...), cl.entity.living_set_health (old name)
C++: Entity::set_health(float health) → Expected<void>; clight::entity::living_set_health(Entity e, float health) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_name

cl_result cl_player_name(cl_entity player, char* buf, size_t cap, size_t* out_len);

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.player.name, entity:name(...), cl.entity.player_name (old name)
C++: Entity::try_name() → Expected<std::string>; clight::entity::player_name(Entity player) → 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_player_send_message

cl_result cl_player_send_message(cl_entity player, cl_text message);

Side: server. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.player.send_message, entity:send_message(...), cl.entity.player_send_message (old name)
C++: Entity::send_message(cl_text message) → Expected<void>; clight::entity::player_send_message(Entity player, cl_text message) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_send_action_bar

cl_result cl_player_send_action_bar(cl_entity player, cl_text message);

Side: server. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.player.send_action_bar, entity:send_action_bar(...), cl.entity.player_send_action_bar (old name)
C++: Entity::send_action_bar(cl_text message) → Expected<void>; clight::entity::player_send_action_bar(Entity player, cl_text message) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_give

cl_result cl_player_give(cl_entity player, cl_item_stack stack);

Puts the stack into the inventory, dropping what doesn’t fit. Takes no ownership of ‘stack’.

Side: server. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.player.give, entity:give(...), cl.entity.player_give (old name)
C++: Entity::give(cl_item_stack stack) → Expected<void>; clight::entity::player_give(Entity player, cl_item_stack stack) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_selected_slot

int32_t cl_player_selected_slot(cl_entity player);

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.player.selected_slot, entity:selected_slot(...), cl.entity.player_selected_slot (old name)
C++: Entity::selected_slot() → int32_t; clight::entity::player_selected_slot(Entity player) → int32_t

cl_player_inventory_get

cl_item_stack cl_player_inventory_get(cl_entity player, int32_t slot);

The stack in a vanilla inventory slot (0-8 hotbar, 9-35 main, 36-39 armor, 40 offhand). Owned.

Side: both. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.player.inventory_get, entity:inventory_get(...), cl.entity.player_inventory_get (old name)
C++: Entity::inventory_get(int32_t slot) → ItemStack; clight::entity::player_inventory_get(Entity player, 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_server_players

cl_result cl_server_players(cl_entity* out, size_t cap, size_t* out_count);

Online players of the running logical server.

Side: server. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.entity.server_players
C++: clight::entity::server_players() → Expected<std::vector<Entity>>
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_client_player

cl_entity cl_client_player(void);

The local player on the client (null when not in a world).

Side: client. Context: ANY (any thread). Since: API 1.0.
Lua: cl.entity.client_player
C++: clight::entity::client_player() → Entity

cl_server_broadcast

cl_result cl_server_broadcast(cl_text message);

Side: server. Context: TICK (tick thread). Since: API 1.0.
Lua: cl.entity.server_broadcast, text:server_broadcast(...)
C++: Text::server_broadcast() → Expected<void>; clight::entity::server_broadcast(cl_text message) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_take

int32_t cl_player_take(cl_entity player, cl_str item, int32_t count);

Removes up to count items with this id from the inventory (slots 0-40 in order, like /clear) and returns how many were removed (0 when it has none).

Side: server. Context: TICK (tick thread). Since: API 1.3.
Lua: cl.player.take, entity:take(...), cl.entity.player_take (old name)
C++: Entity::take(std::string_view item, int32_t count) → int32_t; clight::entity::player_take(Entity player, std::string_view item, int32_t count) → int32_t

cl_player_count_item

int32_t cl_player_count_item(cl_entity player, cl_str item);

How many items with this id are in the inventory (all slots; on the client: the local player’s copy).

Side: both. Context: TICK (tick thread). Since: API 1.3.
Lua: cl.player.count_item, entity:count_item(...), cl.entity.player_count_item (old name)
C++: Entity::count_item(std::string_view item) → int32_t; clight::entity::player_count_item(Entity player, std::string_view item) → int32_t

cl_player_inventory_shrink

int32_t cl_player_inventory_shrink(cl_entity player, int32_t slot, int32_t count);

Removes up to count items from one slot (its components stay) and returns how many were removed.

Side: server. Context: TICK (tick thread). Since: API 1.3.
Lua: cl.player.inventory_shrink, entity:inventory_shrink(...), cl.entity.player_inventory_shrink (old name)
C++: Entity::inventory_shrink(int32_t slot, int32_t count) → int32_t; clight::entity::player_inventory_shrink(Entity player, int32_t slot, int32_t count) → int32_t

cl_player_inventory_set

cl_result cl_player_inventory_set(cl_entity player, int32_t slot, cl_item_stack stack);

Replaces one slot with a copy of stack (an empty stack clears it). Takes no ownership of ‘stack’.

Side: server. Context: TICK (tick thread). Since: API 1.3.
Lua: cl.player.inventory_set, entity:inventory_set(...), cl.entity.player_inventory_set (old name)
C++: Entity::inventory_set(int32_t slot, cl_item_stack stack) → Expected<void>; clight::entity::player_inventory_set(Entity player, 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_player_game_mode

cl_game_mode cl_player_game_mode(cl_entity player);

The player’s game mode (on the client: the local player’s).

Side: both. Context: TICK (tick thread). Since: API 1.4.
Lua: cl.player.game_mode, entity:game_mode(...), cl.entity.player_game_mode (old name)
C++: Entity::game_mode() → cl_game_mode; clight::entity::player_game_mode(Entity player) → cl_game_mode

cl_player_inventory_consume

int32_t cl_player_inventory_consume(cl_entity player, int32_t slot, int32_t count);

Uses up count items of one slot like vanilla’s ItemStack#consume: nothing is removed in creative mode. Returns how many were used up (in creative: count, capped at the stack size).

Side: server. Context: TICK (tick thread). Since: API 1.4.
Lua: cl.player.inventory_consume, entity:inventory_consume(...), cl.entity.player_inventory_consume (old name)
C++: Entity::inventory_consume(int32_t slot, int32_t count) → int32_t; clight::entity::player_inventory_consume(Entity player, int32_t slot, int32_t count) → int32_t

cl_player_send_title

cl_result cl_player_send_title(cl_entity player, cl_text title, cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out);

Shows a title (and an optional subtitle; null keeps the current one) with vanilla’s fade timing in ticks (-1 keeps the player’s current value; vanilla’s defaults are 10, 70, 20).

Side: server. Context: TICK (tick thread). Since: API 1.4.
Lua: cl.player.send_title, entity:send_title(...), cl.entity.player_send_title (old name)
C++: Entity::send_title(cl_text title, cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out) → Expected<void>; clight::entity::player_send_title(Entity player, cl_text title, cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_clear_title

cl_result cl_player_clear_title(cl_entity player, bool reset_times);

Removes the title and subtitle (reset_times: back to 10, 70, 20 ticks).

Side: server. Context: TICK (tick thread). Since: API 1.4.
Lua: cl.player.clear_title, entity:clear_title(...), cl.entity.player_clear_title (old name)
C++: Entity::clear_title(bool reset_times) → Expected<void>; clight::entity::player_clear_title(Entity player, bool reset_times) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_kick

cl_result cl_player_kick(cl_entity player, cl_text reason);

Disconnects the player; the reason is shown on their disconnect screen.

Side: server. Context: TICK (tick thread). Since: API 1.6.
Lua: cl.player.kick, entity:kick(...), cl.entity.player_kick (old name)
C++: Entity::kick(cl_text reason) → Expected<void>; clight::entity::player_kick(Entity player, cl_text reason) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_velocity

cl_result cl_entity_velocity(cl_entity e, cl_vec3* out);

The motion per tick (blocks/tick; players: the last motion their client reported).

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.velocity, entity:velocity(...)
C++: Entity::velocity() → Expected<cl_vec3>; clight::entity::velocity(Entity e) → Expected<cl_vec3>
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_entity_set_velocity

cl_result cl_entity_set_velocity(cl_entity e, cl_vec3 v);

Sets the motion and syncs it (players get it like a knockback).

Side: server. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.set_velocity, entity:set_velocity(...)
C++: Entity::set_velocity(cl_vec3 v) → Expected<void>; clight::entity::set_velocity(Entity e, cl_vec3 v) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_rotation

cl_result cl_entity_rotation(cl_entity e, cl_rotation* out);

The body rotation (yaw) and the look pitch.

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.rotation, entity:rotation(...)
C++: Entity::rotation() → Expected<cl_rotation>; clight::entity::rotation(Entity e) → Expected<cl_rotation>
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_entity_set_rotation

cl_result cl_entity_set_rotation(cl_entity e, float yaw, float pitch);

Side: server. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.set_rotation, entity:set_rotation(...)
C++: Entity::set_rotation(float yaw, float pitch) → Expected<void>; clight::entity::set_rotation(Entity e, float yaw, float pitch) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_head_rotation

cl_result cl_entity_head_rotation(cl_entity e, cl_rotation* out);

The head rotation: head yaw (living entities turn the head apart from the body) and the look pitch.

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.head_rotation, entity:head_rotation(...)
C++: Entity::head_rotation() → Expected<cl_rotation>; clight::entity::head_rotation(Entity e) → Expected<cl_rotation>
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_entity_set_head_rotation

cl_result cl_entity_set_head_rotation(cl_entity e, float yaw, float pitch);

Side: server. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.set_head_rotation, entity:set_head_rotation(...)
C++: Entity::set_head_rotation(float yaw, float pitch) → Expected<void>; clight::entity::set_head_rotation(Entity e, float yaw, float pitch) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_on_ground

bool cl_entity_on_ground(cl_entity e);

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.on_ground, entity:on_ground(...)
C++: Entity::on_ground() → bool; clight::entity::on_ground(Entity e) → bool

cl_entity_eye_position

cl_result cl_entity_eye_position(cl_entity e, cl_vec3* out);

The position of the eyes (position + eye height).

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.eye_position, entity:eye_position(...)
C++: Entity::eye_position() → Expected<cl_vec3>; clight::entity::eye_position(Entity e) → Expected<cl_vec3>
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_entity_look_vector

cl_result cl_entity_look_vector(cl_entity e, cl_vec3* out);

The unit vector the entity looks along (from its pitch and head yaw; Entity#getViewVector).

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.look_vector, entity:look_vector(...)
C++: Entity::look_vector() → Expected<cl_vec3>; clight::entity::look_vector(Entity e) → Expected<cl_vec3>
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_entity_dimensions

cl_result cl_entity_dimensions(cl_entity e, cl_dimensions* out);

The current size (custom size, pose and age included).

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.dimensions, entity:dimensions(...)
C++: Entity::dimensions() → Expected<cl_dimensions>; clight::entity::dimensions(Entity e) → Expected<cl_dimensions>
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_entity_set_dimensions

cl_result cl_entity_set_dimensions(cl_entity e, float width, float height, float eye_height);

A runtime size for collisions, hitbox and pathfinding (eye_height <= 0: 0.85 x height), synced to Celestial clients with CLight, saved with the entity. Not for players (CL_E_UNSUPPORTED: their client owns their size).

Side: server. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.set_dimensions, entity:set_dimensions(...)
C++: Entity::set_dimensions(float width, float height, float eye_height) → Expected<void>; clight::entity::set_dimensions(Entity e, float width, float height, float eye_height) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_reset_dimensions

cl_result cl_entity_reset_dimensions(cl_entity e);

Back to the type’s own size.

Side: server. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.reset_dimensions, entity:reset_dimensions(...)
C++: Entity::reset_dimensions() → Expected<void>; clight::entity::reset_dimensions(Entity e) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_pose

cl_pose cl_entity_pose(cl_entity e);

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.pose, entity:pose(...)
C++: Entity::pose() → cl_pose; clight::entity::pose(Entity e) → cl_pose

cl_entity_set_pose

cl_result cl_entity_set_pose(cl_entity e, cl_pose pose);

Sets the synced pose (not for players: their client sets it). The pose is the animation; the size changes only through entity_set_dimensions.

Side: server. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.set_pose, entity:set_pose(...)
C++: Entity::set_pose(cl_pose pose) → Expected<void>; clight::entity::set_pose(Entity e, cl_pose pose) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_remove

cl_result cl_entity_remove(cl_entity e, cl_remove_reason reason);

Removes the entity (not players: use player_kick). Its handle goes stale.

Side: server. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.remove, entity:remove(...)
C++: Entity::remove(cl_remove_reason reason) → Expected<void>; clight::entity::remove(Entity e, cl_remove_reason reason) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_is_custom

bool cl_entity_is_custom(cl_entity e);

Whether the entity’s type is a mod type (on a client: one the server told it about).

Side: both. Context: TICK (tick thread). Since: API 1.8.
Lua: cl.entity.is_custom, entity:is_custom(...)
C++: Entity::is_custom() → bool; clight::entity::is_custom(Entity e) → bool

cl_entity_anim_play

cl_result cl_entity_anim_play(cl_entity e, cl_str clip, const cl_anim_play_opts* opts);

Plays a clip of the entity’s model (render_entity_model). On the server the state goes to every Celestial client with CLight that sees the entity (also to players who see it later); on a client it changes only this client’s copy until the server sends a new state. CL_E_NOT_FOUND: the entity has no model or the clip does not exist.

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.anim_play, entity:anim_play(...)
C++: Entity::anim_play(std::string_view clip, const cl_anim_play_opts* opts) → Expected<void>; clight::entity::anim_play(Entity e, std::string_view clip, const cl_anim_play_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_anim_layer

cl_result cl_entity_anim_layer(cl_entity e, int32_t layer, const cl_anim_layer_opts* opts);

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.anim_layer, entity:anim_layer(...)
C++: Entity::anim_layer(int32_t layer, const cl_anim_layer_opts* opts) → Expected<void>; clight::entity::anim_layer(Entity e, int32_t layer, const cl_anim_layer_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_anim_stop

cl_result cl_entity_anim_stop(cl_entity e, int32_t layer, float fade);

Stops a layer (-1: every layer), fading out over fade seconds (0: at once).

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.anim_stop, entity:anim_stop(...)
C++: Entity::anim_stop(int32_t layer, float fade) → Expected<void>; clight::entity::anim_stop(Entity e, int32_t layer, float fade) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_anim_clip

cl_result cl_entity_anim_clip(cl_entity e, int32_t layer, char* buf, size_t cap, size_t* out_len);

The clip a layer plays (“” when none).

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.anim_clip, entity:anim_clip(...)
C++: Entity::anim_clip(int32_t layer) → Expected<std::string>; clight::entity::anim_clip(Entity e, int32_t layer) → 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_entity_anim_state

cl_result cl_entity_anim_state(cl_entity e, int32_t layer, cl_anim_layer_state* out);

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.anim_state, entity:anim_state(...)
C++: Entity::anim_state(int32_t layer) → Expected<cl_anim_layer_state>; clight::entity::anim_state(Entity e, int32_t layer) → Expected<cl_anim_layer_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_entity_set_morph

cl_result cl_entity_set_morph(cl_entity e, cl_str name, float weight);

A morph target’s weight (0…1; more exaggerates), over what the clips set; weight < 0 hands it back to the clips.

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.set_morph, entity:set_morph(...)
C++: Entity::set_morph(std::string_view name, float weight) → Expected<void>; clight::entity::set_morph(Entity e, std::string_view name, float weight) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_anim_look_at

cl_result cl_entity_anim_look_at(cl_entity e, const cl_look_at_opts* opts);

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.anim_look_at, entity:anim_look_at(...)
C++: Entity::anim_look_at(const cl_look_at_opts* opts) → Expected<void>; clight::entity::anim_look_at(Entity e, const cl_look_at_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_bone_transform

cl_result cl_entity_bone_transform(cl_entity e, cl_str bone, cl_bone_transform* out);

Where a bone is now (server: this tick’s pose; client: the current pose), for attaching items, particles and hit boxes. CL_E_NOT_FOUND: no model or no such bone.

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.bone_transform, entity:bone_transform(...)
C++: Entity::bone_transform(std::string_view bone) → Expected<cl_bone_transform>; clight::entity::bone_transform(Entity e, std::string_view bone) → Expected<cl_bone_transform>
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_entity_anim_root_motion

cl_result cl_entity_anim_root_motion(cl_entity e, cl_vec3* out);

The root motion of the last tick (world blocks; zero without root-motion clips).

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.anim_root_motion, entity:anim_root_motion(...)
C++: Entity::anim_root_motion() → Expected<cl_vec3>; clight::entity::anim_root_motion(Entity e) → Expected<cl_vec3>
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_entity_model

cl_result cl_entity_model(cl_entity e, cl_model* out);

The entity’s model (CL_E_NOT_FOUND: none).

Side: both. Context: TICK (tick thread). Since: API 1.9.
Lua: cl.entity.model, entity:model(...)
C++: Entity::model() → Expected<Model>; clight::entity::model(Entity e) → 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_level_entities_in_box

cl_result cl_level_entities_in_box(cl_level level, cl_vec3 min, cl_vec3 max, const cl_entity_query* query, cl_entity* out, size_t cap, size_t* out_count);

Every entity whose hitbox touches the box from min to max (Level#getEntities), filtered. On a client: the client’s copies (tags are unknown there; a tag filter matches nothing). The box may be at most 1024 blocks on a side.

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.level_entities_in_box, level:entities_in_box(...)
C++: Level::entities_in_box(cl_vec3 min, cl_vec3 max, const cl_entity_query* query) → Expected<std::vector<Entity>>; clight::entity::level_entities_in_box(Level level, cl_vec3 min, cl_vec3 max, const cl_entity_query* query) → Expected<std::vector<Entity>>
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_nearest_player

cl_result cl_level_nearest_player(cl_level level, cl_vec3 pos, double range, cl_entity* out);

The nearest player within range blocks of pos (range <= 0: any distance), spectators left out (Level#getNearestPlayer). CL_E_NOT_FOUND: none.

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.level_nearest_player, level:nearest_player(...)
C++: Level::nearest_player(cl_vec3 pos, double range) → Expected<Entity>; clight::entity::level_nearest_player(Level level, cl_vec3 pos, double range) → 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_entity_by_uuid

cl_result cl_level_entity_by_uuid(cl_level level, cl_uuid id, cl_entity* out);

The entity (or player) with this UUID in the level. CL_E_NOT_FOUND: none.

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.level_entity_by_uuid, level:entity_by_uuid(...)
C++: Level::entity_by_uuid(cl_uuid id) → Expected<Entity>; clight::entity::level_entity_by_uuid(Level level, cl_uuid id) → 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_entity_by_uuid

cl_result cl_entity_by_uuid(cl_uuid id, cl_entity* out);

The entity (or player) with this UUID in any level of the server (ServerLevel#getEntity over every level).

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.by_uuid
C++: clight::entity::by_uuid(cl_uuid id) → 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_entity_category

cl_result cl_entity_category(cl_entity e, char* buf, size_t cap, size_t* out_len);

The entity’s MobCategory (“monster”, “creature”, …, “misc”; “player” for players).

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.category, entity:category(...)
C++: Entity::category() → Expected<std::string>; clight::entity::category(Entity e) → 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_entity_has_tag

bool cl_entity_has_tag(cl_entity e, cl_str tag);

Entity tags (like /tag; saved with the entity, at most 1024 per entity).

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.has_tag, entity:has_tag(...)
C++: Entity::has_tag(std::string_view tag) → bool; clight::entity::has_tag(Entity e, std::string_view tag) → bool

cl_entity_add_tag

cl_result cl_entity_add_tag(cl_entity e, cl_str tag);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.add_tag, entity:add_tag(...)
C++: Entity::add_tag(std::string_view tag) → Expected<void>; clight::entity::add_tag(Entity e, std::string_view tag) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_remove_tag

cl_result cl_entity_remove_tag(cl_entity e, cl_str tag);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.remove_tag, entity:remove_tag(...)
C++: Entity::remove_tag(std::string_view tag) → Expected<void>; clight::entity::remove_tag(Entity e, std::string_view tag) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_attribute

cl_result cl_entity_attribute(cl_entity e, cl_str id, double* out);

An attribute’s current value (base + modifiers, clamped like vanilla). id: “minecraft:movement_speed” (a missing namespace is minecraft). CL_E_NOT_FOUND: unknown attribute; CL_E_UNSUPPORTED: the entity does not have it (or is not living), like /attribute’s “has no attribute”.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.attribute, entity:attribute(...)
C++: Entity::attribute(std::string_view id) → Expected<double>; clight::entity::attribute(Entity e, std::string_view id) → Expected<double>
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_entity_attribute_base

cl_result cl_entity_attribute_base(cl_entity e, cl_str id, double* out);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.attribute_base, entity:attribute_base(...)
C++: Entity::attribute_base(std::string_view id) → Expected<double>; clight::entity::attribute_base(Entity e, std::string_view id) → Expected<double>
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_entity_set_attribute_base

cl_result cl_entity_set_attribute_base(cl_entity e, cl_str id, double value);

Sets the base value (saved; synced to clients like vanilla when the attribute is syncable).

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.set_attribute_base, entity:set_attribute_base(...)
C++: Entity::set_attribute_base(std::string_view id, double value) → Expected<void>; clight::entity::set_attribute_base(Entity e, std::string_view id, double value) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_add_attribute_modifier

cl_result cl_entity_add_attribute_modifier(cl_entity e, cl_str attribute, cl_str modifier, double amount, cl_attribute_op op);

Adds a modifier with its own id (“my_mod:rage”); modifiers with different ids stack, the same id replaces the old one. Saved with the entity.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.add_attribute_modifier, entity:add_attribute_modifier(...)
C++: Entity::add_attribute_modifier(std::string_view attribute, std::string_view modifier, double amount, cl_attribute_op op) → Expected<void>; clight::entity::add_attribute_modifier(Entity e, std::string_view attribute, std::string_view modifier, double amount, cl_attribute_op op) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_remove_attribute_modifier

cl_result cl_entity_remove_attribute_modifier(cl_entity e, cl_str attribute, cl_str modifier);

CL_E_NOT_FOUND: the entity has no such modifier.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.remove_attribute_modifier, entity:remove_attribute_modifier(...)
C++: Entity::remove_attribute_modifier(std::string_view attribute, std::string_view modifier) → Expected<void>; clight::entity::remove_attribute_modifier(Entity e, std::string_view attribute, std::string_view modifier) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_has_attribute_modifier

bool cl_entity_has_attribute_modifier(cl_entity e, cl_str attribute, cl_str modifier);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.has_attribute_modifier, entity:has_attribute_modifier(...)
C++: Entity::has_attribute_modifier(std::string_view attribute, std::string_view modifier) → bool; clight::entity::has_attribute_modifier(Entity e, std::string_view attribute, std::string_view modifier) → bool

cl_entity_add_effect

bool cl_entity_add_effect(cl_entity e, cl_str effect, int32_t ticks, const cl_effect_opts* opts);

LivingEntity#addEffect: effect “minecraft:speed” for ticks (-1: infinite; instant effects apply at once). false: nothing changed (the entity is immune, or a stronger / longer effect is active; last_error tells bad arguments).

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.add_effect, entity:add_effect(...)
C++: Entity::add_effect(std::string_view effect, int32_t ticks, const cl_effect_opts* opts) → bool; clight::entity::add_effect(Entity e, std::string_view effect, int32_t ticks, const cl_effect_opts* opts) → bool

cl_entity_remove_effect

bool cl_entity_remove_effect(cl_entity e, cl_str effect);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.remove_effect, entity:remove_effect(...)
C++: Entity::remove_effect(std::string_view effect) → bool; clight::entity::remove_effect(Entity e, std::string_view effect) → bool

cl_entity_has_effect

bool cl_entity_has_effect(cl_entity e, cl_str effect);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.has_effect, entity:has_effect(...)
C++: Entity::has_effect(std::string_view effect) → bool; clight::entity::has_effect(Entity e, std::string_view effect) → bool

cl_entity_effect

cl_result cl_entity_effect(cl_entity e, cl_str effect, cl_effect_info* out);

CL_E_NOT_FOUND: the effect is not active.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.effect, entity:effect(...)
C++: Entity::effect(std::string_view effect) → Expected<cl_effect_info>; clight::entity::effect(Entity e, std::string_view effect) → Expected<cl_effect_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_entity_clear_effects

int32_t cl_entity_clear_effects(cl_entity e);

Removes every effect (like milk); returns how many.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.clear_effects, entity:clear_effects(...)
C++: Entity::clear_effects() → int32_t; clight::entity::clear_effects(Entity e) → int32_t

cl_entity_set_synced_bool

cl_result cl_entity_set_synced_bool(cl_entity e, cl_str key, bool value);

Synced per-entity data: small key / value pairs the server keeps on an entity (players too) and sends to every Celestial client with CLight that sees it (at once, and to players who see it later). Vanilla clients get nothing. For render state, animation state, mod HUDs. Keys are ids (“my_mod:charge”); at most 64 keys per entity, strings at most 1024 bytes. Saved with the entity (players: for the session). Setting the same value again sends nothing.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.set_synced_bool, entity:set_synced_bool(...)
C++: Entity::set_synced_bool(std::string_view key, bool value) → Expected<void>; clight::entity::set_synced_bool(Entity e, std::string_view key, bool value) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_set_synced_number

cl_result cl_entity_set_synced_number(cl_entity e, cl_str key, double value);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.set_synced_number, entity:set_synced_number(...)
C++: Entity::set_synced_number(std::string_view key, double value) → Expected<void>; clight::entity::set_synced_number(Entity e, std::string_view key, double value) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_set_synced_string

cl_result cl_entity_set_synced_string(cl_entity e, cl_str key, cl_str value);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.set_synced_string, entity:set_synced_string(...)
C++: Entity::set_synced_string(std::string_view key, std::string_view value) → Expected<void>; clight::entity::set_synced_string(Entity e, std::string_view key, std::string_view value) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_clear_synced

cl_result cl_entity_clear_synced(cl_entity e, cl_str key);

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.clear_synced, entity:clear_synced(...)
C++: Entity::clear_synced(std::string_view key) → Expected<void>; clight::entity::clear_synced(Entity e, std::string_view key) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_synced_type

cl_synced_type cl_entity_synced_type(cl_entity e, cl_str key);

What a key holds (NONE: not set). On a client: what the server sent for the client’s copy.

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.synced_type, entity:synced_type(...)
C++: Entity::synced_type(std::string_view key) → cl_synced_type; clight::entity::synced_type(Entity e, std::string_view key) → cl_synced_type

cl_entity_synced_bool

bool cl_entity_synced_bool(cl_entity e, cl_str key);

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.synced_bool, entity:synced_bool(...)
C++: Entity::synced_bool(std::string_view key) → bool; clight::entity::synced_bool(Entity e, std::string_view key) → bool

cl_entity_synced_number

double cl_entity_synced_number(cl_entity e, cl_str key);

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.synced_number, entity:synced_number(...)
C++: Entity::synced_number(std::string_view key) → double; clight::entity::synced_number(Entity e, std::string_view key) → double

cl_entity_synced_string

cl_result cl_entity_synced_string(cl_entity e, cl_str key, char* buf, size_t cap, size_t* out_len);

CL_E_NOT_FOUND: no string under the key.

Side: both. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.synced_string, entity:synced_string(...)
C++: Entity::synced_string(std::string_view key) → Expected<std::string>; clight::entity::synced_string(Entity e, 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_entity_hurt

bool cl_entity_hurt(cl_entity target, float amount, cl_str damage_type, const cl_hurt_opts* opts);

Damages an entity with a damage type (“minecraft:magic”, “my_mod:laser”), through the whole vanilla pipeline (invulnerability, armor, enchantments, effects, totems, entity.damage, death). true: it took the damage. Non-living entities react like to any hit (end crystals explode, item frames drop their item, …).

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.hurt, entity:hurt(...)
C++: Entity::hurt(float amount, std::string_view damage_type, const cl_hurt_opts* opts) → bool; clight::entity::hurt(Entity target, float amount, std::string_view damage_type, const cl_hurt_opts* opts) → bool

cl_entity_knockback

cl_result cl_entity_knockback(cl_entity e, double strength, double dx, double dz);

LivingEntity#knockback: pushes the entity away from the direction (dx, dz) (the attacker’s position minus the entity’s, like vanilla) with strength (vanilla hits: 0.4), against its knockback resistance.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.knockback, entity:knockback(...)
C++: Entity::knockback(double strength, double dx, double dz) → Expected<void>; clight::entity::knockback(Entity e, double strength, double dx, double dz) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_set_passenger

cl_result cl_entity_set_passenger(cl_entity vehicle, cl_entity passenger, const cl_ride_opts* opts);

Puts passenger on vehicle (it leaves its old vehicle first). Players can be passengers, not vehicles. CL_E_CONFLICT: the vehicle refused (force off), or it would ride itself / its own passenger.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.set_passenger, entity:set_passenger(...)
C++: Entity::set_passenger(Entity passenger, const cl_ride_opts* opts) → Expected<void>; clight::entity::set_passenger(Entity vehicle, Entity passenger, const cl_ride_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_dismount

cl_result cl_entity_dismount(cl_entity e);

Gets off the vehicle (Entity#stopRiding). CL_E_NOT_FOUND: not riding.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.dismount, entity:dismount(...)
C++: Entity::dismount() → Expected<void>; clight::entity::dismount(Entity e) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_eject_passengers

cl_result cl_entity_eject_passengers(cl_entity e);

Every passenger gets off (Entity#ejectPassengers).

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.eject_passengers, entity:eject_passengers(...)
C++: Entity::eject_passengers() → Expected<void>; clight::entity::eject_passengers(Entity e) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_vehicle

cl_result cl_entity_vehicle(cl_entity e, cl_entity* out);

What the entity rides. CL_E_NOT_FOUND: nothing.

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.vehicle, entity:vehicle(...)
C++: Entity::vehicle() → Expected<Entity>; clight::entity::vehicle(Entity e) → 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_entity_passengers

cl_result cl_entity_passengers(cl_entity e, cl_entity* out, size_t cap, size_t* out_count);

The passengers (the first one controls the vehicle).

Side: server. Context: TICK (tick thread). Since: API 1.10.
Lua: cl.entity.passengers, entity:passengers(...)
C++: Entity::passengers() → Expected<std::vector<Entity>>; clight::entity::passengers(Entity e) → Expected<std::vector<Entity>>
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_player_add_movement_modifier

cl_result cl_player_add_movement_modifier(cl_entity player, const cl_movement_modifier* m);

Adds (or replaces) a movement modifier. Speed, jump and step go through vanilla attribute modifiers, so the client’s own movement prediction applies them (vanilla clients too: no rubber-banding). can_sprint = false: Celestial clients with CLight cannot start sprinting; on vanilla clients sprinting gives no extra speed. Modifiers last until removed or the player leaves (not saved: add them again in player.join).

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.add_movement_modifier, entity:add_movement_modifier(...), cl.entity.player_add_movement_modifier (old name)
C++: Entity::add_movement_modifier(const cl_movement_modifier* m) → Expected<void>; clight::entity::player_add_movement_modifier(Entity player, const cl_movement_modifier* m) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_remove_movement_modifier

cl_result cl_player_remove_movement_modifier(cl_entity player, cl_str id);

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.remove_movement_modifier, entity:remove_movement_modifier(...), cl.entity.player_remove_movement_modifier (old name)
C++: Entity::remove_movement_modifier(std::string_view id) → Expected<void>; clight::entity::player_remove_movement_modifier(Entity player, std::string_view id) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_has_movement_modifier

bool cl_player_has_movement_modifier(cl_entity player, cl_str id);

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.has_movement_modifier, entity:has_movement_modifier(...), cl.entity.player_has_movement_modifier (old name)
C++: Entity::has_movement_modifier(std::string_view id) → bool; clight::entity::player_has_movement_modifier(Entity player, std::string_view id) → bool

cl_player_movement

cl_result cl_player_movement(cl_entity player, cl_movement_state* out);

The combined modifiers (on a client: what the server sent for the local player).

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.movement, entity:movement(...), cl.entity.player_movement (old name)
C++: Entity::movement() → Expected<cl_movement_state>; clight::entity::player_movement(Entity player) → Expected<cl_movement_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_player_set_part_visible

cl_result cl_player_set_part_visible(cl_entity player, cl_player_part part, bool visible);

Shows or hides a part of the player model (a base part hides its outer layer, its armour and, for an arm, what the hand holds). On the server: every Celestial client with CLight that sees the player (and the player’s own client, first person included); on a client: this client’s view only, until the server sends a change. Vanilla clients see the whole player.

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.set_part_visible, entity:set_part_visible(...), cl.entity.player_set_part_visible (old name)
C++: Entity::set_part_visible(cl_player_part part, bool visible) → Expected<void>; clight::entity::player_set_part_visible(Entity player, cl_player_part part, bool visible) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_part_visible

bool cl_player_part_visible(cl_entity player, cl_player_part part);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.part_visible, entity:part_visible(...), cl.entity.player_part_visible (old name)
C++: Entity::part_visible(cl_player_part part) → bool; clight::entity::player_part_visible(Entity player, cl_player_part part) → bool

cl_player_set_part_model

cl_result cl_player_set_part_model(cl_entity player, cl_player_part part, cl_str path, const cl_part_model_opts* opts);

Draws a glTF model (model_load path, “my_mod:models/peg_leg.glb”) at a part of the player model, following the part’s animation; the part itself hides unless keep_part. path empty: the vanilla part again. Synced like player_set_part_visible. Load the model on the client at setup (model_load) to avoid a load on first sight.

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.set_part_model, entity:set_part_model(...), cl.entity.player_set_part_model (old name)
C++: Entity::set_part_model(cl_player_part part, std::string_view path, const cl_part_model_opts* opts) → Expected<void>; clight::entity::player_set_part_model(Entity player, cl_player_part part, std::string_view path, const cl_part_model_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_set_hand_disabled

cl_result cl_player_set_hand_disabled(cl_entity player, cl_hand hand, bool disabled);

Disables a hand: the player cannot use, place, attack or break with it (the server ignores it; Celestial clients with CLight do not even try). Main hand disabled: no attacks, mining or item use with it; off hand disabled: the off-hand item is not used and F cannot swap into it.

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.set_hand_disabled, entity:set_hand_disabled(...), cl.entity.player_set_hand_disabled (old name)
C++: Entity::set_hand_disabled(cl_hand hand, bool disabled) → Expected<void>; clight::entity::player_set_hand_disabled(Entity player, cl_hand hand, bool disabled) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_hand_disabled

bool cl_player_hand_disabled(cl_entity player, cl_hand hand);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.hand_disabled, entity:hand_disabled(...), cl.entity.player_hand_disabled (old name)
C++: Entity::hand_disabled(cl_hand hand) → bool; clight::entity::player_hand_disabled(Entity player, cl_hand hand) → bool

cl_player_lock_slot

cl_result cl_player_lock_slot(cl_entity player, int32_t slot, bool locked, bool select_lock);

Locks an inventory slot (0-8 hotbar, 9-35 main, 36-39 armour, 40 off hand): the player cannot move, drop, swap or shift-click its item (mods still change it with player_inventory_set). select_lock: the hotbar slot cannot be selected either.

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.lock_slot, entity:lock_slot(...), cl.entity.player_lock_slot (old name)
C++: Entity::lock_slot(int32_t slot, bool locked, bool select_lock) → Expected<void>; clight::entity::player_lock_slot(Entity player, int32_t slot, bool locked, bool select_lock) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_slot_locked

bool cl_player_slot_locked(cl_entity player, int32_t slot);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.slot_locked, entity:slot_locked(...), cl.entity.player_slot_locked (old name)
C++: Entity::slot_locked(int32_t slot) → bool; clight::entity::player_slot_locked(Entity player, int32_t slot) → bool

cl_player_set_input_override

cl_result cl_player_set_input_override(cl_entity player, const cl_input_override* o);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.set_input_override, entity:set_input_override(...), cl.entity.player_set_input_override (old name)
C++: Entity::set_input_override(const cl_input_override* o) → Expected<void>; clight::entity::player_set_input_override(Entity player, const cl_input_override* o) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_clear_input_override

cl_result cl_player_clear_input_override(cl_entity player);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.clear_input_override, entity:clear_input_override(...), cl.entity.player_clear_input_override (old name)
C++: Entity::clear_input_override() → Expected<void>; clight::entity::player_clear_input_override(Entity player) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_input_override

cl_result cl_player_input_override(cl_entity player, cl_input_override* out);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.input_override, entity:input_override(...), cl.entity.player_input_override (old name)
C++: Entity::input_override() → Expected<cl_input_override>; clight::entity::player_input_override(Entity player) → Expected<cl_input_override>
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_player_food

int32_t cl_player_food(cl_entity player);

Food 0…20 (FoodData#foodLevel), saturation 0…food (FoodData#saturationLevel), exhaustion 0…40.

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.food, entity:food(...), cl.entity.player_food (old name)
C++: Entity::food() → int32_t; clight::entity::player_food(Entity player) → int32_t

cl_player_set_food

cl_result cl_player_set_food(cl_entity player, int32_t food);

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.set_food, entity:set_food(...), cl.entity.player_set_food (old name)
C++: Entity::set_food(int32_t food) → Expected<void>; clight::entity::player_set_food(Entity player, int32_t food) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_saturation

float cl_player_saturation(cl_entity player);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.saturation, entity:saturation(...), cl.entity.player_saturation (old name)
C++: Entity::saturation() → float; clight::entity::player_saturation(Entity player) → float

cl_player_set_saturation

cl_result cl_player_set_saturation(cl_entity player, float saturation);

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.set_saturation, entity:set_saturation(...), cl.entity.player_set_saturation (old name)
C++: Entity::set_saturation(float saturation) → Expected<void>; clight::entity::player_set_saturation(Entity player, float saturation) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_exhaustion

float cl_player_exhaustion(cl_entity player);

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.exhaustion, entity:exhaustion(...), cl.entity.player_exhaustion (old name)
C++: Entity::exhaustion() → float; clight::entity::player_exhaustion(Entity player) → float

cl_player_exhaust

cl_result cl_player_exhaust(cl_entity player, float amount);

Adds exhaustion (Player#causeFoodExhaustion: not in creative / spectator).

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.exhaust, entity:exhaust(...), cl.entity.player_exhaust (old name)
C++: Entity::exhaust(float amount) → Expected<void>; clight::entity::player_exhaust(Entity player, float amount) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_air

int32_t cl_entity_air(cl_entity e);

Air supply in ticks (300 full, -20 drowning; Entity#getAirSupply). Works on every living entity.

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.entity.air, entity:air(...)
C++: Entity::air() → int32_t; clight::entity::air(Entity e) → int32_t

cl_entity_max_air

int32_t cl_entity_max_air(cl_entity e);

Side: both. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.entity.max_air, entity:max_air(...)
C++: Entity::max_air() → int32_t; clight::entity::max_air(Entity e) → int32_t

cl_entity_set_air

cl_result cl_entity_set_air(cl_entity e, int32_t air);

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.entity.set_air, entity:set_air(...)
C++: Entity::set_air(int32_t air) → Expected<void>; clight::entity::set_air(Entity e, int32_t air) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_set_natural_regen

cl_result cl_player_set_natural_regen(cl_entity player, bool enabled);

Natural regeneration from food for one player (the naturalRegeneration game rule still applies to everyone).

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.set_natural_regen, entity:set_natural_regen(...), cl.entity.player_set_natural_regen (old name)
C++: Entity::set_natural_regen(bool enabled) → Expected<void>; clight::entity::player_set_natural_regen(Entity player, bool enabled) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_player_natural_regen

bool cl_player_natural_regen(cl_entity player);

Side: server. Context: TICK (tick thread). Since: API 1.11.
Lua: cl.player.natural_regen, entity:natural_regen(...), cl.entity.player_natural_regen (old name)
C++: Entity::natural_regen() → bool; clight::entity::player_natural_regen(Entity player) → bool

cl_entity_path_to

cl_result cl_entity_path_to(cl_entity e, cl_vec3 pos, double speed, const cl_path_opts* opts);

Walks a mob to pos at speed (a multiplier of its movement speed, like vanilla goals: 1.0 walks) along a planned path (PathNavigation#moveTo). The mob’s own goals may give it another path (ai_clear_goals for full control). CL_E_NOT_FOUND: no path at all (a partial path still moves; entity_path tells whether it reaches the target). CL_E_UNSUPPORTED: not a mob.

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.path_to, entity:path_to(...)
C++: Entity::path_to(cl_vec3 pos, double speed, const cl_path_opts* opts) → Expected<void>; clight::entity::path_to(Entity e, cl_vec3 pos, double speed, const cl_path_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_follow_path

cl_result cl_entity_follow_path(cl_entity e, cl_path p, double speed);

Follows a path from level_find_path (PathNavigation#moveTo(Path)).

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.follow_path, entity:follow_path(...)
C++: Entity::follow_path(cl_path p, double speed) → Expected<void>; clight::entity::follow_path(Entity e, cl_path p, double speed) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_path

cl_path cl_entity_path(cl_entity e);

A copy of the path the mob follows (null: none).

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.path, entity:path(...)
C++: Entity::path() → Path; clight::entity::path(Entity e) → Path
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_entity_path_state

cl_path_state cl_entity_path_state(cl_entity e);

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.path_state, entity:path_state(...)
C++: Entity::path_state() → cl_path_state; clight::entity::path_state(Entity e) → cl_path_state

cl_entity_path_done

bool cl_entity_path_done(cl_entity e);

PathNavigation#isDone: no path, arrived or stuck.

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.path_done, entity:path_done(...)
C++: Entity::path_done() → bool; clight::entity::path_done(Entity e) → bool

cl_entity_path_stop

cl_result cl_entity_path_stop(cl_entity e);

PathNavigation#stop.

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.path_stop, entity:path_stop(...)
C++: Entity::path_stop() → Expected<void>; clight::entity::path_stop(Entity e) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_look_at

cl_result cl_entity_look_at(cl_entity e, cl_vec3 pos, float yaw_speed, float pitch_speed);

Turns the mob’s head towards pos (LookControl#setLookAt, degrees per tick; <= 0: the mob’s own head speeds). Lasts two ticks like vanilla: call it every tick to keep looking. CL_E_UNSUPPORTED: not a mob.

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.look_at, entity:look_at(...)
C++: Entity::look_at(cl_vec3 pos, float yaw_speed, float pitch_speed) → Expected<void>; clight::entity::look_at(Entity e, cl_vec3 pos, float yaw_speed, float pitch_speed) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_look_at_entity

cl_result cl_entity_look_at_entity(cl_entity e, cl_entity target, float yaw_speed, float pitch_speed);

The same at an entity’s eyes.

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.look_at_entity, entity:look_at_entity(...)
C++: Entity::look_at_entity(Entity target, float yaw_speed, float pitch_speed) → Expected<void>; clight::entity::look_at_entity(Entity e, Entity target, float yaw_speed, float pitch_speed) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_data_get

cl_result cl_entity_data_get(cl_entity e, cl_str key, char* buf, size_t cap, size_t* out_len);

Data attachments: NBT values under namespaced keys (“my_mod:quests”) on any entity or player, saved with it under “clight:data” (players: in their player file), kept as they are when the mod is removed. Values cross the API as SNBT text ({level:3,done:[1b,0b]}) or as binary NBT (network framing: the type byte, then the payload). At most 256 keys, 1 MiB per value. On a client: the synced keys of the client’s copy. CL_E_NOT_FOUND: no value under the key.

Side: both. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.data_get, entity:data_get(...)
C++: Entity::data_get(std::string_view key) → Expected<std::string>; clight::entity::data_get(Entity e, 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_entity_data_set

cl_result cl_entity_data_set(cl_entity e, cl_str key, cl_str snbt, cl_data_flags flags);

CL_E_PARSE: bad SNBT. Setting the same value again sends nothing.

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.data_set, entity:data_set(...)
C++: Entity::data_set(std::string_view key, std::string_view snbt, cl_data_flags flags) → Expected<void>; clight::entity::data_set(Entity e, std::string_view key, std::string_view snbt, cl_data_flags flags) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_data_get_nbt

cl_buf cl_entity_data_get_nbt(cl_entity e, cl_str key);

The value as binary NBT (owned buf; null when unset).

Side: both. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.data_get_nbt, entity:data_get_nbt(...)
C++: Entity::data_get_nbt(std::string_view key) → Buf; clight::entity::data_get_nbt(Entity e, 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_entity_data_set_nbt

cl_result cl_entity_data_set_nbt(cl_entity e, cl_str key, cl_buf data, cl_data_flags flags);

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.data_set_nbt, entity:data_set_nbt(...)
C++: Entity::data_set_nbt(std::string_view key, cl_buf data, cl_data_flags flags) → Expected<void>; clight::entity::data_set_nbt(Entity e, std::string_view key, cl_buf data, cl_data_flags flags) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_data_remove

cl_result cl_entity_data_remove(cl_entity e, cl_str key);

Side: server. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.data_remove, entity:data_remove(...)
C++: Entity::data_remove(std::string_view key) → Expected<void>; clight::entity::data_remove(Entity e, std::string_view key) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_data_keys

cl_result cl_entity_data_keys(cl_entity e, char* buf, size_t cap, size_t* out_len);

The keys, one per line.

Side: both. Context: TICK (tick thread). Since: API 1.12.
Lua: cl.entity.data_keys, entity:data_keys(...)
C++: Entity::data_keys() → Expected<std::string>; clight::entity::data_keys(Entity e) → 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_entity_set_render_param

cl_result cl_entity_set_render_param(cl_entity e, cl_str name, float value);

A render parameter of an entity: a number a model’s custom shader reads (model_shader_opts.params). It is the entity’s synced number under the same key (entity_set_synced_number), so on the server it reaches every Celestial client with CLight that sees the entity (vanilla clients ignore it). On a client: this client’s own value, which wins over the synced one until entity_clear_render_param.

Side: both. Context: TICK (tick thread). Since: API 1.13.
Lua: cl.entity.set_render_param, entity:set_render_param(...)
C++: Entity::set_render_param(std::string_view name, float value) → Expected<void>; clight::entity::set_render_param(Entity e, std::string_view name, float value) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_render_param

float cl_entity_render_param(cl_entity e, cl_str name);

The value (on a client: its own, else the synced one; 0 when unset).

Side: both. Context: ANY (any thread). Since: API 1.13.
Lua: cl.entity.render_param, entity:render_param(...)
C++: Entity::render_param(std::string_view name) → float; clight::entity::render_param(Entity e, std::string_view name) → float

cl_entity_clear_render_param

cl_result cl_entity_clear_render_param(cl_entity e, cl_str name);

Side: both. Context: TICK (tick thread). Since: API 1.13.
Lua: cl.entity.clear_render_param, entity:clear_render_param(...)
C++: Entity::clear_render_param(std::string_view name) → Expected<void>; clight::entity::clear_render_param(Entity e, std::string_view name) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_set_material_variant

cl_result cl_entity_set_material_variant(cl_entity e, cl_str variant);

The material variant (glTF KHR_materials_variants) the entity’s model draws with: a variant name of the model (“” = the default materials). Synced like render parameters (server: every Celestial client with CLight; client: local).

Side: both. Context: TICK (tick thread). Since: API 1.13.
Lua: cl.entity.set_material_variant, entity:set_material_variant(...)
C++: Entity::set_material_variant(std::string_view variant) → Expected<void>; clight::entity::set_material_variant(Entity e, std::string_view variant) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_material_variant

cl_result cl_entity_material_variant(cl_entity e, char* buf, size_t cap, size_t* out_len);

Side: both. Context: ANY (any thread). Since: API 1.13.
Lua: cl.entity.material_variant, entity:material_variant(...)
C++: Entity::material_variant() → Expected<std::string>; clight::entity::material_variant(Entity e) → 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_entity_path_to_entity

cl_result cl_entity_path_to_entity(cl_entity e, cl_entity target, double speed, float repath, const cl_path_opts* opts);

Walks a mob to another entity and plans the path again whenever the target moved more than repath blocks (<= 0: 1 block; checked every 4 ticks). Within opts.reach it stands; it walks again when the target moves away. Lasts until entity_path_stop or the target is gone (or in another level). The same options as entity_path_to.

Side: server. Context: TICK (tick thread). Since: API 1.13.
Lua: cl.entity.path_to_entity, entity:path_to_entity(...)
C++: Entity::path_to_entity(Entity target, double speed, float repath, const cl_path_opts* opts) → Expected<void>; clight::entity::path_to_entity(Entity e, Entity target, double speed, float repath, const cl_path_opts* opts) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_set_casts_shadow

cl_result cl_entity_set_casts_shadow(cl_entity e, cl_shadow_mode mode);

Per entity (kept by its UUID while the client runs, so a reused network id never inherits it). Client handles, and on the integrated server the server’s handles of the same entity.

Side: client. Context: TICK (tick thread). Since: API 1.18.
Lua: cl.entity.set_casts_shadow, entity:set_casts_shadow(...)
C++: Entity::set_casts_shadow(cl_shadow_mode mode) → Expected<void>; clight::entity::set_casts_shadow(Entity e, cl_shadow_mode mode) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_casts_shadow

bool cl_entity_casts_shadow(cl_entity e);

Whether the entity casts a shader pack shadow by its type and entity settings (the player’s setting aside).

Side: client. Context: TICK (tick thread). Since: API 1.18.
Lua: cl.entity.casts_shadow, entity:casts_shadow(...)
C++: Entity::casts_shadow() → bool; clight::entity::casts_shadow(Entity e) → bool

cl_attachment_register

cl_result cl_attachment_register(cl_str key, const cl_attachment_desc* desc);

Registers a key (“mana”, “my_mod:mana”) for every scope (entities, players, chunks, saved data). Call it on both sides at setup. CL_E_ALREADY_EXISTS: another mod registered the key; the same mod may register it again (a hot reload).

Side: both. Context: ANY (any thread). Since: API 1.20.
Lua: cl.entity.attachment_register
C++: clight::entity::attachment_register(std::string_view key, const cl_attachment_desc* desc) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_equipment

cl_item_stack cl_entity_equipment(cl_entity e, cl_equip_slot slot);

What a living entity or player wears or holds in the slot (owned stack; empty for an empty slot). Server: the whole stack; client: the item and count the server sent (SetEquipment), the local player’s own inventory. CL_E_WRONG_TYPE (in cl_last_error): not a living entity.

Side: both. Context: TICK (tick thread). Since: API 1.20.
Lua: cl.entity.equipment, entity:equipment(...)
C++: Entity::equipment(cl_equip_slot slot) → ItemStack; clight::entity::equipment(Entity e, cl_equip_slot 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_entity_set_equipment

cl_result cl_entity_set_equipment(cl_entity e, cl_equip_slot slot, cl_item_stack stack);

Puts a stack (or an empty one) into the slot; players get it in their inventory, mobs show it to every client.

Side: server. Context: TICK (tick thread). Since: API 1.20.
Lua: cl.entity.set_equipment, entity:set_equipment(...)
C++: Entity::set_equipment(cl_equip_slot slot, cl_item_stack stack) → Expected<void>; clight::entity::set_equipment(Entity e, cl_equip_slot slot, cl_item_stack stack) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_entity_set_drop_chance

cl_result cl_entity_set_drop_chance(cl_entity e, cl_equip_slot slot, float chance);

Mob#setDropChance: 0 never drops, 1 drops (damaged like vanilla), above 1 always drops undamaged. Mobs only.

Side: server. Context: TICK (tick thread). Since: API 1.20.
Lua: cl.entity.set_drop_chance, entity:set_drop_chance(...)
C++: Entity::set_drop_chance(cl_equip_slot slot, float chance) → Expected<void>; clight::entity::set_drop_chance(Entity e, cl_equip_slot slot, float chance) → Expected<void>
Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.