.. _adding-behavior:

***************************
Add behavior to your agents
***************************

To add behavior to your agents you first have to create a Crowd Sim Node Tree.
In the CrowdSim Node Editor 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.

Overview
========

The Crowd Sim Node Editor contains various nodes to build up your behavior
tree. Together they control the behavior of the simulation. :ref:`node-behavior`
is the start node.

.. image:: /images/node-behavior.png
  :align: center

At the output socket of the behavior node other nodes can be added. During execution
per frame the node tree will be executed. Each node can be in one of the next states:

* **Not executed**: This can happen when a :ref:`category-composites` node won't
  select all sub trees to execute.

  .. image:: /images/node-conditional.png
    :align: center

* **Success**: The node execution has been completed successfully. Each node has its own
  definition if it is successfully executed. For example the :ref:`node-target-navigation`
  node will be successfully executed when it is within reach of its target. Otherwise it
  will be in its running state.

  .. image:: /images/node-target-navigate.png
    :align: center

* **Failure**: The node execution has been completed, but failed. This could happen when
  a test fails. For example the :ref:`node-check-agent-model` will be in fail state for
  agents that aren't of the selected model/character.

  .. image:: /images/node-check-agent-model.png
    :align: center

* **Running**: The node execution takes multiple frames and have not been completed. An
  example is the :ref:`node-move` node that will be running for the number of frames
  that are set in the node. Only the last frame will result in its success state.

  .. image:: /images/node-move.png
    :align: center

.. note::
  When using the debugger it is possible to look at the state of each node for each frame
  in the animation for each agent. See :ref:`debugger` for more information how to use it.



Nodes
=====

.. toctree::
  :maxdepth: 2

  category-start
  category-filter
  category-composites
  category-decorators
  category-states
  category-targets
  category-navigation
  category-avoid
  category-movement
  category-animation
  category-collisions
  group-nodes

Quickstart Templates
====================

.. toctree::
  :maxdepth: 2

  category-templates