This tutorial will help to get you started with brainbugz, after you are finished, you will know the basic concepts on how to create steering desires, combine different steering desires and fields and how to establish a working node connection setup.
It is assumed you are familar with the basic creation and setup of particle systems and creation of geometry. Please consult the Maya docs if any questions appear on this.

- switch the work area from "perspective"- to "top"-view
- create a particle object "bugs" using the particle tool (about 60 -70 particle will be sufficient)
- create a polyCube "terrarium", scale it so that the particles are inside the cube and there is some space for them to move
- make the "bugs" collide with the "terrarium"

Your work area should somewhat look like this:

- create 3 steering desire nodes and 1 combine desires node using the "brainbugz" menu:

- rename the steeringDesire nodes to "bugsCohesion", "bugsAlignment", "bugsSeparation"
- rename the combineDesires node to "bugsFlocking"

- start the brainbugz "Connection Editor" using the brainbugz menu, this will help us to do all the necessary connection work

You may open the "Connection Graph" by clicking on the small arrow, this will show you the current connections made, starting with the node selected in the "Select Node" outliner

The basic rules for connection editing:
- the connection graph has got to start from a particle node, and it has got to end there
- all steering desires and fields must have incoming connections from a particle node
- steering desires and fields outgoing connetctions can be combined using combine nodes
- combine nodes can be combined with other combine nodes

- connect the particle node with the steering desires (select the particle node "bugs", all connectable nodes for incoming and outgoing connections will be displayed in the relative outliner, connect the 3 steering desires at "outgoing connections")

- select the "bugsFlocking" combine desires node and connect the steering desires to it (incoming)
(image shows "Connection Mode - Incoming")

- the final step in connection setup is to connect "bugsFlocking" outgoing connection to the "bugs" particle node incoming connection

- close the "Connection Editor" as we are finished with our setup

So, what did we just do? We created 3 Steering Desires, that will be combined to 1 higher level desire and established all connection necessary to make the system work. Now we have got to set the attributes for the different steering desires.

- select the "bugsAlignment" steering desire, open the Attribute Editor
- set "Steering Desire" to "Neighbor - Alignment"

- open "General Bug Attributes"
- set "Sensor Range" to "1.0"
- set "Senor Angle" to "160"

- select "bugsCohesion"
- set "Steering Desire" to "Neighbor - Cohesion"
- set "Sensor Range" to "1.8"
- set "Senor Angle" to "170"

- select "bugsSeparation"
- set "Steering Desire" to "Neighbor - Separation"
- set "Sensor Range" to "0.5"
- set "Senor Angle" to "115

Alignment will force the "bugs" to align themselves to nearby (as specified by the field of view) bugs.
Cohesion will force the "bugs" to move in the direction of nearby bugs.
Separation will prevent the "bugs" from crowding together with nearby bugs.

Now we will combine these simple steering desires in one higher level desire "bugsFlocking"

- select bbCombineDesires node "bugsFlocking"
- set "Combine Mode" to "Priority"
- set the priorities as shown in the image

Separation will have the highest priority, only if this produces no result (because no nearby bugs are in the sensor range), the next desire Alignment is taken into account. Only if this produces no result Cohesion will be evaluated.
Note how we set the different sensor ranges, so the higher priorized desires don't overrule lower priorized desires.

Hit "Play" to start the simulation. Nothing happens - why?

- switch to Component Mode
- select the particles "bugs"
- open the Component Editor, Load Components

You see, all the particles have no velocity - as the local coordinate system of the particles is velocity aligned, the "bugs" don't know where to look for nearby neighbors. So we have got to change this.

- set the x-component of the particles velocity to 1 (alternative you can use other methods to get the particles going)

Note: Edit the "Mass" of the particles here, too.

- start the simulation again

You'll notice some bugs will get very fast, and some will be very slow or eventually stop. This can be prevented by speed clamping the particles.

- select particles "bugs"
- select "Clamp Speed Particle" from the brainbugz menu

This will add two attributes "bb Minimum Speed" and "bb Maximum Speed" as well as a runtime expression to the selected particle node which will enforce min- and max speed.

- set "bb Minimum Speed" to "1.0"
- set "bb Maximum Speed" to "3.5"

- start the simulation again, notice the effect

- experiment with different settings for the steering desires, change combination mode to "Weights" and change the different weights

Let`s make the flock move a little bit more coordinated, eg. it should move along a path.

- create a nurbsCurve "path", this will be the motion path
- create a nurbsPlane "targetPlane", this will be the plane the "bugs" will be seeking
- animate the "targetPlane" along the "path" using "Attach to Motion Path"

The work area should look somewhat like this:

- create steering desire "bugsPlaneArrival"
- create combine desires "bugsPathFollowFlocking"
- set up the connections using the "Connection Editor" so it matches the graph below

- select steering desire "bugsPlaneArrival"
- select steering desire "Target - Arrival"
- add "targetPlane" to the connected Geometry using the "bb (Dis)Connect Nodes" window

- select bbCombineDesires"bugsPathFollowingFlocking"
- set "Combine Mode" to "Weights"
- set the weights according to the image below

- start simulation
- experiment with different weights, different steering desires
- enjoy!