Getting Started

Prelude 覆盖什么

ranim::prelude::* 覆盖日常作者 API：Eval / IntoAnimNode / Unplaced/ PlaybackExt 等动画协议，AnimSequence / AnimStack / AnimLagged 与seq! / stack! / lagged!，Pure / Iterative / Static，Sound /AudioClip，以及 RanimScene / TimeMark / App / Plugin。

以下类型有意不放进 prelude，需要时显式导入：

use ranim_core::audio::AudioError;
use ranim_core::animation::build::{At, Paramed};
use ranim_core::animation::node::{AnimNode, AnimationInfo};
use ranim_core::frame::EvaluatedFrame;

• EvaluatedFrame：读取求值结果或直接驱动渲染时使用；

• AnimNode / AnimationInfo：运行时 introspection API；

• At / Paramed：需要给返回值命名的 timing wrapper；

• AudioError：音频解码/文件错误处理。

用 Plugin 组织项目（可选）

ranim::Plugin 就是 bevy 的 Plugin。插件持有自己的配置，在 build 中安装项目能力——build 的签名是 fn build(&self, app: &mut bevy_app::App)；ranim::App 与 bevy_app::App 是同一类型，写成 &mut App 完全等价。场景注册等方法由 AppExt trait（prelude 已导出）在 App 上提供。场景变多、需要跨二进制复用，或要携带自定义渲染配置时，把它们收进插件：

// 追加到 src/lib.rs
pub struct DemoScenesPlugin;

impl Plugin for DemoScenesPlugin {
    fn build(&self, app: &mut App) {
        app.add_scenes([hello::scene()]);
    }
}

二进制入口安装库导出的插件，场景定义仍留在 lib 中：

// src/main.rs（native）
use my_animation::DemoScenesPlugin;
use ranim::prelude::*;

fn main() {
    let mut app = App::new();
    app.add_plugins(DemoScenesPlugin);
    run_cli(app.build());
}

宿主既可以直接安装插件类型，也可以安装另一个 crate 的普通 Rust 工厂函数：

let mut app = App::new();
app.add_plugins(DemoScenesPlugin);

// 在另一个应用中使用这个 crate：
let mut app = App::new();
app.add_plugins(my_project::plugin());

插件在添加时执行构建，也可以通过 app.add_plugins(...) 继续安装依赖插件。多个插件可写成元组，例如 app.add_plugins((GeometryPlugin, TextPlugin))。带配置的插件直接构造，例如 DemoPlugin { quality: 4 }，不要求实现 Default。项目资源就是 bevy world 资源：app.insert_resource(...) 存入（类型需#[derive(Resource)]，ranim::Resource 已再导出），经 app.world() 读取；多个项目互不共享全局注册表。

自定义渲染配置（可选）

渲染配置依赖 ranim 的 render feature（默认的 cmd-preview 会间接启用它）。启用 items 的项目未注册RenderSetup 时，渲染与预览使用的默认配置等价于：

RenderSetup::new(|render_app| {
    render_app.add_plugins(RanimItemsPlugin);
})

ranim_items::RanimItemsPlugin 捆绑三个内置物件插件（CameraFramePlugin、VItemPlugin、MeshItemPlugin），覆盖裸内置类型与 Vec<VItem>。它与三个单件插件互斥：Bevy 插件在 App 内唯一，重复安装会 panic。

关闭 items 时默认配置为空，通用 render 不会引入内置物件；自定义渲染项目通过 RenderSetup 安装自己的插件。

若完整输出是默认配置未覆盖的类型——如 Vec<Circle>、Transformed<T, G> 或自定义类型——在插件中注册自己的 RenderSetup，为实际完整类型加入ExtractPlugin<T>（只注册 T 不会读取这些组合）：

use ranim::{
    items::RanimItemsPlugin,
    render::{RenderSetup, extract::ExtractPlugin},
};

pub struct ProjectPlugin;

impl Plugin for ProjectPlugin {
    fn build(&self, app: &mut bevy_app::App) {
        app.add_scenes([hello::scene()]);
        app.insert_resource(RenderSetup::new(|render_app| {
            render_app.add_plugins((
                RanimItemsPlugin,
                ExtractPlugin::<MyOutput>::default(),
            ));
        }));
    }
}

RenderSetup 是 bevy Resource，保存在项目 App 中，preview / output 从所属App 取得并在每次安装渲染 SubApp 时重放，分辨率变化和后台导出也使用同一项目的配置。保存 setup 不会初始化 GPU，纯 CPU 求值与 inspect 也不执行该回调。详见完整求值帧与渲染提取。

hold 与 forward

forward 表示明确的空白时间；hold 表示把当前状态延长一段时间。新模型不会隐式认为一个动画结束后物件仍然存在。

sequence
    .push(square.fade_in())
    .hold(1.0)    // 保持淡入后的状态
    .forward(0.5) // 接下来 0.5 秒没有该 Sequence 的输出
    .push(circle.fade_in());

show 与 hide

show() 和 hide() 是用于 Sequence 状态切换的零时长事件。cursor 上出现状态事件时，后续 hold 使用这些事件组成新的完整状态快照，不再继承左侧状态。

sequence
    .push(square.show())
    .hold(1.0)
    .push(square.hide())
    .hold(1.0);

hide 不会跨 Sequence 查找同一个 item。需要独立显示/隐藏的内容应放在独立 Sequence 中，再通过根 Stack 并行组合。

WASM 预览宿主

WASM 的入口同样来自宿主装配，不限制场景源码的位置：场景可以继续放在 lib 中，入口从库中取得描述符或 Plugin，再导出 app() -> WasmApp。本节展示仓库 example 的写法；普通项目的 src/lib.rs + src/main.rs 完整示例见项目入口。

命令行入口 run_cli 只面向原生目标（需要 cmd-render feature）。仓库的 example把平台入口与共享装配放在两个文件中：

examples/arc/
├── main.rs    # 唯一 bin target：native CLI / WASM 空 main 和 app() 导出
└── scenes.rs  # 共享场景、ScenesPlugin 与 RenderSetup

main.rs 声明 mod scenes。原生 main() 创建 App、安装 scenes::ScenesPlugin后调用 run_cli(app.build())；WASM 下则提供空 main()，并在同一文件中导出 app()，使用同一套装配，把定稿后的项目交给 JavaScript：

#[cfg(target_arch = "wasm32")]
#[wasm_bindgen::prelude::wasm_bindgen]
pub fn app() -> ranim::wasm::WasmApp {
    use ranim::prelude::*;

    let mut app = App::new();
    app.add_plugins(scenes::ScenesPlugin);
    ranim::wasm::WasmApp::new(app.build())
}

在根 Cargo.toml 中只声明一个 example，两种平台都使用它：

[[example]]
name = "arc"
path = "examples/arc/main.rs"
required-features = ["anims", "render"]

required-features 声明共享能力，场景所需的 typst、gltf 等 feature 也在其中。原生 CLI 还需 cmd-render，egui 预览由 cmd-preview 提供；两者默认均启用。关闭 default 的原生导出使用 anims,cmd-render，WASM 使用 anims,render。原生未开启 cmd-render 时，入口给出编译错误，提示启用该 feature。

main.rs 用函数级 cfg 切换入口；app() 导出也只在 WASM 下编译：

mod scenes;

#[cfg(not(target_arch = "wasm32"))]
fn main() { /* 创建项目，run_cli(app.build()) */ }

#[cfg(target_arch = "wasm32")]
fn main() {}

WASM bin 和 cdylib 在该平台都生成 .wasm 模块，且都支持 wasm-bindgen 导出。bin 需要 main()，wasm-bindgen 将它接入模块初始化；这里的空函数立即返回，模块与导出函数继续存在。加载模块不会自动装配项目或启动预览，JavaScript在 await init() 后显式调用 app() 创建项目，再调用 createPreview 申请 GPU。cdylib 无需 main()，但绑定运行时初始化和显式的 #[wasm_bindgen(start)]仍会在加载时执行。本项目没有声明自动启动应用的函数。独立项目仍可选择 [lib] crate-type = ["cdylib"]，开启 ranim/render 并直接依赖wasm-bindgen；库入口直接声明 mod scenes 并导出 app() 即可。

cargo build --example arc --target wasm32-unknown-unknown --no-default-features --features anims,render
wasm-bindgen --target web --out-dir pkg --out-name arc target/wasm32-unknown-unknown/debug/examples/arc.wasm

页面初始化模块后，显式选择场景并启动预览：

<canvas id="preview" width="1280" height="720"></canvas>
<script type="module">
  import init, { app } from "./pkg/arc.js";
  await init();
  const project = app();
  console.log(project.sceneNames());
  const canvas = document.getElementById("preview");
  const preview = await project.createPreview(canvas, "arc");
  project.free();
  preview.renderAt(1.5);
  // 页面卸载预览时：preview.dispose(); preview.free();
</script>

sceneNames() 返回以换行分隔的注册场景名。createPreview 的 Promise 等待GPU 与场景初始化；返回的会话提供 duration、renderAt(seconds)、resize(width, height)（物理像素）与 dispose()。播放时钟由 Web 端管理，WASM 不自行启动事件循环。每个 WasmApp 创建一次预览；需要新的预览时重新调用 app()。

仓库的 cargo examples build [EXAMPLES...] 会完成编译、wasm-bindgen和 wasm-opt。视口与控制条源码分别位于 website/static/ranim-viewport.js和 website/static/ranim-controls.js，由 Notist SSG 直接提供；为 rustdoc 等其他输出目录构建时，会把这两个组件及其音频和 timeline 模块复制到输出根目录。<ranim-viewport> 负责 canvas 和播放时钟，<ranim-controls> 通过 for绑定同一 DOM 根中的视口 ID，可放在页面任意位置；同一视口也能绑定多个控制条。JavaScript 可以用 controls.target = viewport 显式绑定，包括跨Shadow DOM 的组合。网站和 rustdoc 都用这两个组件，无需 egui：

<script type="module" src="./ranim-viewport.js"></script>
<script type="module" src="./ranim-controls.js"></script>
<ranim-viewport id="arc-view" src="./examples/arc/pkg/ranim_example.js" scene="arc"></ranim-viewport>
<ranim-controls for="arc-view"></ranim-controls>

进度条右侧的展开按钮会打开动画 timeline，显示与原生 egui 相同来源的动画树和时间片段；点击片段只选中并查看详情，点击或拖动上方时间刻度才改变进度。还可折叠子轨道、缩放时间轴。给控制条添加timeline-expanded，或设置 controls.timelineExpanded = true 可默认展开。视口在会话就绪时读取一次 WasmPreview.timeline()，通过 viewport.timeline提供元数据；播放时只更新指针，不会反复跨 WASM 读取整棵动画树。

场景有声音时，视口在初始化时读取一次 WasmPreview.audio() 的预混音声道，点击播放后通过 Web Audio 播放，画面时间跟随音频输出时钟。播放、暂停和拖动进度条会同时控制声音；暂停中定位保持安静，播放中定位从新位置继续。切换场景或卸载视口会关闭音频设备，无声音场景仍按墙钟播放。控制条的扬声器按钮可调音量或静音；同一视口的多个控制条共享设置，切换场景后保留音量。自定义宿主可设置 viewport.volume（0–1）和 viewport.muted，并监听 volumechange。

命令行：预览与渲染

项目二进制的 run_cli 提供全部命令行入口：

cargo run -- preview
cargo run -- output
cargo run -- output hello
cargo run -- render hello

不渲染、只查询场景信息时使用 inspect：

cargo run -- inspect scenes
cargo run -- inspect tree
cargo run -- inspect frame hello --at 1.0

tree 的 Scene 名称在只有一个 Scene 时可以省略；frame 必须指定 Scene 名称，--at 为采样时间（秒）。需要完整几何数据时给 frame 加 --verbose，机器可读输出加 --format json。

preview 可以接收一个可选 Scene 名称；output 可以接收零个或多个 Scene 名称，并渲染它们声明的所有 #[output(...)]；render 接收恰好一个 Scene 名称，使用默认输出设置（1920x1080、60 fps、mp4）做一次临时渲染，不读取 #[output(...)]。完整说明见命令行入口。

在本仓库中运行示例：

cargo run --example getting_started0 -- preview
cargo run --example getting_started0 --no-default-features --features anims,cmd-render -- output

带 required-features（如 typst、gltf）的示例需要同时开启对应 feature。