演员切换状态

功能描述

切换指定演员的状态。能安全提供状态帧的角色会进行新旧画面交融；其他角色会自动使用淡出、应用状态、淡入的安全转场。转场完成后继续执行剧情。

语法结构

actor change <角色名称> <新状态>

参数详解

参数	必需	示例	说明
角色	是	kona	指定要切换状态的演员名称
新状态	是	happy	指定要切换到的新状态

示例

actor change kona happy

状态切换转场

actor change 会自动选择转场方式：

1. 角色场景能提供当前与目标状态帧时，使用预乘 Alpha shader 进行像素交融。
2. 无法安全提供状态帧时，依次淡出当前角色、应用状态并淡入。
3. 转场结束后，继续执行下一条剧情命令。

在 KonadoStageController 节点的检查器中可以配置转场：

属性	默认值	说明
actor_state_transition_enabled	true	是否为演员状态切换启用淡入淡出
actor_state_transition_duration	0.3	完整转场的总时长（秒）；安全降级时淡出和淡入各占一半

关闭 actor_state_transition_enabled 或把 actor_state_transition_duration 设为 0 时，状态会立即切换。

转场不会复制角色场景。内置 AnimatedSprite2D 示例通过纯纹理状态帧实现真正交融；自定义状态帧必须完整表示角色画面，不能只包含其中一个可见部件。视频、Spine、Live2D 和无法提供完整安全状态帧的自定义角色场景会自动降级，不会重复运行脚本、音频或动态媒体。目标演员不存在或角色场景无法应用该状态时，系统会结束本次命令并继续剧情，不会一直等待。