pixelfx は何をしますか？
コードとしてのピクセルアートエフェクト。各エフェクトは1つのファイル src/fx/<カテゴリ>/<名前>.js であり、2つのバッファに描画します:
color（ピクセル: 不透明、ディザリング、または真の半透明）と light（加算発光）。画像を使用しないため、エフェクトはライブ再生、色変更、ミラーリング、シード変更、任意のエンジン用のスプライトシートへのレンダリングが可能です。
この手法はHugo Duprezのものです（How to make (good) pixel art effects with Claude）：コードは粘土であり、自分の目を信じ、参考資料を参照すること。ワンショットプロンプトでは平凡なエフェクトしか作れません。レンダリングし、見て、改良するドラフトが良いものを作ります。
最初に
- pixelfxのチェックアウト内で作業します。ワーキングディレクトリに
tools/render.mjsがない場合は、プロジェクトの隣にクローンを作成します:git clone https://github.com/patch-gg/pixelfx。インストール手順は不要です。ツールはNodeのみを使用します。 - 実行を確認します:
node tools/render.mjs fire/torchを実行するとrecords/fire/torch/contact.pngが作成されます。そのPNGを画像表示ツールで開いてください。このコンタクトシートが、今後すべてのエフェクトを確認する方法です。
1. まず既存のエフェクトを探す
node tools/list.mjs <単語> でID、名前、タグ、説明を検索します（node tools/list.mjs frost、node tools/list.mjs slash loop）。docs/CATALOG.md にはカテゴリ別の全リストが記載されています。選択する前に、候補をレンダリングして見てください。ほとんどのリクエストは、既存のエフェクトに異なるオプションを適用したものです:
palette：メインのランプ、暗から明への16進文字列。src/core/color.js内の任意のPALランプ（fire ember lava smoke dust ice water electric volt poison holy heal arcane shadow blood earth stone gold leaf wood metal bone neon cyber matrix candy night）、または独自のもの。青い火は{"palette": PAL.ice}です。seed：異なるが同等の表現を得るため;flip：左向きにするため;angle：回転させるため;light(0..1+)：発光強度用; さらに各エフェクト固有のノブ（meta.options内のサイズ、数、半径、テキスト、高さ...）。- コードを編集せずにオプションを試す:
node tools/render.mjs fire/torch --opts '{"palette":["#102","#215","#43a","#8cf","#fff"]}'
2. ゲームに組み込む
JSまたはTSのCanvasまたはWebGLゲーム（プレーンなCanvas、Phaser、PixiJS、Kaplay、three.js）：コードを直接使用します。依存関係はありません。src/core と必要なエフェクトファイルをコピーするか、リポジトリに依存します。
import { createFrame, clearFrame, createFx, composite } from "pixelfx"; // src/core/index.js
import * as frostNova from "pixelfx/fx/ice/frost-nova"; // src/fx/ice/frost-nova.js
const frame = createFrame(320, 180); // ゲームのピクセル解像度; ox, oy でカメラとともにスクロール
const img = new ImageData(320, 180);
const fx = createFx(frostNova, { x: hero.x, y: hero.y, flip: hero.facing < 0 });
// 毎フレーム
fx.update(dt);
clearFrame(frame);
fx.draw(frame, "back"); // キャラクターの後ろに配置するもの
drawCharacters(); // 独自のスプライト、または自分で frame.color に描画
fx.draw(frame, "front");
composite(frame, img.data, background); // 背景の上に色とライトを合成; null の場合は透明
ctx.putImageData(img, 0, 0); // その後、image-rendering: pixelated でキャンバスを拡大
if (fx.done()) removeIt(); // ワンショットは自動終了; fx.stop() でループをフェードアウト
複数のエフェクトが1つのフレームを共有できます。WebGLエンジンでは、合成されたRGBAを毎フレームテクスチャにアップロードするか、エフェクトを1回スプライトシートにレンダリングして（後述）、他のアニメーションと同様に再生します。
任意のエンジン（Godot、Unity、GameMaker、Defold、LÖVE、Bevy、Construct）：スプライトシートをエクスポートします。node tools/render.mjs ice/frost-nova --sheet を実行すると、records/ice/frost-nova/frost-nova.png（グリッド状の透明フレーム）と frost-nova.json（Asepriteスタイルのフレーム。Phaserのアトラスローダー、Godot、UnityのAsepriteインポーター、およびほとんどのツールで読み取れます; meta.pixelfx にはfps、ループ、フレームサイズ、列、ピボットがあります）が書き出されます。ピボットを meta.pixelfx.pivot（エフェクトの原点、例：足元）に設定し、最近傍フィルタリングと圧縮なしでインポートし、meta.pixelfx.fps で再生します。発光は色+アルファとしてシートに焼き付けられ、暗いシーンでは加算として読み取られます。明るいシーンの場合は、色を変えたバージョンをレンダリングするか、エフェクトを暗いレイヤーに保持します。
ライブラリ全体の場合: node tools/render.mjs <カテゴリ> --sheet でカテゴリ全体を処理します。
ヒットには背後にボディが必要です。 エフェクトだけではステッカーのように見えます。キャラクターを伴うエフェクトには act が含まれます：ボディがどのように予備動作するか、いつ停止するか、ターゲットがどのように反応するか。ゲームの構築方法に関係なく使用できます:
- 標準キャラクターを使用する場合:
createFxの代わりにcreateAct(slash, { x, y })を使用します。act.update(dt)、act.draw(frame)、そしてact.shakeで画像を揺らします。フリーズ中は自動的に静止します。node tools/act.mjs <id> --sheetで全てをスプライトシートに焼き付けます。 - ゲーム独自のキャラクターを使用する場合: タイミングを読み取ります。
slash.actまたはシートのJSON内のmeta.pixelfx.act（windup、recovery、tとfreezeを含むhits）。エフェクトの前にwindup秒間キャラクターの攻撃アニメーションを再生し、各ヒット時にエフェクトとキャラクターの両方の更新をfreeze秒間停止します。ホスト側のヒットストップは、actの有無にかかわらず、任意のエフェクトで機能します。
src/fx/moves/ には、エフェクトから連鎖した完全な攻撃（予備動作から回復まで）があります。誰かがエフェクトではなく「技」を要求した場合は、そこから始めてください。
3. 新しいものを作る
最初に docs/AUTHORING.md を読んでください：そこには契約（メタ情報、純粋エフェクト用の draw(p, t, o) またはシミュレートエフェクト用の create(o)、ローカル座標、シームレスループ、空で終了）、ツールキット、ペインターAPI、品質基準が記載されています。その後:
- アートの方向性を一行で述べる: それが何か、どのように動くか、パレット、タイミング。「フロストノヴァ：クリスタルが足元からリング状に噴出し、中心に白いフラッシュ、破片が飛び散り、床は霜で覆われたままフェードする。」
- ライブラリ内で参考資料を探す:
node tools/list.mjs <単語>を実行し、最も近い2〜3つのエフェクトファイルを読んでそのテクニックを借用します（src/core/sim.js内のParticlesとBitsは火花、煙、破片用、p.discは半透明ボリューム用、cycleはシームレスパーティクル用、tileFbmスクロールは炎と水用）。Hugo Duprezのエフェクト も最も近いものを参照してください：それらが品質基準です。彼のエフェクトが同じ画面サイズでより詳細、光、または生命感を持っている場合、あなたのエフェクトは未完成です。 - ドラフトを作成する。
node tools/new.mjs <カテゴリ>/<名前>（ループの場合は--loopを追加）で作業ファイルが得られます。方向性が未確定の場合は、3〜5の根本的に異なるドラフト（<名前>-a.js..-e.js）を作成し、すべてレンダリングして（node tools/render.mjs "<カテゴリ>/<名前>-*"）、選択する前にすべてのコンタクトシートを見てください。ユーザーがいる場合は、最も優れた2〜3つを見せてください（--gifで共有用アニメーションを作成）。 - 見て、判断し、修正する。 レンダリングし、
records/<id>/contact.pngを開き、こだわりのピクセルアーティストのように判断します。最も悪い部分を修正し、再度レンダリングします。最低3ラウンド。傑作にはもっと時間がかかります。--allですべてのフレームを表示、--mp4でフルスピードの動きを表示します。 - キャラクターが関与する場合は演技を付ける:
export const actを追加します（docs/AUTHORING.mdの「Acts」を参照）。t = 0 の前の予備動作、リリースフレームでのポーズ変更、接触時のフリーズ、回復を含みます。node tools/act.mjs <id>は連続した12 fpsステップを表示します：コンタクトシートのサンプルではなく、これらと--mp4から動きを判断します。 - チェックする。
node tools/check.mjs <id>は、キャンバス外への描画、空で終了しないワンショット、ループの継ぎ目、シードされていないランダム性、遅いフレーム、act内のキーの順序異常、不明なポーズフィールド、テレポートする手を検出します。チェックがクリーンに通るまで修正します。保持しなかったドラフトは削除します。
何を探すべきか、および通常の修正:
| あなたが見るもの | 修正 |
|---|---|
| 1倍でぼやけて読める | 色数を減らし、明確なシルエット、1つの焦点、より大きな形状 |
| スペックル：形状内の孤立したノイズピクセル | ノイズの閾値を下げ、at() で量子化し、小さな形状ではノイズを使用しない |
| 浮遊感があり、パンチがない | 速入り遅出し（ease.outQuart/outExpo）、1〜2フレームの白いヒーローフレーム、より短い合計時間 |
| 硬い、または機械的 | すべてのパーティクルを変化させる（サイズ、速度、遅延、寿命）、二次的な動きを追加する（火花、煙、破片） |
| 色あせている | 発光を減らす（k 0.2〜0.5）、エッジステップを暗くし、白は最も熱いコアのみに残す |
| 平坦 | 片側からの光：明るい左上、暗い右下ステップ; ベースに暗いランプステップ |
| 滑らかなグラデーション、ベクター風 | カラーではハードランプステップ; 柔らかさはライトと半透明の煙のみに使用 |
| 煙があるべき場所にチェッカーボード | SMOKE、VAPOUR、または DUST パーティクル、または p.disc：真に半透明で、上部にライトが当たる |
| ループがラップするときの継ぎ目 | cycle、loopNoise(phase)、セル全体の tileNoise スクロール、sin(phase * TAU * n) |
| 突然消えるワンショット | t = 持続時間の前に、縮小、ディザリングアウト、またはフェードアウトさせる |
| 死んだキャラクターに素晴らしいエフェクト | actを与える：予備動作、リリースポーズ、接触フリーズ、反応するターゲット、回復 |
| actが無重力に感じられる | 打撃と逆方向の予備動作、より長いフリーズ（最大0.2秒）、より大きなシルエット変更、シェイク |
| ヒットが同期していない | ヒットキーをあなたが目分量で決めた時間ではなく、エフェクト自身の定数に移動する |
| 武器の持ち方が悪い | 肘の曲がりを維持し、シャフトは胸の前に; スイング時、ブレードは手に遅れる; 腕は約15px伸び、それ以上伸びないので、ボディを踏み込ませる |
| 腕が交差する、またはポーズが平坦に見える | キャラクターは4分の3正面をこちらに向ける: 開いた腕の場合、近い手は左（fx < 0）、遠い手は右、turn: 1 を使用; yaw は実際にキャラクターを回転させる |
方向性エフェクトは右向き、地面エフェクトはy = 0に立ち、アクターエフェクトは o.actor（24 x 38の標準キャラクターのマスクとピクセル）をラップし、Math.random は使用しません。汎用モチーフは問題ありませんが、特定のゲームのスプライト、キャラクター、ロゴを再作成しないでください。
4. JSの代わりにネイティブコード
ゲームがJSを実行できず、スプライトシートでは不十分な場合（移動するターゲットを追跡するエフェクト、または実行時にインスタンスごとの色が必要な場合）、エフェクトを移植します。純粋エフェクトは時間の関数です。シミュレートエフェクトは src/core/sim.js 内のパーティクルをステップ実行します。2バッファのアイデア、ディザリングされたアルファ用の4x4 Bayer閾値、パレットランプルックアップを維持します。JSオリジナルとポートを並べてレンダリングし、一致することを確認します。