mcpField
F
flipbook

flipbook

github.com/drawcall-aiクリエイティブ・メディア040 回インストール18 週間前に更新
リポジトリ

flipbook について

@drawcall/flipbookは、KTX2スプライトシートからアニメーションするビルボードエフェクトを表示するThree.jsライブラリです。リアルタイムシーンで演出重視のエフェクトを扱う開発者向けで、再生、向き、配置を調整できます。

主な機能

  1. 01Three.js KTX2Loaderでフリップブックを読み込み
  2. 02再生速度、長さ、ループを設定
  3. 03球面、円柱、ビルボード無効を選択
  4. 04スプライトの高さ、不透明度、原点を設定
  5. 05URLから読み込み、またはバイト列を指定

活用シーン

  1. 01シーンにスプライトシートの爆発や衝撃を表示
  2. 02ループする炎や火花のエフェクトを配置
  3. 03シーンエフェクトのビルボード方向を制御

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/drawcall-ai/flipbook --skill flipbook

インストール後、Claude Code で/flipbookを入力して読み込まれたか確認します。

同梱ファイルagents/openai.yaml

詳細

@drawcall/flipbook

@drawcall/flipbookを使うと、KTX2スプライトシートから読み込む軽量なThree.jsビルボードエフェクトを利用できます。すぐに使えるフリップブックアセットは@drawcall/marketから入手できます。

あらかじめレンダリングされたスプライトシートは、爆発、炎、魔法、衝撃など、アートディレクションに沿ったエフェクトに適しています。コードで生成するパーティクルより見栄えがよく、実行時のコストもほとんどかかりません。一方、サーフェス法線に沿って飛び散る火花、物理演算による破片、イベントごとに数や方向が変わるエフェクトなど、プロシージャルでパラメトリックなバーストには、プールされたパーティクルを使います。この2つは組み合わせられます。フリップブックの爆発にプロシージャルな破片のバーストを加えると、どちらか単独よりも効果的です。

インストール

pnpm add @drawcall/flipbook three

threeはピア依存関係です。

基本的な使い方

import { Flipbook } from "@drawcall/flipbook";
import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js";

const ktx2Loader = new KTX2Loader()
  .setTranscoderPath("/basis/")
  .detectSupport(renderer);
Flipbook.setKtx2Loader(ktx2Loader);

const flame = new Flipbook("/flame.ktx2", {
  height: 0.6,
  origin: "bottom-center",
  billboard: "cylindrical"
});

scene.add(flame);
await flame.ready;

function animate(deltaSeconds: number) {
  flame.update(deltaSeconds);
}

アセットのURLが事前にわかっている場合は、new Flipbook(url, options)を使います。読み込みを別の場所で制御する場合は、new Flipbook(options).load(url)または.setData(bytes)を使います。

KTX2Loaderでは、setTranscoderPathに渡すパスでBasisトランスコーダーファイル（basis_transcoder.jsと.wasm）を配信する必要があります。これらはバンドルされていないため、three/examples/jsm/libs/basis/から配信する静的ディレクトリ（例：public/basis/）にコピーしてください。これらがないと、Basis圧縮された.ktx2ファイルをデコードできず、何も描画されません。これは「フリップブックが何も表示されない」最も一般的な原因です。

アセットの入手

フリップブックアセットには@drawcall/marketをおすすめします。

npx @drawcall/market search --type flipbook "flame"

ダウンロードした.ktx2ファイルをFlipbookのURLとして使います。例：new Flipbook("/effects/flame.ktx2")。

KTX2の要件

KTX2は、Three.jsのKTX2Loaderで読み込むBasis圧縮KTX2、または非圧縮のR8G8B8A8です。

必須のメタデータ：

  • flipbook.columns
  • flipbook.rows

任意のメタデータ：

  • flipbook.aspectRatio。デフォルトは各フレームのテクスチャのアスペクト比です
  • flipbook.frames。デフォルトはcolumns * rowsです
  • flipbook.duration。デフォルトはframes / 24です
  • flipbook.playbackRate。デフォルトは1です
  • flipbook.billboard。spherical、cylindrical、noneを指定できます

オプション

  • height：ワールド空間での平面の高さです。幅はaspectRatioから決まります
  • origin：炎、松明、衝撃、地面に固定するエフェクトには"bottom-center"を使います
  • billboard：向きを自由に変えるスプライトには"spherical"、Y軸方向に直立させるスプライトには"cylindrical"、手動で向きを設定するメッシュには"none"を使います
  • playbackRate：アセットの再生速度に乗算します
  • loop：爆発などの一度だけ再生するエフェクトではfalseにします
  • autoPlay：手動で再生を開始する場合はfalseにします
  • opacity：マテリアルの不透明度の倍率です
  • randomStart：ループするエフェクトを多数使う場合は、インスタンスの再生が同期しないようtrueのままにします

よくあるパターン

一度だけ再生する衝撃エフェクト：

const impact = new Flipbook("/impact.ktx2", {
  autoPlay: false,
  loop: false,
  origin: "bottom-center"
});

impact.restart();

ループするパーティクルを多数使う場合：

const sparks = positions.map((position) => {
  const spark = new Flipbook("/spark.ktx2", {
    height: 0.25,
    randomStart: true
  });

  spark.position.copy(position);
  scene.add(spark);
  return spark;
});

function animate(deltaSeconds: number) {
  for (const spark of sparks) spark.update(deltaSeconds);
}

デバッグ

  • 何も表示されない場合は、flipbook.readyを待ち、URLのレスポンスを確認します。
  • フレームがおかしい場合は、flipbook.columns、flipbook.rows、flipbook.framesのメタデータを確認します。
  • スプライトの向きがおかしい場合は、spherical、cylindrical、noneを切り替えます。
  • エフェクトが浮いたり沈んだりする場合は、メッシュの位置を調整する前にoriginを調整します。
  • 一度だけ再生するエフェクトがループする場合は、loop: falseにします。

コメント

Markdown 対応