カスタム アセットのプレビューを定義する
previews 拡張機能を使用して、Asset Preview で特定のタイプのアセットが選択されたときの Asset Browser パネルの動作方法を定義できます。プラグインを使用して Stingray に新しいタイプのリソースを追加した場合、エディタでの作業時に、プロジェクト内の同じタイプの異なるリソースを区別する視覚的フィードバックを得ることができる便利な方法です。
Asset Preview は、エンジンのビューポートをホストするエディタ パネルです。このパネルとビューポートの基本的な外観と動作は事前設定されていますが、各 preview の拡張機能を、特定のタイプのリソースの動作専用に使用できます。preview 拡張機能は、これをリソース タイプとスクリプト モジュールを関連付けることで実行します。Asset Browser で指定したタイプのリソースが選択されると、エディタはこれらのモジュールをロードして、リソースが選択されている間これらを使用します。
以下を指定することができます。
指定されたタイプのアセットが選択および選択解除されたときに呼び出されるオプションの JavaScript モジュール。このモジュールは、選択の変更に応じて、エディタの JavaScript 環境でアクションを実行する場合に使用します。
ビューポートのバックグランドで実行されるエンジンの動作を定義するオプションの Lua モジュール。たとえば、ビューポート上で押したキーに対応して、エンジンが新しいアセットをスポーンすることが可能です。多くの場合、選択したアセットの視覚的な表現をビューポートに表示するために、これらのモジュールのいずれかを設定します。
preview 拡張機能は、プラグイン設定、JavaScript モジュール、Lua モジュールがすべて連携するように設定する必要があるため、環境設定がやや難しい場合があります。幸いにも、標準の Stingray プラグインには、ユーザ独自のプラグインのモデルとして使用できるいくつかのサンプルが用意されています。
blend_shapes プラグインには、カスタム プラグインで resource、asset_type、preview 拡張機能を一緒に使用して新しい種類のアセットを定義する方法に関する良いサンプルが用意されています。blend_shapes/preview-blend-shapes.js および blend_shapes/preview-blend-shapes.lua ファイルは、その preview 拡張機能によって使用される、JavaScript と Lua モジュールを定義します。
asset_preview プラグインでは、マテリアル、テクスチャ、パーティクル エフェクト、およびアニメーションなどの Stingray リソースに対して、いくつかの異なる preview 拡張機能を利用できます。それぞれの拡張機能は若干異なるため、ここではさまざまな方法を説明します。
たとえば、マテリアルの preview 拡張機能は Lua モジュール(preview_behaviors/preview-material.lua)を使用して設定します。このモジュールは新しい球体をスポーンして、それにユーザが現在選択しているマテリアルを割り当てます。一方、テクスチャのプレビュー モジュール(preview_behaviors/preview-texture.lua)は、stingray.Gui Lua API を使用して、ビューポート カメラの前面にテクスチャをレンダーします。
preview 拡張機能に JavaScript モジュールを使用することを選択した場合、プラグインに必要な JavaScript preview 拡張機能の関数(たとえば、setup()、clear()、title() 関数など)に関係なく、モジュールはこれらを実装するオブジェクトを返す必要があります。
たとえば、次のようになります。
define([], function () {
'use strict';
var MyAssetBehavior = {
setup: function (config, asset, viewportName, $scope) {
// ... do setup tasks here...
}
};
return MyAssetBehavior;
});
モジュールで定義できるすべての関数、およびエンジンが呼び出すときにこれらの関数に渡すパラメータの詳細については、core/js/extensions/preview-behaviors.js ファイル内のコメント、および preview 拡張機能が含まれている標準の Stingray プラグイン内のJavaScript のモジュールのコメントを参照してください。
preview 拡張機能に Lua モジュールを使用することを選択した場合、モジュールは必要となる一連の関数を実装するオブジェクトを返す必要があります。asset_preview プラグインの asset_preview/preview-behaviors/preview-base.lua ファイルに、これらの関数すべての基本的な実装が含まれています。通常、ユーザ独自の Lua オブジェクトはこの基本的なインタフェースに基づいて、アセット タイプで必要となるビューポートとエンジンの動作方法をカスタマイズするために必要な関数のみを実装します。
たとえば、次のようになります。
local BasePreviewBehavior = require("preview_behaviors/preview-base")
local MyAssetPreviewBehavior = class(BasePreviewBehavior, MyAssetPreviewBehavior)
-- overrides BasePreviewBehavior.init(), calling the base implementation
function MyAssetPreviewBehavior:init (resource, asset_preview)
BasePreviewBehavior.init(self, asset, asset_preview)
-- ... do any custom Lua initialization here ...
end
-- ... reimplement other functions from the base here ...
return MyAssetPreviewBehavior
Lua の preview 拡張機能モジュールで使用できるすべての関数のリストについては、asset_preview/preview-behaviors/preview-base.lua ファイルで定義された基本的なインタフェースを参照してください。
JavaScript モジュールとは異なり、使用する Lua ファイルがプロジェクト コンテンツ内に存在しなければなりません。resources 拡張機能を使用して、このフォルダをプロジェクトの一部としてマウントすることが必要になる可能性があります。「プロジェクト コンテンツを拡張する」を参照してください。
preview 拡張機能ごとに、次の環境設定パラメータが必要です。
extensions = {
previews = [
{
type = "resource_type"
name = "Resource Type"
title = "Asset Preview Title"
modules = ["my-resource-type-module.js" "my-resource-type-module.lua"]
config = {
enableViewportSettings = true
viewportMenuEntries = {
Physics = true
}
}
}
]
}
type
この preview 拡張機能に関連付けられるリソース タイプ(つまり、ファイル拡張子)です。ほとんどの Stingray リソース(.unit、.material、.texture など)にはプレビュー動作が既に組み込まれているため、通常、これはお使いのプラグインを使用して Stingray に追加する新しい種類のリソースとなります。必須。
name
アセット タイプの表示名です。必須。
title
Asset Browser で指定されたタイプのアセットが選択されると、Asset Preview に表示されるタイトルです。必須。
$project および $editor の動的文字列の他に、次の動的文字列を使用できます。
- $asset: Asset Browser で現在選択されている項目のリソース名に置換されます。
- $type: 上記の type 値に置換されます。
また、JavaScript モジュールで必要に応じてカスタム title() 関数を作成し、タイトルをより直接的にコントロールすることができます。
modules
Asset Browser で特定のタイプのアセットが選択されたときに、Asset Preview パネルとそのビューポートの動作を定義する、すべての JavaScript と Lua モジュールの配列です。これらのファイル名は、.stingray_plugin ファイルの位置に対応して指定する必要があります。必須。
Lua モジュールを含める場合、そのモジュールもエディタによって使用されるマウントしたリソース パスに存在する必要があることに注意してください。つまり、このモジュールは、プロジェクトのソース フォルダ、コア リソース フォルダ、またはこのプラグインに設定した resource 拡張機能で識別されるフォルダ(または標準の asset_preview プラグインなど、インストールされた別のプラグインによって設定されたフォルダ)内にある必要があります。Lua モジュールが上記のパスのいずれかに存在しない場合、エディタではこのモジュールをエンジンにロードすることができません。「プロジェクト コンテンツを拡張する」も参照してください。
config
Asset Browser のビューポートに設定できる設定の種類を定義するオブジェクトです。オプション。
エディタはこのファイルから次のキーを読み取ります。さらに、このオブジェクトは、modules 設定(存在する場合)に入力した JavaScript モジュールの setup() 関数に渡されるため、このオブジェクトにユーザ独自のキーを追加して、モジュールで読み取ることができます。
enableViewportSettings
Asset Preview に設定アイコン
を表示するかどうかを決定します。この値を true に設定した場合、viewportMenuEntries オブジェクトを使用して、このメニューでどの設定がユーザに表示されるかを設定し、defaultViewportSettings オブジェクトを使用して、これらの設定の既定値を設定します。
viewportMenuEntries
ユーザがコントロールできるビューポートの設定を決定します。
これらの設定の一部は、ビューポート自体にある View メニューにあります。また、enableViewportSettings が true に設定されている場合は、これらの設定の一部は設定メニュー
次の設定はすべてオプションです。これらを指定しない場合は、以下に示す既定値に応じて、各設定は表示また非表示になります。ユーザが変更できる状態になっている設定については、設定の既定値は、これらの既定の可視性設定の次に表示されている defaultViewportSettings オブジェクトによって設定される(設定の可視性ではない)ことに注意してください。
Grid
ビューポートの View > Grid のメニュー項目を表示または非表示にします。既定は true です。
Gizmos
ビューポートの View > Gizmos メニュー項目を表示または非表示にします。既定は true です。
PerfHud
ビューポートの View > Performance HUD メニュー項目を表示または非表示にします。既定は true です。
Meshes
ビューポートの View > Meshes メニュー項目を表示または非表示にします。既定は false です。
Bones
ビューポートの View > Bones メニュー項目を表示または非表示にします。既定は false です。
RootMotion
FollowCamera
Physics
Flow
PlaybackRate
BoneSize
ResetToggles
defaultViewportSettings
上記の viewportMenuEntries セクションにリストされた設定の既定値を定義します。
このオブジェクトには環境設定自体の既定値のみが含まれますが、viewportMenuEntries はその設定の可視性のみを決定することに注意してください。たとえば、defaultViewportSettings.gizmoVisibility はビューポートにギズモが既定で表示されるかどうかをコントロールしますが、viewportMenuEntries.Gizmo は Gizmos メニュー オプションがユーザに表示されるかどうかをコントロールします。
gridVisibility
ビューポートの View > Grid メニュー項目の既定の設定をコントロールします。true または false になる場合があります。
gizmoVisibility
ビューポートの View > Gizmos メニュー項目の既定の設定をコントロールします。true または false になる場合があります。
perfHudVisibility
ビューポート内でどのパフォーマンス HUD が有効にされるべきかを設定します。次の値を 1 つまたは複数含む配列が許可されます: artist、audio、culling、fps、lua、memory、network。
showMesh
ビューポートの View > Meshes メニュー項目の既定の設定をコントロールします。true または false になる場合があります。
showSkeleton
ビューポートの View > Bones メニュー項目の既定の設定をコントロールします。true または false になる場合があります。
hasRootMotion
doesFollowCamera
doesApplyPhysics
doesApplyFlow
playbackSpeed
skeletonBoneSize