aispritejs — Sprite 動畫狀態機

import { Aside } from ‘@astrojs/starlight/components’;

aispritejs 是一個輸入驅動的 2D sprite 動畫 runtime。你設定 inputs（speed、isGrounded、jump），它根據 JSON 定義的 transition graph 決定當前要播哪個 frame，不需要在遊戲邏輯裡硬寫 play("walk")。

核心是零依賴的純 TypeScript，不含任何 renderer import。PixiJS v8 adapter 以 subpath export 提供。

安裝

pnpm add aispritejs
# PixiJS adapter 需要額外安裝 pixi.js（optional peer）
pnpm add pixi.js

心智模型

inputs → [transition graph] → active state → (Δt) → active frame → adapter → texture

• Number input：連續值，如 speed
• Boolean input：開關，如 isGrounded
• Trigger input：一次性，消耗後自動 reset，如 jump、attack

快速開始（純核心，零依賴）

import { createSpriteAnimator } from "aispritejs";

// graph 定義：inputs、states、transitions、animations
const anim = createSpriteAnimator(graph);

// 設定 inputs
anim.setInput("speed", 4);
anim.setInput("isGrounded", true);
anim.fireTrigger("jump");

// 監聽狀態切換與非 loop clip 結束
anim.onStateChange((to, from) => console.log(from, "→", to));
anim.onComplete((state) => console.log(state, "結束"));

// 在 render loop 每幀呼叫
anim.update(deltaMs);
const frameKey = anim.activeFrameKey; // 交給 renderer 使用

快速開始（PixiJS v8 adapter）

import { Assets, Sprite } from "pixi.js";
import { createPixiSpriteAnimator } from "aispritejs/pixi";

// textures 是 PIXI.Spritesheet 或 frameKey → Texture map
const view = createPixiSpriteAnimator(sprite, graph, spritesheet);

// 每幀：自動切換 sprite.texture 到當前 frame
view.update(deltaMs);

// 控制 inputs
view.setInput("speed", 4);
view.fireTrigger("jump");

Transition graph 結構範例

const graph = {
  inputs: {
    speed:       { type: "Number",  default: 0 },
    isGrounded:  { type: "Boolean", default: true },
    jump:        { type: "Trigger" },
  },
  states: {
    idle:  { animation: "idle",  loop: true },
    walk:  { animation: "walk",  loop: true },
    jump:  { animation: "jump",  loop: false, onEnd: "idle" },
  },
  transitions: [
    { from: "idle",  to: "walk", conditions: [{ input: "speed", op: "GreaterThan", value: 0 }] },
    { from: "walk",  to: "idle", conditions: [{ input: "speed", op: "Equals",      value: 0 }] },
    { from: "Any",   to: "jump", conditions: [{ input: "jump",  op: "Trigger" }] },
  ],
  animations: {
    idle: ["idle_0", "idle_1", "idle_2"],
    walk: ["walk_0", "walk_1", "walk_2", "walk_3"],
    jump: ["jump_0", "jump_1", "jump_2"],
  },
};

單一 sprite 沒有狀態切換，或只有一個 looping clip，直接用 PixiJS 的 `AnimatedSprite` 就夠了。`aispritejs` 的設計目的是**輸入驅動的多狀態切換**。

Subpath exports

Subpath	用途
aispritejs	核心：createSpriteAnimator
aispritejs/pixi	PixiJS v8 adapter：createPixiSpriteAnimator
aispritejs/atlas	Atlas 解析輔助
aispritejs/schema	JSON graph 的 Zod schema（用於驗證設計工具輸出）

常見搭配

• 與 aiecsjs 搭配：每個 entity 帶一個 SpriteAnimator，ECS system 每幀 update 並取 activeFrameKey
• 與 aifsmjs 搭配：遊戲邏輯 FSM 決定行為，輸出 inputs 給 SpriteAnimator 決定視覺
• 獨立使用：UI 動畫、角色選擇畫面等，不需要 ECS