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:animations/other_animation.json",
      "animations": ["animation_name_1", "animation_name_2"]
    },
    {
      "file_id": "mod_id:animations/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, where the path is relative to the assets/mod_id/ folder. For example, mod_id:animations/other_animation.json resolves to assets/mod_id/animations/other_animation.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.

Using the Blockbench Plugin

The Azurelib Blockbench plugin supports managing animation includes directly through the Animation tab, without needing to edit the JSON manually.

To add or edit includes via the plugin:

1. Open your model in Blockbench with the Azurelib plugin installed.
2. Navigate to the Animate section.
3. Now click the Animation tab
4. Click Edit Animation Includes to open the includes editor dialog.
5. Use Add Include to add a new entry, then fill in:
   • File ID: The resource location of the animation file to include, e.g. mod_id:animations/other_animation.json (path is relative to assets/mod_id/).
   • Animations: A comma-separated list of animation names to pull from that file.
6. Click Confirm to save your changes. The includes block in your animation JSON will be updated automatically.

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:animations/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. Remember that the path in file_id is relative to assets/mod_id/, so mod_id:animations/example.json maps to assets/mod_id/animations/example.json.