工艺-动画

Craft Animation

Craft Animation 是一个适用于 Forge 模组开发的可复用动画库。

它本身并不是一个直接添加武器、生物或游戏系统的内容模组。相反，它提供了一个共享的动画基础框架，其他模组可以用它来以一致的方式加载、播放、采样和应用动画。其目标是通过一个通用的运行时结构来支持玩家、生物、通用实体、方块、方块实体、物品以及基于显示的渲染对象。

支持的目标

• 玩家
• 生物
• 通用实体
• 方块
• 方块实体
• 物品
• 基于显示的渲染对象

包含的系统

• 共享动画目标类型
• 基于关键帧的片段结构
• 缓动支持
• 用于播放、停止、循环和播放速度的控制器
• 活跃动画主体的运行时追踪
• 基于 JSON 的动画加载
• 示例动画资源

支持的格式 Craft Animation 围绕两种主要的输入路径设计：

• 通用的内置 JSON 片段格式
• Emotecraft 风格的表情 JSON 加载

这意味着你可以直接编写自己的片段格式，或者将现有的玩家动画数据结构作为流程的一部分重复使用。

如何在你的模组中连接和使用它 该库旨在连接到你自己的渲染器、模型或游戏代码。它本身不会自动将完成的动画注入到每个原版渲染路径中。正常的工作流程如下：

1. 创建一个动画 JSON 文件 示例位置：

assets/yourmod/animations/guardian_idle.json

你可以使用内置的示例文件作为参考：

assets/craftanimation/animations/example_idle.json

2. 加载并注册片段 通过 CraftAnimationApi.library() 使用 AnimationLibrary。

AnimationClip clip = CraftAnimationApi.library().loadBuiltin(
    "assets/yourmod/animations/guardian_idle.json",
    getClass().getClassLoader()
);

如果片段已经注册，稍后你可以通过以下方式获取它：

AnimationClip clip = CraftAnimationApi.library().require("yourmod:guardian_idle");

3. 创建一个动画主体键 运行时通过 AnimationSubjectKey 为每个主体维护独立的动画状态。

玩家示例：

AnimationSubjectKey key = AnimationSubjectKey.player(
    level.dimension().location().toString(),
    player.getUUID()
);

生物示例：

AnimationSubjectKey key = AnimationSubjectKey.mob(
    level.dimension().location().toString(),
    mob.getUUID()
);

方块实体示例：

AnimationSubjectKey key = AnimationSubjectKey.blockEntity(
    level.dimension().location().toString(),
    pos.getX(), pos.getY(), pos.getZ()
);

4. 开始播放

CraftAnimationApi.runtime().play(key, clip);

你也可以直接访问控制器并更改播放速度：

CraftAnimationApi.runtime().controller(key).setSpeed(1.25F);

5. 每 tick 推进动画

CraftAnimationApi.runtime().tick(key, deltaTicks);

或者一次性更新所有活跃的控制器：

CraftAnimationApi.runtime().tickAll(deltaTicks);

6. 采样当前姿势

AnimationPose pose = CraftAnimationApi.runtime().sample(key);

采样的 AnimationPose 是你应用到自己玩家渲染器、实体模型、方块实体渲染器、自定义物品渲染器或显示渲染逻辑中的内容。

简而言之，正常的使用流程是：

• 加载一个片段
• 创建一个主体键
• 播放片段
• tick 运行时
• 采样姿势
• 在你的渲染/模型代码中应用姿势

典型用例

• 玩家手持自定义武器时的闲置姿态
• 生物的闲置、行走或攻击姿势
• Boss 或脚本化实体的动画播放
• 方块实体的机器或结构运动
• 基于显示的过场时间线和视觉特效

注意事项

• 此模组主要是一个面向开发者的库。
• 单独安装它不会添加主要的游戏内容。
• 最终的视觉动画结果仍然取决于消费模组如何将采样姿势应用到其渲染器或模型层。
• 运行时是共享的，但最终的实现路径对于玩家、实体、方块和自定义渲染系统是不同的。

目标用户

• Forge 模组开发者
• 需要可复用数据驱动动画系统的项目
• 希望保持一个通用动画架构的多版本模组环境