actions 拡張機能を使用して名前の付いたコマンドまたはスクリプト ブロックを定義し、プラグインに含まれる他の拡張機能からトリガすることができます。
actions 拡張機能で設定したアクションは、それ自体では何も行いません。プラグインでのユーザの操作に応答して、これらのコマンドを起動するようにプラグインを設定する必要があります。たとえば、次のことを行うことができます。
2 つの異なる方法で、アクションの定義と呼び出しができます。
actions 拡張機能のアクションを定義し、これに一意の名前を付けることができます。名前を付けたアクションは、プラグイン内の他の拡張機能から呼び出すことができます。また、名前で参照することにより、他のプラグインから呼び出すこともできます。たとえば、次の環境設定は print_message という名前でアクションを設定し、プラグインによって追加された新しいメニュー項目をユーザが選択したときに、そのアクションを呼び出します。
extensions = {
actions = [
{
name = "print_message"
type = "js"
script = """
console.warn("Hello world!")
"""
}
]
menus = [
{
path = "Window/Print message"
action = "print_message"
}
]
}
このアプローチによってすべてのアクションを 1 箇所に保持できるため、環境設定を整理して保持するのに役立つ場合があります。また、複数の異なる拡張機能から同じアクションを参照する必要がある場合に、重複を避けるのに役立ちます。
別の拡張機能の定義内に、アクションをインラインで定義できます。たとえば、次の環境設定は、それを呼び出すメニュー項目の定義内にあるアクションを定義するという点以外は、上記の設定とまったく同じです。この場合は、actions セクションがまったく不要で、さらにそのアクションは name が不要なことに留意してください。
extensions = {
menus = [
{
path = "Window/Print message"
action = {
type = "js"
script = """
console.warn("Hello world!")
"""
}
}
]
}.stingray_plugin ファイルでアクションを設定できる場所では、常に複数アクションの配列を代わりに使用できます。配列内の各アクションは、名前を付けたアクション、または定義されたインラインのアクションのいずれかです(上記を参照)。配列内での混合と一致が便利な場合はこれを行うことができます。
extensions = {
actions = [
{
name = "print-another-message"
type = "js"
script = """
console.warn("Another message!")
"""
}
]
event = [
{
on = "my-event"
do = [
{
type = "js"
script = """
console.warn("Hello world!")
"""
}
"print-another-message"
]
}
]
}
これらのアクションは、配列内で表示される順序でトリガされます。ただし、エディタの JavaScript の非同期の性質により、2 番目のアクションが実行を開始する前に、1 番目のアクションよる実行がすべて実際に完了するという保証はありませんので注意してください。
すべての action 拡張機能には、次のパラメータが必要になります。選択したタイプに基づいて、次のセクションで説明する他のパラメータもいくつか設定する必要があります。
extensions = {
actions = [
{
name = "unique-action-name"
type = "js"
// ... add other parameters here
}
]
}
name
アクションに名前を与えます。この名前を使用することにより、プラグイン内のどこからでも、あるいは他のプラグインからでも、そのアクションをトリガできます。
このパラメータは、actions 拡張機能内でアクションを定義する場合に必要です。別の拡張機能(menus 拡張機能内など)内でインラインのアクションを定義している場合にのみ省略可能です。
アクションに名前を設定する場合、その名前は現在のプラグインだけでなく、インストールされているすべてのプラグインにおける、すべての名前の付いたアクションの中で一意の名前にする必要があります。1 つのプラグインのみが指定した名前でアクションを登録できます。別のプラグインが同じ名前を使用しようとすると、エディタは新しいアクションの登録が拒否します。サードパーティーのプラグインに定義されている別のアクションの名前との競合を回避するには、一種のネームスペースとして、お使いのプラグインに関連する接頭辞を追加することを検討してください。
type
このアクションが行う動作を決定します。現在、許容値は次のとおりです: copy、js、module、lua、process、event。これらの各タイプには、追加の環境設定パラメータの異なるセットが必要です。以下を参照してください。
1 つの場所から別の場所にファイルをコピーするようにアクションを設定するには、copy タイプを使用します。
extensions = {
actions = [
{
name = "duplicate-a-material"
type = "copy"
source = "plugin-resources/source.material"
destination = "$project/content/materials/source_copy.material"
}
]
}
source
コピーするソース ファイルのパスとファイル名です。このパスは常に、.stingray_plugin ファイルの位置を基準にしています。
destination
コピーの新しいパスとファイル名です。このパスは絶対パスである必要がありますが、現在のプロジェクト フォルダを指定するには $project 文字列を使用できます。
JavaScript コードの埋め込みスニペットを実行するようにアクションを設定するには、js タイプを使用します。
extensions = {
actions = [
{
name = "recompile-all-resources"
type = "js"
script = """
// This calls the engine service to force a compilation.
require(['services/engine-service'], function (engineService) {
engineService.enqueueDataCompile().then(console.warn.bind(console, 'Compilation requested.'));
}.bind(this));
"""
}
]
}
script
このアクションが実行する JavaScript のスニペットが含まれています。上記の例に示すように、ここで必要な任意のエディタ サービスを取り込むために require 呼び出しを使用できます。「組み込みのエディタ サービスを使用する」を参照してください。
例のように、3 重引用符 """ でコードが囲まれていることを確認します。
個別の .js ファイルで定義されたモジュールから JavaScript 関数を実行するようにアクションを設定するには、js タイプを使用します。.js ファイルの名前、および module と function_name の設定で呼び出す関数の名前を設定します。
extensions = {
actions = [
{
name = "recompile-all-resources"
type = "js"
module = "my-plugin-javascript-file"
function_name = "myFunctionName"
}
]
}
module
.stingray_plugin ファイルの位置を基準として、実行する関数を定義する JavaScript ファイルのパスとファイル名です。必須。
function_name
JavaScript モジュールから起動する関数の名前です。オプション。これを省略した場合、モジュール ファイル自体が関数を返す必要があります。
たとえば、上記の設定では、my-plugin-javascript-file.js ファイルで定義されたモジュール内にあることが予測される、myFunctionName という名前の関数を実行するようにアクションを設定します。そのファイルの内容は、次のようになります。
define([], function () {
'use strict';
var exports = {}
exports.myFunctionName = function() {
console.warn("Custom function triggered!")
}
return exports;
});
または、次の例のように、JavaScript モジュールが単一の関数を返す場合は、function_name 設定を省略することができます。
define([], function () {
'use strict';
return function() {
console.warn("Custom function triggered!")
};
});
Lua コードの埋め込みスニペットを実行するようにアクションを設定するには、lua タイプを使用します。
extensions = {
actions = [
{
name = "spawn-a-terrain"
type = "lua"
script = """
print("Spawning terrain")
local level_editor_viewport_window = ({next(Editor:all_level_editing_viewports())})[2]
print("Level viewport", level_editor_viewport_window)
if level_editor_viewport_window then
local terrain_make_result = Terrain.make(stingray.Vector3(0,0,0), stingray.Quaternion.identity(),
1, {x = 1024, y = 1024, z = 64}, level_editor_viewport_window)
print("Terrain spawned", terrain_make_result)
end
"""
}
]
}
script
このアクションが実行する Lua のスニペットが含まれています。このコードは、Stingray Lua API に完全にアクセスできる、エディタの Lua 環境で実行されます。また、エディタが現在のレベルを変更するために内部で使用する、すべての Lua 編集コードを利用することができます。たとえば、上記のスニペットでは、Level Viewport を検索し、新しい地表をスポーンするために、この Lua 編集環境で定義されている Editor および Terrain オブジェクトから関数を使用します。これらのインタフェースは、現在ドキュメントに記載されていませんが、core/editor_slave/stingray_editor の下にある Stingray のコア リソースに完全なソース コードがあります。
例のように、3 重引用符 """ でコードが囲まれていることを確認します。
コンピュータ上の外部プログラムを実行するようにアクションを設定するには、process タイプを使用します。
extensions = {
actions = [
{
name = "open-in-text-editor"
type = "process"
path = "notepad.exe $1"
}
]
}
実行するプログラムの後に、コマンド ラインに渡す任意のパラメータを選択します。たとえば、上記のパスでは、基本的なメモ帳のテキスト エディタを起動し、起動時にアクションに渡される任意のファイル名を開きます。下記の「アクションにパラメータを渡す」も参照してください。
ユーザのアクションで、エディタにイベントを発行することができます。そして、このイベントに対してユーザのプラグイン(またはその他のプラグインやエディタ自体)が応答できます。
extensions = {
actions = [
{
name = "emit-a-named-event"
type = "event"
event = "my-custom-named-event"
}
]
}
イベントの詳細については、「エディタのイベントを発行および処理する」も参照してください。
event
プラグインが発行するべきイベントの名前です。
アクションにパラメータを渡すことができる、別の拡張機能(カスタム メニューまたはアセット タイプなど)からアクションをいつでも起動できます。アクションの環境設定で、$1、$2、$3 などの変数を使用して、これらのパラメータを参照できます。
たとえば、プラグインに認識させたい新しい種類のデータ ファイル用にカスタム アセット タイプを定義するとします。ユーザが Asset Browser でこれらのアセットの 1 つをダブルクリックしたときに、次の設定は open-in-default-editor という名前のアクションを起動し、ユーザがクリックしたアセットのファイル名を渡します。このアクションはそのパラメータを使用して、そのファイル タイプに関連付けられている既定のアプリケーションでそのアセットを開きます。
extensions = {
actions = [
{
name = "open-in-default-editor"
type = "process"
path = "cmd /C start $1"
}
]
asset_types = [
{
type = "xml"
category = "Custom"
icon = "myPluginImages/xml.svg"
invoke = "open-in-default-editor $project/$1"
}
]
}
「カスタム アセット タイプを登録する」も参照してください。