Entity AI (goals, brains, pathfinding)

Status: Partly implemented (API 1.12). Pathfinding (plan and follow paths, doors, ladders, mod path costs, the entity’s current size), looking, goals in the vanilla goal and target selectors (mod mobs and vanilla mobs, also per entity type) and targets are implemented. Brain memories, sensors and behaviours (villagers, piglins, axolotls, wardens) are Planned.

Guide: AI and Pathfinding. Function tables: ai, entity, level.

Paths

C	Lua	What it does
cl_level_find_path(level, from, to, opts)	level:find_path(from, to, opts)	Plans a path without moving anything (PathNavigation#createPath); an owned cl_path, null when there is none at all.
cl_path_get_info, cl_path_nodes, cl_path_retain, cl_path_release	path:info(), path:nodes()	reaches_target, node count, next node, target, last node, length; the nodes first to last.
cl_entity_path_to(e, pos, speed, opts)	e:path_to(pos, speed, opts)	Plans and walks (PathNavigation#moveTo); CL_E_NOT_FOUND / false without any path.
cl_entity_follow_path(e, path, speed)	e:follow_path(path, speed)	Walks a planned path.
cl_entity_path, cl_entity_path_state, cl_entity_path_done, cl_entity_path_stop	e:path(), e:path_state(), e:path_done(), e:path_stop()	The current path (a copy), NONE / MOVING / DONE / STUCK, vanilla’s isDone, stop.
cl_ai_path_cost_register(desc)	cl.ai.path_cost(id, fn)	A named per-node cost (negative: impossible) for path_opts.cost (Lua also avoid = fn).

cl_path_opts: width / height (0: the entity’s current hitbox), mode (CL_NAV_WALK, CL_NAV_SWIM, CL_NAV_FLY, CL_NAV_AMPHIBIOUS; CL_NAV_DEFAULT the entity’s own), doors (-1 own, 0, 1; with 1 cl_entity_path_to also adds vanilla’s OpenDoorGoal), climb (#climbable blocks), reach (default 1 like vanilla), max_nodes (0: follow range x 16, 64…768), max_fall, water (the water malus; below -1 the entity’s own, -1 never), cost, entity (whose navigation cl_level_find_path plans for). Paths come from the same path finder vanilla mobs use; the CLight extras are off for vanilla navigation.

Looking and targets

cl_entity_look_at(e, pos, yaw_speed, pitch_speed) and cl_entity_look_at_entity (Lua e:look_at(pos_or_entity, speed)) are LookControl#setLookAt (two ticks, like vanilla). cl_ai_set_target / cl_ai_target (Lua e:set_target, e:target()) are Mob#setTarget / getTarget.

Goals

C	Lua	What it does
cl_ai_goal_type_register(desc, &holder)	cl.ai.goal_type{...}	A goal type: can_use (required), can_continue, start, tick, stop, removed, flags (CL_GOAL_MOVE, CL_GOAL_LOOK, CL_GOAL_JUMP, CL_GOAL_TARGET), targets, interruptable, every_tick.
cl_ai_add_goal(e, priority, type, &goal)	cl.ai.add_goal(e, priority, spec), e:add_goal(priority, spec)	Adds a goal to one mob’s goal (or target) selector; Lua specs are tables of functions with a state.
cl_ai_type_goal(entity_type, priority, type)	cl.ai.type_goal(type, priority, spec_or_id)	Every mob of the type gets the goal when it registers its goals (new and loaded mobs).
cl_ai_remove_goal, cl_ai_goal_running, cl_ai_goal_entity, cl_ai_goal_type	goal:remove(), goal:running(), goal:entity(), goal:type()
cl_ai_clear_goals(e, which)	e:clear_goals(which)	GoalSelector#removeAllGoals for CL_GOALS_GOALS, CL_GOALS_TARGETS or CL_GOALS_ALL (vanilla goals included; they come back on load).

Goal changes take effect at the end of the server tick. Goals are not saved. Mod goals run on brain mobs too (their goal selector runs before the brain), but not on the creaking (it never runs its goal selector).