動畫與特效

移動角色

先顯示角色，再設定移動：

[show guide expression=smile position=center]
[move guide x=80 duration=400 wait=true]
@guide
我往旁邊移動了一點。

duration=400 是 400 毫秒，wait=true 讓劇情等移動結束再繼續。需要平滑移動時使用 x、y 或 scale；單純切換位置 slot 不一定會產生滑動效果。

建立時間軸

新增 Animations/camera-pulse.pxtimeline：

{
  "format": "PrismatiXTimeline",
  "schemaRevision": 2,
  "id": "tutorial.camera-pulse",
  "name": "Camera pulse",
  "duration": 2,
  "tracks": [
    {
      "id": "camera-zoom",
      "binding": {"kind": "camera", "target": "main", "property": "zoom"},
      "keyframes": [
        {"time": 0, "value": 1, "easing": "linear"},
        {"time": 1, "value": 1.05, "easing": "easeInOut"},
        {"time": 2, "value": 1, "easing": "easeInOut"}
      ]
    }
  ],
  "markers": [],
  "nestedClips": []
}

再於專案的 assets 追加：

{
  "id": "71000000-0000-4000-8000-000000000002",
  "name": "Camera pulse",
  "kind": "timeline",
  "source": "Animations/camera-pulse.pxtimeline"
}

在已顯示背景與角色的段落中播放：

[timeline Animations/camera-pulse.pxtimeline]

時間軸的 duration 和關鍵影格 time 使用秒。這個範例讓鏡頭在兩秒內由 1 倍放大到 1.05 倍，再回到 1 倍。

軌道可綁定 stage、ui、camera、text、audio 或 shader；實際的 target 和 property 要選擇 runtime 支援的值。關鍵影格曲線有 step、linear、easeIn、easeOut、easeInOut、backOut，與 Story 移動使用的曲線名稱不同。

markers 在指定時間發出帶資料的標記，nestedClips 用來組合其他動畫。

等待與控制播放

在具有 runtime、animation 能力，並宣告 await: true 的 Extension command 中：

const resource = ctx.animation.load('Animations/camera-pulse.pxtimeline');
const handle = ctx.animation.play(resource, { speed: 1 });
await ctx.animation.wait(handle);

handle 還可用於 pause、resume、seek、finish、cancel、status、error。seek 的位置使用秒；等待請用 wait，讓引擎繼續處理畫面與輸入。

Story 的 timeline 只指定資源，需要完整播放控制時使用上述 API。

鏡頭與粒子

在已設定所需能力的 Extension 中：

ctx.stage.camera({ x: -24, y: 10, zoom: 1.08 });
ctx.stage.particles('weather.snow', 'snow', {
  seed: 42,
  rate: 60,
  maxParticles: 300,
});
// 離開這個效果的生命週期時：
// ctx.stage.clearParticles('weather.snow');

粒子預設包含 rain、snow、sakura、dust、light、motes。固定 seed 可讓原生系統重現相同的取樣結果。

Stage 也提供 group、parent、transform、order、visible，用來控制一組節點。透明度要注意單位：StageNodeTransform.opacity 使用 0–1，部分 layer／renderer 的 alpha 則使用 0–255。

自訂轉場

一般選單可直接使用內建 crossfade。需要分塊轉場時，可以註冊原生合成設定：

ctx.effects.register('tutorial.tiles', (screen) => ({
  operator: 'tiles',
  columns: 10,
  rows: 6,
  stagger: 0.42,
  order: 'row-major',
  outgoing: screen.outgoing,
  incoming: screen.incoming,
  progress: screen.progress,
  viewport: screen.viewport,
}));

程式描述轉場方式，實際每幀繪製由原生端負責。播放時用 ctx.effects.play 取得 handle，再透過 wait、stop、cancel 或 status 控制。

flash 和 fade 可用於基本圖形層級；blur、vignette、color-grade 和自訂 shader 需要 gpu-effects。

自訂 GPU 效果

在 prismatix.json 加入：

{
  "graphicsTier": "gpu-effects",
  "effects": [{"id": "dream-tone", "source": "Effects/dream-tone.pxeffect"}]
}

建立 .pxeffect 描述檔：

{
  "format": "PrismatiXEffect",
  "schemaRevision": 3,
  "id": "dream-tone",
  "targetLayer": "stage",
  "shader": "Effects/dream-tone.frag.hlsl",
  "uniforms": [
    {"name": "amount", "type": "number", "slot": 0,
      "default": 0.5, "minimum": 0, "maximum": 1}
  ]
}

還需要準備 shader 指向的 HLSL，格式見固定 shader 介面。Revision 3 支援 stage、node、transition；uniform 最多八個，名稱與 slot 不可重複，型別可選 number、vec2、color。這裡的 color 使用 0–1。

Packager 會離線編譯和檢查 shader，Player 只攜帶編譯結果。可產生的格式取決於建置平台；WASM Preview 目前沒有自訂 GPU 效果後端。

動畫中的存讀檔

Stage、Timeline 和受管理的 seed 可參與存檔與回溯。全螢幕轉場則會在還原時取消，以讀檔後的畫面為準，不會保存每張 GPU 影格。試玩時要檢查動畫中存檔、讀檔、取消和切換場景的結果。

實作參考：Timeline schema、軌道 schema、時間軸範例、Runtime SDK。