# 多动作定义与切换
Sprite 与 Spine 共用 `Animation` 的动作接口,支持 `&mut dyn Animation`:
| `animations()` | 按来源/定义顺序返回 `(名称, 真实时长)`,静态 Spine 动作可为零时长 |
| `animation_name()` | 查询当前动作名 |
| `set_animation(name)` | 按名称硬切换;同名选择不做额外工作;未知名称返回 `Error::AnimationNotFound` |
动作列表不为空,名称唯一且包含当前动作。`duration()`/`clip_duration()` 对应当前动作。
切换本身不持有或重置时钟。后续 `render(time, width, height)` 中的时间相对于所选动作:
从头播放就传零,指定中间时刻就传相应局部时间。
`playback_mode()`/`set_playback_mode(mode)` 查询与设置实例级的 Loop/Once,切换动作后保留;
`is_finished(elapsed)` 按当前模式和所选动作的真实时长判断。模式默认 Loop,不为各片段分别保存。
固定 view、变换与 opacity 仍由每次渲染传入,与动作选择独立。
切换失败后原选择仍可使用;改变尺寸、查询动作或重复渲染不会推进播放或触发事件。
## RGBA 输入与图片解码
`RgbaFrame::new(width, height, pixels)` 接收并持有 `Vec<u8>`,不复制输入。
尺寸必须非零,缓冲长度必须恰为 `width × height × 4`,且大小可寻址。
像素从左上角按行紧密排列,无行填充,通道顺序为 RGBA8,RGB 为 sRGB,alpha 为非预乘。
`pixels()` 借用读取,`pixels_mut()` 可原地修改通道,但不能改变已验证的缓冲长度。
`SpriteAnimation::new(frames, frame_duration)` 接收至少一帧,所有帧尺寸相同,帧时长非零。
图集通过 `from_sheet(sheet, cell_width, cell_height, frame_duration)` 切分:
网格无外边距、无间隔,图集宽高必须整除单元格宽高。
图片解码由调用方完成。以下示例需要在应用的 `Cargo.toml` 中直接声明 `image`:
```toml
[dependencies]
image = { version = "0.25", default-features = false, features = ["png", "webp"] }
```
```rust,no_run
use std::time::Duration;
use anitty::{RgbaFrame, SpriteAnimation};
let image = image::open("character.webp")?.into_rgba8();
let sheet = RgbaFrame::new(image.width(), image.height(), image.into_raw())?;
let sprite = SpriteAnimation::from_sheet(sheet, 64, 64, Duration::from_millis(100))?;
# Ok::<(), anitty::Error>(())
```
PNG/WebP 使用同一个 RGBA 入口;`from_sheet` 不负责动画 WebP 的逐帧解码,也不读取动作元数据。
第三方解码器只要提供相同的 RGBA 格式也可接入。
## Sprite 定义
`SpriteAnimation::new`/`from_sheet` 默认创建一个名为 `default`、
包含全部源帧的动作。`from_sheet` 仍将规则图集从左到右、从上到下展平,不自动把行解释为不同动作。
用 `set_clips(Vec<SpriteClip>)` 替换全部动作定义,并选择第一项:
```rust
use std::time::Duration;
use anitty::{Animation, RenderOptions, RgbaFrame, SpriteAnimation, SpriteClip, Transform};
// 实际应用也可用 image 解码图集,再通过 from_sheet 切出源帧。
let frames = (0..6)
.map(|i| RgbaFrame::new(1, 1, vec![i * 40, 0, 0, 255]))
.collect::<Result<Vec<_>, _>>()?;
let mut sprite = SpriteAnimation::new(frames, Duration::from_millis(80))?;
sprite.set_clips(vec![
SpriteClip {
name: "idle".into(),
frames: 0..2,
frame_duration: Duration::from_millis(140),
},
SpriteClip {
name: "walk".into(),
frames: 2..6,
frame_duration: Duration::from_millis(80),
},
])?;
// 从这里开始,同一调用方式也适用于 SpineAnimation。
let actor: &mut dyn Animation = &mut sprite;
actor.set_animation("walk")?;
assert_eq!(actor.clip_duration(), Duration::from_millis(320));
let options = RenderOptions {
transform: Transform {
scale: [-1.0, 1.0], // 水平镜像;与动作选择独立
translation: [12.0, 0.0],
..Transform::default()
},
..RenderOptions::default()
};
let frame = actor.render_with_options(Duration::from_millis(80), 128, 128, &options)?;
assert_eq!((frame.width(), frame.height()), (128, 128));
# Ok::<(), anitty::Error>(())
```
`frames` 是从零开始、包含起点但不包含终点的源帧范围,允许不同动作重叠引用源帧。
`frame_duration` 是该动作每帧的固定时长,不要求所有动作使用相同间隔。
切换只更改选择,不解码图集或复制帧像素;所有源帧仍使用同一个逻辑尺寸。
定义要求:列表非空、名称非空且唯一、范围非空且不越界、帧间隔非零、总时长可表示。
`set_clips` 先验证完整定义,再替换;失败后动作列表、选择和渲染能力均保持。
内部透明帧不会被忽略;是否省略图集末尾的空格由导入方明确决定。
目前不支持任意帧索引序列、单动作内不同帧时长或裁剪图集元数据。
## 切换、重播与宿主时间
切换到动作开头的完整调用示例:
```rust
use std::time::Duration;
use anitty::{Animation, RgbaFrame, SpriteAnimation};
fn restart_at_beginning(actor: &mut dyn Animation, name: &str) -> Result<(), anitty::Error> {
actor.set_animation(name)?;
let frame = actor.render(Duration::ZERO, 64, 64)?;
assert_eq!(frame.width(), 64);
Ok(())
}
let frame = RgbaFrame::new(1, 1, vec![255, 255, 255, 255])?;
let mut actor = SpriteAnimation::new(vec![frame], Duration::from_millis(100))?;
restart_at_beginning(&mut actor, "default")?;
# Ok::<(), anitty::Error>(())
```
应用在需要从头开始时重置自己的局部时间,后续逐帧递增该时间。
同名 `set_animation` 是无操作,不能用它代替时钟重置;也不要每帧都将时间设为零。
切换不保存每个动作上次播放到的位置,是否恢复进度由应用决定。
移动方向改变可以只调整 `RenderOptions::transform.scale` 的符号,不必重新开始动作。
变换作用于输出画布内部;角色在终端界面中的布局位置仍由宿主管理。
Spine 切换到不同动作时会测量自动边界;跨动作需要固定比例和原点时,复用同一个 `options.view`。
当前切换没有过渡混合。动作队列、业务状态机和完成通知由应用驱动,
库提供 `set_animation`、`clip_duration` 和 `is_finished` 等基础操作。
按时间采样、暂停、调速和结束帧的语义见 [渲染与坐标](rendering.md)。
从终端测试多个动作的方法见 [CLI 示例](examples.md)。