Add behavior to your agents

To add behavior to your agents you first have to create a Crowd Sim Node Tree. In the Node Editor enable Crowd Sim and press New

Note

CrowdSim3D uses behavior trees for adding logic to the agents. See https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) for more information and https://www.youtube.com/watch?v=YCMvUCxzWz8 for an overview of behavior trees.

The Crowd Sim Node Editor contains various nodes to build up your behavior tree.

Object

The Object subtree contains the root node that executes the behavior tree. It also contains various nodes to filter objects or to debug.

Behavior

../../_images/node-behavior.png

This node is the most important node, it executes the behavior tree. This is the root node and should be part of your behavior tree.

  • Subframes: The number of additional subframes that are calculated. Increasing this setting will improve the quality of certain nodes like the Avoid Node.
  • Smooth frames: When this value is larger then 0 a post processing step will happen. During this step the result of the simulation is smoothened with the result of the surrounding frames. It is usefull to remove simulation glitches.

Object Selector

../../_images/node-object-selector.png

With this node you can filter on a group of agents:

  • By agent: When checked only agents will be selected. When not checked also other objects can be selected.
  • By name: Filter obects by name. A wildcard * can be added to select multiple objects. For example Agent_*.
  • By factory: Filter only agents that originated from a specific factory.

This node can be attached to various nodes like the Populate node.

Collection Operation

../../_images/node-collection-operation.png

Use this node to perform set operations on collections of objects.

Options:

  • Operation: Type of operation to perform
    • Union: Combine the two attached collections
    • Intersection: Return a collection with only objects that are part of both input collections
    • Symmetric Difference: Return a collection containing the objects that only belong to a single input collection
    • Difference: Return a collection containing all objects in input collection a that are not part of input collection b

Object Distance Filter

../../_images/node-object-distance-filter.png

This node can be used to filter a set of objects based on the distance with the active agent.

Options:

  • Near distance: All objects closer then the Near distance will be removed from the selection.
  • Far distance: All objects further then the Far distance will be removed from the selection.

Debug

Debugger

../../_images/debug-properties.png

Activating the Debugger in the Properties panel will show per agent which nodes are evaluated during the simulation. The debug information is gathered during execution of the behavior.

Debug Node

../../_images/node-debug.png

This node can be used to debug agent information. You can add this node to a subtree. When executing the behavior debug information is gathered. Select an agent and run the simulation to see the data per frame.

Composites

Composites define a subtree and the base rule of how this subtree should be executed.

Sequence

../../_images/node-sequence.png

Nodes in the subtree are executed in order, first child-1, then child-2 and so on. Execution of the subtree stops when a child node fails or when all children nodes succeed.

In case of failure the Sequence node returns a Failure state. In case of all children succeeding the Sequence returns a Success or Running state.

The randomize option makes it possible to pick children in the subtree in random order.

Options:

  • Randomize: test output sockets in a random order.

Selector

../../_images/node-selector.png

Nodes in the subtree are executed in order, first child-1, then child-2 and so on. Execution of the subtree stops when a child succeeds or when all children fail.

In case of failure the Selector node returns a Failure state. In case a child succeeds the Selector returns a Success or Running state.

The randomize option makes it possible to pick children in the subtree in random order.

Options:

  • Randomize: test output sockets in a random order.

Parallel

../../_images/node-parallel.png

Nodes in the subtree are executed in parallel. Execution of the subtree stops when a child node fails or when all children nodes succeed.

In case of failure the Parallel node returns a Failure state. In case all children succeed the Parallel returns a Success state.

Decorators

Decorators can modify the result of a node. These decorators can be added as a node or as a modifier in the output of a node. These modifiers are:

Inverter

../../_images/node-inverter.png

Inverts the result. Success becomes Failure and Failure becomes Success. Error and Running remain unchanged.

Inverter
In Out
Running Running
Success Fail
Fail Success
Error Error

Always Succeed

../../_images/node-always-succeed.png

A node always succeed.

Always Succeed
In Out
Running Success
Success Success
Fail Success
Error Success

Always Fail

../../_images/node-always-fail.png

A node always fails.

Always Fail
In Out
Running Fail
Success Fail
Fail Fail
Error Fail

Until Success

../../_images/node-until-success.png

Node keeps running until a Success or an Error is returned.

Until Fail

../../_images/node-until-fail.png

Node keeps running until a Fail or an Error. In case of a failure a Success is returned.

Conditional

../../_images/node-conditional.png

Perform if … else … logic.

If the subtree of a conditional returns Success then the success subtree is executed.

If the subtree of a conditional returns Fail then the failure subtree is executed.

Limiter

../../_images/node-limiter.png

With this decorator you can limit the number of times the subtree is evaluated.

Options:

  • Limit: Max number of times the subtree may be evaluated. Returns Fail when limit is met. Otherwise the result of the child subtree is returned.

Guard

../../_images/node-guard.png

With the Guard decorator you can limit the number of times a subtree is evaluated in the current frame.

Options:

  • Limit: Max number of times the subtree may be evaluated in a frame. Returns Fail when limit is met. Otherwise the result of the child subtree is returned.

Max Time

../../_images/node-max-time.png

With this decorator you can set the maximum time in frames for the child node to be evaluated.

Options:

  • Frames: Max number of frames a node may run before finishing. Returns Fail when limit is met. Otherwise the result of the child subtree is returned.

Repeat

../../_images/node-repeat.png

Set the number of times a child node should be repeated (like a for loop).

Options:

  • times: Number of times the subtree must be executed. Loop is halted when an error occurs.

States

State properties

In the side panel of the CrowdSim node tree you can define State Properties. These state properties can be used to store state of an agent.

../../_images/crowdsim-state-properties-panel.png

By pressing Add State Property you can add a new state property to the list. By pressing Remove State Property you can remove the highlighted state property. You can change the name of a state property by double clicking on its name.

A state property has a type. There are 4 types available:

  • String
  • Boolean
  • Float
  • Integer

You can also set a default value for the state properties you define.

There are several nodes that can check values or perform an operation on a state property or an agent variable.

State Operation

../../_images/node-state.png

With this node you can perform an operation - Add, Set, Subtract, Multiply - on your State property.

Options:

  • State Property: State property to perform the operation on
  • Operation: Type of operation to perform
    • Set: Update the property to the given value
    • Add: Add the given value to the property
    • Subtract: Subtract the given value from the property
    • Multiply: Multiply the property with the given value
  • Value: The given value for the operation. When using Boolean values you should use 0 for false and 1 for true
Supported state operations
Type Supported Operations
String Set
Integer Set, Add, Subtract, Multiply
Float Set, Add, Subtract, Multiply
Boolean Set

Check State

../../_images/node-check-state.png

With this node you can check your State property against another value.

Options:

  • State Property: State property to perform the operation on
  • Check: Type of check to perform
    • Equal: Is the property equal to the given value
    • Less than: Is the property less than the given value
    • Greater than: Is the property greater than the given value
    • Is True: Is the property true
    • Is False: Is the property false
  • Value: The given value for the operation. When using Boolean values you should use 0 for false and 1 for true
Supported state checks
Type Supported Check
String Equal, Less than, Greater than
Integer Equal, Less than, Greater than
Float Equal, Less than, Greater than
Boolean Is True, Is False

Check Scene Attribute

With this node you can check the value of a scene attribute. For now only the frame number is supported. You can have logic that will only apply in case of a certain frame number.

../../_images/node-check-scene-attribute.png

Options:

  • Scene Attribute: The scene attribute to be checked. For now only frame number is supported.
  • Check: Type of check to perform

Check Attribute

With this node you can check an internal variable of the agent. You can use this node together with the Conditional node to add specific behavior based on the attribute.

../../_images/node-check-attribute.png
  • Attribute: The attribute to check.
    • Collision Impact: The impact that has been calculated during the last intersection test.
    • Agent Speed: Check the current speed of the agent.
    • Agent Model: Check the model (and armature) of the agent.
    • Agent Factory: Check the factory of the agent.
    • Grid Position: The position of the agent when a grid distribution is applied.
  • Check: The check to perform. Only valid when Attribute is Collision Impact, Grid Position or Agent Speed. Options are
    • Equals: is the attribute equal to the value
    • Less than: is the attribute less than the value
    • Greater than: is the attribute greater than the value
  • Value: The value to perform the check against. Only valid when Attribute is Grid Position, Collision Impact or Agent Speed.
  • Model: The model to check against. Only valid when Attribute is Agent Model.
  • Character: The character to check against. Only valid when Attribute is Agent Model and Model is an armature. This field is optional. When not used only the model will be checked.
  • Factory: The factory to check against. Only valid when Attribute is set to Agent Factory.

Set Attribute

With this node you can set or update an internal variable.

../../_images/node-set-attribute.png

Options:

  • Variable: Variable to update
    • Speed Vector: Allows the updating of direction and speed of the agent.
  • Direction: The direction to set. Only valid when Variable is Speed Vector.
  • Velocity: The velocity to set. Only valid when Variable is Speed Vector.

Actions

With Actions you can define certain actions for your agent.

Note

Tips

  • When your agents are not moving it can be because most of the action nodes only update an internal desired speed vector.

    This vector describes the direction and velocity that the agent wants/can move. Use the Advance Ground Movement node to convert the desired speed vector to actual movement.

There are several actions to perform:

Action

The Action node can be used for simple translation and rotation movement. This node applies the movement directly.

../../_images/node-action.png

Options:

  • Duration: the duration that the action takes (in frames).
  • Translation: the translation that happens during the Duration. The translation is applied in the local coordinate system of the object.
  • Rotation: the rotation that happens during the Duration. The rotation is applied in the local coordinate system of the object.

Play Action

With this node you can add animations to your agent.

Play Actions Type

../../_images/node-play-action.png

With this option you can add your own actions. The crowd simulation plays the animation. You can set the number of frames in the Blend In - Blend Out option.

With Add Action you can add a new action slot. Multiple actions can be played back at the same time.

Options:

  • Priority: When merging actions what priority should be considered. Higher number means higher priority and the animation will not be interfered with actions that plays with less priority.
  • Duration: The duration to play the action.
  • Blend In: Number of frames to blend in the animation
  • Blend Out: Number of frames to blend out the animation.

Walk Type

../../_images/node-play-action-walk.png

With this option you can generate a walk cycle based on the actual velocity and angular velocity of the agent.

This node uses the velocity and angular velocity of an animation action. The data can be modified in the Dope Sheet.

../../_images/action-crowdsim-panel.png

In the Dope Sheet ‣ Action Editor ‣ CrowdSim you can set the velocity and the angular velocity of the action.

The Play Action node selects up to 3 closest animation actions based on the actual velocity and angular velocity of the agent. With this It merges these actions to create a better suited animation for the actual velocity and angular velocity of the agent.

Options:

  • Blend Type: How to blend in the animation. Possible options are:
    • Linear Ease: Use linear ease blending
    • Linear Smooth: Use linear blending
    • Cubic Smooth: Use cubic blending
  • Blend In: Number of frames to blend in the animation
  • Blend Out: Number of frames to blend out the animation.

Advance Ground Movement

With this node the current desired speed vector is used to advance the position of the agent for this frame.

../../_images/node-advance-ground-movement.png

Options:

  • Angular Velocity: Maximum angular velocity in degrees per second.
  • Stick on Edge: When a navigation mesh is used make sure that the agent will always be placed at the nearest location on the navigation mesh.

Avoid

With this node you can set the Algorithm for Avoiding other agents and obstacles. The Avoid node uses the desired speed vector and the surrounding area of the scene to avoid obstacles like walls and other agents.

At the end of this action the desired speed vector is updated.

Simple

../../_images/node-avoid.png

Uses a very basic algorithm to avoid agents only. Obstacles are not supported.

Options:

  • Viewing Angle: Set the Angle to consider. The algorithm will use this angle to look for agents to avoid.
  • Viewing distance: Set the distance to be considered. The algorithm will use this distance to determine how far to look for agents to avoid.
  • Number of Segments: This option relates to the viewing Angle. The viewing Angle will be divided in a number of segments. The algorithm will evaluate each segment to look for agents to avoid. The segment with the least number of agents will be taken.
  • Agent Distance: This option determines the minimal distance between agents to take into account.
  • Look Ahead: With this option you can determine how far ahead - in terms of time and samples - the algorithm should look.
  • Advanced Options: With this option you can set the Deceleration factor.

RVO2

../../_images/node-avoid-rvo2.png

Uses the RVO2 algorithm to avoid agents and obstacles. The navigation mesh used in the Navigate node will be converted into obstacles. For every area where an agent cannot walk on the navigation mesh an obstacle wall will be added to the evaluation.

Options:

  • Maximum Neighbors: Sets the maximum of neighbors to be considered.
  • Agent Distance: Sets the distance between agents to be considered.
  • Viewing Distance: Sets the viewing distance to be considered.
  • Time Horizon: Sets the Time Horizon for agents to be considered.
  • Time Horizon Obstacles: Sets the Time Horizon for obstacles to be considered.

Force Based

../../_images/node-avoid-force-based.png

Uses a basic force based algorithm to avoid agents and obstacles. The navigation mesh used in the Navigate node will be converted into obstacles. For every area where an agent cannot walk on the navigation mesh an obstacle wall will be added to the evaluation.

Options:

  • Scaling: Sets an overall scaling factor for the forces.

Force Based (TTC)

../../_images/node-avoid-force-based-ttc.png

Uses a time to collision force based algorithm to avoid agents and obstacles. The navigation mesh used in the Navigate node will be converted into obstacles. For every area where an agent cannot walk on the navigation mesh an obstacle wall will be added to the evaluation.

Options:

  • Scaling: Sets an overall scaling factor for the forces.

Look At

../../_images/node-look-at.png

Look at a target. This nodes makes it possible to have agents look at a target object. Create a target property and set the target using the Lock target node. Set the target of this node to the same property.

Options:

  • Target Property: Target property to look at or to follow.

Targets

In the side panel of the CrowdSim node tree you can define Target Properties. These target properties can be used in the Behavior tree to let an agent lock to another agent or object.

../../_images/crowdsim-target-properties-panel.png

By pressing Add Target Property you can add a new target property to the list. By pressing Remove Target Property you can remove the highlighted target property. Double clicking on the target property you can change its name.

Several nodes uses the target properties:

Lock to Target

Lock to a target.

../../_images/node-lock-target.png

Socket:

  • Agents: The selection of agents to choose from. When socket is not linked, all agents in the scene will be used as selection.

Options:

  • Target Property: Target property to store the locked target in. If a target property is already filled for the active agent, then this node will be ignored. You first need to use the Unlock Target node to unset the target property.
  • Randomize: Randomize the agent selection before choosing one.
  • Maximum: Maximum that the target can be selected for the chosen target property.

Unlock Target

Unset the target property from the active agent.

../../_images/node-unlock-target.png

Options:

  • Target Property: Target property to unset.

Has Locked Target

Test if the active target has a target selected for the chosen target property.

../../_images/node-locked-target.png

Options:

  • Target property: Target property to check.

Is Agent Targeted

Test if an agent is locked by another target. It tests the reverse of ‘Has Locked Target’.

../../_images/node-agent-targeted.png

Options:

  • Target property: Target property to check.

Collisions

Intersection

../../_images/node-intersection.png

This node checks whether the active agent intersects with another mesh or agent. You can configure how precise the detection has to be calculated. You can choose between:

  • World Bounding box: Uses axis aligned bounding box (AABB) checking.
  • Local Bounding box: Checks bounding box in local space.
  • Convex hull: Checks intersection by using the convex hulls of the objects.
  • Triangle Mesh: Checks intersection by using the triangular meshes of the objects.

When an intersection is detected the intersection impact internal variable is updated with the detected force.