NavigationServer2D
A server interface for low-level 2D navigation access.
NavigationServer2D.swift:38class NavigationServer2D
NavigationServer2D is the server that handles navigation maps, regions and agents. It does not handle A* navigation from AStar2D
or AStarGrid2D
.
Maps are divided into regions, which are composed of navigation polygons. Together, they define the traversable areas in the 2D world.
For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than edge_connection_margin
to the respective other edge’s vertex.
You may assign navigation layers to regions with regionSetNavigationLayers(region:navigationLayers:)
, which then can be checked upon when requesting a path with mapGetPath(map:origin:destination:optimize:navigationLayers:)
. This can be used to allow or deny certain areas for some objects.
To use the collision avoidance system, you may use agents. You can set an agent’s target velocity, then the servers will emit a callback with a modified velocity.
This server keeps tracks of any call and executes them during the sync phase. This means that you can request any change to the map, using any thread, without worrying.
This object emits the following signals:
Superclasses
class Object
Base class for all other classes in the engine.
Citizens in SwiftGodot
Conformances
protocol CustomStringConvertible
A type with a customized textual representation.
protocol Equatable
A type that can be compared for value equality.
protocol Hashable
A type that can be hashed into a
Hasher
to produce an integer hash value.protocol Identifiable<ID>
A class of types whose instances hold the value of an entity with stable identity.
protocol VariantRepresentable
Types that conform to VariantRepresentable can be stored directly in
Variant
with no conversion. These include all of the Variant types from Godot (for exampleGString
,Rect
,Plane
), Godot objects (those that subclass SwiftGodot.Object) as well as the built-in Swift types UInt8, Int64 and Double.protocol VariantStorable
Types that conform to VariantStorable can be stored in a Variant and can be extracted back out of a Variant.
Types
class Signal1
Signal support.
Type members
static var shared: NavigationServer2D
The shared instance of this class
static func agentCreate(
) -> RID Creates the agent.
static func agentGetAvoidanceEnabled(agent: RID
) -> Bool Return
true
if the specifiedagent
uses avoidance.static func agentGetAvoidanceLayers(agent: RID
) -> UInt32 Returns the
avoidance_layers
bitmask of the specifiedagent
.static func agentGetAvoidanceMask(agent: RID
) -> UInt32 Returns the
avoidance_mask
bitmask of the specifiedagent
.static func agentGetAvoidancePriority(agent: RID
) -> Double Returns the
avoidance_priority
of the specifiedagent
.static func agentGetMap(agent: RID
) -> RID Returns the navigation map
RID
the requestedagent
is currently assigned to.static func agentGetMaxNeighbors(agent: RID
) -> Int32 Returns the maximum number of other agents the specified
agent
takes into account in the navigation.static func agentGetMaxSpeed(agent: RID
) -> Double Returns the maximum speed of the specified
agent
.static func agentGetNeighborDistance(agent: RID
) -> Double Returns the maximum distance to other agents the specified
agent
takes into account in the navigation.static func agentGetPaused(agent: RID
) -> Bool Returns
true
if the specifiedagent
is paused.static func agentGetPosition(agent: RID
) -> Vector2 Returns the position of the specified
agent
in world space.static func agentGetRadius(agent: RID
) -> Double Returns the radius of the specified
agent
.static func agentGetTimeHorizonAgents(agent: RID
) -> Double Returns the minimal amount of time for which the specified
agent
’s velocities that are computed by the simulation are safe with respect to other agents.static func agentGetTimeHorizonObstacles(agent: RID
) -> Double Returns the minimal amount of time for which the specified
agent
’s velocities that are computed by the simulation are safe with respect to static avoidance obstacles.static func agentGetVelocity(agent: RID
) -> Vector2 Returns the velocity of the specified
agent
.static func agentHasAvoidanceCallback(agent: RID
) -> Bool Return
true
if the specifiedagent
has an avoidance callback.static func agentIsMapChanged(agent: RID
) -> Bool Returns true if the map got changed the previous frame.
static func agentSetAvoidanceCallback(agent: RID, callback: Callable
) Sets the callback
Callable
that gets called after each avoidance processing step for theagent
. The calculatedsafe_velocity
will be dispatched with a signal to the object just before the physics calculations.static func agentSetAvoidanceEnabled(agent: RID, enabled: Bool
) If
enabled
istrue
, the specifiedagent
uses avoidance.static func agentSetAvoidanceLayers(agent: RID, layers: UInt32
) Set the agent’s
avoidance_layers
bitmask.static func agentSetAvoidanceMask(agent: RID, mask: UInt32
) Set the agent’s
avoidance_mask
bitmask.static func agentSetAvoidancePriority(agent: RID, priority: Double
) Set the agent’s
avoidance_priority
with apriority
between 0.0 (lowest priority) to 1.0 (highest priority).static func agentSetMap(agent: RID, map: RID
) Puts the agent in the map.
static func agentSetMaxNeighbors(agent: RID, count: Int32
) Sets the maximum number of other agents the agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe.
static func agentSetMaxSpeed(agent: RID, maxSpeed: Double
) Sets the maximum speed of the agent. Must be positive.
static func agentSetNeighborDistance(agent: RID, distance: Double
) Sets the maximum distance to other agents this agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe.
static func agentSetPaused(agent: RID, paused: Bool
) If
paused
is true the specifiedagent
will not be processed, e.g. calculate avoidance velocities or receive avoidance callbacks.static func agentSetPosition(agent: RID, position: Vector2
) Sets the position of the agent in world space.
static func agentSetRadius(agent: RID, radius: Double
) Sets the radius of the agent.
static func agentSetTimeHorizonAgents(agent: RID, timeHorizon: Double
) The minimal amount of time for which the agent’s velocities that are computed by the simulation are safe with respect to other agents. The larger this number, the sooner this agent will respond to the presence of other agents, but the less freedom this agent has in choosing its velocities. A too high value will slow down agents movement considerably. Must be positive.
static func agentSetTimeHorizonObstacles(agent: RID, timeHorizon: Double
) The minimal amount of time for which the agent’s velocities that are computed by the simulation are safe with respect to static avoidance obstacles. The larger this number, the sooner this agent will respond to the presence of static avoidance obstacles, but the less freedom this agent has in choosing its velocities. A too high value will slow down agents movement considerably. Must be positive.
static func agentSetVelocity(agent: RID, velocity: Vector2
) Sets
velocity
as the new wanted velocity for the specifiedagent
. The avoidance simulation will try to fulfill this velocity if possible but will modify it to avoid collision with other agent’s and obstacles. When an agent is teleported to a new position far away useagentSetVelocityForced(agent:velocity:)
instead to reset the internal velocity state.static func agentSetVelocityForced(agent: RID, velocity: Vector2
) Replaces the internal velocity in the collision avoidance simulation with
velocity
for the specifiedagent
. When an agent is teleported to a new position far away this function should be used in the same frame. If called frequently this function can get agents stuck.static func bakeFromSourceGeometryData(navigationPolygon: NavigationPolygon?, sourceGeometryData: NavigationMeshSourceGeometryData2D?, callback: Callable
) Bakes the provided
navigationPolygon
with the data from the providedsourceGeometryData
. After the process is finished the optionalcallback
will be called.static func bakeFromSourceGeometryDataAsync(navigationPolygon: NavigationPolygon?, sourceGeometryData: NavigationMeshSourceGeometryData2D?, callback: Callable
) Bakes the provided
navigationPolygon
with the data from the providedsourceGeometryData
as an async task running on a background thread. After the process is finished the optionalcallback
will be called.static func freeRid(RID
) Destroys the given RID.
static func getDebugEnabled(
) -> Bool Returns
true
when the NavigationServer has debug enabled.static func getMaps(
) -> VariantCollection<RID> Returns all created navigation map
RID
s on the NavigationServer. This returns both 2D and 3D created navigation maps as there is technically no distinction between them.static func isBakingNavigationPolygon(NavigationPolygon?
) -> Bool Returns
true
when the provided navigation polygon is being baked on a background thread.static func linkCreate(
) -> RID Create a new link between two positions on a map.
static func linkGetEnabled(link: RID
) -> Bool Returns
true
if the specifiedlink
is enabled.static func linkGetEndPosition(link: RID
) -> Vector2 Returns the ending position of this
link
.static func linkGetEnterCost(link: RID
) -> Double Returns the enter cost of this
link
.static func linkGetMap(link: RID
) -> RID Returns the navigation map
RID
the requestedlink
is currently assigned to.static func linkGetNavigationLayers(link: RID
) -> UInt32 Returns the navigation layers for this
link
.static func linkGetOwnerId(link: RID
) -> UInt Returns the
ObjectID
of the object which manages this link.static func linkGetStartPosition(link: RID
) -> Vector2 Returns the starting position of this
link
.static func linkGetTravelCost(link: RID
) -> Double Returns the travel cost of this
link
.static func linkIsBidirectional(link: RID
) -> Bool Returns whether this
link
can be travelled in both directions.static func linkSetBidirectional(link: RID, bidirectional: Bool
) Sets whether this
link
can be travelled in both directions.static func linkSetEnabled(link: RID, enabled: Bool
) If
enabled
istrue
, the specifiedlink
will contribute to its current navigation map.static func linkSetEndPosition(link: RID, position: Vector2
) Sets the exit position for the
link
.static func linkSetEnterCost(link: RID, enterCost: Double
) Sets the
enterCost
for thislink
.static func linkSetMap(link: RID, map: RID
) Sets the navigation map
RID
for the link.static func linkSetNavigationLayers(link: RID, navigationLayers: UInt32
) Set the links’s navigation layers. This allows selecting links from a path request (when using
mapGetPath(map:origin:destination:optimize:navigationLayers:)
).static func linkSetOwnerId(link: RID, ownerId: UInt
) Set the
ObjectID
of the object which manages this link.static func linkSetStartPosition(link: RID, position: Vector2
) Sets the entry position for this
link
.static func linkSetTravelCost(link: RID, travelCost: Double
) Sets the
travelCost
for thislink
.static func mapCreate(
) -> RID Create a new map.
static func mapForceUpdate(map: RID
) This function immediately forces synchronization of the specified navigation
map
RID
. By default navigation maps are only synchronized at the end of each physics frame. This function can be used to immediately (re)calculate all the navigation meshes and region connections of the navigation map. This makes it possible to query a navigation path for a changed map immediately and in the same frame (multiple times if needed).static func mapGetAgents(map: RID
) -> VariantCollection<RID> Returns all navigation agents
RID
s that are currently assigned to the requested navigationmap
.static func mapGetCellSize(map: RID
) -> Double Returns the map cell size used to rasterize the navigation mesh vertices.
static func mapGetClosestPoint(map: RID, toPoint: Vector2
) -> Vector2 Returns the point closest to the provided
toPoint
on the navigation mesh surface.static func mapGetClosestPointOwner(map: RID, toPoint: Vector2
) -> RID Returns the owner region RID for the point returned by
mapGetClosestPoint(map:toPoint:)
.static func mapGetEdgeConnectionMargin(map: RID
) -> Double Returns the edge connection margin of the map. The edge connection margin is a distance used to connect two regions.
static func mapGetIterationId(map: RID
) -> UInt32 Returns the current iteration id of the navigation map. Every time the navigation map changes and synchronizes the iteration id increases. An iteration id of 0 means the navigation map has never synchronized.
static func mapGetLinkConnectionRadius(map: RID
) -> Double Returns the link connection radius of the map. This distance is the maximum range any link will search for navigation mesh polygons to connect to.
static func mapGetLinks(map: RID
) -> VariantCollection<RID> Returns all navigation link
RID
s that are currently assigned to the requested navigationmap
.static func mapGetObstacles(map: RID
) -> VariantCollection<RID> Returns all navigation obstacle
RID
s that are currently assigned to the requested navigationmap
.static func mapGetPath(map: RID, origin: Vector2, destination: Vector2, optimize: Bool, navigationLayers: UInt32
) -> PackedVector2Array Returns the navigation path to reach the destination from the origin.
navigationLayers
is a bitmask of all region navigation layers that are allowed to be in the path.static func mapGetRandomPoint(map: RID, navigationLayers: UInt32, uniformly: Bool
) -> Vector2 Returns a random position picked from all map region polygons with matching
navigationLayers
.static func mapGetRegions(map: RID
) -> VariantCollection<RID> Returns all navigation regions
RID
s that are currently assigned to the requested navigationmap
.static func mapGetUseEdgeConnections(map: RID
) -> Bool Returns whether the navigation
map
allows navigation regions to use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin.static func mapIsActive(map: RID
) -> Bool Returns true if the map is active.
static func mapSetActive(map: RID, active: Bool
) Sets the map active.
static func mapSetCellSize(map: RID, cellSize: Double
) Sets the map cell size used to rasterize the navigation mesh vertices. Must match with the cell size of the used navigation meshes.
static func mapSetEdgeConnectionMargin(map: RID, margin: Double
) Set the map edge connection margin used to weld the compatible region edges.
static func mapSetLinkConnectionRadius(map: RID, radius: Double
) Set the map’s link connection radius used to connect links to navigation polygons.
static func mapSetUseEdgeConnections(map: RID, enabled: Bool
) Set the navigation
map
edge connection use. Ifenabled
istrue
, the navigation map allows navigation regions to use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin.static func obstacleCreate(
) -> RID Creates a new navigation obstacle.
static func obstacleGetAvoidanceEnabled(obstacle: RID
) -> Bool Returns
true
if the providedobstacle
has avoidance enabled.static func obstacleGetAvoidanceLayers(obstacle: RID
) -> UInt32 Returns the
avoidance_layers
bitmask of the specifiedobstacle
.static func obstacleGetMap(obstacle: RID
) -> RID Returns the navigation map
RID
the requestedobstacle
is currently assigned to.static func obstacleGetPaused(obstacle: RID
) -> Bool Returns
true
if the specifiedobstacle
is paused.static func obstacleGetPosition(obstacle: RID
) -> Vector2 Returns the position of the specified
obstacle
in world space.static func obstacleGetRadius(obstacle: RID
) -> Double Returns the radius of the specified dynamic
obstacle
.static func obstacleGetVelocity(obstacle: RID
) -> Vector2 Returns the velocity of the specified dynamic
obstacle
.static func obstacleGetVertices(obstacle: RID
) -> PackedVector2Array Returns the outline vertices for the specified
obstacle
.static func obstacleSetAvoidanceEnabled(obstacle: RID, enabled: Bool
) If
enabled
istrue
, the providedobstacle
affects avoidance using agents.static func obstacleSetAvoidanceLayers(obstacle: RID, layers: UInt32
) Set the obstacles’s
avoidance_layers
bitmask.static func obstacleSetMap(obstacle: RID, map: RID
) Sets the navigation map
RID
for the obstacle.static func obstacleSetPaused(obstacle: RID, paused: Bool
) If
paused
is true the specifiedobstacle
will not be processed, e.g. affect avoidance velocities.static func obstacleSetPosition(obstacle: RID, position: Vector2
) Sets the position of the obstacle in world space.
static func obstacleSetRadius(obstacle: RID, radius: Double
) Sets the radius of the dynamic obstacle.
static func obstacleSetVelocity(obstacle: RID, velocity: Vector2
) Sets
velocity
of the dynamicobstacle
. Allows other agents to better predict the movement of the dynamic obstacle. Only works in combination with the radius of the obstacle.static func obstacleSetVertices(obstacle: RID, vertices: PackedVector2Array
) Sets the outline vertices for the obstacle. If the vertices are winded in clockwise order agents will be pushed in by the obstacle, else they will be pushed out.
static func parseSourceGeometryData(navigationPolygon: NavigationPolygon?, sourceGeometryData: NavigationMeshSourceGeometryData2D?, rootNode: Node?, callback: Callable
) Parses the
SceneTree
for source geometry according to the properties ofnavigationPolygon
. Updates the providedsourceGeometryData
resource with the resulting data. The resource can then be used to bake a navigation mesh withbakeFromSourceGeometryData(navigationPolygon:sourceGeometryData:callback:)
. After the process is finished the optionalcallback
will be called.static func queryPath(parameters: NavigationPathQueryParameters2D?, result: NavigationPathQueryResult2D?
) Queries a path in a given navigation map. Start and target position and other parameters are defined through
NavigationPathQueryParameters2D
. Updates the providedNavigationPathQueryResult2D
result object with the path among other results requested by the query.static func regionCreate(
) -> RID Creates a new region.
static func regionGetConnectionPathwayEnd(region: RID, connection: Int32
) -> Vector2 Returns the ending point of a connection door.
connection
is an index between 0 and the return value ofregionGetConnectionsCount(region:)
.static func regionGetConnectionPathwayStart(region: RID, connection: Int32
) -> Vector2 Returns the starting point of a connection door.
connection
is an index between 0 and the return value ofregionGetConnectionsCount(region:)
.static func regionGetConnectionsCount(region: RID
) -> Int32 Returns how many connections this
region
has with other regions in the map.static func regionGetEnabled(region: RID
) -> Bool Returns
true
if the specifiedregion
is enabled.static func regionGetEnterCost(region: RID
) -> Double Returns the enter cost of this
region
.static func regionGetMap(region: RID
) -> RID Returns the navigation map
RID
the requestedregion
is currently assigned to.static func regionGetNavigationLayers(region: RID
) -> UInt32 Returns the region’s navigation layers.
static func regionGetOwnerId(region: RID
) -> UInt Returns the
ObjectID
of the object which manages this region.static func regionGetRandomPoint(region: RID, navigationLayers: UInt32, uniformly: Bool
) -> Vector2 Returns a random position picked from all region polygons with matching
navigationLayers
.static func regionGetTransform(region: RID
) -> Transform2D Returns the global transformation of this
region
.static func regionGetTravelCost(region: RID
) -> Double Returns the travel cost of this
region
.static func regionGetUseEdgeConnections(region: RID
) -> Bool Returns whether the navigation
region
is set to use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin.static func regionOwnsPoint(region: RID, point: Vector2
) -> Bool Returns
true
if the providedpoint
in world space is currently owned by the provided navigationregion
. Owned in this context means that one of the region’s navigation mesh polygon faces has a possible position at the closest distance to this point compared to all other navigation meshes from other navigation regions that are also registered on the navigation map of the provided region.static func regionSetEnabled(region: RID, enabled: Bool
) If
enabled
istrue
the specifiedregion
will contribute to its current navigation map.static func regionSetEnterCost(region: RID, enterCost: Double
) Sets the
enterCost
for thisregion
.static func regionSetMap(region: RID, map: RID
) Sets the map for the region.
static func regionSetNavigationLayers(region: RID, navigationLayers: UInt32
) Set the region’s navigation layers. This allows selecting regions from a path request (when using
mapGetPath(map:origin:destination:optimize:navigationLayers:)
).static func regionSetNavigationPolygon(region: RID, navigationPolygon: NavigationPolygon?
) Sets the
navigationPolygon
for the region.static func regionSetOwnerId(region: RID, ownerId: UInt
) Set the
ObjectID
of the object which manages this region.static func regionSetTransform(region: RID, transform: Transform2D
) Sets the global transformation for the region.
static func regionSetTravelCost(region: RID, travelCost: Double
) Sets the
travelCost
for thisregion
.static func regionSetUseEdgeConnections(region: RID, enabled: Bool
) If
enabled
istrue
, the navigationregion
will use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin.static func setDebugEnabled(Bool
) If
true
enables debug mode on the NavigationServer.static func simplifyPath(PackedVector2Array, epsilon: Double
) -> PackedVector2Array Returns a simplified version of
path
with less critical path points removed. The simplification amount is in worlds units and controlled byepsilon
. The simplification uses a variant of Ramer-Douglas-Peucker algorithm for curve point decimation.static func sourceGeometryParserCreate(
) -> RID Creates a new source geometry parser. If a
Callable
is set for the parser withsourceGeometryParserSetCallback(parser:callback:)
the callback will be called for every single node that gets parsed wheneverparseSourceGeometryData(navigationPolygon:sourceGeometryData:rootNode:callback:)
is used.static func sourceGeometryParserSetCallback(parser: RID, callback: Callable
) Sets the
callback
Callable
for the specific source geometryparser
. TheCallable
will receive a call with the following parameters:class var godotClassName: StringName
Instance members
var mapChanged: Signal1
Emitted when a navigation map is updated, when a region moves or is modified.
var navigationDebugChanged: SimpleSignal
Emitted when navigation debug settings are changed. Only available in debug builds.