Interface IRootApi

Namespace

VMagicMirror.Buddy

スクリプトから Api 変数としてアクセスできるような、サブキャラの制御に利用できるAPI群です。

public interface IRootApi

Properties

Audio

音声ファイルの再生に関するAPIを取得します。

IAudio Audio { get; }

Property Value

IAudio

Remarks

v4.0.0の時点でこのAPIはサウンドエフェクト等、短い音声の再生のみを想定したAPIとなっています。

AvatarFacial

アバターの表情に関するAPIを取得します。

IAvatarFacial AvatarFacial { get; }

Property Value

IAvatarFacial

AvatarLoadEvent

アバターのロード状態や、ロード状態に関するイベントのAPIを取得します。

IAvatarLoadEvent AvatarLoadEvent { get; }

Property Value

IAvatarLoadEvent

AvatarMotionEvent

アバターの動作をイベントとして検出するAPIを取得します。

IAvatarMotionEvent AvatarMotionEvent { get; }

Property Value

IAvatarMotionEvent

AvatarPose

アバターの姿勢に関するAPIを取得します。

IAvatarPose AvatarPose { get; }

Property Value

IAvatarPose

BuddyDirectory

このサブキャラのデータが入っているディレクトリの絶対パスを取得します。

string BuddyDirectory { get; }

Property Value

string

Remarks

このプロパティは main.csx スクリプトを含むディレクトリの絶対パスを返します。 静的なデータ定義を行ったテキストなど、サブキャラに同梱したファイルがある場合はこのディレクトリを参照してファイルを読み込めます。

Show(string) 等では、パスを相対パスとして評価する場合、このプロパティで取得できるディレクトリからの相対パスとして評価します。 そのため、サブキャラのオブジェクトを単に表示する場合、必ずしもこのプロパティを参照する必要はありません。

DeviceLayout

アバターの周辺のデバイス配置に関するAPIを取得します。

IDeviceLayout DeviceLayout { get; }

Property Value

IDeviceLayout

Input

ユーザーの入力に関するAPIを取得します。

IInput Input { get; }

Property Value

IInput

InteractionApiEnabled

メインアバターの姿勢や表情、およびユーザーのマイク入力などを取り扱えるインタラクションAPI全般にアクセス可能かどうかを取得します。

bool InteractionApiEnabled { get; }

Property Value

bool

Remarks

この値はアプリケーションのEditionおよびユーザー設定によって変化します。 値が false の場合、 AvatarMotionEvent のイベントが発火しなかったり、 AvatarPose で有効なポーズが取得できなかったりする状態になります。

ユーザー入力がないと進行不能になってしまうような挙動をサブキャラに対して実装する場合、 このフラグも組み合わせて挙動をカスタムすることで意図しないスタックを防げます。

Language

アプリケーションに適用されている言語を取得します。

AppLanguage Language { get; }

Property Value

AppLanguage

Remarks

VMagicMirrorのローカライズシステムの実装都合により、この値は日本語・英語以外の言語選択を行うと Unknown を返します。

多くの言語に対応できるようなサブキャラを作成する場合、このプロパティの代わりに IProperty によって ユーザーが言語選択を別途選択できるようにすることも検討して下さい。

MainThreadContext

アプリケーションのメインスレッドのコンテキストを取得します。

SynchronizationContext MainThreadContext { get; }

Property Value

SynchronizationContext

Remarks

スクリプト上で非同期処理を行った結果をスプライトやVRMアバターに適用したい場合、メインスレッドに処理を戻るときに使用できます。

より簡単にメインスレッドへアクセスしたい場合、変わりに RunOnMainThread(Func<Task>) を使用することを検討してください。

Property

マニフェストで定義されたプロパティにアクセスできるAPIを取得します。

IProperty Property { get; }

Property Value

IProperty

Screen

アバターを表示しているウィンドウに関するAPIを取得します。

IScreen Screen { get; }

Property Value

IScreen

Transforms

マニフェストで定義されたTransformの参照にアクセスできるAPIを取得します。

IManifestTransforms Transforms { get; }

Property Value

IManifestTransforms

Methods

Create2DSprite()

アバターウィンドウの最前面に画像を表示するためのスプライトのインスタンスを生成します。

ISprite2D Create2DSprite()

Returns

ISprite2D

Remarks

空間上へ3次元的に板状の画像を表示したい場合、代わりに Create3DSprite() を使用します。

Create3DSprite()

画像を空間上で板状のオブジェクトとして配置するためのスプライトのインスタンスを生成します。

ISprite3D Create3DSprite()

Returns

ISprite3D

Remarks

平面的に画像を表示したい場合、代わりに Create2DSprite() を使用します。

GetCancellationTokenOnDisabled()

サブキャラが終了するときにキャンセル扱いされるようなCancellationTokenを取得します。

CancellationToken GetCancellationTokenOnDisabled()

Returns

CancellationToken

Remarks

サブキャラの挙動として非同期処理を実装する場合、この値を使用することで、サブキャラが意図せず実行され続けることを防止できます。

InvokeDelay(Action, float)

指定した処理を、指定された秒数のあとで実行します。

void InvokeDelay(Action func, float delaySeconds)

Parameters

func Action

実行したい関数

delaySeconds float

実行のディレイ秒数

Remarks

このメソッドは、メインアバターの仕草を検出したとき、やや遅れてリアクションを取る場合などに有効です。

InvokeInterval(Action, float)

指定した処理を、指定された間隔で実行します。

void InvokeInterval(Action func, float intervalSeconds)

Parameters

func Action

実行したい関数

intervalSeconds float

実行間隔の秒数

Remarks

このメソッドは、Updateより低頻度で処理を実行したい場合などに有効です。

このメソッドを呼び出すと、直ちに func が1回実行されます。 初回の呼び出しを遅延させる場合、 InvokeInterval(Action, float, float) を使用します。

InvokeInterval(Action, float, float)

指定した処理を、指定された間隔で実行します。

void InvokeInterval(Action func, float intervalSeconds, float firstDelay)

Parameters

func Action

実行したい関数

intervalSeconds float

実行間隔の秒数

firstDelay float

初回に処理を実行するまでの遅延の秒数

Remarks

このメソッドは、Updateより低頻度で処理を実行したい場合などに有効です。

Log(string)

ログ情報を出力します。

void Log(string value)

Parameters

value string

Remarks

ログファイルは VMagicMirror_Files/Logs/{buddy_name}.txt として出力されます。 buddy_name には、サブキャラのデータを格納しているフォルダ名が入ります。

このメソッドで出力するログは、VMagicMirrorのサブキャラ設定で開発者モードを有効にし、ログ詳細度を Info かそれより詳細なレベルに設定した場合のみ出力されます。

LogError(string)

エラー相当のログ情報を出力します。

void LogError(string value)

Parameters

value string

Remarks

ログファイルは VMagicMirror_Files/Logs/{buddy_name}.txt として出力されます。 buddy_name には、サブキャラのデータを格納しているフォルダ名が入ります。

このメソッドで出力するログは、VMagicMirrorのサブキャラ設定で開発者モードがオフであるか、または開発者モードでログ詳細度を Error かそれより詳細なレベルに設定した場合のみ出力されます。

LogWarning(string)

警告相当のログ情報を出力します。

void LogWarning(string value)

Parameters

value string

Remarks

ログファイルは VMagicMirror_Files/Logs/{buddy_name}.txt として出力されます。 buddy_name には、サブキャラのデータを格納しているフォルダ名が入ります。

このメソッドで出力するログは、VMagicMirrorのサブキャラ設定で開発者モードを有効にし、ログ詳細度を Warning かそれより詳細なレベルに設定した場合のみ出力されます。

Random()

0以上、1未満のランダムな値を取得します。

float Random()

Returns

float

RunOnMainThread(Func<Task>)

指定したタスクをメインスレッドで実行します。

void RunOnMainThread(Func<Task> task)

Parameters

task Func<Task>

メインスレッドで実行したいタスク

Remarks

VMagicMirrorはUnity Engineで実行されており、VRMやスプライトの操作はゲームエンジンのメインスレッド上で行う必要があります。 スクリプト上でTaskによる非同期処理を行う場合、このメソッドを用いることで、非同期処理の結果をサブキャラに適用しやすくなります。

Events

Start

サブキャラのロード後に一度だけ呼ばれます。

event Action Start

Event Type

Action

Remarks

Update の最初の呼び出しよりも前に呼ばれることが保証されます。

Update

毎フレームごと、つまり描画内容の更新のたびに呼ばれます。 引数には、前回のフレームからの経過時間が秒単位で渡されます。

event Action<float> Update

Event Type

Action<float>

Remarks

引数は通常、 1/60 に近い値になります。

このイベントは毎フレーム呼ばれるため、長時間かかる処理をイベントハンドラとして実行するのは避けるようにしてください。