A set of behaviors, each of which is a set of goals, that together influence the movement of an agent.


@interface GKCompositeBehavior : GKBehavior


By composing GKGoal objects into subgroups (GKBehavior objects) and composing those behaviors into composite behaviors, you can control certain aspects of a GKAgent object's movement in concert. To assign a behavior to an agent, use its behavior property.

For example, you might create a behavior for a set of agents to stay together as a flock (with cohesion, alignment, and separation goals) while loosely following a path. With a single GKBehavior object, whenever you want to change the importance of the flocking goals relative to the path-following goals, you’d need to individually change the weight of each goal. With a composite behavior, you can adjust the relative influence of a group of goals together, as in the following code.

GKBehavior *flock = [GKBehavior behaviorWithGoals:@[
    [GKGoal goalToAlignWithAgents:agents maxDistance:10 maxAngle:M_PI_4],
    [GKGoal goalToCohereWithAgents:agents maxDistance:10 maxAngle:M_PI_4],
    [GKGoal goalToSeparateFromAgents:agents maxDistance:10 maxAngle:M_PI_4]
GKBehavior *meanderOnPath = [GKBehavior behaviorWithgoals:@[
    [GKGoal goalToFollowPath:path maxPredictionTime:1.0 forward:YES],
    [GKGoal goalToWander:10]
GKCompositeBehavior *composite = [GKCompositeBehavior behaviorWithBehaviors:@[
    flock, meanderOnPath

After constructing this behavior, you can use the setWeight:forBehavior: method to increase or decrease the influence of the flock and meanderOnPath behaviors relative to one another.

To learn more about using goals and agents, see Agents, Goals, and Behaviors in GameplayKit Programming Guide.


Creating a Composite Behavior

+ behaviorWithBehaviors:

Creates a composite behavior from the specified individual behaviors.

+ behaviorWithBehaviors:andWeights:

Creates a behavior with the specified behaviors and weights.

Managing the Individual Behaviors in a Composite Behavior

- setWeight:forBehavior:

Sets the weight for the specified individual behavior’s influence on agents, adding that behavior to the composite behavior if it is not already present.

- weightForBehavior:

Returns the weight for the specified individual behavior’s influence on agents.

- removeBehavior:

Removes the specified individual behavior from the composite behavior.

- removeAllBehaviors

Removes all individual behaviors from the composite behavior.


The number of individual behaviors in the composite behavior.

Working with Behaviors Using Subscript Syntax

- objectForKeyedSubscript:

Returns the weight associated with the behavior specified by subscript syntax.

- setObject:forKeyedSubscript:

Sets the weight for the behavior specified by subscript syntax.

- objectAtIndexedSubscript:

Returns the individual behavior at the specified index in the composite behavior’s list of behaviors.


Inherits From

See Also

Agents, Goals, and Behaviors


A component that moves a game entity according to a set of goals and realistic constraints.


An agent that operates in a two-dimensional space.


An agent that operates in a three-dimensional space.


An influence that motivates the movement of one or more agents.


A set of goals that together influence the movement of an agent.


A polygonal path that can be followed by an agent.


Implement this protocol to synchronize the state of an agent with its visual representation in your game.