PathAgent:set_target
methodPathAgent:set_target(grid: Grid, x: integer, y: integer)Path toward cell (x, y) on the grid, repathing immediately (and afterward on the agent's repath cadence, when one was configured).
handle6 methods, 3 fields
PathAgent
A grid mover that owns the walk-the-waypoints bookkeeping: pathing to a target, waypoint acceptance including the final waypoint, motion carry-over, and repath cadence. Positions are continuous cell coordinates (a cell center is x + 0.5). Methods that path take the Grid explicitly, so a mutated grid is read live and one agent can move across grid swaps.
- Obtained from
Grid:agent
The examples on this page start from:
lua
-- An 8 x 6 room with a wall (1) down column 3, open at the bottom.
local grid = datumhue.grid.new(8, 6)
grid:fill_rect(3, 0, 1, 5, 1)
-- It starts in the middle of cell (0, 0) and walks 4 cells a second.
local agent =
grid:agent({ x = 0.5, y = 0.5, speed = 4, blocked = { 1 } })Fields 3
| Field | Type | Access | Description |
|---|---|---|---|
x | number | read-only | Position in cells (a cell center is x + 0.5). |
y | number | read-only | Position in cells (a cell center is y + 0.5). |
speed | number | read/write | Movement speed in cells per second; writable, so per-frame speed changes (sprint, slow, status effects) need no new agent. |
Methods 6
PathAgent:advance
methodPathAgent:advance(grid: Grid, dt: number) -> grid.AgentStepMove along the current path for dt seconds and return the position and status. With no target, the agent stays put.
agent:set_target(grid, 7, 0)
-- Half a second at 4 cells a second: 2 cells along the path.
local step = agent:advance(grid, 0.5)
print(string.format("%.3f %.3f", step.x, step.y)) --> 1.914 1.914
print(step.arrived, step.blocked) --> false falsereturns grid.AgentStep record 5 keys
| Key | Type | Description |
|---|---|---|
| x | number | position after the step, in cells |
| y | number | position after the step, in cells |
| arrived | boolean | the target cell has been reached |
| blocked | boolean | a target is set but no path to it exists |
| stopped? | grid.AgentStop | when the walk halted before a stop_before cell: the cell and its value |
PathAgent:drive
methodPathAgent:drive(grid: Grid, tx: integer, ty: integer, dt: number) -> grid.AgentStepThe per-frame driving loop as one call: retarget to cell (tx, ty) only when it differs from the current goal, advance for dt seconds, and return the step. When the position moved more than 1/16 of a cell since the previous drive — another hand teleported the agent — the goal is dropped first so the walk rebuilds from the new position.
datumhue.on_update(function(dt)
-- Sets a new target only when the goal cell changes.
local step = agent:drive(grid, 7, 0, dt)
if step.arrived then
print("arrived at", step.x, step.y)
end
end)returns grid.AgentStep record 5 keys
| Key | Type | Description |
|---|---|---|
| x | number | position after the step, in cells |
| y | number | position after the step, in cells |
| arrived | boolean | the target cell has been reached |
| blocked | boolean | a target is set but no path to it exists |
| stopped? | grid.AgentStop | when the walk halted before a stop_before cell: the cell and its value |
PathAgent:stop
methodPathAgent:stop()Drop the target and path; the agent stays where it is.
PathAgent:teleport
methodPathAgent:teleport(x: number, y: number)Place the agent at (x, y) and drop the path; the target, when set, repaths on the next advance.
PathAgent:waypoint
methodPathAgent:waypoint() -> grid.AgentWaypoint?The cell the agent is currently walking toward, or nil when it has no path.
returns grid.AgentWaypoint record 2 keys
| Key | Type | Description |
|---|---|---|
| x | integer | waypoint cell |
| y | integer | waypoint cell |