Pathfinder

Pathfinder Module Documentation

Overview

The Pathfinder module offers robust tools for character movement and navigation, leveraging both custom pathfinding algorithms and the game engine's native capabilities.

Path Creation with Game Engine

Create Path Using Game Engine

pathfinder.create_path_game_engine(pos)

• pos: vec3 - The destination for path creation.

Note

Generates a path to the specified position using the game engine's pathfinding functionality. While accurate, it's resource-intensive and best used sparingly. It's recommended to store the path for repeated use rather than generating it multiple times.

Waypoint Navigation

Get Next Waypoint

pathfinder.get_next_waypoint(pos, waypoint_list, threshold)

• pos: vec3 - The current position.
• waypoint_list: Table of vec3 - A list of waypoints.
• threshold: Number - The distance threshold for selecting the next waypoint.

Note

Identifies the next waypoint in a list, ideal for navigating paths generated by create_path_game_engine. When used in conjunction with request_move, it streamlines movement by avoiding unnecessary move orders.

Movement Functions

Force Immediate Movement

pathfinder.force_move(pos)

• pos: vec3 - The target position for immediate movement.

Note

Instantly moves the player character to the specified position, overriding any current movement or actions. Useful for urgent or precise movement requirements.

Request Movement (Optimized)

pathfinder.request_move(pos)

• pos: vec3 - The desired position to move to.

Note

Submits a movement request to the player character. Unlike force_move, it only sends a command if the player isn't already moving, optimizing movement and reducing command redundancy.

-- register on_key_release callback to call the code each time you release a key
on_key_release(function(key)
    
    if key ~= 0x48 then
        return;
    end

    -- this code only reads each time you release: [0x48] H KEY

    local local_player = get_local_player();
    if not local_player then
        return;
    end

    -- move to the cursor position
    local cursor_position = get_cursor_position();
    pathfinder.request_move(cursor_position);
end);

Custom Pathfinding Functions

Calculate Path Points

Calculates a path from a start position to a goal position using a custom pathfinding algorithm.

pathfinder.calculate_and_get_path_points(start, goal)

• start: vec3 - The starting position of the path.
• goal: vec3 - The target position of the path.

Note

Returns a table of vec3 waypoints representing the calculated path from start to goal.

Movement with Pathfinder

Move to Position with Custom Pathfinder

pathfinder.move_to_cpathfinder(pos, efficient)

• pos: vec3 - The target position for movement.
• efficient: Boolean - If true, optimizes the path for shorter distances.

Note

This function is best used for short to medium distance movements, utilizing the orbwalker's integrated pathfinder. For longer distances, consider using the game engine's pathfinder. The efficient parameter allows for quicker, less resource-intensive path calculations.

Move to Position with Custom Pathfinding

Initiates movement to a specified position using a custom pathfinding algorithm with various configuration options.

pathfinder.move_to_cpathfinder_custom_full(pos, algo_type, batch_length, circle_rad, circular_precision, max_algo_steps, anti_stuck_rad, anti_stuck_time)

• pos: vec3 - The target position for movement.
• algo_type: Integer - Specifies the algorithm type to use.
• batch_length: Float - Defines the batch processing length for the pathfinding algorithm.
• circle_rad: Float - The radius used for circular path calculations.
• circular_precision: Float - The precision of circular path calculations.
• max_algo_steps: Integer - The maximum steps the algorithm will execute before stopping.
• anti_stuck_rad: Float - Radius to detect if the character is stuck.
• anti_stuck_time: Float - Time to consider the character as stuck.

Move to Position with Custom Pathfinding (Algorithm 1)

Initiates movement using a specific set of default parameters tailored for a certain type of navigation, with overloads allowing flexibility.

pathfinder.move_to_cpathfinder_custom_a1(pos, batch_length, circle_rad, max_algo_steps, [anti_stuck_rad, anti_stuck_time])

• pos: vec3 - The target position for movement.
• batch_length: Float - The batch processing length for pathfinding.
• circle_rad: Float - The radius used for circular paths.
• max_algo_steps: Integer - Maximum algorithm steps to execute.
• anti_stuck_rad: Float - (Optional) Radius to check for being stuck.
• anti_stuck_time: Float - (Optional) Time to determine if stuck.

Move to Position with Custom Pathfinding (Algorithm 2)

Similar to Algorithm 1 but uses different default parameters and focuses on circular precision in pathfinding.

pathfinder.move_to_cpathfinder_custom_a2(pos, circular_precision, max_algo_steps, [anti_stuck_rad, anti_stuck_time])

• pos: vec3 - The target position for movement.
• circular_precision: Float - Precision for circular path calculations.
• max_algo_steps: Integer - Maximum steps the algorithm executes.
• anti_stuck_rad: Float - (Optional) Radius to check if the character is stuck.
• anti_stuck_time: Float - (Optional) Time to determine if stuck.

Clear Stored Path

pathfinder.clear_stored_path()

Note

Clears the currently stored path in the pathfinder. This can be useful to reset or clear navigation paths.

• Returns: void

Force Move Raw

pathfinder.force_move_raw(pos)

• pos: vec3 - The position to move to.

Note

Forces a movement to the specified position without considering the current pathfinding logic. This can be useful for direct movement commands.

• Returns: bool indicating whether the movement command was successfully issued.

Sprt Waypoints

pathfinder.sort_waypoints(waypoint_list, point)

Set Last Waypoint Index

pathfinder.set_last_waypoint_index(value)

--- Gets the next waypoint from the waypoint list based on current position and threshold.
--- @param pos vec3
--- @param waypoint_list vec3[]
--- @param threshold number
--- @return vec3
function pathfinder.get_next_waypoint(pos, waypoint_list, threshold) end
-- note: changed on july 20, 2024

--- @param point vec3
--- @param waypoint_list vec3[]
--- list of waypoints for example those you get from get_engine_waypoints
--- and then 2nd parameter for example player_position
function pathfinder.sort_waypoints(waypoint_list, point) end

--- @param value integer
-- this is the index used by pathfinder.get_next_waypoint as reference
-- useful to reset to 1, can be used for other things aswell
function pathfinder.set_last_waypoint_index(value) end