Transition from CBA to AnimSettings

Overview

Version 3.5 of the SDK introduces the following animation pipeline changes:

  • Intermediate animation format .i_caf. Used to distinguish compressed and uncompressed .caf files.
  • Previously existing Animations.cba is split into set of files:
    • Per-animation .animsettings with compression settings.
    • DbaTable.xml that defines list of DBA (Animation Databases) created.
    • SkeletonList.xml defines skeleton aliases that are refered by .animsettings.
  • New tools introduced in Sandbox: Animation Import and Animation Compression Editor

These changes address the following deficiencies of the animation pipeline:

  • Need for manual editing of Animations.cba when adding animations or changing compression settings.
  • Long iterations for compression changes: previously users had to blindly change compression values and wait for the next build to preview the results.
  • Confusion caused by using caf-filetype for both compressed and intermediate files.

Conversion process

Below you will find some scripts and the guide that may help you perform the conversion.

Note that provided conversion scripts are not a complete solution on their own, rather an example of how this can be done.
Please inspect content of the scripts carefully before running them to prevent any loss of data. These may also not work in your environment and require code changes.

Steps below are assuming that Perforce is used as a version control system.
If you use another version control system for assets you will need to perform necessary changes yourself.

Conversion consists of the following steps:

  • Renaming of existing .caf files into .i_caf.
    Note that these .caf files should be those that were created during the export from DCC, not those created by the build process with the RC.
  • Create SkeletonList.xml out of Animations.cba.
  • Create .animsettings for each animation based on the settings from Animations.cba.
  • Create DbaTable.xml based on the information from Animations.cba.

Preparation

  • Get conversion scripts: CBAConversion.zip
    These are Python scripts for interpreter version 2.7.
  • Sync Animations/Animations.cba and all .caf files from P4.

Local test

I recommend doing a local test before proceeding with real files, as this will lock all .caf files later:

  • Get specific revision of .caf/Animations.cba, corresponding to the build you're going to compare animations with.
  • Run the following scripts, while in the Animations folder:
skeletonlist_from_cba.py
rename_caf_to_i_caf_local.py
animsettings_from_cba.py
dbatable_from_cba.py
  • Rename/remove Animations.cba.
  • Get all .chr, .chrparams and .cga files from P4.
  • Now compile animations to compare them with the existing build. Make sure OUTPUT_FOLDER is empty before running the RC:
cd GAME_DATA_FOLDER
rc.exe *.i_caf /threads=6 /animConfigFolder=Animations /sourceroot=GAME_DATA_FOLDER /targetroot=OUTPUT_FOLDER /cafAlignTracks=1
  • Check resulting animations. I recommend doing a binary comparison with the existing build that used the same assets. CAF and IMG files should match. DBA file content may be different, as files are added into the DBA in a different order from a .cba-build. DBA size should not be significantly different.
  • Clean up changes, by running the following command, while in the Animations folder:
del SkeletonList.xml
del DbaTable.xml
remove_animsettings.py
rename_i_caf_to_caf.py
  • and restore Animations.cba.

Actual conversion

Assuming that you already have Animations.cba and all .caf files synced, and you have no files from the local test left.

  • Check-out all .caf files - this will lock files in P4, so no-one else will be able to checkout them.
  • Adjust Animations/config.py with your p4 settings.
  • Run the following commands:
skeletonlist_from_cba.py
rename_caf_to_i_caf.py
animsettings_from_cba.py
dbatable_from_cba.py
add_animsettings_to_p4.py
  • Rename/remove Animations.cba
  • Check-in the changed files.