动画控制器入门指南

guide

动画控制器入门指南

状态机基础
状态机实例
动画控制器详解
控制器实例解析
- 基础双状态控制器
- 三状态进阶版
RPAC高级功能
BPAC特性
运行流程详解
高级技巧

动画控制器（AC）是一种状态机，可同时应用于资源包和行为包。在资源包中（RPAC），它们用于播放动画；在行为包中（BPAC），则用于执行命令和"命令动画"。

状态机基础

状态机是一种特殊的逻辑管理方式，基于一系列状态运作。每个状态包含两个核心属性：

当前状态下执行的操作
如何切换到其他状态

状态机在传统编程中应用广泛，不仅存在于Minecraft中！了解更多可参考此链接。

状态机同一时间只能处于一个状态。运行时，可以理解为在不同状态间切换：执行当前状态逻辑→通过transitions跳转到新状态。

状态机实例

状态机的优势在于能将动画逻辑自然地分解为流程化状态。例如直升机螺旋桨动画：

地面状态：
- 不播放动画
- 离地时切换至飞行状态
飞行状态：
- 播放旋转动画
- 着陆时返回地面状态

状态流程图解：

矩形代表状态，箭头表示状态转移。更复杂的例子可加入爆炸状态：

状态可多向跳转，也可作为终止状态（如爆炸后无需动画）。这种分支流程正是动画控制器的强大之处。

动画控制器详解

动画控制器是Minecraft特有的状态机，需放置在资源包或行为包的animation_controllers文件夹中。

绑定控制器到实体

控制器需通过两个步骤绑定实体：

在animations中定义简称
通过scripts/animate激活控制器

示例实体描述文件：

RP/entity/helicopter.ce.json 或 BP/entities/helicopter.se.json

json

"description": {
    "identifier": "wiki:helicopter",
    "animations": {
        "blade_controller": "controller.animation.helicopter.blade"
    },
    "scripts": {
        "animate": ["blade_controller"]
    }
}

条件触发示例（仅当有骑乘者时运行）：

json

"scripts": {
    "animate": [{
        "blade_controller": "q.has_rider"
    }]
}

资源包控制器(RPAC)

控制骨骼动画
绑定RP实体

行为包控制器(BPAC)

执行命令/触发事件
绑定BP实体

控制器实例解析

基础双状态控制器

RP/animation_controllers/helicopter.ac.json

json

{
    "format_version": "1.10.0",
    "animation_controllers": {
        "controller.animation.helicopter.blade": {
            "initial_state": "ground",
            "states": {
                "ground": {
                    "transitions": [{
                        "flying": "!q.is_on_ground"
                    }]
                },
                "flying": {
                    "animations": ["flying"],
                    "transitions": [{
                        "ground": "q.is_on_ground"
                    }]
                }
            }
        }
    }
}

关键要素：

初始状态设为ground
地面状态通过!q.is_on_ground检测离地
飞行状态播放动画并通过q.is_on_ground检测着陆

三状态进阶版

RP/animation_controllers/helicopter.ac.json

json

"explode": {
    "animations": ["explode"]
}

新增特性：

多条件转移（飞行中爆炸）
终止状态（爆炸后无转移）

RPAC高级功能

资源包控制器可调用音效和粒子效果，需先在实体文件中定义：

RP/entities/custom_tnt.json

json

"sound_effects": {
    "explosion": "wiki.custom_tnt.explosion"
},
"particle_effects": {
    "fuse_lit": "wiki:tnt_fuse_lit_particle"
}

控制器调用示例：

json

"explode_state":{
    "sound_effects":[{
        "effect":"explosion"
    }],
    "particle_effects": [{
        "effect": "fuse_lit"
    }]
}

注意：并非所有粒子都适用，遇到问题时建议参考烈焰人控制器的实现方案。

BPAC特性

行为包控制器新增两个字段：

on_entry：进入状态时执行的命令
on_exit：离开状态时执行的命令

命令类型包含：

斜杠命令（如/say）
实体事件（如@s wiki:transform_into_plane）
Molang表达式（如v.tickets += 1）

示例控制器：

BP/animation_controllers/helicopter.ac.json

json

"ground": {
    "on_entry": ["/say 已切换至地面模式！"],
    "transitions": [{
        "flying": "!q.is_on_ground"
    }]
}

运行流程详解

初始化阶段

实体加载时进入每个控制器的初始状态（未定义则使用default状态）。

每刻运行逻辑

执行当前状态的动画/on_entry命令
从上至下检测转移条件，首个符合条件的触发转移
状态转移时执行on_exit命令

注意：每游戏刻最多执行一次状态转移。

重置机制

当实体重载时（玩家进出、区块重载等），控制器会重置到初始状态，需确保默认状态能正确处理动画重启。

高级技巧

可在控制器中创建并重映射变量：

json

"variables": {
    "ground_speed_curve": {
        "input": "q.ground_speed",
        "remap_curve": {
            "0.0": 0.2,
            "1.0": 0.7
        }
    }
}