Skip to content
Download

AI and navigation (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. 16 functions, the newest from API 1.12.

Explanations and examples: Entity AI, Guide: AI and pathfinding. Every function of the ai 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_ai_path_cost_register cl.ai.path_cost_register server MAIN 1.12
cl_level_find_path cl.ai.level_find_path server TICK 1.12
cl_path_retain cl.ai.path_retain both ANY 1.12
cl_path_release cl.ai.path_release both ANY 1.12
cl_path_get_info cl.ai.path_get_info both ANY 1.12
cl_path_nodes cl.ai.path_nodes both ANY 1.12
cl_ai_goal_type_register cl.ai.goal_type_register server MAIN 1.12
cl_ai_add_goal cl.ai.add_goal server TICK 1.12
cl_ai_type_goal cl.ai.type_goal server MAIN 1.12
cl_ai_remove_goal cl.ai.remove_goal server TICK 1.12
cl_ai_goal_running cl.ai.goal_running server TICK 1.12
cl_ai_goal_entity cl.ai.goal_entity server TICK 1.12
cl_ai_goal_type cl.ai.goal_type server TICK 1.12
cl_ai_clear_goals cl.ai.clear_goals server TICK 1.12
cl_ai_set_target cl.ai.set_target server TICK 1.12
cl_ai_target cl.ai.target server TICK 1.12

cl_ai_path_cost_register

cl_result cl_ai_path_cost_register(const cl_path_cost_desc* desc);

Registers a named path cost (“my_mod:avoid_light”) that path_opts.cost refers to. Any time on the server thread; the same id again replaces it.

  • Side: server. Context: MAIN (startup (main thread)). Since: API 1.12.
  • Lua: cl.ai.path_cost_register
  • C++: clight::ai::path_cost_register(const cl_path_cost_desc* desc) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_level_find_path

cl_path cl_level_find_path(cl_level level, cl_vec3 from, cl_vec3 to, const cl_path_opts* opts);

Plans a path from from to to without moving anything (PathNavigation#createPath). With opts.entity: for that mob’s navigation, size and maluses. Null when there is no path at all (cl_last_error CL_E_NOT_FOUND); a partial path otherwise. The same code vanilla mobs use.

  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.level_find_path, level:find_path(...)
  • C++: Level::find_path(cl_vec3 from, cl_vec3 to, const cl_path_opts* opts) → Path; clight::ai::level_find_path(Level level, cl_vec3 from, cl_vec3 to, const cl_path_opts* opts) → 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_path_retain

void cl_path_retain(cl_path p);
  • Side: both. Context: ANY (any thread). Since: API 1.12.
  • Lua: cl.ai.path_retain, path:retain(...)
  • C++: Path::retain() → void; clight::ai::path_retain(cl_path p) → void

cl_path_release

void cl_path_release(cl_path p);
  • Side: both. Context: ANY (any thread). Since: API 1.12.
  • Lua: cl.ai.path_release, path:release(...)
  • C++: Path::release() → void; clight::ai::path_release(cl_path p) → void

cl_path_get_info

cl_result cl_path_get_info(cl_path p, cl_path_info* out);
  • Side: both. Context: ANY (any thread). Since: API 1.12.
  • Lua: cl.ai.path_get_info, path:get_info(...)
  • C++: Path::get_info() → Expected<cl_path_info>; clight::ai::path_get_info(cl_path p) → Expected<cl_path_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_path_nodes

cl_result cl_path_nodes(cl_path p, cl_block_pos* out, size_t cap, size_t* out_count);

The nodes (the block positions the feet pass through), first to last.

  • Side: both. Context: ANY (any thread). Since: API 1.12.
  • Lua: cl.ai.path_nodes, path:nodes(...)
  • C++: Path::nodes() → Expected<std::vector<cl_block_pos>>; clight::ai::path_nodes(cl_path p) → Expected<std::vector<cl_block_pos>>
  • 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_ai_goal_type_register

cl_result cl_ai_goal_type_register(const cl_goal_type_desc* desc, cl_holder* out);

Registers a goal type (“my_mod:hunt”). Any time on the server thread; the same id again replaces it for new goals.

  • Side: server. Context: MAIN (startup (main thread)). Since: API 1.12.
  • Lua: cl.ai.goal_type_register
  • C++: clight::ai::goal_type_register(const cl_goal_type_desc* desc) → Expected<cl_holder>
  • 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_ai_add_goal

cl_result cl_ai_add_goal(cl_entity e, int32_t priority, cl_str type, cl_goal* out);

Adds a goal of a type to one mob (mod mobs and vanilla mobs; brain mobs too: the goal selector runs before the brain). priority: lower runs first (vanilla goals use 0…10). Not saved: add goals again when mobs load (ai_type_goal does it for a whole type). CL_E_UNSUPPORTED: not a mob.

  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.add_goal, entity:add_goal(...)
  • C++: Entity::add_goal(int32_t priority, std::string_view type) → Expected<Goal>; clight::ai::add_goal(Entity e, int32_t priority, std::string_view type) → Expected<Goal>
  • 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_ai_type_goal

cl_result cl_ai_type_goal(cl_str entity_type, int32_t priority, cl_str type);

Every mob of an entity type (vanilla or mod) gets the goal when it registers its goals: new and loaded mobs.

  • Side: server. Context: MAIN (startup (main thread)). Since: API 1.12.
  • Lua: cl.ai.type_goal
  • C++: clight::ai::type_goal(std::string_view entity_type, int32_t priority, std::string_view type) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ai_remove_goal

cl_result cl_ai_remove_goal(cl_goal g);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.remove_goal, goal:remove_goal(...)
  • C++: Goal::remove_goal() → Expected<void>; clight::ai::remove_goal(Goal g) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_ai_goal_running

bool cl_ai_goal_running(cl_goal g);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.goal_running, goal:goal_running(...)
  • C++: Goal::running() → bool; clight::ai::goal_running(Goal g) → bool

cl_ai_goal_entity

cl_result cl_ai_goal_entity(cl_goal g, cl_entity* out);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.goal_entity, goal:goal_entity(...)
  • C++: Goal::entity() → Expected<Entity>; clight::ai::goal_entity(Goal g) → 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_ai_goal_type

cl_result cl_ai_goal_type(cl_goal g, char* buf, size_t cap, size_t* out_len);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.goal_type, goal:goal_type(...)
  • C++: Goal::type() → Expected<std::string>; clight::ai::goal_type(Goal g) → 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_ai_clear_goals

int32_t cl_ai_clear_goals(cl_entity e, cl_goal_list which);

Removes every goal of the list (GoalSelector#removeAllGoals: vanilla and mod goals; running ones stop). The vanilla goals come back when the mob loads again. Brain AI (villagers, piglins …) is not a goal list. Returns how many.

  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.clear_goals, entity:clear_goals(...)
  • C++: Entity::clear_goals(cl_goal_list which) → int32_t; clight::ai::clear_goals(Entity e, cl_goal_list which) → int32_t

cl_ai_set_target

cl_result cl_ai_set_target(cl_entity e, cl_entity target);

Mob#setTarget (null: none) and Mob#getTarget (CL_E_NOT_FOUND: none).

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

cl_ai_target

cl_result cl_ai_target(cl_entity e, cl_entity* out);
  • Side: server. Context: TICK (tick thread). Since: API 1.12.
  • Lua: cl.ai.target, entity:target(...)
  • C++: Entity::target() → Expected<Entity>; clight::ai::target(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.