|
Wwise SDK 2024.1.1
|
コマンドアドオンの概要
コマンドアドオンを使い、Wwise Authoringの新しいコマンドを定義できます。各コマンドが、Wwiseによってトリガーされる外部プログラムの1つに関連付けられています。プログラムが実行されると、選択中のオブジェクトから派生する、事前に定義された様々な引数を受領します。
アドオンしたコマンドのトリガー方法は、以下の通り、いくつかあります:
- キーボードショートカット
- コンテキストメニュー
- メインメニュー
- Control Surface
- WAAPI で、 ak.wwise.ui.commands.execute を使用
アドオンしたコマンドを定義できるレベルが、いくつかあります:
- ユーザデータディレクトリ内の、以下の下:
- Windows: "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons\\Commands"
- macOS: "$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands"
- Installationフォルダ内の、以下の下:
- Windows: "%WWISEROOT%\\Authoring\\Data\\Add-ons\\Commands"
- macOS: "/Library/Application Support/Audiokinetic/Wwise <version>/Authoring/Data/Add-ons/Commands"
- プロジェクトフォルダ内の、"Add-ons\\Commands"の下
- ak.wwise.ui.commands.register を使用
 | 注釈: IDのコンフリクトがある場合、最初にロードしたコマンドだけが登録されます。コマンドは、上記の順番でロードされます。 |
| 注釈: インスタレーションフォルダやユーザーデータディレクトリで指定したコマンドアドオンは、Wwise起動時にロードされます。プロジェクト下で指定したコマンドアドオンは、プロジェクトをロードするときにロードされます。 |
さらにWwiseでコマンドを実行する度に、WAAPIがサブスクライバーに対し ak.wwise.ui.commands.executed で通知し、選択されたオブジェクトをパスし、WAAPIリターンの設定に従います。 アドオンコマンドは実行するプログラムがなくても定義できるので、WAAPIクライアントで自分のコードを実行するためにパブリケーションイベントを使うこともできます。
コマンドアドオンの定義
定義するフィールド
コマンドの内容を以下のフィールドで定義します:
- id: コマンドの、人間が読めるユニークIDを定義します。IDのコンフリクトの可能性を減らすために、作者名、プロダクト名、コマンド名のコンカチネーションを利用したIDにしてください。
- displayName: ユーザーインターフェースに表示される名前を定義します。
- program: コマンドを実行したときに稼働するプログラム、またはスクリプトを定義します。引数は 'args' で指定します。
- args: 引数を定義します。サポートされているビルトイン変数に関しては、ドキュメンテーションを参照してください。なお、複数選択の場合は、startModeフィールドに従い変数を拡張します。
- cwd: プログラムを実行するための、カレントワーキングディレクトリを定義します。
- defaultShortcut: デフォルトでこのコマンドに使うショートカットを定義します。このショートカットでコンフリクトが発生する場合は、使用されません。このショートカットは、Keyboard Shortcut Managerで変更できます。
- redirectOutputs:（Windowsのみ）プログラムの標準のアウトプットストリーム（stdout + stderr）の対象を変更し、終了時にWwiseにつなげるべきかを、定義します。 This also prevents the window from displaying. Note that this feature should only be used for programs that will run briefly. この値はブール型で、デフォルトはfalseです。
- startMode: Wwiseユーザーインターフェースで複数選択した場合に、引数フィールドの変数をどのように拡張するのかを指定します。可能な値は以下のとおりです：
- SingleSelectionSingleProcess: 単一選択のみに対応し、プログラムを1回だけ起動します。
- MultipleSelectionSingleProcessSpaceSeparated: プログラムは1回だけ起動し、変数が拡張され引数がスペースで区切られ、それぞれの引数をダブルクオーテーションマークで囲みます。
- MultipleSelectionMultipleProcesses: プログラムは選択したアイテム毎に1回ずつ、並行して起動します。稼働中の各インスタンスが、それぞれ選択されたアイテムを1つずつ受領します。
- contextMenu: コマンドが、コンテキストメニューのどこに表示されるのか、そしてこのコマンドが、どのオブジェクトタイプに表示されるのかを、指定します。このフィールドに含めることのできるアイテムを、以下に示します:
- basePath: 親サブメニュー用に、フォワードスラッシュで区切ったパスを定義します。空の場合は、メニューが最初のレベルにインサートされます。
- enabledFor: このアイテムを有効にするオブジェクトタイプ名の、コンマで区切ったリストを定義します。サポートされるタイプ名のリストを確認するには、 Wwiseオブジェクトリファレンス を参照してください。空の場合は、すべてのタイプが許容されます。
- visibleFor: このアイテムが見えるオブジェクトタイプ名の、コンマで区切ったリストを定義します。サポートされるタイプ名のリストを確認するには、 Wwiseオブジェクトリファレンス を参照してください。空の場合は、すべてのタイプが許容されます。
- mainMenu: コマンドが、Wwiseメニューのどこに表示されるのかを指定します。
- basePath: 親サブメニュー用に、フォワードスラッシュで区切ったパスを定義します。少なくともトップメニューに関連する1つのレベルだけは、定義する必要があります。
共通のDirectory
マシン固有の絶対パスを避けるために、 program フィールドには、事前に定義された以下のディレクトリを使います。これらは、プログラムへの引数としてパスを送るために args フィールドで使ったり、使用中のディレクトリを定義するために cwd フィールドで使ったりすることもできます。
| 変数 | 参照先 |
|---|---|
| ${CurrentCommandDirectory} | 現在のコマンドが定義されるディレクトリ。上記の通り、"Add-ons\\Commands"となるべきです。 |
| ${WwiseInstallRoot} | Wwiseインストールディレクトリ。 |
| ${WwiseInstallBin} | Wwise.exeディレクトリ。 |
| ${WwiseInstallAddons} | Windows: "${WwiseInstallRoot}\\Authoring\\Data\\Add-ons" macOS: "/Library/Application Support/Audiokinetic/Wwise <version>/Authoring/Data/Add-ons/Commands" |
| ${WwiseUserAddons} | Windows: "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons" macOS: "$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands" |
| ${WwiseProjectRoot} | Wwiseプロジェクトディレクトリ。 |
| ${WwiseProjectAddons} | "${WwiseProjectRoot}\\Add-ons" |
| ${WwiseProjectOriginals} | "${WwiseProjectRoot}\\Originals" |
| ${WwiseProjectSoundbanks} | プラットフォーム別に生成されるサウンドバンクのディレクトリ。 |
引数の変数
args フィールド（プログラム引数）では0から複数の変数まで使用できます。変数は選択したオブジェクトから情報を取得する方法を提供します。例えばオブジェクトIDを取得して引数として渡すことができます。変数は選択したオブジェクトからCustom Properties値などのプロパティ値をアクセスする方法も提供してくれます。Custom Propertiesについてさらに詳しく知るには、 カスタムプロパティの定義 を参照してください。
可能な変数の式の一覧で見るには、 Wwise Authoring Query Language (WAQL) リファレンス の Object Expressions セクションと Value Expressions セクションを参照してください。
複数を選択している場合、これらの変数がどのように解決されるかは、 startMode を参照してください。
Examples:
| 変数 | 型 | 説明 |
|---|---|---|
| ${id} | string | オブジェクトID（GUID）。 |
| ${name} | string | オブジェクト名。 |
| ${notes} | string | オブジェクトnotes。 |
| ${type} | string | オブジェクトタイプ。使用可能なタイプについては Wwiseオブジェクトリファレンス を参照。 |
| ${path} | string | プロジェクトのルートからのオブジェクトパス。例: '\\Actor-Mixer Hierarchy\\Default Work Unit\\Sound1' |
| ${filePath} | string | オブジェクトが入っているファイルへのパス。パスはWork Unitファイル、またはプロジェクトファイル。 |
| ${originalWavFilePath} | string | オリジナルWAVファイルへの絶対パス。これはSoundオブジェクトやAudio Sourceオブジェクトに限り、有効。 |
| ${convertedWemFilePath} | string | 変換されたwemファイルの絶対パス。選択肢からプラットフォームを指定。これはSoundオブジェクトやAudio Sourceオブジェクトに限り、有効。 |
| ${soundbankBnkFilePath} | string | SoundBankオブジェクトに関連する、生成されたSoundBankファイルの絶対パス。SoundBankオブジェクトに限り有効。 |
| ${workunitIsDirty} | boolean | Work UnitまたはProject（wprojファイル）がダーティである場合、つまり変更されているが保存されていない場合は、true。 |
| ${Volume} | string | Voice Volume。 |
| ${OutputBus.name} | string | Output Bus名。 |
コマンドアドオンの例
コマンド定義ファイルを使った例
新しいコマンドを作成するには、 コマンドアドオンの定義 に記載されたディレクトリの1つの下にJSONファイルを作成し、そのバージョンを2に指定します。 なお、このディレクトリには、複数のサードパーティがファイルを作成することができるので、注意してください。 ファイル名のコンフリクトの可能性を減らすために、ファイル名の命名規則として、次を推奨します: companyname_productname.json
例： mycompany_myproduct.json
WAAPIを使った例
上記と全く同じJSONコマンドコードを、WAAPI ak.wwise.ui.commands.register にパスすれば、現在のWwiseプロセスに新しいコマンドを追加できます。
なお、 ak.wwise.ui.commands.register で追加したコマンドは永続化されません。このWwiseプロセスが終了するまで、残ります。 次回は、再度登録する必要があります。
WAAPIと合わせてアドオンコマンドを使う
アドオンコマンドを使って、WAAPIスクリプトやプログラムを実行することができます。これを使えば、Wwise機能やプロジェクトデータにアクセスできます。WAAPIで何ができるかについては、 Wwise Authoring API (WAAPI)を使用する を参照してください。
Macでアドオンコマンドを使う
Macでアドオンコマンドを実行するのに使うのは
. Any app, executable or script can be directly specified in program.
例： mycompany_myproduct_forMac.json