mcpField
F
flipbook

flipbook

github.com/drawcall-ai创意与媒体040 次安装18 周前更新
代码仓库

关于 flipbook

@drawcall/flipbook 是一个 Three.js 库，可通过 KTX2 精灵图集显示动画广告牌特效，适合在实时场景中制作美术指导风格特效的开发者，并提供播放、朝向和位置选项。

主要功能

  1. 01使用 Three.js KTX2Loader 加载翻页动画
  2. 02配置播放速度、时长和循环
  3. 03选择球形、柱形或关闭广告牌朝向
  4. 04设置精灵高度、不透明度和原点
  5. 05通过 URL 加载资源或直接提供字节数据

适用场景

  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 获取可直接使用的翻页动画素材。

对于爆炸、火焰、魔法和撞击等艺术指导型特效，预渲染精灵图集是理想选择——它的视觉效果远胜于代码生成的粒子，而且运行时几乎不消耗资源。相反，对于程序化、参数化的爆发效果（例如沿表面法线飞溅的火花、物理碎片，或每次事件的数量和方向都不同的效果），请使用池化粒子。两者可以组合使用：翻页动画爆炸加上程序化碎片爆发，效果比单独使用任一方式更好。

安装

pnpm add @drawcall/flipbook three

three 是 peer dependency。

基本用法

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 需要 Basis 转码器文件（basis_transcoder.js 和 .wasm），并且这些文件必须由你通过 setTranscoderPath 指定的路径提供。这些文件不会随包一起提供——请将它们从 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