Stingray プラグインを定義する

すべての Stingray プラグインは、.stingray_plugin リソースタイプのデータファイル内で定義されています。新しいプラグインの作業を開始する場合は、これらのファイルのいずれかを手動で作成する必要があります。

このページでは、.stingray_plugin ファイルの形式、および使用できるすべての環境設定について説明します。

注: 現時点では、エンジン専用のプラグインに .stingray_plugin ファイルは必要ありません。エンジン専用プラグインを取得するために必要なのは、.dll ファイルをエンジンのプラグインフォルダに格納することだけです。ただし、将来はエンジンのプラグインにも .stingray_plugin ファイルが使用されるようになるため、常に作成しておくことをお勧めします。

サンプルの .stingray_plugin ファイル

次のコードブロックには、独自プラグインを開発するためのモデルとして使用できる、最小限の作業用プラグインの定義が含まれています。この情報をコピーし、.stingray_plugin 拡張子付きの新しいテキストファイルに貼り付けて、エディタの Plugin Manager に表示できるようにします。Plugin Manager の使い方の詳細については、こちらを参照してください。

node.js で使用される package.json 形式に精通している場合は、これらのフィールドの多くについて既に理解しているはずです。

// Required metadata about the plug-in, shown in the Plugin Manager.
//
name = "My Custom Plugin"
version = "1.0.0"

// Optional descriptive metadata about the plug-in.
//
description = "A minimal custom plug-in that triggers some Javascript code."
author = {
    name = "Stingray"
    company = "Autodesk inc."
    url = "https://gamedev.autodesk.com/"
}
thumbnail = "my_image.png"

keywords = ["plugin"]
license = {
    type = "MIT"
    url = "https://opensource.org/licenses/MIT"
}
repository = {
    type = "git"
    url = "http://www.github.com/octocat/hello-world.git"
}

// Extensions define the ways the plug-in extends Stingray.
// All plug-ins need at least one extension in order to be successfully loaded.
//
extensions = {
    menus = [{
        path = "Edit/Hello world"
        action = {
            type = "js"
            script = """
                console.warn('Hello!')
            """
        }
    }]
}

// Dependencies that your plug-in needs in order to work.
//
platforms = ["win64"]
dependencies = {
    "stingray" = ">=1.6"
}

この方法の代わりに、組み込みの Stingray プラグインまたはサンプルプラグインのいずれかから .stingray_plugin ファイルをコピーして、そこから作業を開始することができます。すべての環境設定値(特に一意の name)が変更されていることを確認してください。

必要なメタデータ

すべてのプラグイン定義には次の設定が含まれている必要があります。

name

Plugin Manager でプラグインに対して表示する名前。

この名前は、ロードされているすべてのプラグイン間で一意でなければならないため、他のサードパーティが作成した同様なプラグインと競合する可能性がない固有の名前を使用することをお勧めします。

version

リリースするプラグインの各バージョンを区別するために使用できる文字列。<メジャー>.<マイナー>.<ビルド> という形式を使用してください。各値は、プラグインを更新すると増加する整数です。たとえば、バージョン 1.2.300 はバージョン 1.2.305、1.3.0、2.0.0 などよりも前になります。

SemVer セマンティックバージョン管理システムのドキュメントを参照してください。

オプションの説明メタデータ

次のパラメータはすべてオプションです。これらは、Plugin Manager で表示専用として使用されます。

description

プラグインの機能の簡単な概要です。

author

ユーザを識別します。シンプルな文字列の名前を付けるか、次のキー(すべてオプション)を持つオブジェクトを指定することができます。

name

ユーザの名前。

company

ユーザの会社名。

url

ユーザの組織の Web アドレス。

email

プラグインのユーザがユーザにアクセスするための電子メールアドレス。

thumbnail

エディタの Plugin Manager でプラグインに対して表示するイメージファイルを指定します。このパスは、.stingray_plugin ファイルの場所を基準にする必要があります。オプションです。既定では、thumbnail.png ファイルが存在する場合は、このファイルを使用します。

keywords

プラグインの機能を示す文字列の配列です。エディタはこれらを使用して、オンライン検索するアセットの種類をフィルタします。

plugin は、Plugin Manager の Get More Plugins リストに表示されるプラグインを識別します。

project-example は、Project Manager の Online Projects タブに表示されるサンプルプロジェクトを識別します。

project-template は、Project Manager の Templates タブに表示されるオンラインテンプレートプロジェクトを識別します。

asset-package は、Asset Browser の Online Assets フォルダに表示されるアセットを識別します。

注: これらのキーワードは現在 Gamedev ポータルを介してオートデスクによって共有されているパッケージでのみ有効です。お客様はこのリポジトリを介してパッケージを共有することはできませんが、引き続き適切なキーワードを設定することをお勧めします。この方法では、アクセスを取得するとプラグインをアップロードできるようになります。

将来使用するオプションの説明メタデータ

次のパラメータはすべてオプションです。これらは将来使用するためのものですが、すぐに使用しない場合でも、含めておくことをお勧めします。

license

プラグインの管理に使用するソフトウェアのライセンスです。これは、Stingray ユーザがプラグインをインストール、使用、変更、および再配布する権限を示します。このプロパティの値には、SPDX ライセンスリスト内の単一の文字列値、または次の値を含むオブジェクトを指定できます。

type

ライセンスタイプの文字列の説明です。通常はライセンスの名前になります。

url

ユーザがライセンスの完全なコピーを参照してダウンロードできる Web アドレスです。

repository

ユーザがプラグインのコードをダウンロードしたり、クローンを作成したりできる場所です(その場所が有効な場合)。プラグインがオープンソースである場合は、このフィールドを含めることにより、プラグインの開発チームに投稿するのに適した場所にユーザを転送できるようになります。この値には、次のフィールドを含むオブジェクトを指定する必要があります。

type

svn、git、bitbucket など、プラグインで使用されるコードリポジトリのタイプを示す文字列です。

url

ユーザがプラグインのソースコードをダウンロードしたり、投稿したりできる Web アドレスです。

拡張機能

プラグインが Stingray システムに追加する機能を定義します。各プラグインには、エディタが正常にロードできるよう、1 つ以上の拡張機能が必要です。

これらの拡張機能の仕組み、およびプラグインで使用できる拡張機能の詳細については、「拡張機能を使用してプラグインの動作を定義する」を参照してください。

従属関係

Stingray はときどき変更されるさまざまなコンポーネント間で多数の相互作用が行われる複雑なシステムです。通常、プラグインの使用目的は一部の場合に限定される可能性があります。たとえば、特定のプラットフォームに限って使用したり、Stingray の特定のバージョンに対してのみ使用したり、他の特定のプラグインが「同様に」インストールされている場合にのみ使用したりします。

platforms および dependencies プロパティを使用して、プラグインで必要な他のプラットフォーム、プラグイン、およびバージョンを正確に特定することができます。

注: 現在、エディタに適用されている唯一の従属関係は、基本 Stingray アプリケーションでの従属関係です。エディタでは、プラットフォームの従属関係や他のプラグインでの従属関係はまだ処理されません。ただし、最初からこれらを含めることをお勧めします。こうすることにより、Stingray でバージョン管理が実施されたときに、後で行う作業が軽減されるだけでなく、プラグインが実際に利用しているものを正確に特定する際にも一般に役立ちます。

platforms

プラグインのサポート対象となるプラットフォームを識別する文字列の配列です。現在、すべてのプラグインは win64 のみをサポートしています(「アルファ SDK の制限事項」も参照)。

dependencies

そのプラグインが Stingray のどのプラグインに従属するか、また、他のプラグインのどのバージョンをインストールする必要があるかをリストする項目の配列です。各項目のキーは、別の Stingray プラグインの name キーと一致する必要があります。各プラグインの独自の version プロパティ(上記を参照)と同様に、各キーの値には、このプラグインの互換性のあるバージョンを示す semver タグを指定する必要があります。

たとえば、 "stingray" >= "1.5" と指定した場合、プラグインを正常にロードするには、基本となる Stingray アプリのバージョンが 1.5 以上でなければなりません。

今後、プラグインで利用する新機能がバージョン 1.8 の Stingray の script_editor プラグインで導入されたものである場合は、"Script Editor" >= "1.8.0" も追加します。プラグインの従属関係について、バージョン番号とは、プラグインの .stingray_plugin 記述ファイルに示されている plug-in のバージョンのことです。対応付けるプラグインのバージョンが含まれている Stingray バージョンではありません。

Github でこのページを編集