Asset file descriptions and interdependencies

Atoms Crowd works with several file formats and assets.

Agent Type

An agent type is defined by three files:

  • Skeleton (.atomsskel): the skeleton file containing the joint structure and metadatas
  • Geo (.geos): the proxy geometry used in the viewport when the proxy mode draw mode is enabled
  • Skin (.geos): the sking geometry used in the viewport when the skin mode draw mode is enabled



Animation clip

An animation clip is defined by one file:

  • Clip (.fbx/.atomsclip): the animation file containing the joint animation and metadata animated values



Scene Json

A scene json represents of the data displayed in the Atoms UI.
This file can be exported and imported from/into your host app and its content is generally stored on an attribute of a node called tcAtomsNode.

This files is a descriptor for your scene setup and contains all definitions for Animation Clips, Agent Types, Simulation Events, Behaviour Modules and State Machines.

You don't necessarily need a scene json to setup your scene as this process can be done with the API. Please note, if any asset registered via script won't be editable through the Atoms UI.


As the scene json contains the actual definition of animation clip and agent types with all their parameters, this file will contain the paths to clip files, skeleton files, proxy and skin geo files.

Variation Json

A variation json describes the variation data for one or more agent types.
It stores a dictionary containing all geometries, materials and their associations for each agent type. It can also contain optional a cloth setup file and a lookfile.

This file can be exported and imported from/into your host app and its content is generally stored on an attribute of a node called tcAtomsNode.

Variation Json can be store on a disk on file or generated at run-time with our API.

A variation json table can be generated using the variation builder tool.


A variation json contains references to the variation geos files, the variation materials, preview images and the material textures for the variation draw mode in the viewport. 

Atoms Cache

An Atoms cache stores the simulation of one or more agents groups. An atoms caches only contains skeleton data and metadata values, it does not contain any geometry data.

Each cache is broken into several files to improve performances. 
Each cache has a file with no padding and .atoms extension containing global info, such as start frame, end frame, agent ids, etc.

For each frame 4 files are created:

  • header: basic info such as number of agents at the current frame, number of created agents and number of deleted agents
  • frame: agent data such as agent type, position, velocity, bbox and variation
  • meta: agents metadata
  • pose: agent skeleton data

To make sure caches are portable, all agent type files (containinig skeleton and joint metadatas) are saved in a subfolder next to your cache files. The cache will also have a header file containing global infos, such as start frame, end frame, agent ids, etc.

You need a cache to render your crowds.



Cloth Cache

A cloth cache stores the cloth deformation data of your simulation geos.

Each frame file contains the points, normals and bounding box data for each cloth geo of your simulation agents, plus a global bounding box for all the cloth geos.




Alembics are used as xgen scalp geos and and curves.

Alembics can also be used as geos for your agents, both skin and variations (if you wish to do so you have to store the skin weights with the menu command).




As already explained in the reference guide you can render from your host app using an Atoms Proxy or you can render directly with our procedurals.

In all cases, for rendering you always need:

  • an atoms cache
  • a variation json file (when rendering you can pass directly its content to the procedurals)

Optionally you can provide:

  • a cloth cache
  • a groom cache (the scalp geo)
  • a groom curve cache

Copyright © 2017, Toolchefs LTD.