# anitty
用 Rust 将角色动画渲染为 RGBA 帧,再通过终端图形协议显示。
支持 Sprite 帧序列、规则 PNG/WebP 图集,以及可选的 Spine 3.8 二进制素材。
输出支持 iTerm2 inline image、Kitty Graphics 和 SIXEL。渲染使用 CPU,不需要 GPU。
## 安装
通过 Cargo 从 crates.io 添加依赖(以下对应 `0.1.0` 发布版本):
```sh
cargo add anitty@0.1.0
```
或在应用的 `Cargo.toml` 中写入:
```toml
[dependencies]
anitty = "0.1.0"
```
启用可选的 Spine 3.8 支持:
```toml
[dependencies]
anitty = { version = "0.1.0", features = ["spine-38"] }
```
默认提供 Sprite 和全部三个终端 backend;`spine-38` 额外启用 Spine 3.8,`spine` 是它的别名。
使用 crates.io 依赖与从源码构建具有相同的功能。Spine 是动画来源,iTerm2/Kitty/SIXEL 是终端输出 backend,
可自由组合。
默认构建不需要 C 编译器;启用 Spine 后需要 C 工具链。固定版本的 runtime 源码随 crate 分发,
由构建脚本编译并静态链接,无需另行下载或安装 spine-c,也无需部署其动态库。
构建要求及独立的 Spine 许可证见 [开发与发布](https://github.com/aynakeya/anitty/blob/main/docs/development.md)。
## 最小 Rust 示例
以下示例创建一个半透明色块,在支持 iTerm2 图片协议的终端当前光标处绘制一帧:
```rust,no_run
use std::{io, time::Duration};
use anitty::{Animation, Backend, Iterm2, RgbaFrame, SpriteAnimation};
fn main() -> Result<(), anitty::Error> {
let source = RgbaFrame::new(16, 16, [255, 128, 64, 192].repeat(16 * 16))?;
let mut animation = SpriteAnimation::new(vec![source], Duration::from_millis(100))?;
let mut backend = Iterm2;
let mut output = io::stdout().lock();
let frame = animation.render(Duration::ZERO, 64, 64)?;
backend.draw(frame, &mut output)?;
backend.finish(&mut output)?;
Ok(())
}
```
`render(time, width, height)` 返回借用的、指定像素尺寸的 `RgbaFrame`。
后续传入新的局部时间即可播放;支持向后跳转。宽高每次传入,内部复用输出缓冲区,
不需要先调用 resize。图片解码、命名动作和片段切换见 [动画使用指南](https://github.com/aynakeya/anitty/blob/main/docs/animations.md)。
需要变换或固定取景时使用 `render_with_options(time, width, height, &options)`;
坐标查询使用 `mapping(width, height, &options)`。Loop/Once 播放模式保存在动画实例上,
视觉选项按次传入。详见 [渲染与坐标](https://github.com/aynakeya/anitty/blob/main/docs/rendering.md)。
## 从源码运行 CLI 示例
`anitty` 是库,添加 Cargo 依赖后不会安装 CLI。要运行仓库提供的交互示例,先获取源码:
```sh
git clone https://github.com/aynakeya/anitty.git
cd anitty
```
在支持图像协议的终端中,从仓库目录运行内置角色,无需下载素材:
```sh
cargo run --release --example sprite
```
按 `q`、`Esc` 或 `Ctrl+C` 退出。示例在 Unix 上自动探测 backend;在 Konsole 中优先使用
iTerm2 PNG 保留透明效果。也可以显式指定协议:
```sh
cargo run --release --example sprite -- --backend iterm2
cargo run --release --example sprite -- --backend kitty
cargo run --release --example sprite -- --backend sixel --sixel-background '#242828'
cargo run --example probe
```
SIXEL 会将透明像素合成到实色背景,不能保留半透明。不同终端的图像替换语义也可能不同,
详见 [backend 与终端接入](https://github.com/aynakeya/anitty/blob/main/docs/backends.md)。当前实际验证平台是 Linux/Konsole;
Windows 原生探测示例尚未实现,需显式指定 backend。
## 库与应用的职责
库负责动作采样、RGBA 渲染、变换和坐标映射,以及终端协议编码。
应用负责时钟、播放循环、暂停与调速、动作决策、终端布局、输入和终端模式。
库不会启动播放线程或自动探测终端;[探测 API](https://github.com/aynakeya/anitty/blob/main/docs/terminal.md) 由应用显式驱动。
`Backend::draw` 在当前光标位置绘制并 flush,调用方须串行化输出,并保证画面能放入视口。
播放结束后调用 `finish` 释放 backend 自身资源;它不负责清屏或恢复宿主界面。
## 文档
- [文档目录](https://github.com/aynakeya/anitty/blob/main/docs/README.md):Rust API 指南与使用范围。
- [CLI 示例](https://github.com/aynakeya/anitty/blob/main/docs/examples.md):图集、Spine、协议探测和单帧导出。
- [Spine 3.8](https://github.com/aynakeya/anitty/blob/main/docs/spine.md):素材要求、PMA、兼容范围和限制。
- [API reference](https://docs.rs/anitty/0.1.0/anitty/)(发布后生成);本地可运行 `cargo doc --no-deps --features spine-38 --open`。
项目代码使用 [MIT License](https://github.com/aynakeya/anitty/blob/main/LICENSE)。可选 Spine runtime 使用独立的
[Spine Runtimes License](https://github.com/aynakeya/anitty/blob/main/vendor/spine-c/3.8/LICENSE),不属于 MIT 授权范围。