crowdmaster documentationcrowdmaster.org/docs/crowdmaster.pdf · crowdmaster documentation, release...

CrowdMaster DocumentationRelease

John Roper, Peter Noble

Aug 23, 2017

CONTENTS

i

CrowdMaster Documentation, Release

Welcome to the CrowdMaster Manual!

CrowdMaster is a crowd simulation addon for Blender 3D.

It’s key features include:

• Node-based interface

• Customizable agent generation

• Powerful animation tools

You can download a PDF version of this manual here.

CONTENTS 1

https://www.blender.org

http://crowdmaster.org/docs/CrowdMaster.pdf


2 CONTENTS

CHAPTER

ONE

GETTING STARTED

This section will help you to get up and running with CrowdMaster. As you follow this manual, we assume that you

• Have experience using Blender and can navigate the interface

• Can create and modify simple geometry

• Can manage files and folders on your computer

Note: While reading the manual, if you have any Blender-related issues, please take a look at its manual.

1.1 Preferences

The preferences are split up into three sections, General Settings, Addon Update Settings, and Debug Options.

1.1.1 General Settings

This section holds the general settings for the addon.

Use Custom Icons

CrowdMaster comes with a custom icon set. This option allows you to choose if you want to use it or use Blender’sbuilt-in icons.

Start Animation Automatically

When this is enabled, running the simulation starts the animation playing. Also, stopping the simulation stops theanimation. When the option is disabled, the user has to manually start and stop the animation after hitting the start andstop simulation buttons respectively.

3

https://docs.blender.org/manual/en/dev/


Fig. 1.1: The main simulation tab with Use Custom Icons turned on.

Fig. 1.2: The main simulation tab with Use Custom Icons turned off.

Ask To Save

When this is enabled, if the file that you are working in has not been saved, CrowdMaster will give you a This filemust be saved! message when you press the Simulate button.

Use Node Color

If this is enabled, while you are simulating, the nodes will change color to display their output value.

Show Debug Options

This enables a number of debugging features and the simulator and addon updater are set into verbose mode.

1.1.2 Addon Update Settings

This section holds the settings for the addon updater. These are talked about in detail in Updating.

4 Chapter 1. Getting Started


1.1.3 Debug Options

These settings are only for developers. If you do not have Show Debug Options turned on, you will see anwarning message and the option to turn Show Debug Options on.

If you enable Show Debug Options, a few tools will become available to you.

Run Short Tests

This tool tests certain parts of the code to quickly check for errors.

1.2 Updating

This section holds the settings for the addon updater. This module allows the user to install updates for CrowdMasterwithout leaving Blender.

Note: After installing a new version, you will have to restart Blender for the changes to take effect.

1.2. Updating 5


1.2.1 Auto-check for Update

When enabled, CrowdMaster will look for an update based on the interval of time since last update that you have set.

1.2.2 Check now for CrowdMaster update

Pressing the big button will cause the updater to check immediately to see if there is an update available. If so, it willdownload and install.

1.2.3 Install latest develop / old version

If you find a bug or you want to see the difference between two or more versions, you can use this option to install anearlier version of CrowdMaster.

1.2.4 Restore addon backup

Each time that the updater installs a new version, it backups the version that was previously installed. If you want, youcan use this option to reinstall from that backup.

6 Chapter 1. Getting Started

CHAPTER

TWO

AGENT GENERATION

The generation system provides procedural way to quickly generate many agents at once. Once generated, the agentsare automatically connected to the animation system for simulation.

2.1 Nodes

The agent generation system is made up of a number of nodes. This serves as a reference for each node in the system.

2.1.1 Geometry Nodes

The geometry nodes are responsible for working with geometry and their modifiers such as armatures.

Constrain Bone

Fig. 2.1: The Constrain Bone node

Apply a constraint to the main bone in the Child Object (currently only able to set the main bone using the LinkArmature node) to the main object in Parent Group.

Useful for attaching armatures to objects that are used as a bounding box.

7


Fig. 2.2: The Group node

Group

Selects a group of 3D objects from the scene to use in the node tree.

Link Armature

Fig. 2.3: The Link Armature node

Used for loading an armature from a different blend. Multiple armatures cannot be created from the same blend so thefile is duplicated into the folder specified in the main tool bar.

Group File

The path to the blend.

8 Chapter 2. Agent Generation


Group Name

The name of the group to link from the file.

Rig Object

The name of the rig object in the group.

Additional Group

A comma separated list of groups to be imported at the same time.

Constrain Bone

The main bone in the armature rig (the bone that gets location and rotation applied to it).

Modify Bone

Fig. 2.4: The Modify Bone node

Bone Name

The name of a bone in the main rig of an agent which will be modified by the value of a tag.

2.1. Nodes 9


Attribute

The attribute that will be attached to the value of a tag at each frame.

Tag name

The name of the tag to get the value from.

Object

Fig. 2.5: The Object node

Selects a 3D object from the scene to use in the node tree.

Parent

Used to parent props such as hats and weapons onto agents.

Parent Mode

Bone

The inputted child object is parented to the Parent group using the bone specified in the Bone Name field.

Armature

The inputted child object has an Armature modifier applied pointing to the Parent Group armature. If a modiferwith the name Armature exists on the object, the modifier’s settings will be overwritten.

Bind To

Vertex Groups

Activate Use Vertex Groups on the armature modifier.



Fig. 2.6: The Parent node in Bone mode

Fig. 2.7: The Parent node in Armature mode

2.1. Nodes 11


Bone Envelopes

Activate Use Bone Envelopes on the armature modifier.

Geo Switch

Fig. 2.8: The Geo Switch node

Switches between the two inputted objects based on the Amount value.

2.1.2 Template Nodes

The template nodes manage the data about each agent.

Template

The main node in the generation tree. This holds all of the geometry for a single agent.

Brain Type

The name of the brain type that the simulation will be setup in. This value must be exacly the same as one of the agentsimulation node trees.

Defer Geometry

Copies only the armature of an agent or an empty if the agent does not have an armature. Because of this, simulationis extremely fast. Later on, you can use the Place Deferred Geometry utility to add the mesh(es) back onto each agent.



Fig. 2.9: The Template node

Add To Group

Adds the generated agents to a Blender group. Add the name you want into the Group name field, and all the agentsplugged into that will be added into a group of that name, prefixed with cm_.

For example, if you set the group name to be soldiers, the outputted group will be cm_soldiers.

Combine

Combines multiple templates into one.

Point Towards

Aligns each agent so that they are all facing a specified object or vertex of a mesh.

Random

Randomizes the rotation (on the z axis) and uniform scale of each agent that is generated.

Min/Max Random Rotation

Chooses a random rotation for each agent starting at the Min Rand Rotation value and ending at the Max RandRotation value.

Min/Max Random Scale

Chooses a random scale for each agent starting at the Min Rand Scale value and ending at the Max RandScale value.

2.1. Nodes 13


Fig. 2.10: The Add To Group node

Fig. 2.11: The Combine node



Fig. 2.12: The Combine node with multiple inputs

Fig. 2.13: The Point Towards node

2.1. Nodes 15


Fig. 2.14: The Random node

Random Material

Target material

If the specified material appears on any object that is part of an agent then it will be replaced. This material must haveits link mode set to Object.

Material list

Name

The material to replace with.

Weight

Weight the probability of selecting this material.

Set Tag

Will set an initial tag (before the first frame of simulation) with this name and value for all agents generated down-stream of this node.

Template Switch

Switches between the two inputted templates based on the Amount value.

2.1.3 Positioning Nodes

The positioning nodes control how the agents are laid out in the scene when generated.



Fig. 2.15: The Random Material node

2.1. Nodes 17


Fig. 2.16: The Set Tag node

Fig. 2.17: The Template Switch node



Formation

Fig. 2.18: The Formation node

Positions the agents in a formation.

Number of Agents

This is the number of agents to be generated from this node.

Rows

The number of rows that the agents will be aligned in.

Row Margin

The amount of space between each row.

Column Margin

The amount of space between each column.

Ground

This aligns the height of each generated agent so that it is placed on the surface of the Ground object.

Mesh

Scatters agents over the faces of a mesh.

2.1. Nodes 19


Fig. 2.19: The Ground node



Fig. 2.20: The Mesh node

2.1. Nodes 21


Guide mesh

The mesh that agents will be placed on.

Number of Agents

The number of agents to place over the mesh.

Overwrite position

Overwrite rather than add to template position.

Relax

Prevent agents being placed too close together.

Relax Iterations

Iterations to use when relaxing. More iterations will probably produce a better result but will take longer.

Relax Radius

Radius to push other agent away to.

Obstacle

Fig. 2.21: The Obstacle node

Uses the objects in the inputted group as obstacles for the generator. Agents will not be placed where there is anobstacle object.



Obstacles

The group in which each of the obstacle objects is held.

Margin

The margin around each obstacle object. This effectively scales up each object used as an obstacle.

Note: Currently, only the bounding boxes of each object are used. This results in less-realistic generation when usingobjects such as spheres and cylinders.

Offset

Fig. 2.22: The Offset node

Offsets each generated agent based on the values entered.

Overwrite

If checked, this overwrites the location of each agent instead of just moving it.

Location Object

If filled, the location and rotation of this object will be used as the offset.

Location Offset

This is the amount that each agent will be offset from it’s original location.

2.1. Nodes 23


Rotation Offset

This is the amount that each agent will be offset from it’s original rotation.

Path

Fig. 2.23: The Path node

Generates agents along a defined path.

Path name

The path that agents will be placed on. Defined in the paths panel.



Number of Agents

The number of agents to place over the length of the path.

Relax


Relax Iterations


Relax Radius


Group By Mesh Islands

This adds agents to different groups depending on which part of the path they are placed on. A path mesh island is asection of the path mesh that isn’t connected by any vertices to another mesh island. Checking this option won’t makeany difference to where agents are placed.

The following example uses this simple node tree and path:

Without Group By Mesh Islands selected, all agents are added to the same group.

With Group By Mesh Islands selected, agents on the path indicated in red are added to one group and agents on thepath indicated in blue are added to a different group.

Random

Positions the agents randomly around the scene.

Number of Agents

This is the number of agents to be generated from this node.

2.1. Nodes 25


2.1. Nodes 27


Fig. 2.24: The Random node



Location Type

This is the type of max boundary that the node uses.

Radius

This uses a max radius as the boundary for the generated agents.

Area

Max X

The maximum distance from zero that agnets can be generated in the X direction.

Max Y

The maximum distance from zero that agnets can be generated in the Y direction.

Sector

Creates agents in an area shaped like a slice of pie.

2.1. Nodes 29


Radius

The radius of the circle to take the slice from.

Direction

The angle at the middle of the section.

Angle

The internal angle of the sector.

Relax

Relax the locations of each agent to avoid overlap.

Iterations

Number of relax iterations to use.

Radius

Maximum radius for relax interactions.

Target

Positions one agent on each object in the inputted group.

Positions one agent on each vertex in the inputted object.

Vertex Colors

Paint Mode

Place

Scatters agents over an area of a mesh with vertex colors.

Guide Mesh

The mesh that agents will be placed on.

Note: The more high-poly the guide mesh is, the slower it will take to place agents. However, if the guide mesh islow-poly, the results will be less accurate.

2.1. Nodes 31


Fig. 2.25: The Target node

Fig. 2.26: The target node in vertex mode



Fig. 2.27: The Vertex Colors node in placement mode

2.1. Nodes 33


Invert

Invert the effect of the node. For example, if the chosen color is black, all agents will positioned everywhere that thereis not black.

VCols ID

The ID of the vertex colors slot on the mesh that you would like to use.

Color

The color that the agents should be placed over.

Number of Agents

The number of agents to place over the mesh.

Overwrite position

Overwrite rather than add to template position.

Relax


Relax Iterations


Relax Radius


Edit

Removes any agents that are not on the painted area.

Guide Mesh

The mesh that the vertex color data will be pulled from.

Note: The more high-poly the guide mesh is, the slower it will take to place agents. However, if the guide mesh islow-poly, the results will be less accurate.



Fig. 2.28: The Vertex Colors node in edit mode

Invert

Invert the effect of the node. For example, if the chosen color is black, all the agents that are not on black will stay.

VCols ID

The ID of the vertex colors slot on the mesh that you would like to use.

Color

The color that the agents should be placed over.

2.1.4 Output Nodes

The output nodes are responsible for starting the generation of the agents and reporting about it.

Generate

Always the last node in the tree. To generate the agents, plug everything in, and hit Generate Agents.

2.1.5 Layout Nodes

The layout nodes don’t have an effect on the execution of the node tree, but they help to keep the tree organized.

2.1. Nodes 35


Fig. 2.29: The Generate node

Frame

Fig. 2.30: The Frame node

Just like a regular frame node in all the other node tree types.

Note

Can display any piece of text.

Note Text

Text that you want to put into the node.



Fig. 2.31: The Note node

Grab Text From Clipboard

If you have text in the clipboard, you can add it into the node using this instead of adding it manually.

Clear Text

Clears all text that is in the node. If the text does not dissapear when you click it, just move the node a little and it willupdate.

Reroute

Fig. 2.32: The Reroute node

Just like a regular reroute node in all other node tree types.

2.2 Utilities

Agent Generation has one utility to make your work easier.

2.2. Utilities 37


2.2.1 Place Deferred Geometry

Used alongside the Template node, Place Deferred Geometry places the meshes for each agent after they have beengenerated (and possibly simulated) with the Defer Geometry setting turned on.

2.3 Workflow

The agent generation system allows for a very modular workflow, however there are some considerations that youshould keep in mind.

2.3.1 Overview

The standard workflow for agent generation is:

1. Objects (Geometry)

2. Templates (Agent Info)

3. Positioning (Layout)

4. Generate (Output)

The nodes in the system are arranged so as to make this order apparent. In the add menu for the node tree, the groupsof nodes are arranged in the order of which they should be used.

2.3.2 Structure

Objects (Geometry)

This is the actual geometry that will be duplicated and modified to create the pack of agents. These objects can besingle or they can be grouped together.

Included in this group are modifiers that (among other things) allow you to randomize which objects are selected forgeneration.



Templates (Agent Info)

The template tools are used to connect the agents generated to the animation/simulation system. Most important is theTemplate node. This node does most of the dirty work and at least one is required in every tree.

Additionaly, the Template node takes the objects inputted and joined them into a virtual group that can be scaled,rotated, etc.

Positioning (Layout)

The positioning nodes are quite self-explanatory. These nodes are responsibe for duplicating the template(s) inputtedand arranging them in the scene.

Half of the nodes place the templates and the other half (such as Obstacle and Ground) modify those placements.Make sure that the modifier nodes always come before the placement nodes.

Generate (Output)

The last node in the agent generation tree is always the Generate node. There should only be one Generate node in thetree.

2.3.3 Common Mistakes

• One or more of the positioning modification nodes are placed after one or more of the positioning placementnodes

This causes the modification nodes to not have any effect at all.

2.3.4 Example Node Trees

Simplest Possible Setup

This node tree has the bare minimum number of nodes needed for agent generation.

Random Geometry Input

This node tree takes multiple pieces of geometry and randomly decides which one to use for each agent in the template.

2.3. Workflow 39


Random Template Input

This node tree takes multiple templates and randomly decides which one to use for each position in the generation.This is different from the example above because it randomly choosed which virtual group of agents with its own nodetree to use, not which geometry.

Formation Of Formations

This node tree demonstrates the power of the node-based system. It allows you to generate duplicates and groupsof already generated agents. This example shows how a group of agents arranged in a formation can be arranged inanother formation.



2.3. Workflow 41

CHAPTER

THREE

AGENT SIMULATION

The agent simulation system makes up the bulk of the CrowdMaster addon. This allows for the animation of manyagents at once with their own procedural brain.

3.1 Toolbars

The CrowdMaster toolbars hold the controls for the overall simulation. You can access the toolbars in the Node EditorTool Shelf (T)

3.1.1 Main

Start Simulation

Start the CrowdMaster simulation. If Start Animation Automatically is on, the animation will start to play. Otherwise,you will have to start it manually.

Stop Simulation

Stop the running CrowdMaster simulation. If Start Animation Automatically is on, the animation will stop playing.Otherwise, you will have to stop it manually.

Simulation Start Frame

The frame that you would like the simulation to start on.

43


Simulation End Frame

The frame that you would like the simulation to end on.

Note: The Simulation Start and End frames do not need to be the same as the scene’s start and end frames.

Utilities

Utilities

Place Deferred Geometry

Used alongside the Template node, this places the meshes for each agent after they have been generated (and possiblysimulated) with the Defer Geometry setting turned on.

Switch Dupli Groups

Used for quickly switching out dupli groups for all selected objects.

Dupli Group Suffix

Match dupli groups that have this suffix.

Dupli Group Target

Select the dupli group to replace with.

For example, replace “group_proxy” with “group_high” by settings suffix to “_proxy” and target to “_high”.

44 Chapter 3. Agent Simulation


3.1.2 Agents

The agents panel holds the information about each agent group in the scene.

Note: You can select multiple agent groups at the same time by shift+clicking on each one.

Header Info

Group Name

The name of each agent group.

Number

The total number of agents in the group.

Origin

Tells how the agents in the group were generated.

Auto

Shows that the agents have been created using the agent generation nodes.

Manual

Shows that the agents have been created manually by the user.

Status

Shows if the agent group has been Frozen for editing.

3.1. Toolbars 45


View Group Details

Freeze Placement

Stops these agents from being re-generated.

Note: Manually created groups won’t have this option since they will never be deleted by regenerating.

Freeze Animation

When checked this group won’t have it’s animation changed when the simulation is started. Useful for adding animatedobjects to the scene that need to interact with the simulation or to freeze a group of agent that you are happy with.

Note: The brain will still be evalued for each of these agents so freezing groups will have little impact on simulationtime.

Reset Group

Deletes this group and all of it’s agents.

3.1.3 Manual Agents

Any selected objects will be added as agents to the named group. If the agent group does not exist then it will becreated. However, if the group already exists but is an auto group (created with nodes) or is frozen then the



selected won’t be added.

3.1.4 Actions

The actions panel holds and manages all of the animation actions to be used for each agent.

Actions

Name

The name of the action.

Armature Action

An action that is completed on the spot (eg. stadium agent sitting and cheering) or an action where the movement isbeing controlled with an output node (eg. walking forward at a constant user defined rate).

Motion Action

Should only include location and rotation. Used for selecting an action for the overall movement of the agents.

3.1. Toolbars 47


Groups

Groups are used in the action pairs section and the action node. When used in action pairs it behaves if each actionhad been added manually. When used in the action node one action from the group will be selected. An action can beassigned to multiple groups by entering the group names in the Group field separated by commas.

Action Pairs

Actions pairs are used by the sync manager to synchronize the play back of animations between agents. eg. Attackand defend move or shaking hands.

Source

Actions that can trigger a paired animation.

Target

The action(s) that are valid pairs for the actions defined in the Source field.

3.1.5 Events

Events are actions that take place during the simulation. To add an event, click the plus button.

The same name can be used for several event entries. When determining if an event is currently active for an agent thelist will be worked down until an entry meets the current conditions (the event is active) or until the end of the list (theevent is inactive).

For example, in the following case (where the selected object is the agent testing for event “ev”) the three event entriesare testing for volumes defined by the three cubes respectively. The event entry outlined in red is tested but found tobe inactive. The event entry outlined in green is tested and found to be active. This means an Input > Event node with



3.1. Toolbars 49


value “ev” will will output {“None”: 1} (as opposed to {“None”: 0} if the event is inactive). The event entry outlinedin black isn’t tested since we already know the event is active.

Categories

Time

This event will be triggered if the current frame is within the range chosen.

Start

The start frame for the event time range.

End

The end frame for the event time range.

Volume

This event will be triggered if an agent enters the volume of the chosen object.



When set to Volume or Time+Volume an event will only be active when the current agent is inside the bounding boxof the specified object.

Warning: The center of the bounding box must be at the origin of the object. However, the object can be rotated,translated or scaled in anyway. The suggested way of creating an event volume is to create a cube and move, rotateand/or scale without entering edit mode.

Time + Volume

This event will be triggered if both the time and volume factors are true. The options are the combined of the twoabove.

3.1.6 Paths

Paths are routes that agents can follow. Paths can be used to tell the agents specifically where to go.

Name

The name of the path, used to access that specific path in the node tree or other toolbars.

Object

The mesh that defines the path. Path objects must be meshes that only have edges (no faces).

Radius

The maximum distance away from the path that agents should go.

3.1. Toolbars 51


Mode

Bidirectional

Agents can move in two directions at once on the path.

Road

Roads behave like bidirectional paths but agents are offset by the value specified in lane separation. The result of thisis agents going in different directions are offset to different sides of the “road”.

Lane Separation

Defines how far apart the road lanes are.

Directional

Agents can only move in one direction at a time on the path.

Draw Directions

Show a visual indicator of the direction of the selected path in the 3D view.

Options and Utilities

All path utilities require require a path to be selected (by hitting the button on the right of each path entry) and for theassociated mesh to be in edit mode.

Breadth First Search To Direct Edges

Breadth first search is performed from selected vertices. Path edge directions are set in the order that the edges arevisited.

Depth First Search To Direct Edges

Depth first search is performed from selected vertices. Path edge directions are set in the order that the edges arevisited.

Switch The Direction Of The Selected Edges

Switch the direction of the currently selected edges to the opposite direction.



Switch The Direction Of The Connected Edges

Flip the direction of every edge that is connected to a selected vertex (an edge is considered connected if there is anyway to reach it from a selected vertex by traversing vertices that have edges directly connecting them).

3.2 Nodes

The agent simulation system is made up of a number of nodes. This serves as a reference for each node in the system.

3.2.1 Input Nodes

The input nodes are responsible for providing data about all aspects of the simulation.

Input

The input node provides data about each agent in the simulation to the node tree. The data is supplied in multiplechannels.

Agent Info

Fig. 3.1: The Input node in Agent Info mode

Agent Info Options

Get tag

Allows an agent to retrieve the value of another agents tag.

3.2. Nodes 53


Any agent name that is included in the input will have their tag looked up. If any agent in the input doesn’t have a tagwith a matching name then it won’t be included in the output.

Get Tag Name

The name of the tag to look up.

Heading rx

Get the x component of the relative heading of any agent passed to the input.

Heading rz

Get the z component of the relative heading of any agent passed to the input.

In the above example the output of the Input heading node is as follows (assuming both agents A and B are in range ofthe sound):

Input heading output: {"A": 0, "B": -0.5}



Constant

Fig. 3.2: The Input node in Constant mode

Constant

Allows you to enter a constant float value.

Flock

Flocking Input

Separate

The direction the agent needs to move to move away from other nearby agent.

Translation Axis

The components of the vector that the agent needs to move in.

tx

Translate on the x axis.

3.2. Nodes 55


Fig. 3.3: The Input node in Flock mode with Separate

ty

Translate on the y axis.

tz

Translate on the z axis.

Align

The rotation about the X and Z axes needed to align to the average heading of nearby agents.

Rotation Axis

Each axis that the agent needs to rotate on.

rx

Rotate on the x axis.

rz

Rotate on the z axis.



Fig. 3.4: The Input node in Flock mode with Align

Cohere

The direction the agent needs to move to move towards the average position of neighbours. This is the inverse ofseparate mode.

Translation Axis

The components of the vector that the agent needs to move in.

tx

Translate on the x axis.

ty

Translate on the y axis.

tz

Translate on the z axis.

Note: The keys passed to an input node set to flock will be used as input. For example, by plugging an input node insound mode into an input node set to flock mode, the neighbourhood for each agent will be all agents within a specificrange of the sound.

3.2. Nodes 57


Fig. 3.5: The Input node in Flock mode with Cohere

Formation

The formation channel is used to arrange agents to points on a mesh. Formations, like sounds, operate on namedfrequencies. The mesh that defines the layout of the formation must have a tag in the format FormationNAMEwhere NAME is replaced with the frequency. When an agent first requests a position in a formation (simply be usingthat formation frequency) it will not recieve a position but that agent will be assigned a position in the formation forthe following frame (and all frames after if it continues to use the formation).

Formation Group

The group in which the objects that you will use to align the agents is held.

Formation Options

dist

Returns the distance to the current position in the formation that this agent has been assigned to.

rz

Returns the change in rotation about the Z axis needed to face the position in the formation assigned to this agent.

rx

Returns the change in rotation about the X axis needed to face the position in the formation assigned to this agent.



Fig. 3.6: The Input node in Formation mode

Ground

Fig. 3.7: The Input node in Ground mode

The ground channel is used to allow agents to follow terrain. Unlike sound or formation channels, the ground channeldoesn’t use frequencies. To register an object as a ground object simply add a tag called “Ground” with any value.

Warning: The ground channel returns None if the ground is above the agent.

Ground Group

This is the group in which the objects that you will use for align to ground simulations are held.

3.2. Nodes 59


Ground Options

dh

Returns the height difference between the agents position and the nearest piece of ground in the vertical direction.

ahead rz

A value in the range -1 -> 1 representing the rotation about the agents z axis to point towards the ground directly underthe agents position offset by the given vector (Ground Ahead Offset).

Useful for constraining agents to an arbitrary mesh by sampling ahead and/or to the sides and checking if that positionis off the edge of the ground mesh.

ahead rx

A value in the range -1 -> 1 representing the rotation about the agents x axis to point towards the ground directly underthe agents position offset by the given vector (Ground Ahead Offset).

Noise

Noise Options

Random

Returns a random number from 0.0 to 1.0.

Agent Random

Returns a random number that is consistent between frames but can be offset by an integer.



Fig. 3.8: The Input node in Noise mode

Wave

Returns a sine wave varying with time.

https://www.desmos.com/calculator/gwpmwylgg0

Wavelength

The wavelength of the sine wave in frames.

3.2. Nodes 61

https://www.desmos.com/calculator/gwpmwylgg0


Offset

Offset the wave by some fraction of a wavelength. A value of 1 offsets the wave phase by 360 degrees (equivalent tono offset).

Fig. 3.9: Wavelength: 5, Offset: 0

Fig. 3.10: Wavelength: 5, Offset: 0.25 (Cosine wave)

Path

Paths are used to guide agents along user defined routes. A path is simply an object with a number of vertices connectedby edges. Paths can be registered in the path panel.

Path Name

The path that is used for follow path simulations.

Path Options

Allows you to set which axis the agents will be aligned on the path.



Fig. 3.11: Wavelength: 5, Offset: 0.5

Fig. 3.12: Wavelength: 2.5, Offset: 0

Fig. 3.13: The Input node in Path mode

3.2. Nodes 63


rx

Returns the rotations from the agents heading to the target to aim for in order to remain on the path called pathNamein the Z axis. In range -1 to 1 where -1 is all the way behind to the left and 1 is all the way behind to the right.

rz

Returns the rotations from the agents heading to the target to aim for in order to remain on the path called pathNamein the X axis. In range -1 to 1 where -1 is all the way behind below and 1 is all the way behind above.

In lane

Search Distance

For every input to this node, test whether the associated agent is within Search Distance of this agent along the path.Useful for excluding agents that are very close but on a different section of road. For example:

Input: {"B": 1, "C": 1}

Search Distance: 10

The distance along the path to B from A is less than 10 but the distance to C is greater than 10 so the output is:

Output: {"B": 1}



3.2. Nodes 65


Sound

Fig. 3.14: The Input node in Sound mode

This is one of the most useful channels and is usually an agents main source of input. Agents can emit a “sound” thathas a frequency and radius and then any other agent that is “listening” on that frequency will be able to “hear” it iswithin the radius. The sound channel also offers methods to try and predict where other agents will be in the futureand what action should be taken to avoid colliding with them.

Frequency

The frequency that the agent(s) will be transmitting to the other agents.

Sound Mode

Allows you to choose how outputs are calculated.

Basic

Will calculate the values based on the current positions of objects in the scene. The advantages of this are that it issimple to understand, the internal workings use an acceleration data structure to speed up lookups and for most casesthe results are good. The disadvantages are that sometimes agents will steer to avoid each other when actually theywere never in danger of hitting each other. This can lead to a very unnatural curling behavior.



Prediction

Moves all agents along their current path at their current velocity until the current agent reaches the point where thelines representing their direction of motion are closest. The values returned (rz, rx, dist, close etc. . . ) are calculatedwith the agents in these new positions. By doing this the agents seem to gain a sense of where other agents are goingand so can plot a smoother path to navigate through the crowd. The disadvantages of these mode are that it doesn’t(currently) use an acceleration struction to speed up lookups so the time taken will grow quadratically with the numberof agents increasing. This mode can also be harder to understand and can lead to more complex brain graphs. Anotherproblem is that it doesn’t take into account the size of the agent which can lead to issues (for example, if two agentsare approaching each other along parallel paths but the distance between the paths is less than the sum of their radiithen prediction won’t show a collision when there actually is one).

Steering

Uses the radius of each agent to determine when and where collisions will occur. It also takes into account the relativevelocities of agents to calculate a steering vector which is then broken down into components that are retrieved usingrx, rz and acc. This method doesn’t guarantee a collision free simulation but is considerably better than the other twofor dense crowds with varying sizes of agents. The major disadvantages are that it doesn’t (currently) have acceleratedlookup and it needs more inputs to the graph to be useful so leads to bigger graphs than the basic mode.

Options

rx

Returns the rotations from the agents heading to the source of the sound about the X axis. In range -1 to 1 where -1 isall the way behind below and 1 is all the way behind above.

rz

Returns the rotations from the agents heading to the source of the sound about the Z axis. In range -1 to 1 where -1 isall the way behind to the left and 1 is all the way behind to the right.

dist

Returns the distances to the objects. In range 0-1 where 0 indicates the emitter is at the same position as the agent and1 indicates the distance between them is equal to the range of the sound.

close

Returns 1-value for all the values returned by dist.

db

Returns value:sup:2 for all the values returned by close. An easy way to make reactions look more natural whenbashing together a quick agent without using many GRAPH nodes.

3.2. Nodes 67


cert

Used by prediction and steering modes. The certainty will decrease from 1 as the change of a collision decreases. Thechange may decrease due to the collision being a long time in the future or because the agents are very small.

acc

Only used by the steering mode. This is the acceleration recommended to avoid a collision. This value works alongsidethe rotation values (rx and rz) but most collisions can be avoided just using acceleration or rotation.

over

Only used by the steering mode.

Minus Radius

Take agent radius into account when calculating dist. dist is scaled such that it’s 0 when only just in range and 1when the distance between agents <= agent A radius + agent B radius. close and db are also appropriately scaled.

Warning: Minus Radius currently doesn’t change the behaviour of rx or rz but their behaviour will be affectedin a later release.

State

Fig. 3.15: The Input node in State mode

Used by an agent to retrieve information about itself.



State Options

Radius

Returns the radius of the agent. (The length of the vector containing the x, y and z dimensions).

Speed

Returns the speed (in Blender units) of the agent for the last frame.

Global Vel X

The X component of this agents global velocity.

Global Vel Y

The Y component of this agents global velocity.

Global Vel Z

The Z component of this agents global velocity.

Query tag

3.2. Nodes 69


Tag name

The name of the tag to query. If there is a tag with a matching name then the output will be:

Output: {"None": value of tag}

If there is no matching tag then the output will be:

Output: {}

For details on setting tags see Set Tag

World

Used to get information about the global state of the simulation.

World Options

Time

Fig. 3.16: The Input node in World mode with Time

The time since the beginning of the simulation in frames. The world channel includes global target seeking. This actsin a similar way to the sound channel except that there is a single emitter and the range is infinite.

Target

Used for pointing agents towards a specific location in a scene.



Fig. 3.17: The Input node in World mode with Target

Target Object

The object in the scene to seek.

Target Options

rx

Returns the change in rotation about the Z axis needed to face the target. Range -1 to 1.

rz

Returns the change in rotation about the X axis needed to face the target. Range -1 to 1.

Arrived

Return 1 if the distance between the agent and the target is less than the sum of their radii otherwise return 0.

Event

3.2. Nodes 71


Fig. 3.18: The Input node in World mode with Event

Event Name

The name of the event to query. See Events for more details.

Event Options

• Control - Returns True if the event has been triggered and False if it has not been.

• Elapsed - If the event has been triggered, this returns the number of frames remaining in the event.

• Duration - Returns the length of the event (in frames).

3.2.2 Output Nodes

The output nodes are responsible for exporting data from the node tree during simulation.

Note: Keyframes are always created for the location and rotation of each agent whether or not an output node existsin the node tree.

Output

Sets outputs for the agent(s).



Fig. 3.19: The Output node

Output

Position X

The change in position in the x axis (left side and right side).

Position Y

The change in position in the y axis (forwards and backwards).

Position Z

The change in position in the z axis (up and down).

Rotation X

The change in rotation about the x axis (tilt).

Rotation Y

The change in rotation about the y axis (roll).

Rotation Z

The change in rotation about the z axis (pan).

3.2. Nodes 73


Shape Key

The change of the value of a chosen shape key

Shape Key Name

The name of the shape key whose value you would like to affect.

Note: Shape keys do NOT change the calculated radius of each agent.

Multi Input Type

Average

Takes the average value from all the inputs from connected nodes.

Max

Takes the maximum value from all the inputs from connected nodes.

Size Average

Takes a weighed average weighted by the magnitude of the values from all the inputs from connected nodes. Usefulfor when you want it to act like average but very small values to be ignored because there are a variable number ofinput values.



Sum

Sums up all the values in all the inputs from connected nodes.

Print

Fig. 3.20: The Print node

Prints the contents of the inputs prefixed by the label.

Save To File

Save to a file rather than printing to the console.

3.2.3 Basic Nodes

The basic nodes are responsible for manipulating data.

Graph

RBF

Passes each input value through an RBF function.

Multiply

Multiplies the output of the node by this value.

3.2. Nodes 75


Fig. 3.21: The Graph node in RBF mode



Fig. 3.22: An example RBF function

Invert

Inverts the output of the node.

RBFMiddle

The x coordinate of the peak.

RBFTenPP

The ten percent point. The radius from the peak that the output is 0.1.

Range

Passes each input value through a range function.

Multiply

Multiplies the output of the node by this value.

Invert

Inverts the output of the node.

3.2. Nodes 77


Fig. 3.23: The Graph node in range mode



Fig. 3.24: An example range function

3.2. Nodes 79


Lower Zero

The x value where the output starts rising from 0.

Lower One

The x value where the output is first 1.

Upper One

The last x value where there output is 1.

Upper Zero

The x value where the output returns to 0.

Map

Fig. 3.25: The Map node



Maps one range to another. Doesn’t clamp values. For example:

Lower Input: 0

Upper Input: 2

Lower Output: 1

Upper Output: 4

Input: {"A": 0, "B": 1, "C": 2, "D": 4}

Output: {"A": 1, "B": 2.5, "C": 4, "D": 7}

Priority

Inputs come in pairs (values, priorities). To workout the output, the node works down the pairs and adds the contentsof the value multiplied by the priority and the proportion of output still left to set. For example:

Values0 is {"None": 10}

Priority0 is {"None": .2}

Values1 is {"None": -5}

Priority1 is {"None": .5}

defaultValue is 1

Result is: 10*0.2*1 + -5*.5*(1-0.2) + 1*(1-0.2-(1-0.2)*0.5) = 0.4

Useful for when you want some values to overwrite others without making them massive because you don’t want alarge change in the value. For example, if avoiding collisions as well as navigating to a target then collision avoidanceshould always take precedence over navigation.

3.2.4 Logic Nodes

The logic nodes are responsible for managing the logic in the simulation.

And

Combines input values in a similar way to boolean AND except using fuzzy logic. Two methods can be used for this.Firstly, take the product of the inputs and secondly take the min of input values. The first may produce more naturalresults but with larger networks the signal strength may degrade too much. For example, if inputs representing thefollowing things had the values:

agent in front (0.8) and agent close (0.8) and agent making noise(0.8).

The product of these results in 0.512 which is very weak compared to the original values. Using min would give 0.8.This effect is inflated when using even more inputs. However, min may give results that don’t look natural.

SingleOutput

Causes the output to be the product/minimum of all input values.

3.2. Nodes 81


Fig. 3.26: The Priority node

Fig. 3.27: The And node

3.2. Nodes 83


IncludeAll

Causes values to only be considered if that key is found in all input nodes. For example,

Inputs: {"a": 0.5, "b": 1} and {"a": 0.1}

Output with IncludeAll selected: {"a": 0.05}

Output with IncludeAll deselected: {"a": 0.05, "b": 1}

If both SingleOutput and IncludeAll are both selected then only keys that are found in all inputs are used to calculatethe final output.

Or

Fig. 3.28: The Or node

Acts in a very similar way to the AND node. The key differences are that Mul will do 1 -(1-val0)*(1-val1)*(1-val2)...(1-valN) rather than val0*val1*val2...*valN and OR uses themax function rather than the min function.

SingleOutput

Causes the output to be the product/minimum of all input values.

IncludeAll

Causes values to only be considered if that key is found in all input nodes. For example,



Inputs: {"a": 0.5, "b": 1} and {"a": 0.1}

Output with IncludeAll selected: {"a": 0.05}

Output with IncludeAll deselected: {"a": 0.05, "b": 1}

If both SingleOutput and IncludeAll are both selected then only keys that are found in all inputs are used to calculatethe final output.

Not

Fig. 3.29: The Not node

Flips the logic inputted. For example:

NOT 0 = 1

NOT 0.3 = 0.7

NOT 0.5 = 0.5

NOT 0.7 = 0.3

NOT 1 = 0

Input values outside the 0-1 range may not behave as expected. Formula NOT x = 1 - x used.

3.2.5 Strength Nodes

The strength nodes are responsible for giving and removing power from values in the simulation.

Strong

Works in the range 0-1. Decreases values less than 0.5 and increases values that are greater than 0.5. Uses the equationval^2 * (-2*val + 3).

3.2. Nodes 85


Fig. 3.30: The Strong node

The inverse of the WEAK node. This node is intended to be used with only one input. If more than one input isprovided then results will be merged but if there is any conflict of keys then an arbitrary result will be chosen with nowarning.

Weak

Fig. 3.31: The Weak node

Works in the range 0-1. Increases values less than 0.5 and decreases values that are greater than 0.5. Uses the equation2*val - (val^2 * (-2*val + 3))

The inverse of the STRONG node. This node is intended to be used with only one input. If more than one input isprovided then results will be merged but if there is any conflict of keys then an arbitrary result will be chosen with nowarning.

3.2.6 State Nodes

The state nodes are responsible for managing the Finite-State Machine.



State Socket

The output of a state is connected via a State Socket to another state that can be moved to next.

Dependancy Socket

Dependancy sockets are used to restrict which nodes are evaluated based on the current state.

A node will be evaluated if it has nothing connected to its Dependant socket or if any one of the states connected tothe Dependant socket is the current state.

For example:

When in the Start state, none of the input nodes have active states connected to their Dependant sockets so aren’tevaluated (as if they weren’t part of the brain for this frame). When in the “Move” Action state, the input node 1 andinput node 3 are evaluated and the Position Y output is 1 and Rotation Z is 0.05. After 10 frames when thestate moves to “Slow”, the first input node again becomes inactive and the second one becomes active. This makesthe Position Y output 0.1. Input node 3 is still evaluated even though Move is no longer the current state becauseSlow is now the current state and that is also connected to the Dependant socket of Input 3.

Start

This is the entry point to the agents Finite-State Machine. Each brain should only include one start node (if more thanone exist then one will be arbitrarily picked and the others ignored). If the state machine ever reaches a state wherethere is no valid next state then the current state will return to the start.

3.2. Nodes 87


Fig. 3.32: The Start node

Random Wait Time

The agent will pause on the start node for a random number of frames between the given minimum and maximum.

Action

Forms the backbone of the Finite-State Machine used by each agent. An agent can only be in one state at a time. Whenfinished in a state the next state will be picked from other state nodes connected to the To socket. The next action isselected by finding the connected state with the highest value.

State Length

The number of frames spent in this state if there is no action assigned to it.

Cycle State

Allows this node to transition to itself as the next state without connecting To to From.

Action Name

The name of an action or group that will be played when this state is entered. Group names start with [ and end with].

Overlap

When an action is specified in Action Name this option will move the new action clip back this many frames tooverlap the previous action. This can help the actions blend together more smoothly.



Fig. 3.33: The Action node

3.2. Nodes 89


Note: The length of the state will be reduced by this many frames so that the state finishes at the same time as theaction.

Interrupt State

Allow this state to be moved to before the previous one has finished. When selected it will allow this state to alsobecome a sync state.

Sync State

Uses a global sync manager to find pairings of actions. Only an option if the node is already an interrupt state.

Value

The score than this node will receive when evaluating which node to go to next.

Random

Do you want to allow this action to be randomly picked?

3.2.7 Other Nodes

The other nodes are responsible for operating on data being used in the simulation.

Filter

Will only allow key value pairs through if the value meets the given condition. An example use case might be asfollows. In a flocking simulation the separation force should only act away from very close agents. This could beachieved by having two sounds emitted from each agent. One for the cohere range and the other for the separate range.Alternatively you could have just one sound and then use the distance to the emitter to filter out any that are within thecohere range but outside the separate range.

This node is intended to be used with only one input. If more than one input is provided then results will be mergedbut if there is any conflict of keys then an arbitrary result will be chosen with no warning.

Operation

Equal

Only include values equal to the value or tag. For example:

Value: 1

Input: {"a": 1, "b": 0.5, "c": 1}

Output: {"a": 1, "c": 1}

3.2. Nodes 91


Fig. 3.34: The Filter node

Not equal

Only include values not equal to the value or tag. For example:

Value: 1

Input: {"a": 1, "b": 0.5, "c": 1}

Output: {"b": 0.5}

Less than

Only include values less than the value or tag. For example:

Value: 0.6

Input: {"a": 1, "b": 0.5, "c": 0.7}

Output: {"b": 0.5}

Greater than

Only include values greater than the value or tag. For example:

Value: 0.6

Input: {"a": 1, "b": 0.5, "c": 0.7}

Output: {"a": 1, "c": 0.7}



Least only

Only include the single smallest value. For example:

Value: 0.6

Input: {"a": -1, "b": 0.5, "c": 0.7}

Output: {"a": -1}

Most only

Only include the single largest value. For example:

Value: 0.6

Input: {"a": -1, "b": 0.5, "c": 0.7}

Output: {"c": 0.7}

Average

Calculate the average of all inputs. For example:

Input: {"a": -1, "b": 0.5, "c": 0.8}

Output: {"None": 0.1}

Tag

3.2. Nodes 93


If checked then retrieve the value of a tag rather than using the given value.

Tag Name

The name of the tag to retrieve.

Value

The value used for the above comparisons.

Math

Fig. 3.35: The Math node

Used to perform math operations to different values in your simulation.

Operation

Add

Add the first number to the input value.

Subtract

Subtract the first number from the input value



Multiply

Multiply the input value by the first number.

Divide

Divide the input value by the first number.

Set To

Set the input value to the value of the first number.

Set Tag

Fig. 3.36: The Set Tag node

Used to set the name and value of a tag. All tags are removed at the beginning of each new frame. If the name of a tagstarts with the name of a channel then the name and value of the tag as well as the agent that has the tag can be usedby the channel. For example, a tag with the name SoundA and value of 2 will indicate to the sound channel that thisagent emits a sound on frequency A with a radius of 2.

3.2. Nodes 95


Use Threshold

The tag will only be set if the input value to this node exceeds the Threshold value. If not checked, the tag will be setevery frame to the value passed to in via the Input.

Threshold

If the input value does exceed the this value, then the tag receives a value of 1. Otherwise, there will be no tag withthat name for that frame.

Action

Add

Create a tag.

Delete

Delete a tag set in a previous frame.

3.2.8 Layout Nodes

The layout nodes don’t have an effect on the execution of the node tree, but they help to keep the tree organized.

Frame

Fig. 3.37: The Frame node

Just like a regular frame node in all the other node tree types.



Note

Fig. 3.38: The Note node

Can display any piece of text.

Note Text

Text that you want to put into the node.

Grab Text From Clipboard

If you have text in the clipboard, you can add it into the node using this instead of adding it manually.

Clear Text

Clears all text that is in the node. If the text does not dissapear when you click it, just move the node a little and it willupdate.

Reroute

Fig. 3.39: The Reroute node

Just like a regular reroute node in all other node tree types.

3.2. Nodes 97


3.3 Workflow

The agent simulation system allows for a very modular workflow, however there are some considerations that youshould keep in mind.

3.3.1 Overview

3.3.2 Structure

3.3.3 Common Mistakes

My simulation isn’t running

Make sure that the name of your node tree is exactly the same as the agent group it is supposed to be controlling.

3.3.4 Example Node Trees

Simple Movement

This node tree moves the agents forward along the positive-y axis at a rate of 0.1.

Random Actions

This node tree chooses a random action out oif the ones supplied for each agent in the simulation.

3.4 Node Colors

If Use Node Color is turned on and you have selected an agent in the scene, the color of the nodes in the simulationnode tree will change. The color (hue) of each node represents its output value.

3.5 Pie Menu

The easy simulation pie menu can be accessed with the shortcut SHIFT + ALT + M.



3.5. Pie Menu 99

CHAPTER

FOUR

TROUBLESHOOTING AND GLOSSARY

The sections below try to answer common questions and solve common problems that users normally have. If you arenot able to solve your problem and/or you think you have found a bug, create an issue on the tracker and we will besure to take a look.

4.1 Frequently Asked Questions

4.1.1 How can I speed up my simulations?

Running a simulation takes a long time because Blender needs to both calculate the movement of each agent and thenmanipulate the actual geometry to make it happen. To get the best performance out of CrowdMaster, try to have asmany editors and toolbars closed so that Blender does not use up resources updating them. In addition, try turning offfeatures such as Use Node Color because although they make debugging your simulation much easier, they also havea small effect on speed.

4.2 Contribute to Development and Documentation

Of course the biggest thing we always need is development help. We maintain a list of quick projects that would beeasy for a new developer to help out with. You can always drop us an email at [email protected] if you haveany ideas you would like to develop. If you are not a developer, we can always use people to test and give feedbackabout CrowdMaster as we go along.

4.3 Glossary

Agent Each single character, object, or entity being controlled by the crowd simulator.

Finite-State Machine An execution structure made up of a number of events or states which are transitioned betweento form a simulation ‘brain’.

Note: This manual is based on the latest release build of CrowdMaster. If you do not see some of the features thatare shown, please update your version of the addon by going to the main CrowdMaster website or by using the addonupdater module.

101

https://github.com/johnroper100/CrowdMaster/issues

mailto:[email protected]

http://crowdmaster.org/

crowdmaster documentationcrowdmaster.org/docs/crowdmaster.pdf · crowdmaster documentation, release...

Documents