anitty 0.1.0

Anime character animation rendering for terminals
Documentation

anitty

用 Rust 将角色动画渲染为 RGBA 帧,再通过终端图形协议显示。

支持 Sprite 帧序列、规则 PNG/WebP 图集,以及可选的 Spine 3.8 二进制素材。 输出支持 iTerm2 inline image、Kitty Graphics 和 SIXEL。渲染使用 CPU,不需要 GPU。

安装

通过 Cargo 从 crates.io 添加依赖(以下对应 0.1.0 发布版本):

cargo add anitty@0.1.0

或在应用的 Cargo.toml 中写入:

[dependencies]
anitty = "0.1.0"

启用可选的 Spine 3.8 支持:

[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 许可证见 开发与发布。

最小 Rust 示例

以下示例创建一个半透明色块,在支持 iTerm2 图片协议的终端当前光标处绘制一帧:

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。图片解码、命名动作和片段切换见 动画使用指南。

需要变换或固定取景时使用 render_with_options(time, width, height, &options); 坐标查询使用 mapping(width, height, &options)。Loop/Once 播放模式保存在动画实例上, 视觉选项按次传入。详见 渲染与坐标。

从源码运行 CLI 示例

anitty 是库,添加 Cargo 依赖后不会安装 CLI。要运行仓库提供的交互示例,先获取源码:

git clone https://github.com/aynakeya/anitty.git
cd anitty

在支持图像协议的终端中,从仓库目录运行内置角色,无需下载素材:

cargo run --release --example sprite

按 q、Esc 或 Ctrl+C 退出。示例在 Unix 上自动探测 backend;在 Konsole 中优先使用 iTerm2 PNG 保留透明效果。也可以显式指定协议:

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 与终端接入。当前实际验证平台是 Linux/Konsole; Windows 原生探测示例尚未实现,需显式指定 backend。

库与应用的职责

库负责动作采样、RGBA 渲染、变换和坐标映射,以及终端协议编码。 应用负责时钟、播放循环、暂停与调速、动作决策、终端布局、输入和终端模式。 库不会启动播放线程或自动探测终端;探测 API 由应用显式驱动。

Backend::draw 在当前光标位置绘制并 flush,调用方须串行化输出,并保证画面能放入视口。 播放结束后调用 finish 释放 backend 自身资源;它不负责清屏或恢复宿主界面。

文档

  • 文档目录:Rust API 指南与使用范围。
  • CLI 示例:图集、Spine、协议探测和单帧导出。
  • Spine 3.8:素材要求、PMA、兼容范围和限制。
  • API reference(发布后生成);本地可运行 cargo doc --no-deps --features spine-38 --open。

项目代码使用 MIT License。可选 Spine runtime 使用独立的 Spine Runtimes License,不属于 MIT 授权范围。