~~NOTOC~~
====== VCIイベント関数 ======

<WRAP center round important 80%>

このページは過去の情報となります。\\
新しいスクリプトリファレンスは**[[https://developer.virtualcast.jp/vci-docs/api/events/index.html|こちら]]**になります。
</WRAP>

イベント関数とは、条件を満たした時に実行される関数です。

例えば「VCIに触った時に音を鳴らす」「VCIをつかんだ時にアニメーションをさせる」といったような挙動は、イベント関数を通じてそれぞれの処理が実行されます。

イベント関数はシステムによって関数名と関数の挙動が定義されています。

----
===== イベント関数一覧 =====

下表において、VCI上のSubItemのことも便宜上VCIと表現しています。

^ イベント関数 ^ 説明 ^ 条件 ^
| [[#update]] | 毎フレーム実行 |VCIを出したユーザーのみ|
| [[#updateAll]] | 全ユーザーで毎フレーム実行 | |
| [[#onUse]] | VCIを**使った**時に実行 |所有権を持っている|
| [[#onUnuse]] | VCIを**使うのをやめた**時に実行 |:::|
| [[#onTriggerEnter]] | VCIと[[vci:component:unity_collider|Collider]]が**接触した**時に実行  |所有権を持っている \\ [[vci:component:unity_collider|Collider]]の**IsTrigger：有効**|
| [[#onTriggerExit]] | VCIと[[vci:component:unity_collider|Collider]]が**離れた**時に実行  |:::|
| [[#onCollisionEnter]] | VCIと[[vci:component:unity_collider|Collider]]が**接触した**時に実行 |所有権を持っている \\ [[vci:component:unity_collider|Collider]]の**IsTrigger：無効** |
| [[#onCollisionExit]] | VCIと[[vci:component:unity_collider|Collider]]が**離れた**時に実行 |:::|
| [[#onGrab]] | VCIを**つかんだ**時に実行 | |
| [[#onUngrab]] | VCIを**離した**時に実行 | |

==== イベント関数の引数について ====

各イベント関数の引数には **Subitemのgameobject名** が **String型** で渡されます。\\
引数を使って ''SubItem = vci.assets.GetTransform(target)'' 等を使う事により、つかんだり触ったりしたSubitemに対して、処理を行う事ができます。

===== アイテムロード時のタイミングでの処理を書きたい =====

Unityの ''Start'' のような、アイテムロード時に最初に一度だけ実行されるイベント関数はありません。\\
しかし Lua はスクリプト言語ですので、 ''main.lua'' のグローバルな場所に処理を記述すれば、そのタイミングで実行できます。

=== サンプル ===
<file lua main.lua>
function func1()
    print("誰からも呼び出されていないのでこれは実行されない")
end

function func2()
    print("グローバルから呼び出されているので、アイテムをロードしたときに一度だけ実行される")
end

print("アイテムをロードしたときに一度だけ実行される")
func2()
</file>

===== update =====
**update()**

**VCIを出したユーザーのクライアントのみ**で毎フレーム実行されます。\\
他のクライアントでは実行されないので、結果を同期させる際には注意する必要があります。

ただし、updateによる処理であってもオブジェクトのトランスフォームなどはバーチャルキャストの機能によって同期します。\\
詳しくは [[vci:component:sdk:subitem:owned|VCIアイテムとSubItemについて]] を参照してください。

=== サンプル ===
<file lua main.lua>
function update()
end
</file>

===== updateAll =====
**updateAll()**

所有権に関係なく全ユーザーで毎フレーム実行されるupdate()です。\\
詳しくは [[vci:component:sdk:subitem:owned|VCIアイテムとSubItemについて]] を参照してください。

=== サンプル ===
<file lua main.lua>
function updateAll()
end
</file>

===== onUse =====
**onUse(use)**

[[vci:script:reference:eventfunction:ownership:#SubItemの所有権とイベント関数の関係|SubItemの所有権を持っている状態]]でSubItemを使った場合に実行されます。

※使用するにはつかめる事が前提のため、[[vci:component:unity_collider| Collider]]と[[vci:component:sdk:subitem| SubItem]]の**Grabbable**が設定されていないと動作しません。

=== サンプル ===
UseされたSubItemの名前がConsoleに表示されます。
<file lua main.lua>
function onUse(use)
     print("onUse : "..use)
     print("SubItemの "..use.." が使っている状態になりました。")
end
</file>

===== onUnuse =====
**onUnuse(use)**

VCIを持っている状態でVCIを使うのをやめた場合に実行されます。

※使用するにはつかめる事が前提のため、[[vci:component:unity_collider| Collider]]と[[vci:component:sdk:subitem| SubItem]]の**Grabbable**が設定されていないと動作しません。

=== サンプル ===
UseされたSubItemの名前がConsoleに表示されます。
<file lua main.lua>
function onUnuse(use)
     print("Unuse : "..use)
     print("SubItemの "..use.." が使っている状態から離れました。")
end
</file>

===== onTriggerEnter =====
**onTriggerEnter(item, hit)**

VCIとColliderが接触した時に実行されます。\\
onTriggerEnterはVCIのSubItemにアタッチされた[[vci:component:unity_collider| Collider]]の**Is Trigger**が有効だと実行されます。\\
SubItemに物理挙動を持たせたくないが、接触しているかどうかの判定は行いたい時に使います。

キャラクターの各パーツにもColliderは存在するため、キャラクターの接触判定を行うことも出来ます。


=== サンプル ===
SubItem同士が接触するとSubItemの名前のログが流れます。
<file lua main.lua>
function onTriggerEnter(item, hit)
    print("Trigger Enter")
    print(string.format("%s <= %s", item, hit))
end
</file>

===== onTriggerExit =====
**onTriggerExit(item, hit)**

VCIとColliderが接触した状態から離れた時に実行されます。\\
onTriggerExitはVCIのSubItemにアタッチされた[[vci:component:unity_collider| Collider]]の**Is Trigger**が有効だと実行されます。\\
SubItemに物理挙動を持たせたくないが、接触しているかどうかの判定は行いたい時に使います。

=== サンプル ===
SubItem同士が接触した状態から離れるとSubItemの名前のログが流れます。
<file lua main.lua>
function onTriggerExit(item, hit)
    print("Trigger Exit")
    print(string.format("%s <= %s", item, hit))
end
</file>

===== onCollisionEnter =====
**onCollisionEnter(item, hit)**

VCIとCollider(+Rigidbody)が接触した時に実行されます。\\
onCollisionEnterはVCIのSubItemにアタッチされた[[vci:component:unity_collider| Collider]]の**Is Trigger**が無効だと実行されます。\\
SubItemに物理挙動を持たせた上で接触判定を行いたい時に使用します。

=== サンプル ===
SubItem同士が接触するとSubItemの名前のログが流れます。

<file lua main.lua>
function onCollisionEnter(item, hit)
    print("Collision Enter")
    print(string.format("%s <= %s", item, hit))
end
</file>

===== onCollisionExit =====
**onCollisionExit(item, hit)**

VCIとCollider(+Rigidbody)が接触した状態から離れた時に実行されます。\\
onCollisionExitはVCIのSubItemにアタッチされた[[vci:component:unity_collider| Collider]]の**Is Trigger**が無効だと実行されます。\\
SubItemに物理挙動を持たせた上で接触判定を行いたい時に使用します。

=== サンプル ===
SubItem同士が接触した状態から離れるとSubItemの名前のログが流れます。
<file lua main.lua>
function onCollisionExit(item, hit)
    print("Collision Exit")
    print(string.format("%s <= %s", item, hit))
end
</file>

===== onGrab =====
**onGrab(target)**

onGrabはVCIをつかんだ時に実行されます。\\
onGrab(target)の引数にはSubItemの名前が格納されます。

=== サンプル ===
つかんだアイテムの現在地をConsoleに表示するサンプルです。
<file lua main.lua>
function onGrab(target)
    print("onGrab : "..target)
    local item = vci.assets.GetTransform(target)
    print(item.GetPosition())
end
</file>

===== onUngrab =====
**onUngrab(target)**\\
onUngrabはVCIをつかんでる状態から離した時に実行されます。\\
onGrab(target)の引数にはSubItemの名前が格納されます。

=== サンプル ===
下記サンプルはSubItemを離した時に、(0,0,0)の位置に移動させるサンプルです。\\
アイテムを移動させた場合は''SetVelocity(Vector3.zero)''でアイテムに加わってる力を０にすると挙動が安定します。

<file lua main.lua>
function onUngrab(target)
    print("onUngrab : "..target)
    local item = vci.assets.GetTransform(target)
    item.SetLocalPosition(Vector3.zero)
    item.SetVelocity(Vector3.zero)
end
</file>

===== onGrabとonUngrabの仕様について =====

  * onGrabとonUngrabはペアで処理されます。
  * onGrab()の条件：所有権がある状態でGrabした場合に実行されます。(※1)
  * onUngrab()の条件：Grab状態からUngrab状態になる or 所有権が無くなった場合に実行されます。(※2)

※1.所有権が無い状態でGrabしてもonGrab()は実行されません。Grabした状態で所有権を得たらonGrab()を通ります。\\
※2.Grab状態であっても、所有権が無くなった段階でonUngrab()が実行されます。

==== 処理の例 ====

**２人で同じVCIをつかんだ場合**

1.VCIを先につかんでる人が居る。\\
　→ 先:Grab + 所有権有り → onGrab()実行済み\\
2.後から別の人が同じVCIをつかむ。\\
　→ 先:Grab + 所有権無し → onUngrab()が実行される\\
　→ 後:Grab + 所有権有り → onGrab()が実行される