nixie-fx-runtime

NixieFX ランタイム

生成された out/vfx アーティファクトを統合します。ゲーム内でオーサリングプロジェクトのファイルを直接読み込まないでください。

ワークフロー

1. ホストのレンダラー、レンダーループ、アセットパイプライン、カメラまたは投影方式、クリーンアップのライフサイクルを確認します。

2. 選択したオプションのピア依存関係のみをインストールします。

   npm install nixie-fx three
   # or
   npm install nixie-fx pixi.js
   

3. export-bundles.md を読み、nixie-fx/export（loadVfxExportBundle）を使ってコンパイル済みバンドル全体を読み込みます。

4. タスクで両方が必要な場合を除き、バックエンドガイドを1つだけ読みます。

   • Three.js（標準バックエンド）：three.md
   • PixiJS（UI／2Dシーン）：pixi.md

5. ホストアプリケーションが所有する、注入されたプロバイダーを通じてテクスチャ、マテリアルグラフ、メッシュ、サブエフェクトを解決します。

6. レンダラーとエフェクトインスタンスを作成し、ホストの各フレームにつき1回だけレンダラーを更新します。

7. マニフェストのサポートレポートと、ランタイムの不足リソース統計を提示します。一部または未対応の動作を、完全に対応しているものとして黙って扱わないでください。

8. ホストのスコープが終了したら、インスタンス、レンダラー所有のオブジェクト、プロバイダーのリソースを破棄します。

パッケージの境界

パブリックなエントリーポイントのみを使用します。

• バックエンドに依存しないコントラクトとサポートデータには nixie-fx。
• PixiJS との統合には nixie-fx/pixi。
• Three.js との統合には nixie-fx/three。
• マテリアルグラフのコントラクトには nixie-fx/materials。
• ブラウザーで安全に使えるエクスポートスキーマと読み込みには nixie-fx/export。
• Node のファイルシステムを使ったエクスポートツールには nixie-fx/export/node のみ。

nixie-fx/src/** を深い階層からインポートしたり、ランタイムのソースを利用側にコピーしたり、使用しないレンダラーバックエンドをインポートしたりしないでください。

その他のエンジン

エクスポート形式はエンジンに依存しない JSON で、Three.js と PixiJS 向けの公式ランタイムが用意されています。プロジェクトが別のエンジンを対象とする場合、これらのアダプターを無理に導入しないでください。共有シミュレーション（リポジトリ内の src/engine/particles.ts）はレンダラーに依存せず、Three アダプターのソースは移植時の参考実装として使えるほどコンパクトです。

ランタイムのルール

• アプリケーション、シーン、カメラ、クロック、URL、キャッシュ、エラー報告はゲーム側で管理します。
• エフェクトを生成する前に非同期アセットをプリロードします。レンダリング中に使うプロバイダーのゲッターは同期処理でなければなりません。
• renderer.update(deltaSeconds) を1回呼び出します。同じフレーム内で instance.update(deltaSeconds) も呼び出さないでください。
• オーサリング時のパスはバンドル相対の検索キーとして扱います。ホストのプロバイダーで URL またはアトラスフレームにマッピングします。
• 決定論的な再生が必要な場合は、固定シードを使います。
• 非アクティブなランタイムは一時停止または破棄します。非表示のシーンで更新を続けないでください。
• Three.js のパフォーマンスを最適化する場合は、エミッターごとの描画回数を確認し、ホストの最終的な透過描画順序にパブリックな ThreeVfxBatcher を統合します。three.md のバッチ処理の節を読んでください。マテリアルを共有するだけでは描画呼び出しは統合されません。また、カスタムマテリアルを指定すると、現在は標準のインスタンス化高速パスが無効になります。
• 対象のレンダラーで実際にエクスポートしたエフェクトを確認するまでは、エディターとの同等性を主張しないでください。

完了確認

• 他方のピア依存関係をインストールせずに、選択したバックエンドをインポートできます。
• ローダーがマニフェスト、必須のエフェクト ID、選択したバックエンドを受け付けます。
• 選択したバックエンドに対して、マニフェストのエントリーがブロックされていません。
• テクスチャ、マテリアルグラフ、メッシュ、サブエフェクトが、不足参照の統計を発生させずに解決されます。
• シミュレーションはフレームごとに1回進行し、ティアダウン後に停止します。
• 実際のホストアプリケーションでエフェクトを目視確認します。