<!--
{
  "availability" : [
    "iOS: 9.0.0 -",
    "iPadOS: 9.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.11.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "GameplayKit",
  "identifier" : "/documentation/GameplayKit/GKGraph",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "GameplayKit"
    ],
    "preciseIdentifier" : "c:objc(cs)GKGraph"
  },
  "title" : "GKGraph"
}
-->

# GKGraph

A collection of nodes that describes the navigability of a game world and provides *pathfinding* methods to search for routes through that space.

```
class GKGraph
```

## Overview

Individual nodes in a graph represent discrete locations that a character or other object in your game can occupy, and the connections between adjacent nodes represent the ability of a game entity to travel from one location to another. Use the [`GKGraph`](/documentation/GameplayKit/GKGraph) class to create a general graph, or the [`GKGridGraph`](/documentation/GameplayKit/GKGridGraph), [`GKObstacleGraph`](/documentation/GameplayKit/GKObstacleGraph), or [`GKMeshGraph`](/documentation/GameplayKit/GKMeshGraph) subclass to generate specialized graphs that contain more information about the geometry of your game world.

Each set of graph and node classes can generate graphs for different kinds of spaces:

- The base classes [`GKGraph`](/documentation/GameplayKit/GKGraph) and [`GKGraphNode`](/documentation/GameplayKit/GKGraphNode) contain functionality general to all graphs and nodes. You can also use these classes on their own to construct graphs that contain no geometry information. This option is useful for games where the connections between spaces are more important than their physical locations, such as board games.
- Use the [`GKGridGraph`](/documentation/GameplayKit/GKGridGraph) and [`GKGridGraphNode`](/documentation/GameplayKit/GKGridGraphNode) classes to describe game worlds that constrain movement to an integer grid, such as tactical role-playing games.
- Use the [`GKObstacleGraph`](/documentation/GameplayKit/GKObstacleGraph) or [`GKMeshGraph`](/documentation/GameplayKit/GKMeshGraph) class to describe 2D game worlds that allow continuous movement in open spaces that are interrupted by impassable obstacles ([`GKPolygonObstacle`](/documentation/GameplayKit/GKPolygonObstacle) objects). Obstacle graphs automatically generate nodes containing 2D point information ([`GKGraphNode2D`](/documentation/GameplayKit/GKGraphNode2D) objects), and you can also add your own such nodes representing locations of interest.

The graphs modeled by this class are always *directed*—that is, a connection between two nodes describes one direction of travel between them. To enable travel between two nodes in either direction, you must create a connection in each direction. You can choose to connect both directions at once with the [`connectToLowestCostNode(node:bidirectional:)`](/documentation/GameplayKit/GKGraph/connectToLowestCostNode(node:bidirectional:)) method (for graphs) or the addConnection:bidirectional: method (for nodes).

Using a graph for pathfinding typically involves three major steps:

1. Create a graph once (for example, when initializing a game level class) with static information about your game world.
2. When you need to find a route between points, connect temporary nodes to the graph at those points. Use the [`connectToLowestCostNode(node:bidirectional:)`](/documentation/GameplayKit/GKGraph/connectToLowestCostNode(node:bidirectional:)) method to connect nodes using their own geometry information, or the [`connectUsingObstacles(node:)`](/documentation/GameplayKit/GKObstacleGraph/connectUsingObstacles(node:)) or [`connectToAdjacentNodes(node:)`](/documentation/GameplayKit/GKGridGraph/connectToAdjacentNodes(node:)) method to use the additional constraints of obstacle and grid graphs.
3. Call the [`findPath(from:to:)`](/documentation/GameplayKit/GKGraph/findPath(from:to:)) method to find a route between locations in the graph. This method returns an array of graph nodes, starting with the requested start point of the path, and proceeding to adjacent nodes in order until it reaches the requested end point. Use the geometry information contained in each node to make use of the route—for example, in a SpriteKit game you might create a sequence of move actions to move a character from point to point along the path.
4. The temporary nodes you created for finding a path typically have little usefulness after a path has been found. Remove those nodes before reusing the graph for future searches.

To learn more about graphs and pathfinding, see [Pathfinding](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/Pathfinding.html#//apple_ref/doc/uid/TP40015172-CH3) in [GameplayKit Programming Guide](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/index.html#//apple_ref/doc/uid/TP40015172).

## Topics

### Creating a Graph

[`-  initWithNodes:`](/documentation/GameplayKit/GKGraph/init(_:))

Initializes a graph with the specified list of nodes.

[`+  graphWithNodes:`](/documentation/GameplayKit/GKGraph/graphWithNodes:)

Creates a graph with the specified list of nodes.

### Working with Nodes in a Graph

[`-  addNodes:`](/documentation/GameplayKit/GKGraph/add(_:))

Adds the specified nodes to the graph.

[`-  connectNodeToLowestCostNode:bidirectional:`](/documentation/GameplayKit/GKGraph/connectToLowestCostNode(node:bidirectional:))

Adds a node to the graph, connecting it to the node already in the graph for which the connection has the lowest cost.

[`-  removeNodes:`](/documentation/GameplayKit/GKGraph/remove(_:))

Removes the specified nodes from the graph.

[`nodes`](/documentation/GameplayKit/GKGraph/nodes)

The list of nodes in the graph.

### Pathfinding with a Graph

[`-  findPathFromNode:toNode:`](/documentation/GameplayKit/GKGraph/findPath(from:to:))

Computes and returns a sequence of nodes that represents the shortest traversal of the graph between the specified nodes.

## Relationships

### Inherited By

[`GKMeshGraph`](/documentation/GameplayKit/GKMeshGraph)

[`GKObstacleGraph`](/documentation/GameplayKit/GKObstacleGraph)

[`GKGridGraph`](/documentation/GameplayKit/GKGridGraph)

### Conforms To

[`Equatable`](/documentation/Swift/Equatable)

[`Hashable`](/documentation/Swift/Hashable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`NSCoding`](/documentation/Foundation/NSCoding)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`CVarArg`](/documentation/Swift/CVarArg)

[`NSCopying`](/documentation/Foundation/NSCopying)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)