# GKAgent A component that moves a game entity according to a set of goals and realistic constraints. ``` class GKAgent ``` ## Overview The [`GKAgent`](/documentation/GameplayKit/GKAgent) class is abstract, defining only the general functionality of an agent—its movement constraints and the [`behavior`](/documentation/GameplayKit/GKAgent/behavior) property containing its goals ([`GKGoal`](/documentation/GameplayKit/GKGoal) objects). To implement agent-based gameplay, choose a concrete subclass that fits your game. - Use the [`GKAgent2D`](/documentation/GameplayKit/GKAgent2D) class for 2D game worlds, or for 3D games where all gameplay-relevant movement is constrained to two dimensions. - Use the [`GKAgent3D`](/documentation/GameplayKit/GKAgent3D) class for game worlds that allow movement in three dimensions. To learn more about the agent simulation, see [Agents, Goals, and Behaviors](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/Agent.html#//apple_ref/doc/uid/TP40015172-CH8) in [GameplayKit Programming Guide](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/index.html#//apple_ref/doc/uid/TP40015172). ### An Agent is a Component Because [`GKAgent`](/documentation/GameplayKit/GKAgent) is a subclass of [`GKComponent`](/documentation/GameplayKit/GKComponent), you can use Entity-Component architecture to add agent-based behaviors to your game. (For details on this architecture, see [Entities and Components](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/EntityComponent.html#//apple_ref/doc/uid/TP40015172-CH6) in [GameplayKit Programming Guide](https://developer.apple.com/library/archive/documentation/General/Conceptual/GameplayKit_Guide/index.html#//apple_ref/doc/uid/TP40015172).) To integrate agents with gameplay, call each agent’s [`update(deltaTime:)`](/documentation/GameplayKit/GKComponent/update(deltaTime:)) 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 method of a SpriteKit scene or the method of a SceneKit renderer delegate. If your game uses Entity-Component architecture, you can use a [`GKComponentSystem`](/documentation/GameplayKit/GKComponentSystem) object to update all the agents in the game scene for each frame. If not, you must call each agent’s [`update(deltaTime:)`](/documentation/GameplayKit/GKComponent/update(deltaTime:)) method directly. ### An Agent Simulates Movement Based on Goals Each time an agent’s [`update(deltaTime:)`](/documentation/GameplayKit/GKComponent/update(deltaTime:)) method runs, the agent evaluates each [`GKGoal`](/documentation/GameplayKit/GKGoal) object listed in its [`behavior`](/documentation/GameplayKit/GKAgent/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`](/documentation/GameplayKit/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 [`update(deltaTime:)`](/documentation/GameplayKit/GKComponent/update(deltaTime:)) method—such as the [`update(deltaTime:)`](/documentation/GameplayKit/GKComponent/update(deltaTime:)) method of another [`GKComponent`](/documentation/GameplayKit/GKComponent) subclass in your game or a game engine method such as (SpriteKit) or (SceneKit)—examine the position and rotation of each agent and use that information to update the properties of any visual objects representing the agents. - Set the [`delegate`](/documentation/GameplayKit/GKAgent/delegate) property of each agent to an object responsible for that agent’s visual representation. That object can implement the [`agentDidUpdate(_:)`](/documentation/GameplayKit/GKAgentDelegate/agentDidUpdate(_:)) method, 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 [`agentWillUpdate(_:)`](/documentation/GameplayKit/GKAgentDelegate/agentWillUpdate(_:)) method 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. > Tip: > If you use the ``doc://com.apple.gameplaykit/documentation/GameplayKit/GKSKNodeComponent`` class to manage the relationship between an entity and a SpriteKit node, set your ``doc://com.apple.gameplaykit/documentation/GameplayKit/GKSKNodeComponent`` instance as the delegate for that entity’s agent, and GameplayKit will automatically synchronize the agent and its SpriteKit representation. > Note: > The simulation responsible for agent movement is based on realistic physical behaviors; however, this simulation is *not* connected to the physics subsystems in SpriteKit, SceneKit, or any other graphics engine. For example, setting the ``doc://com.apple.gameplaykit/documentation/GameplayKit/GKAgent/mass`` property of an agent does not affect the collision behavior of any SpriteKit physics bodies. ## Topics ### Defining an Agent’s Behavior [`behavior`](/documentation/GameplayKit/GKAgent/behavior) A weighted collection of goals that influence the agent’s movement. ### Constraining an Agent’s Movement [`mass`](/documentation/GameplayKit/GKAgent/mass) The resistance of the agent to changes in speed or direction. [`maxAcceleration`](/documentation/GameplayKit/GKAgent/maxAcceleration) The upper limit to changes in the agent’s speed or direction. [`maxSpeed`](/documentation/GameplayKit/GKAgent/maxSpeed) The agent’s maximum forward speed, in units per second. [`radius`](/documentation/GameplayKit/GKAgent/radius) The agent’s radius. ### Synchronizing an Agent’s Visual Representation [`delegate`](/documentation/GameplayKit/GKAgent/delegate) An object that prepares for or responds to updates in the agent simulation. ### Managing an Agent’s Attributes [`speed`](/documentation/GameplayKit/GKAgent/speed) The agent’s current forward speed, in units per second. ## Relationships ### Conforms To [`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible) [`NSSecureCoding`](/documentation/Foundation/NSSecureCoding) [`NSCopying`](/documentation/Foundation/NSCopying) [`NSCoding`](/documentation/Foundation/NSCoding) [`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible) [`Equatable`](/documentation/Swift/Equatable) [`CVarArg`](/documentation/Swift/CVarArg) [`Hashable`](/documentation/Swift/Hashable) [`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol) ### Inherits From [`GKComponent`](/documentation/GameplayKit/GKComponent) ### Inherited By [`GKAgent3D`](/documentation/GameplayKit/GKAgent3D) [`GKAgent2D`](/documentation/GameplayKit/GKAgent2D) --- Copyright © 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)