Overview

Geometry Caches in CRYENGINE allow storing and playing back arbitrarily animated geometry, similar to a video, but for geometry.

Some use-cases are: complex destruction animations, complicated cloth motion, or special effects that cannot be achieved with CRYENGINE's particle system.

More information can be found here: Production Details and Technology Details.

Features and Limitations

Features

• Imports standard Alembic files:
  • animated transform hierarchies (i.e. fragmenting objects).
  • deforming meshes with constant topology (i.e. cloth, characters).
• Animated visibility.
• Animated vertex colors.
• Automatic detection of geometry instances.
• Physics Proxies.

Limitations

• Not all Alembic features supported:
  • no meshes with changing topology (i.e. fluid caches, DMM):
    • Deforming meshes can be compressed very well, since their vertices just move around.
      Meshes with changing topology would require storing the entire mesh per frame, which would be too much data to stream in real-time.
      Also we'd need to add velocity data to every frame, which many Alembic pipelines don't handle very well.
  • no curves.
  • no subdivision surfaces.
  • no camera, lights, etc.
• No reverse-playback or fast-forward:
  • the animation is streamed in, similar to a Youtube video, so jumping around in time will introduce a delay in the animation.

Filetypes

• *.abc - This is the native Alembic format that you can export from various DCC tools.
• *.cbc - This is a settings file which stores the parameters which were used to convert the Alembic file.
• *.cax - This file is the processed Alembic file which the RC has compressed into an engine friendly format.

Creating GeomCache Assets

General

Alembic is a very flexible format, designed to be extensible for any custom pipeline conceivable.

As such many 3d applications export Alembic slightly differently, making it tricky to import caches from different sources.

A few guidelines need to be followed when creating Alembic caches for GeomCaches:

• Polycount - generally shouldn't exceed what's reasonable for regular assets. There may be no more than 65.536 vertices/triangles per node.
• Data-rate - shouldn't exceed 10 MB/s for all GeomCaches running concurrently. See Optimization section for more info.
• UV Coordinates - GeomCache importer only loads the first UV-channel. All other channels will be ignored.
• Vertex Colors - GeomCache importer only loads the first Vertex color-channel. All other channels will be ignored.

Material IDs

CRYENGINE requires per-face material assignment to be able to set sub-materials to geometry.

Alembic can export this information as face-sets (aka ShadingEngines or ShadingGroups in Maya).

The importer will look for the first integer number in such a face-set name and use it as the material ID.

So generally it's good practice to name your materials something like:

• mat01_wall
• mat02_door
• mat03_etc...
  
  

Physics Proxies

You can create animated, passive, physics proxies by including one of the strings in the following list in the name of a mesh. The surface-type is derived from the assigned material. Physics proxies will not be rendered.

• CryPhys_box - box proxy. Supports non-uniform scale.
• CryPhys_sphere - sphere proxy. Supports uniform scale.
• CryPhys_capsule - capsule proxy. Supports uniform scale.
• CryPhys_cylinder - cylinder proxy. Supports uniform scale.
• CryPhys_mesh - arbitrary mesh. Supports non-uniform scale.

Alembic Export from Maya

We use the built-in Maya 2016 Alembic Exporter and the "CryAbc" script from the Crytek shelf.

Make sure you loaded the Maya Alembic export plugin: from Maya's Main Menu bar -> Windows -> Settings/Preferences -> Plug-In Manager, tick the "Loaded" and "Auto-load" checkbox for the "AbcExport.mll".

1. Run the AbcMat script (inside the Crytek Shelf), to prepare your scene for export. This script slightly modifies your scene to work around some limitations in Maya's Alembic exporter.

2. Bring up the Maya Alembic exporter GUI first.

3. Under the advanced Options, (scroll to the bottom) & make sure to have the essential flags enabled, as in the picture below.

4. Just select the mesh nodes you wish to export and click the "CryAbc" shelf button. A file dialog will pop up and ask you to set the file location and file name for the Alembic file.

Alembic Export from 3ds Max

Beginning with version 2016, 3ds Max officially features an Alembic exporter. Although, it will not export deforming meshes readable for the CryEngine, but only "rigid bodies" with animated transforms. If you want to have deforming meshes, e. g. cloth objects, blendshape animations, etc. , you must export to an Alembic file from Max 2016, re-import the *.abc file in Maya, set the materials according to the Maya Alembic to CRYENGINE workflow and get the scene exported with CryAbc, the Alembic exporter from the crytek shelf. ( Follow the guide section above! )

Third Party Plugin

One alternative is the Exocortex Crate plugin.

These are the essential exporter settings:

Batch Conversion

Running the resource compiler from the command line allows for batch conversion of multiple *.abc files in a row.

This can be useful for automatic asset builds or manually updating all *.cax files after getting a new engine version.

Here's an example for using the resource compiler via command line to convert all *.abc files in the SDK:

rc.exe /refresh /threads *.abc

Using GeomCaches in Sandbox

Importing

The import process is straight-forward:

Create a GeomCache entity from Entity > Render > GeomCache

Load up your *.abc file in the "File" field:

Set up your import properties. There are presets for most use-cases that you'll encounter in production:

The settings in detail:

• Y/Z-axis up - set this according to which axis is up in your source file.
• Playback from memory - will load the entire cache into memory, instead of streaming it. Useful for small, looping caches.
• Block Compression - lossless compression for the entire file
  • store - no compression. Creates big file but compiles fast. Useful for quickly testing complex caches.
  • deflate - strong compression. Default choice for most cases.
  • lz4hc - good compression. Faster unpacking. Can help reducing the CPU-load.
• Precision - lossy compression of vertex positions. Higher values = smaller file, but more jittering.
• Mesh Prediction - lossless compression of mesh-data. Disable to quickly compile complex caches for testing.
• Bi-Directional Prediction - lossless compression of motion-data. Disable to quickly compile complex caches for testing.
• Index Frame Distance - interval at which to place key-frames. Bigger/smaller can improve compression for some caches.

Entity Setup

The entity itself can be used similar to an AnimObject in Trackview and Flowgraph.

The properties in detail:

• File - the GeomCache file for this entity. Load an *.abc to recompile.
• FirstFrameStandIn - CGF to be displayed before the cache animation was triggered. Leave blank to always show cache.
• FirstFrameStandInMaterial - material for the first frame CGF.
• LastFrameStandIn - CGF to be displayed after the cache animation has finished. Leave blank to always show cache.
• LastFrameStandInMaterial - material for the last frame CGF.
• Looping - if enabled, the animation will loop.
• Playing - if enabled, the animation will be playing.
• StandIn - CGF to be displayed while the cache animation is playing. Leave blank to always show cache.
• StandInDistance - when the camera is further away than this distance, stand-in CGFs will be displayed.
• StandInMaterial - material for the stand-in CGF.
• StartTime - time at which to start playing the cache animation.
• StreamInDistance - when the camera is within this range, the pre-caching will start. Leaving the range, will discard the cache data. Should be significantly larger than StandInDistance.

With the appropriate settings, the entity can be used as a looping, animated prop without extra game logic.

Here's an example of an independent GeomCache prop from Ryse that loads and unloads as the player moves closer or further:

Control via Flowgraph

Coordinating game logic with GeomCaches requires a couple of extra steps to work efficiently.

In the following example picture of a looping animation of a GeomCache, the “resting or start” frame of the animation is at frame zero.

After a game event triggers a GeomCache to stop playing, (proximity trigger, gametoken modified, mission complete etc...(debug inputkey in this case))… we hook into certain inputs on the GeomCache Flowgraph node to handle how the entity stops playing correctly.

We call through flowgraph the SetTime input, this resets the timeline of the animation back to frame zero (using the Math:SetNumber node). But since this GeomCache is set to play a looping animation, setting the time back to this “resting” frame is not enough, as the loop will continue on from frame zero.

Optimization

Streaming

Since complex GeomCaches are too large to be fully pre-loaded, their animation data is streamed in a few seconds before being played.

Smaller GeomCaches can be completely loaded into memory, by enabling the "playback from memory" flag on import.

Because of this it is important to keep an eye on the data-rate of individual caches and the combined amount of GeomCache data currently in memory.

These values have been used for Ryse on XboxOne:

• Max. combined data-rate: 10 MB/s
• GeomCache buffer size: 128 MB
• Max. playback from memory size: 16 MB
  
  

Rendering

Most of the time working with GeomCaches comes down to a trade-off between draw-calls and data-rate.

Using many non-deforming meshes with animated transforms results in a low data-rate, but high draw-call numbers and vice-versa.

Some techniques to help GeomCaches performing well:

• Instances - when using many identical, non-deforming objects, ensure that they're instanced in your DCC tool, which will help save drawcalls.
• Visibility - when an object moves out the player's sight (i.e. underground), animate its visibility off. This will prevent it from rendering and also remove unnecessary animation data.
• Merging - when working with many low-poly, non-deforming objects, merging them into a single deforming mesh can help reducing draw-calls significantly at the cost of some data-rate. This technique was used for the siege-tower in Ryse.
• LODs - stand-in CGFs can have LODs like any regular CGF. This way the polycount at a distance can be kept very low and the full GeomCache is only rendered when the camera is close enough.

This sequence illustrates how different techniques affect draw-calls and data-rate, using "e_GeomCacheDebugDrawMode 3" to color instances:

Profiling

The overall memory consumption and streaming performance of all active GeomCaches can be profiled, using "e_GeomCacheDebug 1".

Individual GeomCaches can be profiled with the mesh statistics overlay.

This is how the individual values affect performance:

• Playback from Disk/Memory - whether this GeomCache is streamed or completely loaded into memory.
• Average Animation Data Rate - high values can lead to animation stuttering.
• Animated/Static Tris/Verts - like with regular geometry, more triangles/vertices = slower rendering.
• Animated/Static Meshes - the number of individual meshes (unless instanced) directly translates into draw-calls. Meshes with multiple sub-materials cost multiple draw-calls.

The Statistics Overlay can be enabled in the preferences:

Debugging & Troubleshooting

Common Issues and Solutions

Console Commands

e_GeomCacheDebug - displays GeomCache streaming debug information. Avoid having a full streaming buffer since it will lead to animation stalls:

e_GeomCacheDebugFilter - show debug info only caches with this string in its name.

e_GeomCacheDebugDrawMode - debug draw to identify static geometry, deforming geometry and instances:

• 1 - draw only deforming meshes
• 2 - draw only static meshes
• 3 - meshes with the same color are rendered as instances