Agent type

Owned by Daniele Federico
Last updated: Apr 03, 2023 by Alan Stanzione
6 min read

An Agent type is a specialized Simulation event describing an agent definition. It contains a skeleton, proxy and skinned geos. It has a scale multiplier and can be linked to a State machine.
Atoms Crowd provides tools for exporting the necessary files to define your agent types.

A status icon is displayed in the item list: red means the agent type could not be loaded, while green means the agent type was loaded successfully.
Agent types will show a red icon only when a path for any of the files provided is invalid. Empty paths are not considered invalid, this is because an agent type might have no skeleton and only geo, or vice versa, or none of them. A default skeleton with one joint is created when no skeleton is provided.

On the top bar of the UI you can find a Switch Mode button: this button can switch the mode of this agent type from GUI to Script and viceversa.

On the right corner of the UI there are three buttons (from the right to left):

  • Register: registers the agent type and stores it in the scene

  • Revert: reverts the agent type settings to the last saved state

  • Update (arrow icon): Each agent type has a python script under the hood taking care of registering the asset in Atoms, this script is baked within your scenes. The script can vary between different versions of Atoms and with this button you can update it to the latest available version.

Skeleton

Users can create the agent type skeleton in their favorite 3D package (i.e. Maya, Houdini, etc.) with a hierarchy of joints/bones.
The body skeleton should live under one main root, but you can also have detached joints or hierarchies. These should be added as extra (prop) joints when exporting the skeleton.

For a skeleton to work in Atoms, users have to tag the following joints: any pelvis joint, any foot root (the first joint of a leg), any foot Ik (the IK handle) and any foot tip.
For a biped, you'll have one pelvis, two feet root, two feet Ik's and two feet tips.
Atoms needs these information to place your agents correctly on the ground and apply the foot lock during the simulation.

If you are using a USD file, you can select a specific primitive to load using its full path like "C:/my_usd_skeleton.usd@/Rig/Skeleton". If you want to select a specific variation, use this syntax C:/my_usd_skeleton.usd@/Rig/Skeleton{myvariant=SkeletonA} .

Facing Direction

The facing direction of the skeleton. This value is used by the Atoms mirror algorithm.

Virtual Root

Agent types can have a virtual root, which is a virtual bone acting as root during the simulation. The clip motion of the skeleton root can be transferred to such virtual root, please check the animation clip page to see how.

Users can disable/enable the virtual root and provide its world position. The position of the virtual root is important as it can act as an offset for the agents using this agent type.

Usually a good position for the virtual root would be between the skeleton feet.



Geo Path - Proxy geo

A proxy GEO is a set of low poly geometry that will be used by Atoms when showing your agents in "mesh" mode.
To associate geometry with a joint, users will have to name each piece of geo with the name of the joint followed by "_GEO" (see picture).

The proxy geo is optional; you can leave this field empty if you don't want to provide the proxy geo.

Please check the tutorial section to know how to name your proxy GEO.


All your proxy GEO should live under the same parent, although the hierarchy does not have to be flat.



Proxy GEOS are deprecated and available only for legacy support. 



Skin Path - Skinned geo

The skinned GEO can be single or multiple meshes skinned to the skeleton. At the export time, all the meshes, skin weights, UV and textures are saved inside the skinned GEO definition file.


If you are using a USD file, you can select a specific primitive to load using its full path like "C:/my_usd_character.usd@/MyCharacter/BodyGeo". If you want to select a specific variant use this syntax C:/my_usd_character.usd@/MyCharacter/BodyGeo{myvariant=variationA}



All your skinned GEO should live under the same parent, although the hierarchy does not have to be flat.

Ragdoll Path

The ragdoll path is the file describing the ragdoll setup for this agent type. Use the ragdoll builder tool to create a ragdoll setup.

Character Path

The character path is the file describing the characterization for this agent type. Characterization files are used for retargeting animations from agents of one agent type onto agents of other agent types.

Retargeting factor method

For the retargeting, Atoms uses a factor to know how big characters are compared to each other. The available values are:

  • Pelvis to feet (Default): the factor is calculated as the average distance between the feet and main pelvis.

  • Foot Root to Foot IK: the factor is calculated as the average distance between the feet roots and foot iks.

  • Bounding box: the factor is calculated as the length of the Bounding Box diagonal.

  • User factor: a user defined value.

Pelvis to feet should work for most cases, users should make sure the retargeting factor method is consistent across all agent types. If the user factor method is selected, it is the user responsibility to make sure the provided values produce accurate retargeting results.

State machine

You can link every agent type to a state machine. During the agent creation stage, the state machine module uses this name to build the state machine for each agent of this type.

Scale Multiplier

This value is a multiplier on the global scale of the skeleton. The pelvisHeight, footHeight, velocity metadata are affected by this value.

Radius

Value used as a reference by some Behaviour modules as a size for the agents using this agent type.

Sit Height Offset

The sit height offset is an offset used by the sitting adaptation to offset the sit joint from the height field.

Sit Joint Name

Users can specify a name for the joint to be used by the sitting adaptation, when no name is provided the first pelvis is used.

Sanitize Joint Names

When this option is on, the skeleton joint names are sanitized:

  1. any "." is replaced with "_"

  2. if any joint name contains a ":" then the name is broken up using ":" as a separator and the last token is used as name

Pelvises

In this section, users can tag Skeleton pelvises directly in the Atoms UI. This means you can now avoid using the skeleton exporter and use directly supported mesh and skeleton files.

Skip Iks

In this section, users can tag skip Ik joints as they would do with the skeleton exporter. Skip IK joints instruct Atoms not to use those joints as part of the IK chain when rebuilding the leg.

Legs

In this section, users can tag the leg joints. Each leg has a foot root, foot ik, foot tip and a pole vector.
The pole vector field is automatically populated with the foot root world position as soon as the foot root is selected. The pole vector needs to be in front of the foot root following the direction the skeleton is facing.

Draw Optimization

Atoms Crowd supports levels of detail (LOD), where the geometry of your agent type will be simplified at run-time inside the viewport.
Users can have 3 levels of detail and choose a mode between "Camera Distance" and "Screen Area" (the geo will be simplified based on the area the agent will use in screen space).
The two values for each LOD are:

  • the number of levels of simplification. The iterative algorithm for simplifying the geo will remove 25% of the points at each iteration.

  • the camera distance or screen area (depending on the mode) value.

Preview

The preview widget displays the skeleton for the selected agent type. At the bottom, you have a widget for changing the joint size.
Joints are coloured depending on their tags:

  • Green: pelvis joint

  • Cyan: foot root joint

  • Red: skip ik joint

  • Pink: foot ik joint

  • Yellow: foot tip joint

Each pole vector is shown as a white cube connected with a white line to its foot root.

By right-clicking on the viewport, a menu will appear with the following options:

  • Draw grid: enable/disable the grid in the viewport display

  • Draw Joint Axis: enable/disable the joint axis in the display

  • Draw Skin Mesh: enable/disable the skin mesh visibility

  • Draw Joint Names: enable/disable the joint name visibility

  • Draw Joint World Pos: enable/disable the joint world position visibility, useful for guessing a valid pole vector position

  • Lock Camera: enable/disable the locking on the camera

  • Reset Camera: resets the translation/rotation of the camera

  • Frame Objects: Frame the objects in the viewport.

  • Copy Joint Name: copy the selected joint name to the clipboard

  • Copy Joint Id: copy the selected joint id to the clipboard

Navigation Controls:

  • Alt + left click and drag: Rotate camera

  • Alt + middle click and drag: Pan camera

  • Alt + right click and drag: zoom camera



Copyright © 2017, Toolchefs LTD.