Are your BOIDs doing some strange or weird behaviors and you don’t know what you’re doing wrong with the parameter settings? This wiki page is designed to explain how PySwarm works (under the hood and mostly in layman’s terms) and then offer some suggestions on how you might be able to resolve these problems. Note: If you are having problems with installing the required components, with PIA generating a PySwarm script, or in getting the script to import successfully, visit the Troubleshooting page for details. Note: If you are observing BAMMs in your BOIDs and a solution is not on this page, please either email me or post a comment in the following DAZ3D forums thread:

My BOIDs come to a complete stop during animation, or slow to a crawl.Edit

A BOID’s drive to move is driven by Cohesion, Separation (when they get too close), Alignment, and Attraction. If you have these rules turned off, there is no drive (or motive) for BOIDs to move.

  • Setting the Initial Speed and Min Speed values will keep the BOIDs moving at a minimum speed.

When I start the animation (from the Start Time I entered), the BOIDs turn suddenly one way or anotherEdit

This may happen especially when I have selected “Current BOID Heading” under Initial Heading Parameters.

  • When you have selected “Current BOID Heading,” PySwarm sets the initial velocity vector (heading and speed) based on two parameters – which way the BOIDs are facing (for the heading) and the value you have set in Initial Speed (for the speed). If your Initial Speed is 0, your BOID have no initial velocity, and they will be controlled by whatever vectors (forces) are applied at that point (based on the rules you have active).
  • If you’re using “Current BOID Heading,” set the Initial Speed to a value other than 0.

Not all of my BOIDs move after I import the script.Edit

PySwarm will animate all of (and only) the BOIDs you tell it to find. If it cannot find a BOID in your scene (during PySwarm script import), it will stop the import and inform you of the error. If you are successfully able to import the script, then there are only a few possibilities.

  • Make sure “Number of BOIDs” is set to be the actual number of BOIDs in your scene.

My BOIDs fly sideways or backwards.Edit

While PySwarm can read a BOID’s position (translation) and rotation values, there is no way for it to know which way BOID’s face in their default orientation.

  • Check the Default BOID Orientation setting. Read more at this link - here.

My BOIDs wobble/tilt side to side as they move.Edit

This behavior can be caused by a number of reasons.

  • You may have set the keyframe rate too high (for creating a realistic animation). For example, a fighter pilot does not make flight corrections 15 times a second, so you should not set the keyframe rate at this level. High keyframe rates will cause BOIDs to constantly adjust their path. Try lowering the keyframe rate to a lower value (e.g., 3-5).
  • If you have separation, cohesion, and alignment active, BOIDs are attempting to adjust for a number of competing directives. Try lowering the strength settings for 1-2 of these.
  • You can also reduce the Banking Factor.

My BOIDs bank wildly in their turns.Edit

By default, a BOID’s banking angle is computed as the BOID’s change in heading during this keyframe normalized on a per second basis. For example, if you set the keyframe rate to 10, and a BOID is changing its heading by 4 degrees during that keyframe interval, then the banking angle is 40 degrees (in the direction of the turn).

  • You can adjust the amount a BOID will bank with the Banking Factor. For example, a value of 0.5 in this field will force BOIDs to bank only at half the heading change angle. Keep in mind that this parameter does not alter how BOIDs fly, only how they respond to changes in direction.

My BOIDs do not turn, pitch, or bank realistically.Edit

Nearly every kind of creature and machine has its own way of maneuvering. For example, an airplane’s pitch normally matches the angle of climb or descent. However, this is not true when it is landing (when it’s nose is up slightly). To resolve these kinds of challenges, you will need to segment your animation and run different PySwarm scripts for each segment. For example, in the airplane scenario, you might run one PySwarm script with Pitching Factor at 1.0, but during the sequence when the plane is landing, run a different PySwarm script with Pitching Factor set to -0.5 (or something like this).

  • The only suggestion I have, since there are so many different combinations, is to look at live films/movies, watch how animals or machines move, and then play around with the parameters found in the Initialize and Movement tabs.

My BOIDs are not banking and I want them to.Edit

  • Make sure you do not have Banking Factor set to zero. If so, enter a value representing the percentage of banking (a value of 1.0 is 100%).

My BOIDs are not pitching (up or down) and I want them to.Edit

  • Make sure you do not have Pitching Factor set to zero. If so, enter a value representing the percentage of banking (a value of 1.0 is 100%).

My BOIDs sometime go into a sharp climb or dive, and then roll over when they fly the other way.Edit

This behavior might be fine for some kinds of BOIDs (like airplanes), but not all kinds have this capability (like most (all?) fish and birds).

  • Bound the BOIDs’ pitch by setting the Min and Max Pitch. For example, setting these to -60 and +60 degrees will allow BOIDs to climb and dive steeply, but they won’t roll over.

My BOIDs fly together and then overlap on top of each other.Edit

If you have turned on Alignment and Cohesion, BOIDs will naturally move together, even taking up the same space in the scene. The Separation rule was designed to ensure there is a safe space between BOIDs.

  • Check your Separation settings. If it is not activated, do so.
  • Compare the Separation strength value to those for Alignment and Cohesion. If it is much less (say, 1.0 while you have Alignment and Cohesion at 5 or 6), this value will not override the strong desire to come together. Adjust the strength values to be more even.
  • Also, it could be the Separation distance you have is too small. Click on one of your BOIDs and look at the size value. If your BOIDs are 50 feet long, but your Separation distance is 3 feet, your BOIDs will overlap. Adjust this parameter to something reasonable for “safe distance.”

My BOIDs don’t seem to be affected by the attractor in my scene.Edit

  • Check to see if you have an Attraction Radius set. If you intended on using this, you might need to extend the radius further out.
  • Check your Attractor Strength value. Is it lower than other rule strength settings? If so, you may need to increase this value.
  • Make sure you have the right object selected as your attractor.

My BOIDs’ positions are not initializing within my Containment Zone #1Edit

  • Make sure you have checked the "Activate Zone" box for zone #1.
  • It is possible you have not set the zone parameters correctly. For example, remember that the radius of a sphere or cylinder is HALF the object's width.

My BOIDs are flying outside a safe zone or into a restricted zone.Edit

Note: The current (V0.6) approach to containment is based on BOIDs reacting to zones. That is, BOIDs don’t currently attempt to correct a possible zone collision until they are imminent (one keyframe away from flying into/out of the zone). V0.6.1 involves a rewrite to the containment approach, and may alleviate some containment problems. For now:

  • If you have a requirement to keep BOIDs from flying through a zone boundary, reduce the size of your zone to about 90% of the actual boundary. This will help get BOIDs to respond sooner.
  • Try boosting the zone strength. This will cause BOIDs to react more quickly in attempting to correct a zone infraction.
  • When BOIDs are flying fast, it could take a while for the motivation to correct a zone collision. Lowering the Max Speed may help.

My BOIDs are ignoring zones that I am moving or resizing during animation.Edit

First, let me mention a few restrictions on using Carrara objects in your scene as zones.

  1. PySwarm currently only considers the object’s position (based on its hot point) for moving and overall scale for resizing. If you are resizing your zone objects, use the overall scale value to do so. Future versions will expand on this.
  2. If you are using an object other than a box, cylinder, or sphere primitive, you will still be restricted by how PySwarm “sees” that object (via the Type you select). Thus, cars can be boxes and trees can be cylinders.

With that said, this problem can still be caused by a number of setting issues.


  • Make sure you have the Containment rule activated.
  • Check each zone by selecting them one-by-one from the Zone # pulldown. Make sure you have Activate Zone checked.

If you have the right zones activated, then the problem is most like one of the following:

  • Make sure you entered the right name for the Carrara object you are using.
  • Check the settings.
  • Make sure your Carrara object’s hot point is centered on the object. Click the “HP->Obj” button to make sure.

Some objects in my scene (e.g., BOIDs, camera, focus) are not responding (moving as directed by my script) when I apply changes and re-import my script.Edit


I’ve changed some parameters, and after re-importing, the BOIDs fly about wildly (faster than they should).Edit

If you change the Keyframe Rate and do not clear the keyframes before importing, the new keyframes you are inserting won’t overwrite the old ones, so you will have two “paths” for your BOIDs.

  • Make sure to set the “Clear Keyframes at Start” checkbox.

When my BOIDs land, they are either above or below the ground.Edit

PySwarm uses the BOID’s hot point to identify its position.

  • To determine what value to use in the “Ground” parameter, drag one of your BOIDs to the ground, and position it (with X and Y rotation values set to 0!) how you want it to look when they land. Now use the BOID’s Translation Z-axis value as the Ground value.

After my BOIDs land, they start to take off, but then stop again.Edit

PySwarm puts BOIDs in landed mode when the Z axis translation value is at or below the value set in the Ground parameter. When BOIDs land, PySwarm resets the pitch and bank angles to 0 (leaving the heading unchanged), and positions it on the ground where the BOID strikes it. When the BOID’s landed timer expires, PySwarm launches the BOID on its current heading, using the Initial Speed value and setting the pitch to the Takeoff Angle. If the Takeoff Angle is set to 0 (zero), then the BOID’s Z value will not change and the next keyframe will force the BOID into Landed mode again. This might be a nice feature in some situations (like frogs hopping?), but not in most situations.

  • Be sure to give the Takeoff Angle a value greater than zero.