GeckoLib 玩家兼容

GeckoLib Player Compat

GeckoLib Player Compat 是一个用于将 GeckoLib 动画应用于原版玩家模型的库。它会为每位玩家维护动画状态，并将其从服务器同步到追踪的客户端，同时允许每个模组提供并使用自己的动画资源。

功能特性

• 将 GeckoLib 骨骼变换应用于原版玩家模型，同时保留皮肤覆盖层。
• 为每位玩家提供独立的姿态（pose）和动作（action）通道。激活的动作优先于姿态。
• 将权威状态存储在玩家附件（attachment）中，并同步至玩家本人及所有追踪客户端。
• 默认使用共享的 geckolib_player:player 模型，支持为单个动作提供可选的模型覆盖。
• 允许动画通过数据驱动的锁定文件，抑制所选基础身体部位的默认原版变换。

动画资源

所有常规玩家动画均使用随附的玩家几何模型：

assets/geckolib_player/geckolib/models/player.geo.json

将每个模组的动画文件放置在其自身的命名空间中：

assets/examplemod/geckolib/animations/player_combat.animation.json

该文件被引用为 examplemod:player_combat。

您可以使用 BlockBench 与 GeckoLib Models & Animations 插件来创建和导出动画。

Java API

将 GeckoLib Player Compat 声明为必需依赖，并在调用前注册每个姿态和动作。注册可使动画在 GeckoLib 中可用，并允许服务器验证调用。

import com.iafenvoy.geckolib_player.api.PlayerAnimations;
import net.minecraft.resources.Identifier;
public final class CombatPlayerAnimations {
    public static final Identifier RESOURCE = Identifier.fromNamespaceAndPath("examplemod", "player_combat");
public static void register() {
    PlayerAnimations.registerPose(RESOURCE, "guard");
    PlayerAnimations.registerAction(RESOURCE, "slash", 12);
}

}

在逻辑服务器上使用 ServerPlayer 调用 API：

PlayerAnimations.setPose(player, CombatPlayerAnimations.RESOURCE, "guard");
PlayerAnimations.playAction(player, CombatPlayerAnimations.RESOURCE, "slash");

setPose 会替换玩家当前的姿态。playAction 会替换当前动作，并按注册的时长（以 tick 为单位）播放。当请求的动画未在相应通道中注册时，两者均返回 false。

动作可以临时使用不同的 GeckoLib 模型。姿态始终使用共享的玩家模型。

Identifier model = Identifier.fromNamespaceAndPath("examplemod", "armored_player");
PlayerAnimations.playAction(player, CombatPlayerAnimations.RESOURCE, "slash", model);

上述模型标识符解析为 assets/examplemod/geckolib/models/armored_player.geo.json。

动画锁定

锁定文件是可选的。它会在评估匹配的动画时，阻止原版 setupAnim 变换应用于指定的基础身体部位。当 GeckoLib 动画完全控制手臂、腿、身体或头部时，此功能非常有用。

对于 examplemod:player_combat，请将文件放置在此处：

assets/examplemod/geckolib_player/locks/player_combat.lock.json

锁定文件的命名空间和路径直接映射到动画资源标识符。使用与动画文件相同的 animations 对象布局：

{
  "format_version": "1.8.0",
  "animations": {
    "guard": {
      "locks": [
        "right_arm",
        "left_arm"
      ]
    },
    "slash": {
      "locks": [
        "body",
        "right_arm",
        "left_arm"
      ]
    }
  }
}

支持的锁定名称为 head、body、right_arm、left_arm、right_leg 和 left_leg。皮肤覆盖部分未列出，因为它们继承匹配的基础部位变换，这能使两个皮肤层保持对齐。当原版变换应保持生效时，请省略锁定文件、动画条目或 locks 字段。

运行时行为

每位玩家拥有一个姿态通道和一个动作通道。新请求会替换同一通道中的先前动画。当动作激活时，其评估优先级高于姿态；动作结束后，姿态恢复。状态会自动发送给本地玩家及所有追踪该玩家的客户端，因此集成方无需进行特定于渲染器的网络处理。