Getting Started

Getting Started with SGX Runtime

This guide is for existing SGX users who want to add SGX Runtime to an existing content and game-engine pipeline.

SGX Runtime continues to use the SGX source assets you already produce: character control (.k) files, animation event (.event) files, and associated audio. The key workflow change is that SGX Runtime does not use those source assets directly. You must compile them into SGX Runtime data before they can be loaded and played in your game.

Start with one representative character and one or two event files. Once that workflow is working, incorporate compilation into your normal content build pipeline.

Before You Begin

Before compiling SGX content for Runtime, make sure you have:

• An SGX character control (.k) file.

• One or more SGX event (.event) files created for that character.

• Matching audio files, placed beside the corresponding .event files and using the same base name, when your import workflow requires associated audio.

• The SGX Runtime package, including the Runtime API headers and binaries and the SGX Runtime Compiler.

• A valid SGX Runtime compiler license (.lic) file.

• A Windows 64-bit x86_64 machine to run the compiler.

The compiler runs on Windows 64-bit x86_64. The compiled Runtime data and Runtime API can be deployed to supported desktop, console, and mobile target platforms. See SGX Runtime Platform Support for the complete supported platforms list.

The compiler requires a valid license when compiling SGX character control files. Set the SGX_RUNTIME_LICENSE system environment variable to the path of the .lic file or place the .lic file in the compiler’s current working directory. The license applies to the compiler during development; the Runtime API embedded in your game does not use the compiler license.

Before proceeding, read SGX Runtime Concepts, particularly:

• Terminology, for FaceFX terms used by SGX Runtime documentation.

• Conventions, for audio timing, negative-time pre-roll, reference-pose, and audio-placement requirements.

• Compilation, for an overview of the compilation step.

Compile Your First Character

Use ffxc.exe to compile an SGX character control file and its event files. The compiler executable is located under:

facefx/tools/compiler/bin/

The exact subdirectory depends on the supplied build environment.

For this example, assume the following source layout:

C:\Game\Hero\
├─ Hero.k
└─ Events\
   ├─ Greeting.event
   └─ Greeting.wav

Run the following command:

ffxc --stage-import --outdir="C:\Game\RuntimeData" --events-dir="C:\Game\Hero\Events" "C:\Game\Hero\Hero.k"

This command:

• Compiles Hero.k as the character source data.

• Compiles the .event files in C:\Game\Hero\Events.

• Writes normal Runtime output to C:\Game\RuntimeData.

• Creates an import staging area for the Unreal Engine plugin or another custom engine import workflow.

If the event directory contains nested folders that should also be compiled, add --recurse:

ffxc --stage-import --recurse --outdir="C:\Game\RuntimeData" --events-dir="C:\Game\Hero\Events" "C:\Game\Hero\Hero.k"

Use --stage-import

For SGX content that will be imported through the SGX Runtime Unreal Engine plugin or another engine import workflow, use --stage-import.

--stage-import prepares an import staging area containing only assets that require import during the current compiler run. It also enables the data needed by import tooling to identify the generated assets.

For the example above, compilation creates two separate output locations:

C:\Game\Hero\
├─ Hero.k
├─ Hero.facefx                     Created if it does not already exist;
|                                  used to import Runtime Data into Unreal Engine
├─ Hero.ffxc\                      Import staging area; next to Hero.k
│  └─ ...                          Files requiring import during this compiler run
└─ Events\
   ├─ Greeting.event
   └─ Greeting.wav

C:\Game\RuntimeData\
└─ Hero\
   ├─ Hero.ffxactor
   ├─ Hero.ffxbones                Present only when the character uses bones
   └─ Default\
      └─ Greeting.ffxanim

There will be some metadata file types in the C:\Game\RuntimeData\Hero\ output directory; the files listed in the above diagram are the actual Runtime Data files used by the Runtime API.

The .facefx file and <actor_name>.ffxc staging directory are both created next to the input .k file:

<directory containing Hero.k>\Hero.facefx
<directory containing Hero.k>\Hero.ffxc\

The compiler regenerates the staging area on every run. It contains only files that require import during that run and can be safely deleted after a successful import. The Unreal Engine plugin removes staged files after importing them successfully.

The staging area is separate from the normal compiled Runtime output. Use --outdir to control where the .ffxactor, .ffxbones, and .ffxanim Runtime files are written.

SGX Specific Options

The SGX Runtime Compiler supports both SGX and FaceFX source data. Several compiler options are relevant when compiling SGX character control and event data.

The normal SGX Runtime workflow uses the default pre-roll behaviour. The compiler shifts animation keys into negative time so audio begins at time 0. Do not use --no-preroll-shift unless your audio has been prepared with the required leading padding. See Conventions for more information.

For a complete option reference, including warnings, project files, incremental compilation, and the compiler shared library interface, see SGX Runtime Compiler.

Verify the Output

A successful compilation produces a per-character output directory named after the source .k file. The Runtime files you need are:

The compiler writes animation files into groups derived from the event directory structure. An event file directly inside --events-dir is placed in the Default group. When you use --recurse, subdirectories become animation groups.

For example:

C:\Game\Hero\Events\
├─ Greeting.event
└─ Cinematics\
   └─ Introduction.event

compiled with --recurse produces animation groups similar to:

Hero\
├─ Hero.ffxactor
├─ Hero.ffxbones
├─ Default\
│  └─ Greeting.ffxanim
└─ Cinematics\
   └─ Introduction.ffxanim

Review compiler warnings before using generated data in production. Warnings do not stop compilation, but may identify unused tracks or bones, missing or invalid value constraints, unsupported characters in generated file paths, or other source data issues.

If compilation reports an error, do not use output written for that source file. Correct the reported error, then compile the source file again with --rebuild.

Add Runtime Playback

Compilation produces Runtime data. To play the generated data, integrate either the SGX Runtime API or the SGX Runtime Unreal Engine Plugin.

The Runtime API loads compiled data from memory buffers rather than directly from files. Your engine integration is responsible for reading each compiled file into memory and keeping that memory valid and unchanged for the lifetime of the corresponding Runtime handle.

At a high level, a Runtime integration:

1. Loads .ffxactor, optional .ffxbones, and .ffxanim data into stable memory buffers.

2. Creates actor, bone set, animation, and frame state handles from those buffers.

3. Confirms that the actor, bone set, and animation handles are compatible.

4. Starts an animation on the actor.

5. Processes each actor once per game frame using an always-increasing game time value.

6. Starts associated audio when the channel reports FX_CHANNEL_START_AUDIO_BIT.

7. Retrieves track values and applies them to the corresponding named targets in the game engine.

8. Computes and applies bone transforms when the character uses bones.

Use only compatible Runtime data together. Actor, bone set, and animation files contain an embedded GUID that identifies their source character structure. The Runtime API prevents incompatible files from being used together.

See SGX Runtime API for the complete API documentation, including memory allocation, data validation, handles, playback, frame processing, track values, channel flags, and bone transforms.

Next Steps

After successfully compiling and playing a test character, integrate compilation into your production content pipeline.

• Use direct ffxc invocations for simple or small content batches.

• Use a .ffxcproj project file when compiling many characters or a mixture of SGX and FaceFX source files.

• Use --stage-import for import-driven engine workflows.

• Recompile source content after a Runtime data-format update or when the Runtime API reports FX_ERROR_INCOMPATIBLE_VERSION.

• Review SGX Runtime Concepts when working with FaceFX terminology, negative-time pre-roll, source-data conventions, or the compilation model.

For further reference, see:

• What is SGX Runtime?

• SGX Runtime License

• SGX Runtime Platform Support

• SGX Runtime Files

• SGX Runtime Compiler

• SGX Runtime API