AnimJ

AnimJ is a custom import format for Animation asset files in Resonite. It allows you to build arbitrary animation tracks as external JSON files and import them as native Animation assets. Those can be used to drive values with the Animator component, or sample values with ProtoFlux nodes.

The file extension used to import AnimJ files in to Resonite is .animj, however, the text inside these files is standard JSON.

Basic Overview

Since the AnimJ file is a representation of an Animation asset in Resonite, the file needs to have most of what the Animation asset uses to animate values. These include:

Name
Animation "tracks"
Track type
Track "node" and "property" (these can be anything, but are meant to be what the animation track is controlling)
Track value type (what type of data you want to animate)
Track "keyframes"
Data for each keyframe

Please see the examples for how an animj file is structured, and take a look at the schema for more in-depth documentation.

Schema

This schema is a more in-depth, technical look on how AnimJ files are structured.

Each animation can have one or more animation tracks. Resonite supports different animation track types for different purposes. Each animation track has one or more keyframes that represent a sequence of values. These are the types an animation can use:

The byte values here are for AnimX.

Values
Name	Value	Description
`bool`	0	Byte with starting 1 bits being the value
`bool2`	1	Byte with starting 2 bits being the value
`bool3`	2	Byte with starting 3 bits being the value
`bool4`	3	Byte with starting 4 bits being the value
`byte`	4	Byte
`ushort`	5	2 Bytes
`uint`	6	4 Bytes
`ulong`	7	8 Bytes
`sbyte`	8	1 Byte
`short`	9	2 Bytes
`int`	10	4 Bytes
`long`	11	8 Bytes
`int2`	12	8 Bytes
`int3`	13	12 Bytes
`int4`	14	16 bytes
`uint2`	15	8 Bytes
`uint3`	16	12 Bytes
`uint4`	17	16 Bytes
`long2`	18	16 Bytes
`long3`	19	24 Bytes
`long4`	20	32 Bytes
`float`	21	4 Bytes
`float2`	22	8 Bytes
`float3`	23	12 Bytes
`float4`	24	16 Bytes
`floatQ`	25	16 Bytes (x,y,z,w)
`float2x2`	26	16 bytes arranged by rows starting at top left down to bottom right.
`float3x3`	27	36 bytes arranged by rows starting at top left down to bottom right.
`float4x4`	28	64 bytes arranged by rows starting at top left down to bottom right.
`double`	29	8 Bytes
`double2`	30	16 Bytes
`double3`	31	24 Bytes
`double4`	32	32 Bytes
`doubleQ`	33	40 Bytes
`double2x2`	34	32 Bytes arranged by rows starting at top left down to bottom right.
`double3x3`	35	72 Bytes arranged by rows starting at top left down to bottom right.
`double4x4`	36	128 Bytes arranged by rows starting at top left down to bottom right.
`color`	37	16 Bytes which is 4 floats for RGBA
`color32`	38	4 bytes which is 4 bytes for RGBA
`string`	39	starts with a 7 bit encoded int with the amount of string bytes. each char is 1 byte also known as UTF-8. NOTE: This begins with a nullable 1 byte boolean if being written as part of a string animation track value. (aka Discrete or Raw string animation track)

NOT Supported:

colorX
char
DateTime
TimeSpan
decimal
enums

These are not supported due to them not being contained in the Elements.Core.AnimX.elementTypes list in Resonite's codebase.

Value Examples

Data Type	Example
bool	`True`
bool2	`{"x": True, "y": False}`
bool3	`{"x": True, "y": False, "z": True}`
bool4	`{"x": True, "y": False, "z": True, "w": False}`
byte	`23`
ushort	`1200`
ulong	`2349587120938`
sbyte	`-3`
short	`-56`
int	`69`
int2	`{"x": 12, "y": -4}`
int3	`{"x": 12, "y": -4, "z": 203}`
int4	`{"x": 12, "y": -4, "z": 203, "w": 0}`
uint	`9`
uint2	`{"x": 9, "y": 4}`
uint3	`{"x": 9, "y": 4, "z": 2147483699}`
uint4	`{"x": 9, "y": 4, "z": 2147483699, "w": 1}`
long	`9876543210`
long2	`{"x": 12, "y": -4}`
long3	`{"x": 12, "y": -4, "z": 203}`
long4	`{"x": 12, "y": -4, "z": 203, "w": 0}`
float	`4.3`
float2	`{"x": 4.3, "y": 1.34}`
float3	`{"x": 4.3, "y": 1.34, "z": 2.333E+9}`
float4	`{"x": 4.3, "y": 1.34, "z": 2.333E+9, "w": -5.000000001}`
floatQ	`{"x": 1.889846E-07, "y": -0.5664063, "z": -1.762067E-07, "w": 0.8241262}`
float2x2	Use AnimX to gain access to this feature.
float3x3	Use AnimX to gain access to this feature.
float4x4	Use AnimX to gain access to this feature.
double	`4.3`
double2	`{"x": 4.3, "y": 1.34}`
double3	`{"x": 4.3, "y": 1.34, "z": 2.333E+9}`
double4	`{"x": 4.3, "y": 1.34, "z": 2.333E+9, "w": -5.000000001}`
doubleQ	`{"x": 1.889846E-07, "y": -0.5664063, "z": -1.762067E-07, "w": 0.8241262}`
double2x2	Use AnimX to gain access to this feature.
double3x3	Use AnimX to gain access to this feature.
double4x4	Use AnimX to gain access to this feature.
color	`{"r": 0.2, "g": 0, "b": 1, "a": 0.85}`
color32	`{"r": 51, "g": 0, "b": 1, "a": 217}`
string	`"Hello World!"`

Animation

The base Animation object.

Property	Type	Description	Required
`name`	String	The internal name of the whole Animation	No
`globalDuration`	Number	The amount of time in seconds the whole animation will play for (even if your keyframes end earlier)	No
`tracks`	array of AnimationTrack objects	The list of tracks that are included in the animation	No, but useless without

AnimationTrack

The track(s) inside an Animation.

As of version 2024.7.4.1347 the following properties need to be specified in the exact order or loading will fail ([1]):

Property	Type	Description	Required
`trackType`	`"Raw"`, `"Discrete"`, `"Curve"` or `"Bezier"`	Used to determine how each keyframe is interpolated between frames.	Yes
`valueType`	One of the valid types as a String	Determines what value type is used throughout the track.	Yes
`data`	The rest of the AnimationTrack object (See below)	Holds the keyframe data, as well as the Node and Property properties.	Yes

Note: The AnimationTrack object imported from the JSON isn't what actually gets stored in Resonite. Instead, a custom JsonConverter is used to read the trackType and valuetype properties, and then creates the corresponding object related to those with the data property. (RawAnimationTrack<T>, DiscreteAnimationTrack<T>, CurveAnimationTrack<T>)

Therefore, there is different keyframe data depending on what type you specify in trackType.

The data that applies to all track types:

Property	Type	Description	Required
`node`	String	Designed to be used to specify the object being controlled by the animation. Can be used with the Find Animation Track Index ProtoFlux node.	No
`property`	String	Designed to be used to specify the field of the object that is being controlled by the animation. Can be used with the Find Animation Track Index ProtoFlux node.	No
`keyframes`	See Below	A list of values at specific time intervals to determine what the whole track's value should be at specific times.	No

Data that applies to the Raw Animation Track Type only:

Property	Type	Description	Required
`interval`	Number	The time it takes in seconds to linearly interpolate between each keyframe (Using this will ignore `globalDuration`)	No

Keyframes

The data that contains what the animation track's value should be at specific times.

This is structured differently for each Animation Track Type.

Raw

This track type will set the value at equal intervals only. The Keyframes property is just an array of values for the Raw type. The time between each frame is determined by the interval. The Animation Track will not work as intended, however, unless the interval property is included.

Discrete

This track type will set the value at specified times. These keyframes are objects

Property	Type	Description	Required
`time`	Number	The elapsed amount of time in seconds since the start of the animation in which the accompanying `value` property should be applied.	Yes
`value`	The type set in the `valueType` property. See the examples for representations of each type.	The value that will be set	Yes

Curve

This track type will set the values at the specified time, and interpolate between the frames to get to those values. These keyframes are objects

Property	Type	Description	Required
`time`	Number	The elapsed amount of time in seconds since the start of the animation in which the accompanying `value` property should be reached through interpolation.	Yes
`value`	The type set in the `valueType` property. See the examples for representations of each type.	The value that will be set	Yes
`interpolation`	`"Linear"`, `"Tangent"`, `"Hold"` or `"CubicBezier"`	See Type:KeyframeInterpolation	Yes
`leftTangent`	The type set in the `valueType` property. See the examples for representations of each type.	See Type:KeyframeInterpolation	Only when `interpolation` is set to "Tangent" or "CubicBezier"
`rightTangent`	The type set in the `valueType` property. See the examples for representations of each type.	See Type:KeyframeInterpolation	Only when `interpolation` is set to "Tangent" or "CubicBezier"

CubicBezier

CubicBezier represents the cubic bezier curve alorithm, in which four points are used to create a curve of the data between two keyframes. In the example gif below, P₀ is the current keyframe's value, P₁ is the current keyframe's rightTangent, P₂ is the next keyframe's leftTangent and P₃ is the next keyframe's value. The black dot would be a representation of the current value between two keyframes. This also means you do not need a leftTangent for your first keyframe nor a rightTangent for your last keyframe.

The typical structure of animation track is following:

{   
   "name": "My Animation",
   "globalDuration": 0,
   "tracks": [
       {
           "trackType": "Discrete",
           "valueType": "float",
           "data": {
               "node": "Test",
               "property": "Test",
               "keyframes": [
                   {
                       "time": 0,
                       "value": 1
                   },
                   {
                       "time": 1,
                       "value": 42
                   },
                   {
                       "time": 5,
                       "value": 20
                   }
               ]
           }
       }
   ]
}

follows is a example track with a float3 type:

{
   "name": "Test Animation Data 1",
   "globalDuration": 0,
   "tracks": [
       {
           "trackType": "Discrete",
           "valueType": "float3",
           "data": {
               "node": "TestData",
               "property": "TestData",
               "keyframes": [
                   {
                       "time": 0,
                       "value": {
                           "x": 1.0,
                           "y": 2.0,
                           "z": 3.0
                       }
                   }
               ]
           }
       }
   ]
}

Animation Track

Animation track is a single timeline of values. You can have as many animation tracks in an Animation as you like. Each track can be uniquely identified by Node and Property.

Node indicates which object in the hierarchy given track controls, while Property specifies which of its fields will be controlled when the animation is bound to a scene objects. For example Node "Fan Blade" and Property "Rotation" for track of type floatQ can control rotation animation.

However both are just names and do not need to correspond to anything in the scene. You can ignore the names and refer to the animation track by its index or use the names for a dynamic lookup with ProtoFlux.

Animation Track Types

Resonite currently supports following animation track types. Each type is optimized for different use-case. Animation can mix tracks of different types.

Raw Animation Track

This is the simplest form of animation. It is a raw sequence of values, with a global Interval (length of the animation). The keyframes are uniformly distributed in this track. This can be ideal representation for baked animations with a regular framerate.

Here's example of such track:

{
           "trackType": "Raw",
           "valueType": "float",
           "data": {
               "node": "Test",
               "property": "Test",
               "keyframes": [
                  0.5,
                  0.7,
                  0.8,
                  0.9
               ]
           }
}

Discrete Animation Track

This track is useful for keyframes that are irregular and do not need interpolation. Each value is held for the entire duration of the keyframe, until the next one comes in. This is the type of animation track that Resonite imports subtitles as, but it can be used for any value. It can be useful also in cases you do your own custom interpolation (e.g. with Smooth Lerp) and just need to change the "master" value.

{
           "trackType": "Discrete",
           "valueType": "float",
           "data": {
               "keyframes": [
                   {
                       "time": 0,
                       "value": 2
                   },
                   {
                       "time": 1,
                       "value": 8
                   },
                   {
                       "time": 5,
                       "value": 20
                   }
               ],
               "node": "Test",
               "property": "Test"
           }
}

Curve Animation Track

This is the most versatile (and typical) type of animation track, used for values that are interpolated between. Each keyframe can use different types of interpolation (Hold, Linear and Tangent). The Tangent interpolation keyframes specify the Left and Right tangents, which indicate how the keyframe's base value changes over time as it transitions to the next keyframe.

When importing 3D Model files, this type of animation track is used.

The following example shows the Curve animation track with linear interpolation between keyframes. It also has additional Discrete animation track.

{
   "name": "Universe Timing (Czech)",
   "tracks": [
       {
           "trackType": "Curve",
           "valueType": "float",
           "data": {
               "node": "Scale",
               "property": "",
               "keyframes": [
                   {
                       "time": 0,
                       "value": -17,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 49.97,
                       "value": -17,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 97,
                       "value": -5,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 128,
                       "value": 0,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 134,
                       "value": 0,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 152,
                       "value": 5.5,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 175,
                       "value": 7,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 184,
                       "value": 7.5,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 207,
                       "value": 12,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 247,
                       "value": 27,
                       "interpolation" : "Linear"
                   }
               ]
           }
       },
       {
           "trackType": "Discrete",
           "valueType": "int",
           "data": {
               "node": "Phase",
               "property": "",
               "keyframes": [
                   {
                       "time": 0,
                       "value": 0
                   },
                   {
                       "time": 45,
                       "value": 1
                   },
                   {
                       "time": 49.97,
                       "value": 2
                   },
                   {
                       "time": 247,
                       "value": 3
                   }
               ]
           }
       }
   ]
}

Bezier Animation Track

This track is used to make animations that have handles. this is commonly used in Blender3D

The schema for keyframes with tangents (these define a bezier curve) is following:

{   
   "time": 10,
   "value": 0,
   "leftTangent" : -10,
   "rightTangent" : 5,
   "interpolation" : "Tangent"
}