react-native-skia-sprite-animator v0.3.0 をリリースしました

React Native/Expo 上で Skia スプライトアニメーションを扱うための UI 非依存ライブラリ react-native-skia-sprite-animator が v0.3.0 になりました。今回のリリースは「エディタロジック」をテーマに、アプリ固有の UI に接続できるヘッドレスな編集ツールキットを提供します。

• GitHub: https://github.com/batako/react-native-skia-sprite-animator
• Release notes: https://github.com/batako/react-native-skia-sprite-animator/releases/tag/v0.3.0
• npm: https://www.npmjs.com/package/react-native-skia-sprite-animator

目次

1. v0.3.0 のハイライト
2. useSpriteEditor Hook で状態管理を一手に
3. テンプレートシステムで JSON を好きな形に
4. SpriteEditUtils でスナップやヒットテストを簡単に
5. SpriteAnimator / spriteStorage との連携ワークフロー
6. アップグレード方法と互換性
7. ドキュメント・テストの整備状況
8. 次のロードマップ

1. v0.3.0 のハイライト

• ヘッドレスエディタツールキット: useSpriteEditor, SpriteEditUtils, SpriteTemplate 群を追加。UI を持たないため、ボタンやジェスチャー、ホットキーなど好きな操作に組み込めます。
• テンプレートによる import/export: DefaultSpriteTemplate は spriteStorage 互換 JSON を生成／読込。独自テンプレートを実装すればクラウド同期や独自フォーマットも扱えます。
• ドキュメント刷新: README と docs/editor_api.{md,ja.md} に API 詳細とパターン集を追加し、英日どちらでも同じ情報にアクセス可能にしました。
• 品質向上: Undo/Redo の履歴管理やクリップボード複製、フレーム並べ替えなどを網羅する Jest テストと ESLint/Prettier ベースの CI を整備しました。

2. useSpriteEditor Hook で状態管理を一手に

useSpriteEditor はフレーム配列、アニメーション、選択状態、クリップボード、履歴、メタ情報までをまとめて扱う React Hook です。UI 層は自由に実装でき、Hook が提供するメソッド群にイベントを結びつけるだけでエディタのコア機能が揃います。

import { useSpriteEditor } from 'react-native-skia-sprite-animator';

export function EditorScreen() {
  const editor = useSpriteEditor({ historyLimit: 100 });

  return (
    <>
      <Button title="Add Frame" onPress={() => editor.addFrame({ x: 0, y: 0, w: 64, h: 64 })} />
      <Button title="Undo" onPress={editor.undo} disabled={!editor.canUndo} />
      <Button title="Paste" onPress={() => editor.pasteClipboard()} disabled={!editor.state.clipboard.length} />
    </>
  );
}

主な API:

• state: frames, animations, animationsMeta, selected, clipboard, history, meta 等すべての状態を保持。選択はフレーム ID 基準なので並べ替えでも壊れません。
• addFrame, updateFrame, removeFrame(s), reorderFrames: カーソルやアニメーション参照を自動調整。
• setSelection, selectFrame, selectAll, clearSelection: Shift/Command 風の選択 UI にそのまま対応可能。
• copySelected, cutSelected, pasteClipboard({ index }): クリップボードは ID を振り直したクローンを保持。
• undo, redo, canUndo, canRedo: 既定で 50 スナップショットまで保持。historyLimit で調整できます。
• setAnimations, setAnimationsMeta, updateMeta: アニメーション名やメタ情報 (displayName など) 更新を一元化。
• exportJSON(template?), importJSON(data, template?), reset(nextState?): テンプレート対応の入出力と初期化。

選択 + クリップボードの例

const { state, copySelected, pasteClipboard } = useSpriteEditor();

const onCopy = () => {
  if (!state.selected.length) return;
  copySelected();
};

const onPaste = () => {
  pasteClipboard(); // 選択されている最後のフレーム直後に挿入
};

3. テンプレートシステムで JSON を好きな形に

SpriteTemplate インターフェースを実装すると import/export の構造を差し替えられます。デフォルトでは spriteStorage と同じ JSON を吐き出す DefaultSpriteTemplate が使われます。

interface SpriteTemplate<TData = unknown> {
  name: string;
  version: number;
  toJSON(state: SpriteEditorSnapshot): TData;
  fromJSON?(data: TData): Partial<SpriteEditorSnapshot> | null;
}

活用シナリオ:

• DefaultSpriteTemplate でそのまま saveSprite に渡し、開発中のエディタ → ランタイム → ファイル保存までを一本化。
• exportJSON(customTemplate) で DCC ツールや社内仕様に合わせた JSON を生成。
• importJSON(payload, template) でクラウド上のデータをローカル編集へ持ち帰り、Undo できる状態でロード。

import { DefaultSpriteTemplate } from 'react-native-skia-sprite-animator';

const snapshot = editor.exportJSON(); // = DefaultSpriteTemplate
await saveSprite({ imageTempUri, sprite: snapshot });

const legacy = await loadSprite(id);
editor.importJSON(legacy, DefaultSpriteTemplate); // Undo で戻せる

4. SpriteEditUtils でスナップやヒットテストを簡単に

SpriteEditUtils は UI 実装で頻出するジオメトリ処理をヘルパー化しています。

関数	役割
snapToGrid(value, gridSize, origin?)	グリッドスナップ (origin 省略時は 0)。
normalizeRect(rect)	幅/高さが負の矩形を補正して常に正値に。
pointInFrame(point, rect)	ポインタ位置が矩形内か判定するヒットテスト。
mergeFrames(frames)	複数フレームを覆うバウンディングボックスを返す。

キャンバス上のドラッグハンドルやマーキー選択、ショートカットによる整列処理など、UI 実装時の下回りロジックとして活用できます。

5. SpriteAnimator / spriteStorage との連携ワークフロー

v0.3.0 でもランタイム側 (SpriteAnimator, spriteStorage) の API は変わっていません。エディタで作った JSON をそのままランタイムに渡せば、Skia 上での再生や Expo FileSystem での保存が実現できます。

1. useSpriteEditor でフレームやアニメーションを編集
2. exportJSON() (既定で DefaultSpriteTemplate) で JSON を取得
3. SpriteAnimator に渡してプレビューする、または saveSprite() で expo-file-system に保存
4. loadSprite() で読み込んだ JSON を importJSON() でエディタに戻す

SpriteAnimator は v0.2 で導入した Imperative Handle / イベント群（play, pause, setFrame, onFrameChange, onAnimationEnd など）をそのまま利用できるため、エディタプレビューもシンプルに組み込めます。

6. アップグレード方法と互換性

npm install react-native-skia-sprite-animator@^0.3.0
npx expo install react-native @shopify/react-native-skia expo-file-system

• ランタイムの JSON スキーマは v0.2 から変更なし。
• エディタ内部ではフレームごとに id を持ちますが、exportJSON 時に除去されるため、SpriteAnimator や spriteStorage 側の変更は不要。
• Undo 履歴はデフォルト 50 件。必要に応じて historyLimit を調整してください。

7. ドキュメント・テストの整備状況

• README (英/日) に Editor API セクションを追加。
• docs/editor_api.md / docs/editor_api.ja.md でオプション・戻り値・テンプレート実装例を網羅。
• useSpriteEditor の履歴管理や SpriteEditUtils の挙動を確認する Jest テストを追加。
• ESLint + Prettier + CI を更新し、フォーマットと型カバレッジを高めました。

8. 次のロードマップ

• v0.4: Editor API + SpriteAnimator を組み合わせた簡易スタンドアロンエディタ (Snack or Expo App) 公開を目指します。
• v0.5: JSON テンプレート拡張や配布形態の最適化、デモ UI の強化を計画中です。

---

react-native-skia-sprite-animator が、React Native/Expo における 2D スプライト制作フローをさらに快適にする一助となれば幸いです。🧑‍🎨