====== VCI Event Functions=====

Event functions are functions that are executed when certain conditions are met.

For example, behaviors such as "ring a sound when you touch a VCI" or "run animation when you grab a VCI" can be run through event functions.

The system defines the names and behaviors of event functions.


===== List of event functions=====

----
^ Event functions ^ Description ^
| update() | Executed every frame on the client of the user who spawned the VCI |
| updateAll() | An update() that is executed on every user regardless of ownership |
| onUse(use) | Executed when a grip button is pressed while the VCI is being grabbed. |
| onUnuse(use) | Executed when a grip button is released while the VCI is being grabbed. |
| onTriggerEnter(item, hit) | Executed when a VCI and a [[en:vci:component:unitycomponent:collider| Collider]] hit each other.\\ (Enabled when IsTrigger on the [[en:vci:component:unitycomponent:collider| Collider]] is checked) |
| onTriggerExit(item, hit) | Executed when a VCI and a [[en:vci:component:unitycomponent:collider| Collider]] separate from each other.\\ (Enabled when IsTrigger on the [[en:vci:component:unitycomponent:collider| Collider]] is checked) |
| onCollisionEnter(item, hit) | Executed when a VCI and a [[en:vci:component:unitycomponent:collider| Collider]] (+[[en:vci:component:unitycomponent:rigidbody|Rigidbody]]) hit each other. |
| onCollisionExit(item, hit) | Executed when a VCI and a [[en:vci:component:unitycomponent:collider|Collider]](+[[en:vci:component:unitycomponent:rigidbody|Rigidbody]]) separate from each other. |
| onGrab(target) | Executed when VCI is grabbed (the trigger is pulled). |
| onUngrab(target) | Executed when VCI is released (the trigger is released). |

==== Arguments of event functions ====

**The GameObject name of the Subitem** is passed to the argument of each event functions as a **string**.\\
By using arguments (''SubItem = vci.assets.GetSubItem(target)'', for instance), you can perform specified process on the Subitem you grabbed or touched.

===== Absence of Start function =====

The VCI script doesn't have event functions that correspond to Unity's (C#) "Start" or "Awake."\\
However, **the portion of the script you have written outside of functions are only run once at the time of spawning, which can virtually be used as a Start function.**\\

<file lua main.lua>
-- This section works as a start function
print("Execute at the time of spawning only")

function myFunction()
     -- It won't run when the VCI is called. It must be called from other functions.
     print("Executed from onUse()")
end

function onUse()
     print("Calls myFunction() you defined, when the use button is pressed ")
     myFunction()
end
</file>

===== update =====

The update is executed every frame on **the client of the user who spawned the VCI**.\\
It won't be run on other clients, so be aware when synchronizing the result.

However, the transform of an object is synchronized via standard VirtualCast feature even with the process done by the update.
For details, refer to [[en:vci:component:sdk:subitem:owned|About VCI items and subitems]].\\

<file lua main.lua>
function update()
end
</file>

===== updateAll =====

An update() that is executed on every user every frame regardless of the ownership.\\
For details, refer to [[en:vci:component:sdk:subitem:owned|About VCI items and subitems]].\\

<file lua main.lua>
function updateAll()
end
</file>

===== onUse =====

onUse is executed when a grip button is pressed while the VCI is being grabbed.\\
In the example below, the name of the SubItem being used will be displayed on the Console.

Note: To use, you need to be able to grab it as well. Therefore, a [[en:vci:component:unitycomponent:collider| Collider]] and **Grabbable** on the [[en:vci:component:sdk:subitem| SubItem(VCISDK)]] must be set in order for it to work.

<file lua main.lua>
function onUse(use)
     print("onUse : "..use)
     print("SubItem "..use.." is in gripped state")
end
</file>

===== onUnuse =====

Executed when a grip button is released while the VCI is being grabbed.\\
In the example below, the name of the SubItem being used will be displayed on the Console.

Note: To use, you need to be able to grab it as well. Therefore, a [[en:vci:component:unitycomponent:collider| Collider]] and **Grabbable** on the [[en:vci:component:sdk:subitem| SubItem(VCISDK)]] must be set in order for it to work.

<file lua main.lua>
function onUnuse(use)
     print("Unuse : "..use)
     print("SubItem "..use.." is released from the gripped state.")
end
</file>

===== onTriggerEnter =====

onTriggerEnter is executed when VCI and Collider hit each other.\\
This is executed when the [[en:vci:component:unitycomponent:collider| Collider]] attached to the VCI SubItem has its **IsTrigger** enabled.\\
You could use this when you want to detect collision but doesn't want to give it a physical behavior.

In the example below, when SubItems hit each other, their name log is printed on the console.\\

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

===== onTriggerExit =====

onTriggerExit is executed when a VCI and a Collider separate from each other.\\
This is executed when the [[en:vci:component:unitycomponent:collider| Collider]] attached to the VCI SubItem has its **IsTrigger** enabled.\\
You could use this when you want to detect collision but doesn't want to give it a physical behavior.

In the example below, when SubItems hit each other, their name log is printed on the console.

<file lua main.lua>
function onTriggerExit(item, hit)
    print("Trigger Exit")
    print(string.format("%s <= %s", item, hit))
end
</file>

===== onCollisionEnter =====

onTriggerEnter is executed when a VCI and a Collider (+Rigidbody) hit each other.\\
This is executed when the [[en:vci:component:unitycomponent:collider| Collider]] attached to the VCI SubItem has its **IsTrigger** disabled.\\
You could use this when you want to detect a collision of items with physical behavior.

In the example below, when SubItems hit each other, their name log is printed on the console.

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

===== onCollisionExit =====

onCollisionExit  is executed when a VCI and a Collider separate from each other.\\
This is executed when the [[en:vci:component:unitycomponent:collider| Collider]] attached to the VCI SubItem has its **IsTrigger** disabled.\\
You could use this when you want to detect a collision of items with physical behavior.

In the example below, when SubItems separate from each other from a collided state, their name log is printed on the console.

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

===== onGrab =====

onGrab is executed when a VCI is grabbed.\\
The name of the SubItem is stored in the argument of onGrab(target).

The example below prints the position of the item being grabbed.

<file lua main.lua>
function onGrab(target)
    print("onGrab : "..target)
    local item = vci.assets.GetSubItem(target)
    print(item.GetPosition())
end
</file>

===== onUngrab =====

onUngrab is executed when VCI is released from a grabbed state.\\
The name of the SubItem is stored in the argument of onUngrab(target).

The example below moves the SubItem to the position (0,0,0) when the item is being released.\\
After you moved an item, you can stabilize its movement by disabling the force being applied using ''SetVelocity(Vector3.zero)''.

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

===== About onGrab and onUngrab =====

  * onGrab and onUngrab are processed in pairs.
  * Condition for onGrab(): It is executed when Grabbed while having the ownership. (Note 1)
  * Condition for onUngrab(): It is executed when the state of the item has changed from Grabbed state to Ungrabbed state OR lost the ownership. (Note 2)

Note 1. Grabbing while not having the ownership will not execute onGrab(). Receiving the ownership while grabbing will result in the execution of onGrab().\\
Note 2. Even if the item is in Grabbed state, onUngrab() will be executed when the grabber lost the ownership.

==== Example ====

**When two players grabbed the same VCI**

1. The first player is already grabbing the VCI.\\
　→ First: Grab + owner → onGrab() executed\\
2. The second player later grabs the same VCI.\\
　→ First: Grab + non-owner → onUngrab() executed\\
　→ Second: Grab + owner → onGrab() executes