エンジンマイグレーション
PlayCanvas Engineは常に進化しており、そのアップデートによって、ユーザーがスクリプトを適応させる必要がある破壊的な変更が導入されることがあります。
このガイドでは、リリース間の主要な破壊的な変更のすべてを概観し、ユーザーがコードを新しいバージョンに移行するための役立つリソースを提供します。
問題のトラブルシューティングを行う際は、エンジンのデバッグバージョンを使用することをお勧めします。これは、非推奨メッセージ、警告、および誤った使用に関連するエラーのログを提供するからです。
2.4.0から2.5.0へのマイグレーション
2.5.0での破壊的な変更
ShaderMaterial
ShaderMaterialは以前、各フラグメントシェーダーに必要なコードブロックを自動的に挿入することで、ガンマ補正、トーンマッピング、フォグ処理を効率化していました。この機能は現在削除され、関連する機能を個々のシェーダーが手動で含める責任となりました。
gammaCorrectOutput、toneMap、addFogなどの関数が不足していることによるシェーダーエラーに遭遇した場合、必要な関数をシェーダーに明示的に含めるようにしてください。詳細については、このアップデートを参照してください。
1.75.0から2.4.0へのマイグレーション
メジャーバージョン1からメジャーバージョン2へのマイグレーションは、多数の破壊的な変更を導入する大幅なアップデートです。
破壊的な変更
WebGL 1
WebGL1のサポートは終了しました。エンジンは現在、WebGL2とWebGPU（ベータ版）のみをサポートしています。アプリケーションがWebGL1に依存している場合、エンジンのバージョン1を使い続ける必要があります。
AudioSourceComponent
以前SoundComponentに置き換えられたAudioSourceComponentは、現在完全に削除されました。
レガシースクリプト
2016年から非推奨となり、数年間読み取り専用の状態で維持されてきたレガシーなスクリプトシステムは、現在、完全に削除されます。
非推奨関数
後方互換性を提供していた多数の非推奨関数が削除されました。アプリケーションがEngine 1のデバッグバージョン使用時に非推奨警告を表示する場合、Engine 2へのマイグレーション前にこれらの問題を解決する必要があります。Engine 2では、非推奨警告はもはや表示されず、後方互換性コードは廃止されました。
Basic Material
BasicMaterialは削除されました。同等の機能を実現するには、代替としてエミッシブカラーまたはエミッシブマップが設定されたStandardMaterialを使用できます。
Shader Material
もし、エラーMaterial class cannot be instantiated, use ShaderMaterial insteadを受け取った場合、これは代わりにShaderMaterialを使用するようにコードを修正する必要があることを示しています。エンジンシェーダーがリニアワークフローを使用するようになったため、フラグメントシェーダーで最終ガンマ補正を適用するためにgammaCorrectOutputがどのように使用されているかに注意してください。
テクスチャへのレンダリング
テクスチャへのレンダリングを行う際、レイヤー上でRenderTargetを設定する非推奨の方法は完全に削除されました。代わりに、RenderTargetはカメラに直接設定される必要があります。
エンジンレンダリングコールバック
エンジンは以前、カメラおよびレイヤーのレンダリングのために、フレームごとに複数のコールバックを実行していました。これらは、複数のサブスクライバーをサポートするイベント駆動型システムに置き換えられました。新しいイベントは現在Sceneクラスによって発行されます。詳細については、このプルリクエストを参照してください。
StandardMaterialのティントフラグ
StandardMaterialのティントオプションは混乱を招き、一貫性がありませんでした。そのため、Ambient、Diffuse、Emissiveのティントフラグを削除しました。以前は、これらのフラグは特定のケース、例えばテクスチャが適用された場合などにのみ影響しました。このアップデートにより、ティントカラーは常に適用されるようになりました。ティントを無効にするには、色をニュートラルな値に設定します（新しいマテリアルを作成する際に使用されるデフォルトのティントカラー）：
ティントタイプごとのデフォルトカラーのリストは次のとおりです。
- Ambient:
new Color(1, 1, 1)(白) - Diffuse:
new Color(1, 1, 1)(白) - Emissive:
new Color(0, 0, 0)(黒)
いくつか分かりにくい挙動があります。デフォルトでは、マテリアルが色を発しないように、エミッシブのティントは黒に設定されています。エミッシブテクスチャを割り当てる際は、エミッシブカラーを白に設定することが重要です。そうしないと、黒いティントがテクスチャからのエミッシブの寄与を上書きし、結果として発光が見えなくなります。
黒いムービーテクスチャ
ムービーテクスチャが黒く表示される場合、エンジンのデバッグバージョンで警告を確認してください。それは、マテリアルのティントエミッシブカラーが黒に設定されており、ムービーが黒くレンダリングされていることを示している可能性が高いです。これを修正するには、エミッシブカラーを白に変更してください。
ガンマ補正、トーンマッピング、フォグ設定
以前は、gammaCorrection と toneMapping の設定は Scene にグローバルに適用され、すべてのカメラのレンダリングに影響を与えました。現在、これらの設定は各カメラで直接利用できるようになり、個々のカメラごとに独自の構成とレンダリングが可能になりました。
以前は、フォグ設定は Scene.fog、Scene.fogColor、Scene.fogEnd のように Scene で直接アクセスできました。これらの設定は現在、Scene.fog プロパティの下に移動され、Scene.fog.type、Scene.fog.color、Scene.fog.end、および同様のプロパティを使用して設定できます。
詳細については、このプルリクエストを参照してください。
ガンマ空間テクスチャ
ディフューズ、エミッシブ、スペキュラ、シアーンのような色を表現するテクスチャは、色の範囲を維持し、バンディングを減らすために通常sRGB空間に格納されます。エンジンで使用される際、これらのテクスチャは正確なライティング計算のためにsRGBから線形空間に変換されます。以前は、この変換はシェーダーの計算によって処理され、パフォーマンスに影響を与えていました。WebGL1のサポートが削除されたことにより、現在ではハードウェアを利用してこの変換を効率的に、追加コストなしで実行できるようになりました。唯一の要件は、テクスチャがsRGBフォーマットを使用して作成されている必要があるということです。
- sRGB空間で色を表現するTextureアセットをロードする際は、sRGBエンコーディングを指定することが重要です。詳細については、このプルリクエストを参照してください。
- sRGB空間で色を表現するTextureインスタンスを作成する際は、
PIXELFORMAT_SRGBA8のようなsRGBピクセルフォーマットを使用することが不可欠です。
インスタンシング
コードに transformVS チャンクのインスタンシングセクションへのカスタマイズが含まれている場合、これらのカスタマイズを transformInstancingVS チャンクに移動して更新する必要があります。さらに、どの属性が使用されているかを指定するようにマテリアルを設定してください。さらなる詳細については、このプルリクエストを参照してください。
その他の変更点
変更に関する詳細情報については、各エンジンバージョンのリリースノートを参照してください。