LibAnimatedTextures

Introduction

LibATex provides functionality to allow mod developers to add animated textures to Vintage Story. Does nothing if no other mods make use of this functionality.

By replacing the animated textures at runtime, your mod is guaranteed to keep displaying the correct textures if this mod fails or is not installed.

Currently untested on GNU+Linux and MacOS, but should work

To get started:

1. Just make blocks / models / textures as you would otherwise
2. Add animated versions of the textures you want to animate
3. Create a configuration file to define your animations
4. Enjoy!

Features (WIP)

Currently implemented:

These features are currently implemented and working

• Animated textures (O tested - functional)
  • Replace any texture with an animated version
  • Support for blocks, entities and items
• Partial animations (O tested - functional)
  • Apply small animation frames to only part of a texture, instead of the entire texture
  • Allows for smaller animations for accent animations
  • Examples: eyes blinking, candles flickering
• No-code JSON configuration (O tested - functional)
  • Add animations by simply adding textures and a config file to your own mod
  • Allows for non-programmers to use animated textures
• Time-based Animations (O tested - functional)
  • Sets the animation frame based on the current time of day

Planned features

These features are planned to be implemented in a future update

• Animation manipulation through C#
  • provide custom textures that are rendered onto by the caller
  • allow the starting, stopping, and general configuration at runtime through code
  • sample renderer / shader combo for shader-based animations
  • Github repo coming
  • feature requests welcome!

Potential features

These features might be implemented, or may stay as ideas

• Periodic animations
  • Wait for a specified amount of time in between animation loops
• Periodic random animations:
  • Same as periodic animations, but waits a random time between t_min and t_max between loops

Configuration

To enable animations in your mod, add an animatedtextures.json to your assets/config/ folder (the name has to be exact) with a configuration object supporting the following options:

Notes:

• Mods that don't use animated textures but also don't want their textures to be animated by other mods can set the "AllowsOverriding" option to false, and then leave the "Animations" option blank to disable other mods animating their textures

Animations: an array of configuration items containing the following options:

Notes:

• As should be best practice, only textures with dimensions of a power of 2 are supported (e.g. 16x16, 32x32, ...)
• The animation manager 'ticks' at most every game tick
• Configuration assetlocation paths default to the domain of the mod defining the configuration file being read (e.g. "game:", "libatex:")
• Multiple animated textures cannot write to the same target texture, with the exception of partial animations. Use the Priority option to set animation precedence

{
  "Animations": [
    {
      // a 2x2 animation with all files within this mod
      "AnimationPath": "block/animation1",
      "TargetPath": "block/target1",
      "NumColumns": 2,
      "NumRows": 2
    },
    {
      // a 2x2 animation targeting a game texture that changes 2 times per second
      "AnimationPath": "block/animation2",
      "TargetPath": "block/soil/blueclay",
      "TargetModDomain": "game"
      "NumColumns": 2,
      "NumRows": 2,
      "SecondsPerFrame": 0.5
    },
    {
      // a 4x4 animation with 10 frames
      "AnimationQualifiedPath": "animatedmod:block/animation3",
      "TargetQualifiedPath": "game:block/soil/fireclay",
      "NumColumns": 4,
      "NumRows": 4,
      "NumFrames": 10
    },
  ]
}

{
  "AllowsOverriding": false,
  "Animations": [
    {
      // a partial animation replacing the windmill of the banner texture with 4 frames
      // the target region is 10x10 pixels with an offset of (11,12)
      // we need to use a 32x32 texture, so 2px leftover at the right and bottom
      "AnimationPath": "block/animation1",
      "TargetPath": "game:block/cloth/banner/hansa/keys-top"
      "NumColumns": 3,
      "NumRows": 3,
      "NumFrames": 4,
      "PaddingX": 2,
      "PaddingY": 2,
      "TargetOffsetX": 11,
      "TargetOffsetY": 12
    }
  ]
}

{
  "Animations": [
    {
      "AnimationQualifiedPath": "animatedmod:animated/blinking_face",
      "TargetQualifiedPath": "game:entity/humanoid/trader",
      "NumColumns": 3,
      "NumRows": 3,
      "PaddingX": 2,
      "PaddingY": 2,
      "TargetOffsetX": 10,
      "TargetOffsetY": 14,
      "AtlasType": "entity"
    }
  ]
}

{
  "Animations": [
    {
      "AnimationQualifiedPath": "libatexexamples:block/clock_animated",
      "TargetQualifiedPath": "libatexexamples:block/clock",
      "NumColumns": 4,
      "NumRows": 4,
      "NumFrames": 12,
      "TimeOptions": {
      }
    }
  ]
}

Note about time-based animations; the time of day is represented as a percentage, i.e. a number from 0.0 to 1.0, in order to accomodate different hours per day configurations.

Each frame is spaced evenly across the day, so an animation with 4 frames would receive 6 hours per frame, or 3 hours per frame with a multiplier of 2.0 for example.