ExportStudio(プリセットアイテム)

このページは過去の情報となります。
新しいスクリプトリファレンスはこちらになります。

スタジオ内の情報を取得するのに必要な関数です。
主にアイテムの状態に関する情報を取得したり、VCIスクリプトでアイテムを操作するのに使用します。
バーチャルキャストのアイテムについてはアイテムについてから確認してください。

名前 説明
ExportStudio スタジオのプリセットアイテムをインスタンス化
ExportSystemItem インスタンス化したオブジェクトを操作
ExportSystemCamera インスタンス化したカメラを操作

ExportStudio

バーチャルキャストのプリセットアイテムごとにHas関数Get関数が存在します。

スタジオにアイテムが存在しないのにGetしてしまうとnullになるので、Has関数の結果がtrueの時のみGetするようにします。
また、2019/08/29 時点では凸者も取り出し可能なアイテムに関しては取得する事ができません。

名前 引数: 戻り値 説明
shared ExportShared(グローバル同期変数)で使用
GetOwner fun(): ExportAvatar VCI所有者のアバター を取得します
RoomではVCIを生成した人が退室している状況があり、その場合にGetOwnerを実行するとExportAvatarは入手出来ず、nilになります
GetLocalAvatar fun(): ExportAvatar ローカルマシンのユーザが使用する アバター を取得(v2.0.0a以降)
GetAvatars fun(): ExportAvatar[] スタジオ内のアバター 一覧を取得
GetMic fun(): ExportSystemItem マイク をインスタンス化
HasMic fun(): bool マイク がスタジオに存在すれば true
GetLightSource fun(): ExportSystemItem 光源 をインスタンス化
HasLightSource fun(): bool 光源 がスタジオに存在すれば true
GetMirror fun(): ExportSystemItem をインスタンス化
HasMirror fun(): bool がスタジオに存在すれば true
GetHarisen fun(): ExportSystemItem ハリセン をインスタンス化
HasHarisen fun(): bool ハリセン がスタジオに存在すれば true
GetMosaic fun(): ExportSystemItem モザイク をインスタンス化
HasMosaic fun(): bool モザイク がスタジオに存在すれば true
GetHammer fun(): ExportSystemItem ピコピコハンマー をインスタンス化
HasHammer fun(): bool ピコピコハンマー がスタジオに存在すれば true
GetWindowCamera fun(): ExportSystemCamera モニターカメラ をインスタンス化
HasWindowCamera fun(): bool モニターカメラ がスタジオに存在すれば true
GetHandiCamera fun(): ExportSystemCamera ハンディカメラ をインスタンス化
HasHandiCamera fun(): bool ハンディカメラ がスタジオに存在すれば true
GetAutoFollowCamera fun(): ExportSystemCamera 追従カメラ をインスタンス化
HasAutoFollowCamera fun(): bool 追従カメラ がスタジオに存在すれば true
GetSwitchingCamera fun(): ExportSystemCamera スイッチングカメラ をインスタンス化
HasSwitchingCamera fun(): bool スイッチングカメラ がスタジオに存在すれば true
GetNameBoard fun(idOrName: string): ExportSystemItem ネームプレートをインスタンス化
ExportAvatarから取得したユーザー名かIDを指定
HasNameBoard fun(idOrName: string): bool ネームプレートがスタジオに存在すれば true

ExportSystemItem

ExportStudioでインスタンス化したオブジェクトを操作します。

名前 引数: 戻り値 説明
GetName fun(): string アイテムの名前を取得
GetLocalPosition fun(): Vector3 アイテムの位置を取得
(出現時のローカル座標が原点)
GetPosition fun(): Vector3 アイテムの位置を取得
(ワールド座標の(0,0,0)が原点)
GetLocalRotation fun(): Quaternion アイテムの回転を取得
(出現時のローカルの姿勢が基準)
GetRotation fun(): Quaternion アイテムの回転を取得
(ワールド座標基準)
GetLocalScale fun(): Vector3 アイテムの縮尺を取得
GetRight fun(): Vector3 アイテムの右方向(+X)のベクトル
GetUp fun(): Vector3 アイテムの上方向(+Y)ベクトル
GetForward fun(): Vector3 アイテムの正面(+Z)ベクトル
GetLocalToWorldMatrix fun(): Matrix4x4 アイテムのローカル→ワールド座標に変換した行列
SetPosition fun(position: Vector3): number アイテムの位置(Position)を変更
(ワールド座標) ※1
SetRotation fun(rotation: Quaternion): number アイテムの姿勢(Rotation)を変更
(ワールド座標) ※1
SetLocalPosition fun(localPosition: Vector3): number アイテムの位置(Position)を変更
(ローカル座標) ※1
SetLocalRotation fun(localRotation: Quaternion): number アイテムの姿勢(Rotation)を変更
(ローカル座標) ※1
IsGrabbed fun(): bool grabされているなら true

※1
SetPosition, SetRotation, SetLocalPosition, SetLocalRotation部屋主が出したVCIからのみ実行可能です。

ExportSystemCamera

ExportStudioでインスタンス化したカメラを操作します。
基本的にSystemItemと同じですが、カメラ固有の関数(GetFieldOfView等)が存在します。

名前 引数: 戻り値 説明
GetFieldOfView fun(): number カメラの視野角(FOV)を取得
SetFieldOfView fun(fov: number): number カメラの視野角(FOV)を変更 ※1 ※2
GetMinFieldOfView fun(): number カメラの最小視野角(FOV)を取得
GetMaxFieldOfView fun(): number カメラの最大視野角(FOV)を取得
GetName fun(): string アイテムの名前を取得
GetLocalPosition fun(): Vector3 アイテムの位置を取得
(出現時のローカル座標が原点)
GetPosition fun(): Vector3 アイテムの位置を取得
(ワールド座標の(0,0,0)が原点)
GetLocalRotation fun(): Quaternion アイテムの回転を取得
(出現時のローカルの姿勢が基準)
GetRotation fun(): Quaternion アイテムの回転を取得
(ワールド座標基準)
GetLocalScale fun(): Vector3 アイテムの縮尺を取得
GetRight fun(): Vector3 アイテムの右方向(+X)のベクトル
GetUp fun(): Vector3 アイテムの上方向(+Y)ベクトル
GetForward fun(): Vector3 アイテムの正面(+Z)ベクトル
GetLocalToWorldMatrix fun(): Matrix4x4 アイテムのローカル→ワールド座標に変換した行列
SetPosition fun(position: Vector3): number アイテムの位置(Position)を変更
(ワールド座標) ※1
SetRotation fun(rotation: Quaternion): number アイテムの姿勢(Rotation)を変更
(ワールド座標) ※1
SetLocalPosition fun(localPosition: Vector3): number アイテムの位置(Position)を変更
(ローカル座標) ※1
SetLocalRotation fun(localRotation: Quaternion): number アイテムの姿勢(Rotation)を変更
(ローカル座標) ※1
IsGrabbed fun(): bool grabされているなら true

※1
SetPosition, SetRotation, SetLocalPosition, SetLocalRotation, SetFieldOfView部屋主が出したVCIからのみ実行可能です。

※2
FOV設定可能なカメラは下図の通りです。GetMinFieldOfViewGetMaxFieldOfViewで取得可能な最小値、最大値を超えた値は設定できません。

カメラ名 FOV設定
モニターカメラ 不可
ハンディカメラ
追従カメラ
スイッチングカメラ 不可

また、これらの関数で扱う値は垂直視野角で、単位は度です。

ハンディカメラに表示される焦点距離について

ハンディカメラのプレビュー画面に表示される 50mm といった数値があります。
これはズームとともに連動する値で、現実のカメラではよく使われる「焦点距離」という指標です。
なおかつアスペクト比の違いを吸収するため、焦点距離の中でも対角換算での焦点距離を使用しています。

このようにハンディカメラでは分かりやすさのために焦点距離が使われています。
一方で SetFieldOfView で設定可能な値は垂直換算の FOV です。
ハンディカメラのプレビュー画面に表示されている焦点距離を基準に FOV を設定したい場合は
次の計算で、対角換算の焦点距離から垂直換算の FOV を算出することができます。

$$ FOV = \frac{360}{\pi} \times \arctan{\left(\frac{D}{x \times 2 \sqrt{a^{2}+1}}\right)} \\ \text{x: 35mm判換算焦点距離[mm]} \\ \text{a: カメラのアスペクト比 (基本的に16/9)} \\ \text{D: 35mmフルサイズセンサーの対角長 (≒43.27[mm])} \\ $$

サンプル

CameraPositionResetというSubItemをgrabした時に、ハンディカメラの位置を(0,1,0)の位置にリセットするサンプルです。

スタジオの中にハンディカメラが存在しない状態で vci.studio.GetHandiCamera() を実行してしまうと、エラーになります。
なので vci.studio.HasHandiCamera() == false でハンディカメラが存在しない場合は return をして処理を終了します。

vci.studio.HasHandiCamera() == true の場合は return が実行されずに camera.SetPosition(position) の行までいくので、カメラがリセットされます。
なので、アイテムが存在するか確認するHas関数の後に、アイテムをインスタンス化するGet関数を実行する必要があります。

main.lua
function onUse(use)
    -- PositionResetをUseした時
    if use == "CameraPositionReset" then
        -- カメラの位置をリセットする
        CameraPositionReset()
    end
end
 
function CameraPositionReset()
    -- ハンディカメラが存在しない場合終了する
    if vci.studio.HasHandiCamera() == false then
        print("ハンディカメラが存在しないので終了")
        return
    end
 
    -- リセットする座標
    local position = Vector3.__new(0, 1, 0)
    -- カメラのインスタンス
    local camera = vci.studio.GetHandiCamera()
    -- カメラの位置を変更
    camera.SetPosition(position)
    print("カメラの位置 :"..tostring(camera.GetPosition()))
end

実行結果

カメラの位置 : (0,1,0)
(カメラの座標がワールド座標で(0,1,0)の位置に移動します)

ケースバイケースではありますが Has関数がfalseの場合にreturnする という書き方を推奨します。
trueの場合に実行する でも問題ないのですが、変数のスコープがif文の中になってしまうこと、さらにif文がネストする可能性が大きいです。
Has関数がfalseの場合に処理をしない という事は確実に言える事なので、先頭にその処理を持ってくる事で分かりやすくします。
このようなプログラム書き方をガード節といいます。