~~NOTOC~~
====== ExportTransform ======
<WRAP center round important 80%>

このページは過去の情報となります。\\
新しいスクリプトリファレンスは**[[https://developer.virtualcast.jp/vci-docs/api/|こちら]]**になります。
</WRAP>
ExportTransformクラスはVCIのオブジェクトを扱うクラスです。\\
オブジェクトはUnityのTransformに対応し、加えてRigidbodyやSubItemの操作も含まれます。\\
たとえば移動、回転、縮尺の変更や、力を与えて回転させたり、吹き飛ばしたりする事ができます。

^ ExportAssets ^^^
^ 名前 ^ 説明 ^ バージョン ^
| [[vci/script/reference/exporttransform#GetTransform | GetTransform]] | VCI内のTransformを取得 | |
^ ExportTransform ^^^
^ 名前 ^ 説明 ^ バージョン ^
| [[vci/script/reference/exporttransform#GetName]] | Transformの名前を取得 | |
| [[vci/script/reference/exporttransform#GetPosition / GetLocalPosition]] | Transformの位置を取得| |
| [[vci/script/reference/exporttransform#GetRotation / GetLocalRotation]] | Transformの回転を取得| |
| [[vci/script/reference/exporttransform#GetLocalScale]] | Transformの縮尺を取得 | |
| [[vci/script/reference/exporttransform#GetVelocity]] | Rigidbodyの速度をVector3として取得 | |
| [[vci/script/reference/exporttransform#GetAngularVelocity]] | Rigidbodyの角速度をVector3として取得 | |
| [[vci/script/reference/exporttransform#GetForward / GetRight / GetUp]] | Transformを基準に前・右・上のVector3を取得 | |
| [[vci/script/reference/exporttransform#GetLocalToWorldMatrix]] | ローカル→ワールド座標に変換した時の行列 | |
| [[vci/script/reference/exporttransform#GetAttractable]] | SubItemが引き寄せ可能かどうか | |
| [[vci/script/reference/exporttransform#SetPosition / SetLocalPosition]] | Transformの位置をVector3で変更 | |
| [[vci/script/reference/exporttransform#SetRotation / SetLocalRotation ]] | Transformの回転をQuaternionで変更 | |
| [[vci/script/reference/exporttransform#SetLocalScale]] | Transformの縮尺をVector3で変更 | |
| [[vci/script/reference/exporttransform#SetVelocity ]] | Rigidbodyに加わっている力をVector3で変更 | |
| [[vci/script/reference/exporttransform#SetAngularVelocity ]] | Rigidbodyに加わってる回転をVector3で変更 | |
| [[vci/script/reference/exporttransform#AddForce]] | 指定したForceModeでRigidbodyに力を付与 | v2.2.1a以降 |
| [[vci/script/reference/exporttransform#SetAttractable]] | SubItemの引き寄せを設定 | |
| [[vci/script/reference/exporttransform#IsMine]] | SubItemの所有者かどうか | |
| [[vci/script/reference/exporttransform#IsSubItem]] | SubItemかどうか | |
| [[vci/script/reference/exporttransform#SetActive / ActiveSelf / ActiveInHierarchy ]] | Transform 自身の有効無効設定を設定 | v2.0.1a以降 |
^ 他のクラスで使用 ^^^
^ 名前 ^ 説明 ^ バージョン ^
| GetAnimation | [[vci:script:reference:exportanimation|ExportAnimation]]を使用 |  |
| GetAudioSources | [[vci:script:reference:exportaudiosource|ExportAudioSource]]を使用 | v2.0.3b以降　 |

ExportTransformクラスを使うには ''local transform = vci.assets.GetTransform("SubItemName") '' のようにTransformの名前を指定してインスタンス化します。\\
その後、 ''transform.各関数()'' と各関数を実行できます。

===== VCIの同期について =====

ネットワーク越しに動くものを考える場合、同期を意識する必要があります。\\
バーチャルキャストのスタジオの中にAさん、Bさん、Cさんと居た時、Aさんが動かした結果をBさん、Cさんに反映させる事を「同期させる」といいます。\\
一方、動かした人のパソコンでしか動かないような設定は「ローカルのみで動作する」というような言い方になります。\\
VCIでは主に同期させる方法は以下の通りになります。\\

  * transformはバーチャルキャストの機能によって同期します。\\
  * ''_ALL_'' のついた関数は同期して実行されます。\\
  * [[vci/script/reference/syncvariable|同期変数]]を使用してVCIの状態を同期させます。\\

つまり、transformの同期については、強く意識せずともVCIを出したクライアントで動かした結果が、バーチャルキャストの機能を通じて他のクライアントにも適用されます。\\
詳細なtransformの同期については [[vci:component:sdk:subitem:owned|VCIアイテムとSubItemについて]] をご確認ください。

===== GetTransform =====
<wrap em>ExportAssets</wrap>**.GetTransform fun(name: string): [[vci:script:reference:exporttransform|ExportTransform]]**

VCI 内のオブジェクトを取得します。 \\
引数 ''name'' に取得したいオブジェクト名を入れると、該当オブジェクトの ''ExportTransform'' を取得します。\\
指定した名前のオブジェクトが存在しない場合、 ''nil'' が返ります。

取得した ''ExportTransform'' の関数を使用する事により、 transform の値の取得や変更を行う事ができます。\\
(詳しくは [[vci:script:reference:exporttransform|ExportTransform]] を参照してください)

**(バーチャルキャスト 2.3.1a 以降)**

引数 ''name'' が ''/'' から始まる文字列の場合、 ''name'' を VCIObject から見たパスとして検索し、該当パスにオブジェクトがあった場合はそのオブジェクトの ''ExportTransform'' を取得します。 \\
該当パスのオブジェクトが存在しない場合は、従来通り ''name'' 全体をオブジェクト名として検索します。


=== サンプル ===
<file lua main.lua>
--ExportTransform
--SubItem のオブジェクト名は「SubItem」
local SubItem = vci.assets.GetTransform("SubItem") 

print("Name: " .. SubItem.GetName())
print("Position: " .. SubItem.GetPosition().ToString())
print("LocalPosition: " .. SubItem.GetLocalPosition().ToString())
print("Rotation: " .. SubItem.GetRotation().ToString())
print("LocalRotation: " .. SubItem.GetLocalRotation().ToString())
print("LocalScale: " .. SubItem.GetLocalScale().ToString())
print("Forward: " .. SubItem.GetForward().ToString())
</file>

=== 実行結果 ===
<code>
Name: SubItem
Position: (0.00, 1.00, 0.00)
LocalPosition: (0.00, 0.00, 0.00)
Rotation: (0.00000, 0.70711, 0.00000, 0.70711)
LocalRotation: (0.00000, 0.00000, 0.00000, 1.00000)
LocalScale: (1.00, 1.00, 1.00)
Forward: (1.00, 0.00, 0.00)
</code>

\\


=== サンプル2 パス指定での取得(バーチャルキャスト 2.3.1a 以降) ===

以下のような構造の VCI の場合

{{:vci:script:reference:gettransform_sample_2.png|}}


<file lua main.lua>
local shhere_1 = vci.assets.GetTransform("/SubItem1/Sphere")
print(shhere_1.GetName())
print(shhere_1.GetPosition())

local shhere_2 = vci.assets.GetTransform("/SubItem2/Sphere")
print(shhere_2.GetName())
print(shhere_2.GetPosition())
</file>

=== 実行結果 ===

<code>
Sphere
(1.00, 2.50, 0.00)
Sphere
(2.00, 1.00, 0.00)
</code>

==== 複数のsubItemをfor文で宣言する ====

SubItemの名前を ''Item1'' ''Item2'' ''Item3'' という風に連番で命名します。\\
そしたら for文を使って1からの連番で ''GetTransform()'' する事ができます。\\
※iは ''tostring(i)'' で文字列に変換できます。

=== サンプル ===
<file lua main.lua>
-- テーブルをfor文で宣言する
local _Items = {}
for i=1, 5 do
    _Items[i] = vci.assets.GetTransform("Item"..tostring(i))
    print(_Items[i].."をテーブルに登録しました。")
end
</file>




===== GetName =====
<wrap em>ExportTransform</wrap>**GetName fun(): string**\\
VCIのオブジェクト名を取得できます。

=== 戻り値 ===
string

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")

function onUse(use)
    cubeName = cube.GetName()
    print(cubeName)
end
</file>

=== 実行結果 ===
<code>
"TestCube"
</code>



===== GetPosition / GetLocalPosition =====
**GetPosition fun(): Vector3**\\
**GetLocalPosition fun(): Vector3**\\
Transformの現在地を取得できます。\\
Position()の場合、Unityの原点(0,0,0)が基準になり、LocalPosition()の場合はVCIを出現させた位置が原点として扱われます。

=== 戻り値 ===
Vector3

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")

function onUse(use)
    cubePos = cube.GetPosition()
    print(cubePos)
end
</file>

=== 実行結果 ===
<code>
(0.0, 1.2, 0.0)
</code>


===== GetRotation / GetLocalRotation =====
**GetRotation fun(): Quaternion**\\
**GetLocalRotation fun(): Quaternion**\\
Transformの回転(Quaternion)を取得できます。\\
[[https://blog.virtualcast.jp/blog/2019/11/quaternion/ | Quaternionとは]]
Rotation()の場合、Unity全体が基準の回転（Z+が正面）となり、LocalRotation()の場合はVCIを出現させた時の方向を基準とした回転として扱われます。\\
''SetRotation(Quaternion.identity)'' UnityのZ+が正面方向として、姿勢を変更できます。

=== 戻り値 ===
Quaternion

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")

function onUse(use)
    cubeRot = cube.GetRotation()
    print(cubeRot)
end
</file>

=== 実行結果 ===
<code>
(-0.5, 0.5, 0.5, 0.5)
</code>



===== GetLocalScale =====
**GetLocalScale fun(): Vector3**\\
Transformの縮尺を取得できます。\\
\\
スケールが変更可能なTransformのスケジュールを変える場合、１度GetLocalScale()で取得した値に対して、目的の倍率を掛けた後にSetLocalScale()とする事で「現在の大きさを基準したscaleの変更」をする事ができます。\\
（SetLocalScale()のみだと、現在の大きさを考慮しないスケールの変更となる）

=== 戻り値 ===
Vector3

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")

function onUse(use)
    cubeScale = cube.GetLocalScale()
    print(cubeScale)
end
</file>

=== 実行結果 ===
<code>
(1.0, 1.0, 1.0, 1.0)
</code>



===== GetVelocity =====
**GetVelocity fun(): Vector3**\\
Transformの速度をベクトルとして取得します。\\
サンプルはSubItemをUseした時に、そのVCIの速度を取得し、ログに表示します。

=== 引数 ===
Vector3


=== サンプル ===
<file lua main.lua>
item = vci.assets.GetTransform("subitem")
function onGrab()
    local velocity = item.GetVelocity()
    print(velocity)
end
</file>

===== GetAngularVelocity =====
**GetAngularVelocity fun(): Vector3**\\
Transformの角速度を、ラジアン/秒で表されるベクトルで取得します。\\
サンプルは、SubItemをUseした時に角速度を取得してログに出力します。

=== 戻り値 ===
Vector3

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")

function onUse(use)
    local angularVelocity = cube.GetAngularVelocity()
    print(angularVelocity)
end
</file>



===== GetForward / GetRight / GetUp =====
**GetForward fun(): Vector3**\\
**GetRight fun(): Vector3**\\
**GetUp fun(): Vector3**\\
Transformが現在向いてる前方向のベクトルを取得できます。\\
(Transformを基準にしたZ軸プラスのベクトル)\\
\\
用途としては…GetForward()でオブジェクトの正面方向のベクトルを取得し、onUngrab()（SubItemを離した時）に正面方向のベクトルを使って AddForce()で力を加えると正面方向に力を加える事ができます。\\
「勢いよく前に飛ばす」等ができる。

=== 戻り値 ===
Vector3

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("subitem")

function onUse(use)
    local cubeForward = cube.GetForward()
    print(cubeForward)
    cube.AddForce(cubeForward * 1000)
end
</file>

=== 実行結果 ===
<code>
cubeが向いてる方向に飛ぶ。cubeを離した状態でuseする必要がある。
</code>


===== GetLocalToWorldMatrix =====
**GetLocalToWorldMatrix fun(): Matrix4x4**\\
ローカル座標からワールド座標に変換した時の行列です。

===== GetAttractable =====
**GetAttractable fun(): boolean**

SubItemが引き寄せ可能かどうかを返します。






===== SetPosition / SetLocalPosition =====
**SetPosition fun(position: Vector3):**\\
**SetLocalPosition fun(localPosition: Vector3):**\\
VCIの現在地をVector3で指定した値に変更します。\\
Position()の場合、Unityの原点(0,0,0)が基準になり、LocalPosition()の場合はVCIを出現させた位置が原点として扱われます。\\
\\
位置や回転をSetする場合、Transformに力が加わっているとSet関数で指定した値にした後すぐ力が加わる計算が入るので、意図した結果にならない事があります。\\
なので、Set関数を呼んだ後にSetVelocity(0,0,0) で加わっている力を０にするのがよいです。\\
\\
順番はSetPosition()の後にSetVelocity(0,0,0)です。\\
（逆だと力が0になった後でSetPosition()で力が加わる可能性があります）

=== 引数 ===
vector3

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")

function onUse(use)
    local cubePos = cube.GetPosition()
    print(cubePos)
    cubePos.z = cubePos.z + 1
    print(cubePos)
    cube.SetPosition(cubePos)
    cube.SetVelocity(Vector3.zero)
end
</file>

=== 実行結果 ===
<code>
(0.0, 1.0, 0.0)
(0.0, 1.0, 1.0)
Z軸方向に1移動して止まります。
</code>


===== SetRotation / SetLocalRotation =====
**SetRotation fun(rotation: Quaternion):**\\
**SetLocalRotation fun(localRotation: Quaternion):**\\
VCIの姿勢(回転)をQuternionで指定した値に変更します。\\
Rotation()の場合、Unity全体が基準の回転（Z+が正面）となり、LocalRotation()の場合はVCIを出現させた時の方向を基準とした回転として扱われます。\\
\\
位置や回転をSetする場合、Transformに力が加わっているとSet関数で指定した値にした後すぐ力が加わる計算が入るので、意図した結果にならない事があります。\\
なので、Set関数を呼んだ後にSetVelocity(0,0,0) で加わっている力を０にするのがよいです。\\
\\
順番はSetPosition()の後にSetVelocity(0,0,0)です。\\
（逆だと力が0になった後でSetPosition()で力が加わる可能性があります）

=== 引数 ===
Quaternion

=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")
local subCube = vci.assets.GetTransform("TestCube2")

function onUse(use)
    local cubeRot = cube.GetLocalRotation()
    local subCubeRot = subCube.GetLocalRotation()
    subCube.SetLocalRotation(cubeRot)
    subCube.SetVelocity(Vector3.zero)
    subCube.SetAngularVelocity(Vector3.zero)
end

</file>

=== 実行結果 ===
<code>
subCubeの角度がCubeと等しくなります。
</code>



===== SetLocalScale =====
**SetLocalScale fun(localScale: Vector3):**\\
VCIの縮尺をVector3で指定した値に変更します。\\
\\
スケールが変更可能なTransformのスケジュールを変える場合、１度GetLocalScale()で取得した値に対して、目的の倍率を掛けた後にSetLocalScale()とする事で「現在の大きさを基準したscaleの変更」をする事ができます。


=== サンプル ===
<file lua main.lua>
local cube = vci.assets.GetTransform("TestCube")

function onUse(use)
    local cubeScale = cube.GetLocalScale()
    setScale = cubeScale * 1.5
    cube.SetLocalScale(setScale)
    print(cube.GetLocalScale())
end
</file>

=== 実行結果 ===
<code>
(4回use)
(1.0, 1.0, 1.0)
(1.5, 1.5, 1.5)
(2.3, 2.3, 2.3)
(3.4, 3.4, 3.4)
</code>



===== SetVelocity =====
**SetVelocity fun(velocity: Vector3):**\\
Transformの速度を、指定したVector3の値に設定します。\\
\\
サンプルはSubItemを離した時に、+Z方向に移動するように速度を設定します。\\
実行された直後にVelocityの値を持った状態になります。\\
Vector3.zero をセットすると、物理演算による移動を止める事ができます。

=== 引数 ===
vector3

=== サンプル ===
<file lua main.lua>
item = vci.assets.GetTransform("subitem")
function onUngrab()
    local velocity = Vector3.__new(0, 0, 10)
    print(velocity)
    item.SetVelocity(velocity)
end
</file>

===== SetAngularVelocity =====
**SetAngularVelocity fun(angularVelocity: Vector3):**\\
Transformの角速度を、ラジアン/秒で表されるベクトルで設定します。\\
\\
サンプルは、SubItemを離した時に、velocity変数の値を角速度として設定します。\\

=== 引数 ===
vector3

=== サンプル ===
<file lua main.lua>
item = vci.assets.GetTransform("subitem")
function onUngrab()
    local velocity = Vector3.__new(10, 0, 0)
    print(velocity)
    item.SetAngularVelocity(velocity)
end
</file>


===== AddForce(force: Vec3, forceMode: ForceMode) =====
**AddForce fun(force: Vector3, forceMode: ExportForceMode):**\\
[[vci/script/reference/forcemode#vciforcemode_exportforcemode | ForceMode]]で指定したアルゴリズムを利用し、Vector3の方向に向かって力を加えます。\\



=== forceMode.Forceを利用したサンプル ===

<file lua main.lua>
item = vci.assets.GetTransform("subitem")
function onUngrab()
    item.AddForce(Vector3.__new(0, 0, 10), vci.forceMode.Force)
end
</file>


=== forceMode.Impulseを利用したサンプル ===


<file lua main.lua>
item = vci.assets.GetTransform("subitem")
function onUngrab()
    item.AddForce(Vector3.__new(0, 0, 10), vci.forceMode.Impulse)
end
</file>



===== IsMine =====
**IsMine boolean**\\
SubItemの所有者の場合だけ処理したい場合などに使用します。\\
所有権については [[vci:script:reference:eventfunction:ownership|所有権とイベント関数の関係]] を参考にしてください。

=== サンプル ===
<file lua main.lua>
item = vci.assets.GetTransform('SubItem')
 
function updateAll() -- 所有権に関係なく全ユーザーが十個する
    if item.IsMine then -- SubItemの所有者の場合 true
        item.SetPosition(Vector3.__new(1, 2, 3))
    end
end
</file>

=== SetAttractable ===
**SetAttractable fun(value: boolean):**

SubItemの引き寄せを設定します。

===== IsSubItem =====
**IsSubItem boolean**\\
SubItemであるかどうかを返します。


===== SetActive / ActiveSelf / ActiveInHierarchy =====
**SetActive fun(isActive: boolean):**\\
**_ALL_SetActive fun(isActive: boolean):**\\
**ActiveSelf boolean**\\
**ActiveInHierarchy boolean**\\
Transform の有効無効設定は ''SetActive(isActive: bool)'' で設定することができます。\\
デフォルトの状態は有効です。\\
※SetActiveの場合は非同期でアクティブを変更するため、部屋にいる全員の環境でアクティブを変更する場合は''_ALL_SetActive(isActive: bool)''を使用します。\\

有効状態である場合

  * レンダリングが有効化し、表示されます。
  * 物理判定が有効化し、他の Rigidbody と干渉できる状態になります。
  * Grab や Use といったインタラクションが有効化し、可能になります。

無効状態である場合

  * レンダリングが無効化し、表示されなくなります。
  * 物理判定が無効化し、他の Rigidbody と干渉できない状態になります。
  * Grab や Use といったインタラクションが無効化し、できなくなります。

また ''ActiveSelf'' は自分自身の有効無効設定を取得します。

ただし Transform が他の Transform の子になっている場合は挙動が複雑になります。\\
たとえば Hierarchy 上の親 Transform が無効状態ならば、自身の有効無効に関わらず、無効状態になります。

したがって、その Transform が実際に有効なのか無効なのかを調べるには ''ActiveInHierarchy'' を使うと良いでしょう。

<code txt Transform の Hierarchy 構造>
─ Parent
   └ Child
</code>


=== サンプル ===
<file lua main.lua>
local Parent = vci.assets.GetTransform("Parent")
local Child = vci.assets.GetTransform("Child")

Parent.SetActive(false) -- Parent は無効設定
Child.SetActive(true) -- Child は有効設定

--> Parent も Child も無効状態になり、非表示状態になる

print(Child.ActiveSelf) --> true. Child 自身は有効設定だが...
print(Child.ActiveInHierarchy) --> false. Child は実際には無効状態となる.
</file>