AnimJ（Resonite动画文件）
AnimJ
AnimJ 是 Resonite 中用于动画资产的自定义导入格式。它允许你将任意动画轨道构建为外部 JSON 文件，并将其作为原生动画资产导入。这些动画资产可用于通过 Animator 组件驱动数值，或使用 ProtoFlux 节点采样数值。
将 AnimJ 文件导入 Resonite 时使用的文件扩展名为 .animj，但这些文件内部的文本是标准 JSON 格式。
Basic Overview（基本概述）
由于 AnimJ 文件是 Resonite 中动画资产的表示形式，该文件需要包含动画资产用于驱动数值的大部分内容。这些内容包括：
- 名称
- 动画“轨道”
- 轨道类型
- 轨道的“节点”和“属性”（可以是任意内容，但旨在指定动画轨道所控制的对象）
- 轨道值类型（要动画化的数据类型）
- 轨道“关键帧”
- 每个关键帧的数据
请参阅示例以了解 animj 文件的结构，并查看架构以获取更详细的文档。
Schema（架构）
本节从更深入的技术角度介绍 AnimJ 文件的结构。
每个动画可以包含一个或多个动画轨道。Resonite 支持不同的动画轨道类型以满足不同的用途。每个动画轨道包含一个或多个表示值序列的关键帧。以下是动画可以使用的类型：
这里的字节值适用于 AnimX。
不支持的类型：
- colorX
- char
- DateTime
- TimeSpan
- decimal
- 枚举（enums）
这些类型不支持，因为它们不包含在 Resonite 代码库的 Elements.Core.AnimX.elementTypes 列表中。
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 | 使用 AnimX 以访问此功能。 |
| float3x3 | 使用 AnimX 以访问此功能。 |
| float4x4 | 使用 AnimX 以访问此功能。 |
| 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 | 使用 AnimX 以访问此功能。 |
| double3x3 | 使用 AnimX 以访问此功能。 |
| double4x4 | 使用 AnimX 以访问此功能。 |
| color | {"r": 0.2, "g": 0, "b": 1, "a": 0.85} |
| color32 | {"r": 51, "g": 0, "b": 1, "a": 217} |
| string | "Hello World!" |
Animation（动画）
基础动画对象。
| 属性 (Property) | 类型 (Type) | 描述 (Description) | 必需 (Required) |
|---|---|---|---|
name |
String | 整个动画的内部名称 | 否 |
globalDuration |
Number | 整个动画播放的时长（秒），即使你的关键帧提前结束 | 否 |
tracks |
AnimationTrack 对象数组 | 动画中包含的轨道列表 | 否，但没有则无用 |
AnimationTrack（动画轨道）
动画内部的轨道。
截至版本 2024.7.4.1347，以下属性需要按确切顺序指定，否则加载将失败：
| 属性 (Property) | 类型 (Type) | 描述 (Description) | 必需 (Required) |
|---|---|---|---|
trackType |
"Raw"、"Discrete"、"Curve" 或 "Bezier" |
用于确定每个关键帧之间的插值方式 | 是 |
valueType |
有效类型之一（字符串） | 确定整个轨道使用的值类型 | 是 |
data |
AnimationTrack 对象的其余部分（见下文） | 保存关键帧数据，以及 Node 和 Property 属性 | 是 |
注意：从 JSON 导入的 AnimationTrack 对象并不是实际存储在 Resonite 中的内容。相反，使用自定义的 JsonConverter 来读取 trackType 和 valueType 属性，然后根据这些属性使用 data 属性创建相应的对象（RawAnimationTrack<T>、DiscreteAnimationTrack<T>、CurveAnimationTrack<T>）。
因此，根据你在 trackType 中指定的类型，关键帧数据会有所不同。
Generic Animation Track Data（通用动画轨道数据）
适用于所有轨道类型的数据：
| 属性 (Property) | 类型 (Type) | 描述 (Description) | 必需 (Required) |
|---|---|---|---|
node |
String | 用于指定动画控制的对象。可与 Find Animation Track Index ProtoFlux 节点一起使用。 | 否 |
property |
String | 用于指定被动画控制的对象的字段。可与 Find Animation Track Index ProtoFlux 节点一起使用。 | 否 |
keyframes |
见下文 | 特定时间间隔的值列表，用于确定整个轨道在特定时间的值。 | 否 |
仅适用于原始动画轨道类型的数据：
| 属性 (Property) | 类型 (Type) | 描述 (Description) | 必需 (Required) |
|---|---|---|---|
interval |
Number | 每个关键帧之间线性插值所需的时间（秒）（使用此属性将忽略 globalDuration） |
否 |
Keyframes（关键帧）
包含动画轨道在特定时间应该具有的值的结构。
针对每种动画轨道类型有不同的结构。
Raw（原始）
此轨道类型仅在等间隔设置值。keyframes 属性只是 Raw 类型的值数组。帧之间的时间由 interval 决定。
但是，除非包含 interval 属性，否则动画轨道无法按预期工作。
Discrete（离散）
此轨道类型在指定的时间设置值。
这些关键帧是对象：
| 属性 (Property) | 类型 (Type) | 描述 (Description) | 必需 (Required) |
|---|---|---|---|
time |
Number | 自动画开始以来经过的时间（秒），在该时间点应应用随附的 value 属性。 |
是 |
value |
在 valueType 属性中设置的类型。请参阅值示例以了解每种类型的表示形式。 |
将被设置的值 | 是 |
Curve（曲线）
此轨道类型在指定的时间设置值，并在帧之间插值以达到这些值。
这些关键帧是对象：
| 属性 (Property) | 类型 (Type) | 描述 (Description) | 必需 (Required) |
|---|---|---|---|
time |
Number | 自动画开始以来经过的时间（秒），在该时间点应通过插值达到随附的 value 属性。 |
是 |
value |
在 valueType 属性中设置的类型。请参阅值示例以了解每种类型的表示形式。 |
将被设置的值 | 是 |
interpolation |
"Linear"、"Tangent"、"Hold" 或 "CubicBezier" |
请参阅 KeyframeInterpolation | 是 |
leftTangent |
在 valueType 属性中设置的类型。请参阅值示例以了解每种类型的表示形式。 |
请参阅 KeyframeInterpolation | 仅当 interpolation 设置为 "Tangent" 或 "CubicBezier" 时 |
rightTangent |
在 valueType 属性中设置的类型。请参阅值示例以了解每种类型的表示形式。 |
请参阅 KeyframeInterpolation | 仅当 interpolation 设置为 "Tangent" 或 "CubicBezier" 时 |
CubicBezier
CubicBezier 表示三次贝塞尔曲线算法，其中使用四个点来创建两个关键帧之间数据的曲线。在下面的示例 GIF 中，P0 是当前关键帧的 value，P1 是当前关键帧的 rightTangent，P2 是下一个关键帧的 leftTangent，P3 是下一个关键帧的 value。黑点表示两个关键帧之间的当前值。这也意味着你不需要第一个关键帧的 leftTangent，也不需要最后一个关键帧的 rightTangent。.
Examples（示例）
动画轨道的典型结构如下：
{
"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
}
]
}
}
]
}
以下是一个带有 float3 类型的轨道示例：
{
"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（动画轨道）
动画轨道是一个单一的值时间线。你可以在一个动画中拥有任意多个动画轨道。每个轨道可以通过 Node 和 Property 唯一标识。
Node 指示给定轨道控制层级中的哪个对象，而 Property 指定当动画绑定到场景对象时将控制该对象的哪个字段。例如，对于 floatQ 类型的轨道，Node "Fan Blade" 和 Property "Rotation" 可以控制旋转动画。
然而，这两者都只是名称，不需要对应于场景中的任何内容。你可以忽略名称，通过索引引用动画轨道，或者使用名称与 ProtoFlux 进行动态查找。
Animation Track Types（动画轨道类型）
Resonite 目前支持以下动画轨道类型。每种类型都针对不同的用例进行了优化。动画可以混合不同类型的轨道。
Raw Animation Track（原始动画轨道）
以下是此类轨道的示例：
{
"trackType": "Raw",
"valueType": "float",
"data": {
"node": "Test",
"property": "Test",
"keyframes": [
0.5,
0.7,
0.8,
0.9
]
}
}Discrete Animation Track（离散动画轨道）
{
"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（曲线动画轨道）
在导入 3D 模型文件时，使用此类型的动画轨道。
以下示例展示了带有线性插值关键帧的曲线动画轨道。它还有一个额外的离散动画轨道。
{
"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（贝塞尔动画轨道）
带切线的关键帧架构（用于定义贝塞尔曲线）如下：
{
"time": 10,
"value": 0,
"leftTangent" : -10,
"rightTangent" : 5,
"interpolation" : "Tangent"
}
No comments to display
No comments to display