Metadata

In Atoms, users can create and attach custom data to almost every entity available. We call this custom data "Metadata".
Atoms has already some predefined Metadata on most entities such as Agent Types, Animation Clips, etc.
All the values explained in the previous sections for the Agent type (State Machine, Scale Multiplier) and Animation clip (Loop, Loop Start, Loop End, etc.) are metadata.

This custom data can be accessed and often tweaked at simulation time.
For instance, you might want to tag a specific skeleton joint and access it via python or C++ or stick some custom metadata on an agent to define a specific behaviour.

The available Metadata types are String, Int, Double, Bool, Euler, Vector3, Vector4, Quaternion, Matrix, Box3, Curve, Image and Mesh.
There's also an array type for all these metadata.
The most powerful metadata are the MapMetadata (a map container for mixed type of metadata) and the ArrayMetadata (a vector container for mixed type of metadata)

Metadata are most useful when used in conjunction with custom python and C++ Behaviour Modules.

Atoms Metadata

Below you can find a complete list of all metadata used by Atoms Crowd. Users might edit them during the simulation via python, C++ or using the available tools.
All metadata marked as "read only" should not be edited by the users or the editing might lead to unexpected behaviours.

Clip metadata

name	type	description	read only
atomsBlendFramesAfterFootUp	int	The number of frames used for blending after the foot leaves the ground.	NO
atomsLoop	bool	Tag the clip as loopable.	NO
atomsLoopStart	int	The start frame of the clip.	NO
atomsLoopEnd	int	The end frame of the clip.	NO
atomsNumBlendFrames	int	The number of frames used for blending.	NO

Agent metadata

name	type	description	read only

name	type	description	read only
id	int	The global id.	YES
groupId	int	The local id (the id relative to this agent group).	YES
groupName	string	The local name.	YES
direction	vector3	The agent target direction in world space.	NO
prevDirection	vector3	The agent direction before the initFrame stage.	YES
frameRate	double	The frame rate used for playing the agent animation.	NO
localDirection	vector3	The agent direction in local space.	YES
active	bool	When false, the agent node graph is not evaluated.	NO
position	vector3	The agent position in world space.	NO
scale	vector3	The agent scale. Only the x-axis value is used currently.	NO
selected	bool	The agent selection state.	NO
up	vector3	The agent up vector.	NO
turnAngle	vector3	The current turn angle of the agent.	YES
velocity	vector3	The current velocity in world space.	YES
state	int	The state of the agent to be played by the state machine	NO
animatedHf	map	(for internal use only)	YES
agentType	string	The agent type name	YES
variation	string	The agent variation	NO
cacheId	int	(for internal use only)	YES
retargetingFactor	double	(for internal use only)	YES
collectorDirections	vector4array	(for internal use only)	YES
clothSetupOverride	string	an override metadata for providing a different cloth setup file for an agent	NO
disableIk	bool	Disable the ik and the foot lock during the simulation	NO
disableFootLock	bool	Disable the foot lock during the simulation	NO
disableDirection	bool	When on, the agent the Directional behaviour modules won't affect this agent.	NO
targetAgentId	int	The global agent id of the target agent, used by the followAgent module.	NO
forceClipTransition	bool	Set to true if you want to trigger an agent out of a state at any time, not have to wait for a transition frame	NO
colorVariation	int	Sets the diffuse color slot used for current variation material as specified in the scene variation table	NO
currentState	int	Current state being played	YES
maxLegStretch	double	The multiplier on the leg length used as the maximum stretch factor by the pelvis operator during the feet adaptation	NO
stateMachine	string	The state machine name. This metadata value overrides the state machine defined in the agent type.	NO
onGround	bool	Defines is the agent is on the ground or not.	NO
animFrameRate	double	The frame rate used for playing the agent animation without modifying the pelvis velocity.	NO
transitionBlendInFrames	int	If this metadata is attached on an agent while the state machine is transitioning between two states this value is going to be used for as the number of blend-in frames.	NO
transitionBlendOutFrames	int	If this metadata is attached on an agent while the state machine is transitioning between two states this value is going to be used for as the number of blend-out frames.	NO
locomotionActive	bool	True when the agent is playing animation with locomotion, False otherwise	YES
targetLinearVelocity	double	The target linear velocity for the locomotion	NO
targetAngularVelocity	double	The target angular velocity for the locomotion	NO
footDownThreshold	double	The threshold used for checking if the foot is in foot down state, if not provided Atoms uses the default value of 0.95. The foot down state is now stored in Atoms as a double (not a boolean anymore), for this reason when the foot down state is greater than the foot down threshold the foot is considered "down" and the foot locking system is activated.	NO
velocityOverride	vector3	An override for the velocity metadata. If provided and the useVelocityOverride metadata is set to True, then this velocity is used instead of the velocity coming from the animation
useVelocityOverride	bool	When set to true, Atoms uses the velocityOverride instead of the velocity coming from the animation. The useVelocityOverride metadata is set to false at each frame after the pose is computed.

Agent type metadata

name	type	description	internal only
lowGeo	map	The low geo meshes.	YES
skinGeo	map	The skin geo meshes.	YES
scaleMultiplier	double	Agent type scale multiplier.	NO
stateMachine	string	The state machine name.	NO
boundingBox	box	The agent type bounding box.	YES

Joint metadata

name	type	description	read only
atoms_bindPoseScale	vector3	The joint bind pose scale.	YES
atoms_bindPoseRotate	vector3	The joint bind pose rotation (Euler - XYZ order)	YES
atoms_bindPoseTranslate	vector3	The joint bind pose translation.	YES
atoms_footHeight	double	The foot height.	YES
atoms_footIK	bool	Foot ik joint tag.	YES
atoms_footIkHeight	double	The foot IK height.	YES
atoms_footRoot	bool	Foot root joint tag.	YES
atoms_footOnGround	bool	Foot down joint state.	YES
atoms_frameToFootDown	int	Numbers of frame to next foot down.	YES
atoms_groundNormal	vector3	The ground normal.	YES
jointControlMapping	map	Parent for joint control mapping metadata. This data is used for the animation rig retargeting feature.	YES
jointControlMappingMatrix	matrix	The offset matrix for the given joint.	YES
jointControlMappingName	name	The name of the control to retarget.	YES
atoms_origBindPoseRotate	vector3	The joint original bind pose rotation (Euler - XYZ order)	YES
atoms_origBindPoseScale	vector3	The joint original bind pose scale.	YES
atoms_origBindPoseTranslate	vector3	The joint original bind pose translation.	YES
atoms_pelvisHeight	double	The pelvis height.	YES
atoms_pelvisLocalVelocity	vector3	The pelvis velocity in local space.