Agent group (AtomsUnreal)

To create an "Atoms Agent Group" actor in Unreal, from the modes panel, select the Place mode, then "All Classes" and drag and drop "Atoms Agent Group" into the viewport.

Agent group properties

The agent group contains several properties that you can use to customize the agents' simulation:

Agent simulation name: this identifies the simulation pool where the agents are simulated. Agent groups inside the same pool can communicate between them. The default value is "main" for all the actors created inside a level.
Enable simulation: enable or disable the agents' simulation. This can be changed at runtime.
Simulate only visible agents: if this property is checked only the agents inside the frustum are simulated.
Maximum simulation distance: if the "simulate only visible agents" is checked only the agents closer to this distance from the player are simulated.
Minimum screen height: if the "simulate only visible agents" is checked only the agents that have a screen height greater than this are simulated.
Check static bounding box: if this property is checked, the static bounding box of each agent type component is used to determine whether to simulate the agents.
Behaviours order: Stack order of the behaviour module computed by the group. Please use the "behaviour modules" widget to move a behaviour up or down the stack.
Parent agent group: You can set up a parent agent group actor that is computed before the current agent group.
View mode: agent display mode, please have a look to the "Draw mode" section above.
Variation: Set a variation table asset here to be able to use agent mesh variations.
Frame rate: Internal frame rate used by atoms.
Clamp frame rate: Clamp the tick time to 1.0 / FrameRate if the tick time is higher.
Use static frame: When checked the agent group use the "static frame" property value as input frame time instead of the global scene time. This property can be used inside a sequencer to simulate the agent group at a specific time and velocity.
Static frame: current frame time to simulate the agents when the "use static frame" property is checked.
Reset frame: frame used to reset the simulation of this agent group. Usually used inside the sequencer to reset an agent group at the start of the sequence.
Enable tick interval: when it is checked the actor is ticked using the "tick interval" property value as interval time.
Tick interval: tick interval time used to tick the actor when the "enable tick interval" property is checked.
Agent selection: list of group ids of the agents highlighted inside the editor viewport.
Enable neighbours query: Enable this option if you are going to use the AAtomsAgentGroup::GetAgentsInRange and AAtomsAgentGroup::GetAgentIdsInRange functions to request neghbours agents.
Enable internal KDTree Cache: if this property is checked the internal kdtree are built only at the beginning of the simulation. It’s useful if your agents are static.
Per instance metadata: This contains a list of all the agent metadata that the actor sends to the GPU to be used inside a material using the ParticleColor and DynamicProperty material nodes. The actor can send up to 20 floats per agent to the GPU. The metadata are interleaved so two vector 3 and one double metadata use 7 floats. The first 4 floats are sent to the ParticleColor.rgba output, while the other 16 floats are sent to the DynamicProperty.rgba output using an index from 0 to 3. Have a look at the tutorial sections for more information.
Update per instance metadata at every tick: when it's checked the metadata from the "per-instance metadata" list are sent to the GPU at each tick.
Agent metadata sets: this contains a list of metadata that is used to create agent sets. If you create an int/bool/double metadata on the agents called "foo" and put it in this list then during the simulation you can get a list of all the agents that have foo=1 using the AAtomsAgentGroup::GetAgentsInSet and AAtomsAgentGroup::GetNumAgentInSet functions.
Refresh agent group: reinitialize the agent group clearing all the memory and components and rebuilding all the agents' data and components. This should be used only in the editor.

Hero agents

Usually, all the agents are drawn using a single "Skeletal Instanced Component" using the instancing capability of your GPU. This component can handle many agents using few GPU resources and power. At the moment this component has some limitations. It's not visible by raytracing and doesn't support morph targets. If you want to use these unreal features you need a hero agent. A Hero agent is an agent that is using a single "Posable Bounded Mesh Component". This component inherits from the Skinning Mesh component so it can be used with raytracing or morph targets. Every hero agent uses its own posable component. So if you promote 10 agents to hero agents the agent group adds at least 10 posable mesh component. You can promote any agent you want to hero dynamically during the simulation and you can revert back to a normal agent any hero you want dynamically as well.

Agent Heroes: Promotes agents to hero using a posable bounded mesh component for each agent promoted to hero. Set here the groupId of the agents that you want to promote.
Promote All Agent To Hero: Promotes all agents to hero using a posable bounded mesh component for each agent.
Promote Agent Hero Metadata: Promotes an agent to hero when the metadata specified in this field is at 1 and remove the hero when is at 0. You can use a bool, int or double metadata.

Draw mode

An agent group has 3 different types of view modes: None, Skin and Variations (Default).

In order to see the variations, you need to assign a variation asset to your agent group first (variations can be assigned to your agents with the variation module).

"None" view mode is useful whenever you want to keep your agent group in your scene, but don't want to see the agents while playing or inside the editor.

Metadata

Users can debug metadata values for each agent when using the layout tool.

"Draw Metadata" should be enabled in case users want to see the Metadata values in the editor viewport.

Users can also define the look of the text in the viewport by changing font color, size and offset.

Finally, metadata to be displayed can be selected from the "Add Metadata" drop-down menu, press "Add Metadata" to add the metadata to the list.

When "Only On Selected Agents" is on the metadata will be displayed on selected agents only.

Frustum culling

Users can enable/disable the frustum culling and mesh lod. When it is enabled only the visible agents are sent to the GPU, this can increase the performance.

Enable editor Lod: Enable the agents the skeletal mesh LODs inside the editor.
Enable editor Culling: Enable the agents frustum culling inside the editor.
Enable frustum culling and LODS: Enable the frustum culling of the agents the skeletal mesh LODs during the gameplay.
Overwrite frustum culling FOV: Overwrite the field of view angle used by the frustum culling.
Agent max screen area: This overrides the screen area for each agent when the actor computes the lod level of each agent inside the editor viewport. This is ignored in gameplay.

Add a behaviour module

Select your Agent group actor from the "World Outliner". Then in the Details Panel, click on "Add Component" and scroll down until you find the "AtomsBehaviours" section.

The first module in the module stack must be a layout module ("gridLayout","pointsLayout","cacheReader",etc...). These modules create agents inside the agent group during the simulation. After a layout module you would usually add an animation module ("clipReader", "stateMachine", etc...) which creates the network of nodes to run animation clips inside the agent dg network. At this point, you can add other modules to drive the agents or set metadata.

After adding a module to the stack you can rename it to your liking.

Edit a behaviour module attributes

After selecting a module from the component list, you can edit its metadatas/properties as you would for any Unreal component.

Component attributes may be overridable per agent. For instance, if you look at the picture on the right you will see "Agent Type Override", "Direction Override", etc.
Just click on the "Add Override" button to add an override, each override has an integer value on its left representing the agent group Id. It is important that you set it to the right id if you want the override to work as expected. To find out the agent ID of an agent you can use the layout tool.

You can also delete overrides by pressing the down arrow next to each override and clicking "Delete".

Behaviours are evaluated in order, to control the order of your behaviours you can edit the "Behaviour Order" parameter in the "Atoms Behaviour" section.

Change behaviour order

Atoms calls the behaviour module in order from the first to the last on the behaviour list. Unfortunately you cant reorder the behaviours from the actor component list.

You can change the order of a module from the "Behaviour Modules" property of the agent group actor. Select the behaviour from the list and use the up/down button to move the behaviour.

Tutorial

To create an "Atoms Agent Group" actor in Unreal, from the modes panel, select the Place mode, then "All Classes" and drag and drop "Atoms Agent Group" into the viewport.

Select your Agent group actor from the "World Outliner". Then in the Details Panel, click on "Add Component" and scroll down until you fin the "AtomsBehaviours" section.

Click on the "Grid Layout Behaviour". In the "Behaviour" section, select the agent type asset you created previously in the "agentType" field.
Set the "size" field to (3,3,1).

Then do one of the followings:

Click again on the "Add Component" button and add a "State Machine Behaviour" module.
Click again on the "Add Component" button and add a "Clip Reader Behaviour" module. Type the animation clip asset name in the "clipName" field.

Hit the play button to run the simulation.