Overview

The includes feature in animation JSON files provides a powerful way to reuse animations by referencing external animation files. This mechanism promotes modularity, reduces redundant data, and makes managing complex animations easier. This guide explains how to use the feature effectively in your animation JSON files.

How the includes Feature Works

The includes property is used to reference animations defined in external JSON files. It enables you to import named animations from other files and use them as if they were part of the current animation set.

Key Features

1. Modularity: Enables referencing animations in separate files to keep animation files clean and modular.
2. Reusability: The same animation can be shared across multiple entities or contexts without duplication.
3. Automatic Resolution: Automatically resolves and loads animations from the specified include files when accessed.

JSON Structure for includes

Below is an example of how the property is defined within an animation JSON file: includes

{
  "animations": {
    "example_animation_1": {
      "animation_length": 5,
      "bones": { /* bone animation data here */ }
    }
  },
  "includes": [
    {
      "file_id": "mod_id:path/to/other_animation.json",
      "animations": ["animation_name_1", "animation_name_2"]
    },
    {
      "file_id": "mod_id:path/to/another_animation.json",
      "animations": ["another_animation_name"]
    }
  ]
}

Explanation

1. file_id: Specifies the location of the external JSON file containing animations. This should follow the format mod_id:path/to/file.json.
2. animations: A list of animations from the specified file to include into the current context. These animations can then be referenced by their names.

Loading Included Animations

The framework automatically manages includes by resolving referenced animations from the specified files. Here’s what happens internally: AzBakedAnimations

1. When you request an animation using getAnimation, the system first looks for it in the animations directly declared in the current JSON file.
2. If the animation is not found, it checks the includes for matching entries.
3. For a matching entry, the specified file is loaded, and the animation is retrieved from it.

Practical Example

Animation File 1 (example.json)

{
  "animations": {
    "wave_animation": {
      "animation_length": 2,
      "bones": {
        "arm": {
          "rotation": { /* keyframe data */ }
        }
      }
    }
  }
}

Animation File 2 (main_entity.json)

{
  "animations": {
    "walk_cycle": {
      "animation_length": 3,
      "bones": { /* bone animation data */ }
    }
  },
  "includes": [
    {
      "file_id": "mod_id:example.json",
      "animations": ["wave_animation"]
    }
  ]
}

Common Errors and Debugging

1. Animation Name Conflicts

• If multiple includes reference animations with the same name, the animation from the first resolved file takes precedence.
• Solution: Ensure unique animation names across files.

2. Cyclic Includes

• If an animation file references itself directly or indirectly (cyclic dependency), an exception is thrown:

     The animation file 'file_id' refers back to itself through includes.

• Solution: Carefully design includes to avoid circular references.

3. Missing Files or Animations

• If a file_id or animation name is invalid or missing, the referenced animation cannot be loaded.
• Solution: Double-check paths and animation names.