Movement API

Category: API Reference

Control player movement and walking.

Functions

walk_to

movement:walk_to(tile: Tile) -> boolean

Walk to destination with pathfinding.

Parameters:

Parameter	Type	Required	Description
`tile`	Tile	Yes	Destination tile

Returns:

boolean - True if movement started

Example:

local destination = Tile.new(3200, 3200, 0)
movement:walk_to(destination)

-- Wait for arrival
while movement:is_moving() do
    sleep(100)
end
logger:info("Arrived!")

step_to

movement:step_to(tile: Tile) -> boolean

Step to tile (single minimap click).

Parameters:

Parameter	Type	Required	Description
`tile`	Tile	Yes	Destination tile

Returns:

boolean - True if step executed

walk_path

movement:walk_path(tiles: table) -> boolean

Walk along a path of tiles.

Parameters:

Parameter	Type	Required	Description
`tiles`	table	Yes	Array of Tile objects

Returns:

boolean - True if path started

Example:

local path = {
    Tile.new(3200, 3200, 0),
    Tile.new(3210, 3210, 0),
    Tile.new(3220, 3220, 0)
}

movement:walk_path(path)

is_moving

movement:is_moving() -> boolean

Check if player is currently moving.

Returns:

boolean - True if moving

Example:

while movement:is_moving() do
    sleep(100)
end

current_tile

movement:current_tile() -> Tile

Get current player tile.

Returns:

Tile - Current position

destination

movement:destination() -> Tile?

Get destination tile if moving.

Returns:

Tile? - Destination, or nil if not moving

is_run_toggled

movement:is_run_toggled() -> boolean

Check if run is enabled.

Returns:

boolean - True if run enabled

run_energy

movement:run_energy() -> number

Get run energy (0-100).

Returns:

number - Energy percentage

toggle_run

movement:toggle_run(enabled: boolean) -> boolean

Toggle run on/off.

Parameters:

Parameter	Type	Required	Description
`enabled`	boolean	Yes	True to enable, false to disable

Returns:

boolean - True if successful

Example:

if movement:run_energy() > 50 then
    movement:toggle_run(true)
else
    movement:toggle_run(false)
end

walk_to_with_condition

movement:walk_to_with_condition(tile: Tile, condition: function) -> boolean

Walk to destination with pathfinding, with a stop condition function that can exit the walker early.

Parameters:

Parameter	Type	Required	Description
`tile`	Tile	Yes	Destination tile
`condition`	function	Yes	Function called periodically during walking. Should return `true` to exit the walker early, or `false` to continue.

Returns:

boolean - True if movement started

Example:

-- Exit walker if run energy is low
local destination = Tile.new(3092, 3242, 0)
movement:walk_to_with_condition(destination, function()
    if movement:run_energy() < 60 then
        logger:info("Run energy low, exiting walker to drink stamina")
        return true  -- Exit walker
    end
    return false  -- Continue walking
end)

-- Exit walker if at desired location before destination
movement:walk_to_with_condition(destination, function()
    local player = players:local_player()
    if player then
        local current = player:tile()
        -- Check if we're close enough to our actual goal
        if current:distance_to(actual_goal) <= 2 then
            logger:info("Close enough to goal, exiting walker")
            return true  -- Exit walker
        end
    end
    return false  -- Continue walking
end)

walk_to_no_teleports_with_condition

movement:walk_to_no_teleports_with_condition(tile: Tile, condition: function) -> boolean

Walk to destination without using any teleports (no magic spells, teleport tabs, or jewellery), with a stop condition function that can exit the walker early.

Parameters:

Parameter	Type	Required	Description
`tile`	Tile	Yes	Destination tile
`condition`	function	Yes	Function called periodically during walking. Should return `true` to exit the walker early, or `false` to continue.

Returns:

boolean - True if movement started

Example:

-- Exit walker to eat if health is low
local destination = Tile.new(3200, 3200, 0)
movement:walk_to_no_teleports_with_condition(destination, function()
    local player = players:local_player()
    if player and player:health_percent() and player:health_percent() < 50 then
        logger:info("Health low, exiting walker to eat")
        return true  -- Exit walker
    end
    return false  -- Continue walking
end)

Common Patterns

Walk and Wait

local function walk_and_wait(tile, timeout)
    if not movement:walk_to(tile) then
        return false
    end
    
    local start = os.time()
    while movement:is_moving() do
        if os.time() - start > timeout then
            logger:warn("Movement timeout")
            return false
        end
        sleep(100)
    end
    
    logger:info("Arrived at destination")
    return true
end

walk_and_wait(Tile.new(3200, 3200, 0), 30)

Intelligent Run Management

local function managed_walk(tile)
    -- Enable run if energy available
    if movement:run_energy() > 20 then
        movement:toggle_run(true)
    else
        movement:toggle_run(false)
    end
    
    movement:walk_to(tile)
end

Multi-Waypoint Path

local function walk_waypoints(waypoints)
    for _, waypoint in ipairs(waypoints) do
        if not walk_and_wait(waypoint, 60) then
            logger:error("Failed to reach waypoint")
            return false
        end
        sleep(500)  -- Wait between waypoints
    end
    return true
end

local path = {
    Tile.new(3200, 3200, 0),
    Tile.new(3210, 3210, 0),
    Tile.new(3220, 3220, 0)
}

walk_waypoints(path)

Run Energy Management

local function ensure_run_energy(threshold)
    if movement:run_energy() < threshold then
        logger:info("Run energy low: " .. movement:run_energy() .. "%")
        
        -- Find and drink stamina potion
        local potion = inventory:find_first({name_contains = "Stamina"})
        if potion then
            potion:click()
            sleep(200)
            return true
        end
        
        return false
    end
    
    return true
end

Activity Detection

local function is_player_busy()
    return movement:is_moving() or 
           players:local_player():is_animating() or
           players:local_player():is_interacting()
end

while is_player_busy() do
    sleep(100)
end
logger:info("Player is now idle")

Walk with Exit Conditions

-- Walk with automatic stamina management
local function walk_with_stamina_check(destination)
    return movement:walk_to_with_condition(destination, function()
        -- Exit to drink stamina if energy is low
        if movement:run_energy() < 30 and not movement:is_stamina_active() then
            logger:info("Exiting walker to drink stamina")
            return true  -- Exit walker
        end
        return false  -- Continue walking
    end)
end

-- Walk with health monitoring
local function walk_with_health_check(destination)
    return movement:walk_to_with_condition(destination, function()
        local player = players:local_player()
        if player and player:health_percent() and player:health_percent() < 60 then
            logger:info("Exiting walker to eat")
            return true  -- Exit walker
        end
        return false  -- Continue walking
    end)
end

-- Walk until close enough to actual goal (early exit)
local function walk_until_close(destination, actual_goal, distance)
    return movement:walk_to_with_condition(destination, function()
        local player = players:local_player()
        if player then
            local current = player:tile()
            if current:distance_to(actual_goal) <= distance then
                logger:info("Close enough to goal, exiting walker")
                return true  -- Exit walker early
            end
        end
        return false  -- Continue walking
    end)
end

Related APIs

Camera API - Camera control