Mods / LibATex

Category: #Graphics #Library #Other #Utility
Author: nanotect
Side: Client
Created: Jul 18th at 9:58 PM
Last modified: Jul 27th at 3:51 PM
Downloads: 98
Follow Unfollow 8

Latest file for v1.19.8:
libatex_0.5.0.zip 1-click install


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

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!
  • Time-based animations:
    • Set current animation frame depending on time of day
    • Scale linearly with time (or with a user-provided function)
    • Examples: flowers closing at night, texture-based clocks

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 tmin and tmax 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:

Global Options

These options apply to the animations of this mod as a whole

  • AllowsOverriding: Determines whether or not other mods are allowed to overwrite your textures (animated or otherwise) with their own animated textures. Defaults to true
  • Animations: An optional array of individual animation configuration objects. See the required, alternate and optional options below for valid 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:

Required options

These options are required to create an animated texture

  • string AnimationPath: The assetlocation path to the animated texture
  • string TargetPath: The assetlocation path to the texture to animate
  • int NumColumns: The number of frame columns the animation has
  • int NumRows: The number of frame rows the animation has
Alternate options

These options can be used as replacements for some of the required options.

  • string AnimationQualifiedPath: The qualified path to the animated texture, including domain and starting from the textures/ folder (supersedes AnimationModDomain and AnimationPath)
  • string TargetQualifiedPath: The qualified path to the texture to animate, including domain and starting from the textures/ folder (supersedes TargetModDomain and TargetPath)
Optional options

These options can be left out if not used

  • string AnimationModDomain: The domain of the mod that has the animated texture. Defaults to the domain of the mod defining this config
  • string TargetModDomain: The domain of the mod that has the texture to animate. Defaults to the domain of the mod defining this config
  • string AtlasType: The type of atlas the texture to animate belongs to ["block" | "item" | "entity"]. Defaults to "block"
  • int NumFrames: The number of frames in the texture. Defaults to NumColumns * NumRows
  • int Priority: The priority this animation configuration takes over other animations targeting the same texture. Defaults to 0
  • int PaddingX: The animated texture padding on the right side. Decreases the space used by the frames. Defaults to 0
  • int PaddingY: The animated texture padding on the bottom side. Decreases the space used by the frames. Defaults to 0
  • int TargetOffsetX: The partial animation X-offset within the target texture. Indicates the animation is a partial texture if not 0. Defaults to 0
  • int TargetOffsetY: The partial animation Y-offset within the target texture. Indicates the animation is a partial texture if not 0. Defaults to 0
  • float SecondsPerFrame: The time each frame should be displayed for (note: animations tick every game tick). Defaults to 1.0
  • bool IsPartial: Indicates the animation is a partial animation. Useful if the target offsets are both 0. Defaults to false

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

 

Sample Configurations
Minimum config with common options and variations
{
"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
},
]
}
Configuration with partial animations and global options
{
"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
}
]
}
Configuration targeting a different texture atlas
{
"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"
}
]
}

 

 

 

 

Version For Game version Downloads Release date Changelog Download 1-click mod install*
v0.5.0 98 Jul 27th at 3:51 PM Show libatex_0.5.0.zip Install now

2 Comments (oldest first | newest first)

💬 Jonathonsky, Nov 5th at 1:26 AM

I've been waiting for this! It sounds like optifine on minecraft.

💬 Aerra, Aug 30th at 5:02 PM

This is an amazing utility, thank you so much for your hard work!

(edit comment delete)