Waypoint Navigation Library

This library allows users to build more sophisticated spatial navigation by using a network of waypoints that agents can navigate between.

Using the Waypoints library consists of creating Waypoint agents across your simulation, and specifying the appropriate parameters and behaviors on Navigating agents.

Waypoint Agents

Waypoint agents do not need any behaviors to function correctly. They only need to be initialized in the locations you want, with the correct set of properties.

Proper layout of a waypoint network will likely resemble a visibility graph.

Each waypoint agent must contain a map property which provides information to navigating agents. Each waypoint has an entry which specifies the location of the next waypoint an agent should move to, in order to eventually reach the destination waypoint.

For instance, the value for waypoint_b will not necessarily contain the position for waypoint_b. If an agent must first pass through waypoint_c, then it will contain waypoint_c's position.

Waypoint agents may be hidden from view to reduce clutter in your simulation. Set the agent's hidden property to false to remvove it from the 3D Viewer.

Example definition

{
  "agent_name": "waypoint_center",
  "agent_type": "waypoint,
  "map": {
    "waypoint_north": [0, 5, 0],
    "waypoint_east": [5, 0, 0],
    "waypoint_west": [-5, 0, 0],
    "waypoint_south": [0, -5, 0],
  },
  "position": [0, 0, 0],
  "hidden": true
}

Navigating Agents

Navigating agents must contain specific fields and behaviors in order to make use of the waypoints. They navigate with a two-part process, each handled by different behaviors.

Follow Waypoints

Agents first follow the network of waypoints until they reach the waypoint closest to their destination. This is handled by navigate.js, and causes agents to move in straight lines between waypoints.

Whenever it reaches a waypoint, the agent will consult the waypoint agent's map to determine its next destination.

Move to Destination

If you've laid out the waypoints properly, once an agent reaches its destination waypoint, it will now be able to move in a direct line to its destination location. This movement is handled by move.js and will also be based on the speed of the agent.

Agent's will store the location of the final waypoint in prev_waypoint_position in order to help an agent navigate again once it finishes its tasks in the current destination.

Example definition

{
  "behaviors": [navigate.js, move.js],
  "position: [3, 0, 0],
  "direction": [-1, 0, 0],
  "speed": 2,
  "destination_waypoint": "waypoint_north",
  "destination_position": [0, 5, 0]
  "move_to": [0, 0, 0]
}