Houdini 20.5 Nodes Geometry nodes

Agent geometry node

Creates agent primitives.

On this page
Since 14.0

This node is used to create agent primitives for a crowd of characters. To get the definition of the agents, this can either be from files previously baked from an Agent output node, or directly from a character rig in the scene.

An agent primitive contains references to:

Tip

If the render gets clipped due to bounding boxes in crowds, try creating a collision layer by turning on the Generate Collision Layer parameter.

Parameters

Group

The points in the input geometry to use as agent positions.

Agent Name

Base name of the agent. For each created agent, the name primitive attribute is set to this name with a _‹number suffix. When Allow Attributes to Override is on, this is replaced by any agentname string attributes on the input points.

The value of this parameter can be referenced via the $AGENT local variable.

Current Layers

The layer (or list of layers) to assign to the agent. When Allow Attributes to Override is enabled, this can be replaced by the currentlayers string array attribute (or currentlayer string attribute) on the input points.

By default, this parameter is empty, which means to use the value of the Layer Name parameter. When loading from disk, the layer named default will be used if it exists, and otherwise the first available layer in the agent definition will be used.

Collision Layers

The collision layer (or list of collision layers) to assign to the agent. When Allow Attributes to Override is enabled, this can be replaced by the collisionlayers string array attribute (or collisionlayer string attribute) on the input points.

By default, this parameter is empty, which means to use the value of the Collision Layer Name parameter. When loading from disk, the layer named collision will be used if it exists, and otherwise the first available layer in the agent definition will be used.

Current Clip

Name of the animation clip the agents will be running. When Allow Attributes to Override is enabled, this is replaced by any currentclip string attributes on the input points. By default, this parameter is empty, which means to use the first available clip in the agent definition.

Clip Offset

Time into the current clip to begin playing at (in seconds). When Allow Attributes to Override is enabled, and the input points contain the clipoffset float attribute, then those values are added to this parameter value for each agent.

Apply Clip Locomotion

If enabled, apply the __locomotion__ transform from the agent rig so that you can easily previsualize locomotive clips.

Allow Attributes to Override

Replace the values of Current Layer, Current Clip, and Clip Offset with values from equivalent point attributes, if present.

Keep Primitives

Normally, primitives are deleted for the points that agents are created on. If this is enabled, then the primitives will not be deleted.

Reload

Reloads the agent definition.

Input

Specify the source to create agents from. See below for details on the parameters for each of these input sources.

Character Rig

Create the agent definition from an actual character subnetwork/asset in the scene. To share agent definitions between multiple scenes and reduce the size of caches, you may want to save the agent definition to disk.

Agent Definition Cache

Load the agent definition from disk (previously baked out using the Agent render node or Agent Definition Cache SOP).

FBX

Get the information from an FBX file containing a character.

USD

Create the agent definition from a UsdSkel character (a USD SkelRoot primitive). The source USD stage can be a file on disk or a LOP node. The animation clip’s frame range is determined from the stage’s startTimeCode and endTimeCode metadata, which can be modified using the Configure Layer LOP.

Input: Character Rig

Character Rig

Path to the object subnetwork containing the character rig.

Traverse Outputs

When enabled, the Character Rig path is used to specify which nodes to import by traversing its outputs instead of its children.

Pattern

Pattern used to limit which nodes should be imported. Patterns using usual opglob syntax along with @‹bundle references are accepted.

Note

Relative paths specified here are relative to this node, not to the Character Rig.

Type

Optional mask to further restrict which object node types will be imported. Disable the toggles to prevent baking particular types.

Minimal Nodes

Only import objects whose display flags are on. If you turn this off, all nodes in the character rig are imported into the animation clip.

Keep Transforms for Deforming Shapes

When Minimal Nodes is enabled, specifies whether nodes containing deforming geometry are included in the agent’s rig and clips.

Shape Library

Convert to Polygon Soups

Combine polygon primitives into polygon soup primitives when creating the shape library. This can reduce memory usage, particularly when rendering with Mantra.

Layers

Layer Name

The default layer for the agent, created using the display flags of the objects. Every agent must have at least one layer.

Bounds Scale

Specifies a scale for the bounding box of each shape in the default layer. See the Agent Primitive help page for more information on how an agent’s bounding box is computed.

Generate Collision Layer

Generate a collision layer from geometry containing capture/deform weights. This generates capture region primitives and assigns them to the corresponding bones in the rig.

Collision Layer Name

When Generate Collision Layer is on, the name of the collision layer.

Clip

Clip Name

Name of the baked out clip (agent animation). The animation is taken from the current scene.

Additional Channels

Adds channels from the specified CHOP node to the agent’s clip.

Frame Range

Whether to use the scene’s global frame range or the Start/end/inc parameters.

Start/End/Inc

When Frame Range is “Specific”, the start frame, end frame, and frame increment to bake out.

All values may be decimal (for example, start on frame 1.5).

Shift Clip to Frame 1

Shift output clips from the specified frame range to start at frame 1.

Locomotion

Create Locomotion Joint

When enabled, this will create an extra joint named __locomotion__ which serves as a placeholder for factored out locomotion animation when Convert to In-Place Animation is enabled.

Convert to In-Place Animation

Convert a moving character animation to an in-place clip, by subtracting the positions of the Locomotion Node (relative to the origin or where it was on the first frame depending on Use Pivot from First Frame parameter).

Locomotion Node

The object inside the Character Rig that controls the locomotion of the character (the node in the character rig that has translation channels that move it forward in space). When Convert to In-Place Animation, Houdini uses this to remove the translation from the character animation to keep the character in place. (The crowd solver node assumes that the agent animation is in-place since it will be attached to a moving particle.)

The locomotion animation is placed in a separate transform in the rig named __locomotion__. If this parameter is empty, then __locomotion__ will use the Character Rig.

Locomotion Orient

If this parameter and Locomotion Node are specified, the generated __locomotion__ transform will also contain rotational information using the vector from the Locomotion Node to the Locomotion Orient node. If this transform is the same as the Locomotion Node, its orientation will be directly extracted. This parameter has no effect if Locomotion Node is empty.

Project Positions on Dominant Axis

When creating the animation of the Locomotion Node, project the positions along the dominant axis of motion in the XZ plane. If the clip will be used as an in-place clip with the crowd solver, enabling this option can help to maintain hip swaying in the motion.

Use Pivot from First Frame

When creating the animation of the Locomotion Node, calculate the positions to be relative to the origin. If this option is disabled (the default), then the positions will be relative to where it was on the first frame.

Input: Agent Definition Cache

Cache Directory

The parent directory of agent definition files. This parameter is provided for convenience so that its value can be referenced via the $CACHEDIR local variable in the other filename parameters.

Rig

Specifies the path to the agent’s rig file.

Agent Layers

Filename pattern of the agent layer files to load. The ${LAYER} local variable is used as a * placeholder here so that all matching files are loaded for only each particular agent.

Shape Library

Specifies the path to the agent’s shape library.

Clips

Filename pattern of the animation clips to load. The ${CLIP} local variable is used as a * placeholder here so that all matching files are loaded for only each particular agent. The actual name of the clip is inferred from the string matched by ${CLIP}, or the full filename without the extension if ${CLIP} is not used.

Transform Groups

Filename pattern of the transform group files to load. The ${TRANSFORM_GROUP} local variable is used as a * placeholder here so that all matching files are loaded for only each particular agent.

Metadata

Specifies the path to the agent’s optional metadata file.

Keep External References

Specifies whether the agent primitives should reference the agent definition files on disk. If enabled, saving agents to a geometry file will only store references to the agent definition files, instead of embedding the agent definition in the .bgeo or .geo file (which produces a self-contained, but larger, geometry file).

Delay Load Clips

If enabled, clips will only be loaded from disk when their data is needed. This can improve load times and memory usage for large clip catalogs, but errors from loading clips may not be reported immediately.

Input: FBX

FBX File

Filename of the FBX file to generate agents from.

Import Principled Shader Values

When enabled, create material_override attribute inside the shape geometry which imports the material values from the FBX that are suitable for use with Houdini’s Principled Shader material.

Note

In order to get accurate texture paths, this causes the FBX file to be imported with “Extract Embedded Data” enabled, which will cause .fbm directories on disk to be created with the textures extracted within them.

Convert Units

Specifies whether to convert to Houdini units when importing the FBX file.

Minimal Nodes

Only import objects whose display flags are on. If you turn this off, all nodes in the character rig are imported into the animation clip.

Keep Transforms for Deforming Shapes

When Minimal Nodes is enabled, specifies whether nodes containing deforming geometry are included in the agent’s rig and clips.

Shape Library

Load as Polygon Soups

Create polygon soup primitives instead of polygon primitives when loading geometry from the FBX file. This can reduce memory usage, particularly when rendering with Mantra.

Include Unused Capture Regions

When importing a skinned mesh, additional capture regions with identity transforms are added to the boneCapture attribute for the ancestor joints of any captured joints. It is recommended to only enable this option for compatibility with older scene files, as it can introduce issues with unpacking or merging the rest geometry of multiple skinned shapes.

Layers

Layer Name

The default layer for the agent, created using the display flags of the objects. Every agent must have at least one layer.

Bounds Scale

Specifies a scale for the bounding box of each shape in the default layer. See the Agent Primitive help page for more information on how an agent’s bounding box is computed.

Generate Collision Layer

Generate a collision layer from geometry containing capture/deform weights. This generates capture region primitives and assigns them to the corresponding bones in the rig.

Collision Layer Name

When Generate Collision Layer is on, the name of the collision layer.

Clip

Clip Name

Specifies the names of the animation clip(s). A clip is created for each take in the FBX file. The ${FBX_TAKE_NAME} and ${FBX_TAKE_INDEX} local variables can be used to generate clip names based on the take name and index from the FBX file.

Override Sample Rate

Specifies whether to use the value of the Sample Rate parameter instead of the sample rate stored in the FBX file. This is useful if the application that exported the original FBX file did not set the sample rate correctly.

Sample Rate

Sample rate to use for the clip when Override Sample Rate is enabled.

Locomotion

Create Locomotion Joint

When enabled, this will create an extra joint named __locomotion__ which serves as a placeholder for factored out locomotion animation when Convert to In-Place Animation is enabled.

Convert to In-Place Animation

Convert a moving character animation to an in-place clip, by subtracting the positions of the Locomotion Node (relative to the origin or where it was on the first frame depending on Use Pivot from First Frame parameter).

Locomotion Node

The object inside the Object Subnet that controls the locomotion of the character (the node in the character rig that has translation channels that move it forward in space). When Convert to In-Place Animation, Houdini uses this to remove the translation from the character animation to keep the character in place. (The crowd solver node assumes that the agent animation is in-place since it will be attached to a moving particle.)

The locomotion animation is placed in a separate transform in the rig named __locomotion__. If this parameter is empty, then __locomotion__ will use the Object Subnet.

Locomotion Orient

If this parameter and Locomotion Node are specified, the generated __locomotion__ transform will also contain rotational information using the vector from the Locomotion Node to the Locomotion Orient node. If this transform is the same as the Locomotion Node, its orientation will be directly extracted. This parameter has no effect if Locomotion Node is empty.

Project Positions on Dominant Axis

When creating the animation of the Locomotion Node, project the positions along the dominant axis of motion in the XZ plane. If the clip will be used as an in-place clip with the crowd solver, enabling this option can help to maintain hip swaying in the motion.

Use Pivot from First Frame

When creating the animation of the Locomotion Node, calculate the positions to be relative to the origin. If this option is disabled (the default), then the positions will be relative to where it was on the first frame.

Input: USD

Source

Specifies whether the source USD stage is from a LOP node or USD file on disk.

LOP Path

Specifies the path to a LOP node. The agent definition will be constructed from a UsdSkel character in the USD stage output by this node.

USD File

The path to a USD file on disk.

SkelRoot Primitive Path

The path of a SkelRoot primitive in the USD stage. If the path is empty, the first SkelRoot prim in the stage will be used.

Purpose

Sections of a USD hierarchy can be marked to be used for a specific purpose. Only sections marked as the default purpose or one of the specified purposes are traversed when unpacking the USD packed primitives.

Layers

Layer Name

The default layer for the agent, created using the display flags of the objects. Every agent must have at least one layer.

Bounds Scale

Specifies a scale for the bounding box of each shape in the default layer. See the Agent Primitive help page for more information on how an agent’s bounding box is computed.

Generate Collision Layer

Generate a collision layer from geometry containing capture/deform weights. This generates capture region primitives and assigns them to the corresponding bones in the rig.

Collision Layer Name

When Generate Collision Layer is on, the name of the collision layer.

Clip

Clip Name

Name of the baked out clip (agent animation). The animation is taken from the current scene.

Locomotion

Create Locomotion Joint

When enabled, this will create an extra joint named __locomotion__ which serves as a placeholder for factored out locomotion animation when Convert to In-Place Animation is enabled.

Convert to In-Place Animation

Convert a moving character animation to an in-place clip, by subtracting the positions of the Locomotion Node (relative to the origin or where it was on the first frame depending on Use Pivot from First Frame parameter).

Locomotion Node

The name of the joint that controls the locomotion of the character (the joint in the skeleton that has translation channels that move it forward in space). When Convert to In-Place Animation, Houdini uses this to remove the translation from the character animation to keep the character in place. (The crowd solver node assumes that the agent animation is in-place since it will be attached to a moving particle.)

The locomotion animation is placed in a separate transform in the rig named __locomotion__. If this parameter is empty, then __locomotion__ will use the Object Subnet.

Locomotion Orient

If this parameter and Locomotion Node are specified, the generated __locomotion__ transform will also contain rotational information using the vector from the Locomotion Node to the Locomotion Orient joint. If this transform is the same as the Locomotion Node, its orientation will be directly extracted. This parameter has no effect if Locomotion Node is empty.

Inputs

Points to spawn agents

If given, the input points are used to spawn the agents. These points may contain specific attributes that are used to control properties of the created agents, allowing for multiple agent definitions to be used via the $AGENT local variable.

Locals

AGENT

The name of agent. The value either comes from the agentname string attribute on the input points when Allow Attributes to Override is enabled, or from the value of the Agent Name parameter.

CACHEDIR

A local variable provided for convenience so that the value of the Cache Directory parameter can be easily referenced.

LAYER

Used as a wildcard in the Agent Layers parameter for specifying the layer files to load.

CLIP

Used as a wildcard in the Clips parameter for specifying the clip files to load.

TRANSFORM_GROUP

Used as a wildcard in the Transform Groups parameter for specifying the transform group files to load.

FBX_TAKE_NAME

Contains the name of the current take in the FBX file when evaluating the Clip Name parameter and Input is FBX.

FBX_TAKE_INDEX

Contains the index of the current take in the FBX file when evaluating the Clip Name parameter and Input is FBX.

See also

Geometry nodes