プラグイン

grandMA3 ユーザマニュアル » プラグイン Version 2.0

プラグインは、grandMA3 に機能を追加するための Lua コード要素です。

プラグインを用いると、マクロで実現できる以上のことが可能になります。

重要
プラグインを作成して用いると、「通常」の卓の使用法に比べ、より深くシステムに入り込むことができます。 そのため、複雑な Lua プラグインを使用している場合、状況によっては MA Lighting 技術サポートチームがそれを支援できない場合があります。また、ショーファイルを将来の grandMA3 ソフトウェア・バージョンに移行する際に、Lua プラグインの書き換えが必要になるかもしれません。

プラグインは、Plugins プールに保存されます。

Plugin プール・ウィンドウ

プールは、他のウィンドウと同様に作成できます(ウィンドウの追加 を参照)。

プラグインの新規作成

Plugins プールにプラグインを作成または追加するには、任意の方法で空のプール オブジェクトを編集してください。

Edit UserPlugin ポップアップが開きます。

Edit Plugin ウィンドウ

エディタのタイトルバーにある Setting をオンにすると、プラグインの設定を表示できます。

設定には以下の項目があります。

  • Name:
    プラグインの名前です。タップすると編集できます。
  • Scribble:
    割り当てられているスクリブルです。これをタップすると、スクリブルを選択したり、エディタを開いて新しいスクリブルを作成したりできます。
  • Appearance:
    割り当てられているアピアランスです。これをタップすると、アピアランスを選択したり、エディタを開いて新しいアピアランスを作成したりできます。
  • Note:
    プラグインに注記を追加できます。
  • Lock:
    これをオンにすると、プラグインが変更されないようにロックできます。
  • Author:
    プラグイン作者の名前を追加できます。
  • Version:
    プラグインのバージョンを設定できます。
  • Path:
    プラグイン・フォルダ(gma3_library/datapools/plugins)内のファイルに対するパス(サブフォルダ)です。
  • UserRights:
    このプラグインを実行するために必要なユーザ権限を設定できます。

プラグインには複数の Lua コンポーネントを含めることができますが、少なくとも1つは必要です。

コンポーネントの作成と編集

Lua コンポーネントには Lua コードが含まれています。各コンポーネントは、通常1つのファイルになっています。

New ComponentLua を長押しして、コンポーネントを追加します。

コンポーネント一覧で行を選択し Insert new ComponentLua をタップすることによっても、新しいコンポーネントを追加できます。この場合、選択した行の上に新しい行が作成されます。

プラグインに Lua コンポーネントを追加

各コンポーネントには、以下のようにいくつかの設定と情報の列項目があります。

  • Name:
    コンポーネントの名前です。
  • Scribble:
    割り当てられているスクリブルです。これはどこにも表示されません。
  • Appearance:
    割り当てられているアピアランスです。これはどこにも表示されません。
  • FileName:
    Lua コンポーネント・ファイルの名前です。プラグインをエクスポートするには、ファイル名が必要です。コンポーネントに名前を付けると、ファイル名も作られます。
  • FilePath:
    プラグイン・フォルダ(gma3_library/datapools/plugins)内の Lua ファイルに対するパス(サブフォルダ)です。
  • FileSize (情報のみ):
    Lua コンポーネント・ファイルのサイズをバイト単位で表示します。
  • Installed:
    Yes に設定すると、Lua コンポーネントはインポート元のファイル・アーカイブから更新されます。これは、外部エディタで Lua ファイルを編集してフォルダにコピーする場合に便利です。
    これらの Lua コンポーネントの変更を更新するには、ReloadAllPlugins キーワード を実行する必要があります。
  • IsResource (情報のみ):
    Lua ファイルが内部ライブラリに保存されている内部リソースであるかどうかを示します。 これらのファイルはショーファイルに保存されず、ストリーミングも行われません。
  • InStream (情報のみ):
    Yes の場合、Lua コードがショーファイルに保存され、セッションでストリーミングされますが、ショーファイルに保存されたままになります。No の場合、Lua コードがハードドライブにローカルに保存されます。この Lua コードの内容は、ReloadAllPlugins キーワード によって更新できます。
    Installed を Yes にすると、InStream は No に設定されます。
  • UserRights:
    特定のコンポーネントにユーザ権限を設定できます。
  • SyntaxError (情報のみ):
    構文エラーによって Lua コンポーネントを Lua エンジンにロードできない場合、SyntaxError プロパティが Yes に変わり、コンポーネント行が赤表示になります。

編集したいコンポーネントを選択し、Edit をタップしてください。

Lua Input ポップアップが開きます。

空の Lua Input ポップアップ

テキストは、外部エディタからポップアップにコピーするか(grandMA3 onPC を使用時)、ポップアップに直接入力できます。

既存コードの編集は、Lua Input ポップアップでも行えます。

行番号は、コードのデバッグを行う際などに役立ちます(番号はコードの一部ではありません)。カーソルがある行の番号は白で、それ例外は灰色で表示されます。

Tab によってテキストをインデントすると、タブの先頭位置に灰色の ">" が表示されます。

目的のコードを入力したら、タイトルバーの Save をタップして保存してください。

タイトルバーには以下のボタンもあります。

  • (仮想キーボード):
    仮想キーボードの表示を切り替えます。
  • Lua Code Templates:
    新しいコードを書くテンプレートとして利用できる Lua Code Templates の表示を切り替えます。詳しくは 後述 を参照してください。
  • API Description:
    エディタの右側に表示される grandMA3 固有の Lua API の説明を切り替えます。詳しくは 後述 を参照してください。
  • (Undo):
    直前に行った編集を取り消します。
  • (Redo):
    取り消した操作をやり直します。

コードを保存したら、右上隅の をタップして Lua Input ポップアップを閉じられます。

プラグインの実行

プラグインは、プールでタップするか、Plugin キーワード を用いることによって実行できます。

プラグインを実行すると、最初のコンポーネントが実行されます。このコンポーネントは他のコンポーネントを呼び出す必要がありますが、以下の構文によって特定のコンポーネントを直接呼び出すこともできます。

Plugin [プラグイン番号 または "プラグイン名"].[コンポーネント番号 または "コンポーネント名"]

プラグインは、エクゼキュータやビューボタンにも割り当てられます。詳しくは エクゼキュータへのオブジェクト割り当て を参照してください。

Lua Code Templates

テンプレートは、エディタにコピーできるサンプルコードです。

制限
テンプレートを用いると、既存のコードが削除されます。

タイトルバーにある Lua Code Templates をタップすると、テンプレートが表示されます。

Lua Code Templates

さまざまなテンプレートが隣り合わせに表示されていて、それらを横スクロールバーでスクロールできます。

テンプレートをインポートするには、それを選択し(黄枠表示)、Use Template をタップします。

タイトルバーの Lua Code Templates か、左下隅の Backをタップすると、インポートせずにテンプレートを閉じることができます。

API Description

Lue Input ポップアップの右側に、APIの説明を表示できます。タイトル バーの API Description をタップして、表示のオン/オフを切り替えられます。

grandMA3 固有の Lua 関数がすべて一覧表示され、必要な引数と戻り値の簡単な説明が示されます。

API Description

API Description は3つの要素からなっています。上部には、関数一覧を検索するための入力欄があります。

検索欄の下には実際の関数一覧がアルファベット順で表示されます。いずれかを選択すると、その説明が一覧の下に表示されます。

説明領域の右上隅にある をタップすると、その関数が引数とともに、Lue Input ポップアップの現在のカーソル位置に挿入されます。

プラグインのエクスポート

プラグインは、Edit UserPlugin から Export をタップすることでエクスポートできます。

これによって、プラグインのXMLファイルが作成されます。

Lua コンポーネントのファイル拡張子が ".lua" の場合、そのコンポーネント用に追加の LUA ファイルがエクスポートされます。 コンポーネントに有効なファイル名が無い場合は、Base64 形式でエンコードされたXMLファイルに保存されます。

制限
Lua ファイルは、Lua コンポーネントの "InStream" が "Yes" の場合にのみエクスポートされます。

プラグインのインポート

プラグインを正常にインポートするには、必要なすべてのファイルが揃っていなければなりません。XMLファイルは常に必要です。Lua コンポーネントが追加の Lua ファイルとして保存されている場合は、それらも必要になります。これらのファイルは、目的ドライブの ../gma3_library/datapools/plugins フォルダに置いてください。

  1. 新しいプラグインを作成します。
  2. Import をタップします。
  3. 目的のドライブとXMLファイルを選択します。
  4. Import をタップしてください。
  5. プラグインがインポートされ、エディタを閉じることができます。