poku-pixel-fx は何をしますか？
POKU Pixel FX は、PixelFX by Patch をフォーク・派生した、韓国語ローカライズ済みのTypeScriptベースのオープンソースライブラリです。独立したリポジトリとして管理されており、GitHubのネットワークフォークリンクはありません。上流のMITライセンスはPatch氏とHugo Duprez氏に帰属します。LICENSE と NOTICE.md 内の著作権表示と帰属表示を保持してください。
Node.js 18以上が必要です。GIFおよびMP4プレビューにはffmpegがオプションで利用できます。
ピクセルアートエフェクトをコードで表現します。各エフェクトは src/fx/<カテゴリ>/<名前>.ts という1つのファイルで、color（ピクセル：不透明、ディザリング、または半透明）と light（加算発光）の2つのバッファに描画します。画像は使用しないため、エフェクトをライブ再生、色変更、反転、再シード、スプライトシートにレンダリングして任意のエンジンに出力できます。
手法はHugo Duprez氏の (How to make (good) pixel art effects with Claude) に基づいています：コードは粘土であり、自分の目を信じ、参考資料を見よ。ワンショットのプロンプトでは凡庸なエフェクトしか生まれません。レンダリングして見て、洗練させるドラフトが優れた作品を作ります。
その前に
package.jsonとtools/render.mtsを含むPoku Pixel FXのチェックアウトディレクトリで作業してください。存在しない場合は、ユーザーが選択したプロジェクトまたはワークスペースに公開ライブラリを取得します：git clone https://github.com/Stankjedi/poku-pixel-fx.git。スキルファイルだけではエフェクトライブラリは含まれません。他人のマシン固有のパスを決して使用しないでください。必要に応じてnpm ciでチェックアウトの依存関係をインストールします。既にインストールされている場合は繰り返さないでください。- ツールまたはギャラリーを使用する前に
npm run buildを実行します。コンパイラはランタイムモジュールをbuild/に、CLIツールをbuild-tools/に出力します。 - 動作確認：
node build-tools/tools/render.mjs fire/torchでrecords/fire/torch/contact.pngが作成されます。そのPNGを画像表示ツールで開いてください。このコンタクトシートが今後すべてのエフェクトを確認するための手段です。
1. まず既存のエフェクトを探す
node build-tools/tools/list.mjs <単語> でID、名前、タグ、説明を検索します（node build-tools/tools/list.mjs frost、node build-tools/tools/list.mjs slash loop）。docs/CATALOG.md にカテゴリ別の全リストがあります。候補をレンダリングして、選択する前に実際に見てください。ほとんどのリクエストは、既存エフェクトのオプション変更で対応できます：
palette：暗い色から明るい色へのメインランプ、16進数文字列で指定。src/core/color.ts内の任意の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で定義されています（size、count、radius、text、height...）。- コードを編集せずにオプションを試す：
node build-tools/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 "poku-pixel-fx"; // src/core/index.ts
import * as frostNova from "poku-pixel-fx/fx/ice/frost-nova"; // src/fx/ice/frost-nova.ts
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); // 背景にcolorを重ね、lightを加算; nullで透明
ctx.putImageData(img, 0, 0); // その後、キャンバスを image-rendering: pixelated で拡大
if (fx.done()) removeIt(); // ワンショットは自動で終了; fx.stop() でループをフェードアウト
複数のエフェクトで1つのフレームを共有できます。WebGLエンジンでは、毎フレーム合成したRGBAをテクスチャにアップロードするか、エフェクトをスプライトシートに一度レンダリングして（後述）、他のアニメーションと同様に再生します。
任意のエンジン（Godot、Unity、GameMaker、Defold、LÖVE、Bevy、Construct）：スプライトシートをエクスポートします。node build-tools/tools/render.mjs ice/frost-nova --sheet で records/ice/frost-nova/frost-nova.png（透明フレームがグリッド状に並んだもの）と frost-nova.json（Aseprite形式のフレーム情報。Phaserのアトラスローダー、Godot、UnityのAsepriteインポーターなどほとんどのツールで読み取り可能。meta.pokuFx にfps、ループ、フレームサイズ、列数、ピボットが含まれます）が作成されます。ピボットを meta.pokuFx.pivot（エフェクトの原点、例：足元）に設定し、最近傍補間で圧縮なしでインポートし、meta.pokuFx.fps で再生します。グローはアルファ付きの色としてシートに焼き込まれ、暗いシーンでは加算発光として機能します。明るいシーンでは、色を変えたバージョンをレンダリングするか、エフェクトを暗いレイヤーに配置してください。
ライブラリ全体を出力する場合：node build-tools/tools/render.mjs <カテゴリ> --sheet でカテゴリ全体を処理できます。
攻撃には背後にボディが必要です。 エフェクト単体ではシールのように見えます。キャラクターを伴うエフェクトには act が含まれます：ボディが予備動作をするタイミング、停止するタイミング、ターゲットがどのように反応するか。ゲームの構造に合わせて以下のように使用します：
- 標準キャラクターを使用する場合：
createFxの代わりにcreateAct(slash, { x, y })を使用。act.update(dt)、act.draw(frame)、act.shakeで画面を揺らします。停止中は自動的にそのままの状態を保ちます。node build-tools/tools/act.mjs <id> --sheetで全体をスプライトシートに焼き付けます。 - ゲーム独自のキャラクターを使用する場合：タイミング情報を読み取ります。スラッシュエフェクトの
slash.actまたはシートJSON内のmeta.pokuFx.act（windup、recovery、hits：tとfreeze）。効果発生前のwindup秒間キャラクターの攻撃アニメーションを再生し、各ヒット時にエフェクトとキャラクターの両方の更新をfreeze秒間停止します。ホスト側でのヒットストップ処理は、actの有無にかかわらず任意のエフェクトで機能します。
src/fx/moves/ には、エフェクトから連鎖させた完全な攻撃（予備動作から回復まで）が含まれています。エフェクト単体ではなく、技を求められた場合はまずここを確認してください。
3. 新しいエフェクトを作成する
まず docs/AUTHORING.md を読んでください。これが契約（meta、純粋エフェクト用 draw(p, t, o) またはシミュレーションエフェクト用 create(o)、ローカル座標、シームレスループ、空での終了）、ツールキット、ペインターAPI、品質基準です。docs/QUALITY.md も読んでください。shadow/spatial-severance をクリーンなカーブと洗練されたパーティクルの基準として扱いますが、すべてのエフェクトにこのスタイルを強制しないでください。新しいエフェクトでは、適切な場所で共有のリボン、軌跡トレイル、エンベロープ、パスライティングヘルパーを使用してください。ピクセルパレットを維持し、等倍サイズのシルエット、インパクトのタイミング、ネガティブスペース、透明度を検査してください。自動テストは芸術的な品質を保証しません。
インパクトを伴うエフェクトについては、docs/IMPACT_INTERACTIONS.md も読んでください：1つの接触記述子（時間、ローカル点、法線、マテリアル）を作成し、そこから形状固有の反応とオプションのシーンフィードバックを導出します。地面/ターゲットの反応、二次衝突、収束を確認してください。すべてのマテリアルに同じ衝撃リング、石材破片、画面シェイクを追加しないでください。モーション軽減設定と固定ピボットの透明エクスポートを保持してください。
その後：
- アートディレクションを一言で：それが何か、どのように動くか、パレット、タイミングを表現します。「フロストノヴァ：クリスタルが足元からリング状に噴出し、中心に白いフラッシュ、破片が飛び散り、床は霜が降りてフェードアウトする。」
- ライブラリ内で参考になるものを探す：
node build-tools/tools/list.mjs <単語>で検索し、最も近い2～3個のエフェクトファイルを読んで技法を借用します（src/core/sim.tsのParticlesとBitsはスパーク、スモーク、デブリ用、p.discは半透明のボリューム用、cycleはシームレスなパーティクル用、tileFbmのスクロールは炎や水用）。ローカルライブラリのリファレンスを品質基準として使用します。外部リファレンスはオプションであり、ネットワークアクセスが必要です。 - ドラフトを作成する。
node build-tools/tools/new.mjs <カテゴリ>/<名前>（ループの場合は--loopを追加）で作業ファイルが生成されます。方向性が定まっていない場合は、3～5個の本質的に異なるドラフト（<名前>-a.ts～<名前>-e.ts）を作成し、それらすべてをレンダリングし（node build-tools/tools/render.mjs "<カテゴリ>/<名前>-*"）、選択する前にすべてのコンタクトシートを確認します。ユーザーが近くにいる場合は、最も出来の良い2～3個を見せます（--gifで共有用アニメーションを作成）。ソースファイルを変更した後は、レンダリング前に必ず再ビルドしてください。 - 見て、判断し、修正する。 レンダリングし、
records/<id>/contact.pngを開き、こだわりのあるピクセルアーティストのように判断します。最も悪い部分を修正し、再度レンダリングします。最低3ラウンド。見せびらかし作品はそれ以上かかります。--allですべてのフレームを表示、--mp4でフルスピードの動きを表示。 - キャラクターが関わる場合はアクションを定義する。
export const actを追加します（docs/AUTHORING.mdの「Acts」を参照）。t = 0 の前に予備動作、リリースフレームでのポーズ変更、接触時の停止、回復を含めます。node build-tools/tools/act.mjs <id>で連続した12fpsのステップを表示します：コンタクトシートのサンプルではなく、これらの動きと--mp4から判断します。 - チェックする。
node build-tools/tools/check.mjs <id>で、キャンバス外への描画、空で終了しないワンショット、ループの継ぎ目、シードされていない乱数、遅いフレームを検出します。actの場合：順序が間違ったキー、不明なポーズフィールド、テレポートする手など。クリーンにパスするまで修正します。保存しなかったドラフトは削除します。
何をチェックすべきか、通常の修正方法：
| 見える状態 | 修正方法 |
|---|---|
| 等倍でどろどろに読める | 色数を減らし、明確なシルエット、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) |
| ワンショットが突然消える | duration の前に縮小、ディザリングして消える、またはフェードアウトさせる |
| 死んだキャラクターに素晴らしいエフェクト | actを与える：予備動作、リリースポーズ、接触時の停止、反応するターゲット、回復 |
| actが無重力に感じる | 打撃と逆方向の予備動作、より長い停止（最大0.2秒）、より大きなシルエットの変化、シェイク |
| 攻撃のタイミングが合わない | ヒットキーを自分で目見当で決めた時間ではなく、エフェクト自身の定数に移動 |
| 武器の持ち方が悪い | 肘を曲げたまま、シャフトは胸の前に。スイング時、刃は手より遅れる。腕は約15pxまでしか届かず、伸ばさないので、ボディをステップで移動 |
| 腕が交差する、またはポーズが平面的に見える | キャラクターはこちら側に3/4向き：開いた腕の場合、近い手は左（fx < 0）、遠い手は右、turn: 1 を設定。yaw で実際に向きを変える |
指向性エフェクトは右向き、地面エフェクトは y = 0 に立つ、アクターエフェクトは o.actor（24 x 38の標準キャラクターのマスクとピクセル）をラップし、Math.random は使用しません。汎用モチーフは問題ありませんが、特定のゲームのスプライト、キャラクター、ロゴを再現してはいけません。
4. JSの代わりにネイティブコード
ゲームがJSを実行できず、スプライトシートでは不十分な場合（移動するターゲットを追跡するエフェクト、実行時にインスタンスごとの色が必要な場合など）、エフェクトを移植します。純粋なエフェクトは時間の関数です。シミュレーションエフェクトは src/core/sim.ts でパーティクルをステップ処理します。2バッファのアイデア、ディザリングされたアルファ用の4x4ベイヤーしきい値、パレットランプルックアップを維持します。JSのオリジナルと移植版を並べてレンダリングし、一致することを確認します。
コア、すべてのエフェクト、ギャラリー、CLIはTypeScriptソースです。使用前にビルドしてください。.ts エフェクトを作成または変更した後は、レンダリング前に再ビルドしてください。ギャラリーとCLIの検索は韓国語と英語に対応しています。韓国語のテキストはシステムフォントにフォールバックします。エンジンネイティブな作業については docs/NATIVE_MIGRATION.md を参照してください。ネイティブランタイムが存在すると主張しないでください。
結果を共有する
ユーザーが公開共有をリクエストした場合、ローカルチェックアウトを使用して npm run build を実行し、続けて npm run share -- <カテゴリ>/<エフェクト> を実行します。コマンドは透明なPNGとそのPoku JSONを新しい records/share/ フォルダにレンダリングし、現在のサイトのサイズとアニメーション制限を検証し、絶対ファイルパスと共有ページを表示します。公開やログインは行いません。
https://poku-pixel-fx.stankjedi.chatgpt.site/shared を開き、必要に応じてChatGPTでサインインし、ページのアップロードフローに従ってください。共有フォームで一致するPNGとJSONを一緒に選択し、必要なタイトルとタグを入力し、アップローダーが権利宣言を確認したら送信します。複数の作品の場合、一括セクションで一致するPNGとJSONのファイル名を受け付けます。ユーザーがリクエストしたアートワークを使用し、ブラウザのアップロードと確認のルールに従ってください。IDヘッダーを自作したり、認証情報を入手またはコピーしたり、ユーザーの同意なしにユーザーの法的権利を主張したりしないでください。成功メッセージと結果のエントリを確認してから、公開を主張してください。サイトはアカウントごとにクォータを課す場合があります。ソフトウェアを再配布する際は、LICENSE、NOTICE、およびサードパーティの著作権と許可表示を保持してください。