A component that moves a game entity according to a set of goals and realistic constraints.
- iOS 9.0+
- macOS 10.11+
- Mac Catalyst 13.0+
- tvOS 9.0+
GKAgent class is abstract, defining only the general functionality of an agent—its movement constraints and the
behavior property containing its goals (
GKGoal objects). To implement agent-based gameplay, choose a concrete subclass that fits your game.
GKAgent2Dclass for 2D game worlds, or for 3D games where all gameplay-relevant movement is constrained to two dimensions.
GKAgent3Dclass for game worlds that allow movement in three dimensions.
An Agent is a Component
GKAgent is a subclass of
GKComponent, you can use Entity-Component architecture to add agent-based behaviors to your game. (For details on this architecture, see Entities and Components in GameplayKit Programming Guide.)
To integrate agents with gameplay, call each agent’s
update method each time you want to update the simulation that governs the agent’s behavior. Typically, you call this method once for each frame processed by your game’s graphics engine—for example, in the
update: method of a SpriteKit scene or the
renderer: method of a SceneKit renderer delegate. If your game uses Entity-Component architecture, you can use a
GKComponent object to update all the agents in the game scene for each frame. If not, you must call each agent’s
update method directly.
An Agent Simulates Movement Based on Goals
Each time an agent’s
update method runs, the agent evaluates each
GKGoal object listed in its
behavior property to find the change in direction and speed necessary to move toward fulfilling that goal (within the limits of the time delta and the agent’s maximum speed and turn rate). It then combines the effects from all the goals in its behavior, using the weights specified in the
GKBehavior object to modulate the influence of each goal, resulting in a total change in its direction and speed.
There are two options for using the output of this simulation to move game entities:
In a per-frame update that executes after the agent’s
updatemethod—such as the
With Delta Time:
updatemethod of another
With Delta Time:
GKComponentsubclass in your game or a game engine method such as
renderer:(SceneKit)—examine the position and rotation of each agent and use that information to update the properties of any visual objects representing the agents.
will Render Scene: at Time:
delegateproperty of each agent to an object responsible for that agent’s visual representation. That object can implement the
agentmethod, which the agent calls every time it updates its position and direction. In that method, you can examine the agent’s properties and make corresponding changes to a visual representation.
In addition, an agent delegate can implement the
agentmethod to feed information into the agent simulation. This option can be useful for combining agent-based movement with an external physics engine (such as those found in SceneKit and SpriteKit), or with other APIs that might apply motion to an agent’s visual representation (such as SpriteKit actions). However, the agent simulation cannot account for momentum introduced by such influences, so the accuracy of the agent’s planning will be reduced in these scenarios.