Table of Contents

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 Collider hit each other.
(Enabled when IsTrigger on the Collider is checked)
onTriggerExit(item, hit) Executed when a VCI and a Collider separate from each other.
(Enabled when IsTrigger on the Collider is checked)
onCollisionEnter(item, hit) Executed when a VCI and a Collider (+Rigidbody) hit each other.
onCollisionExit(item, hit) Executed when a VCI and a Collider(+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.

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

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 About VCI items and subitems.

main.lua
function update()
end

updateAll

An update() that is executed on every user every frame regardless of the ownership.
For details, refer to About VCI items and subitems.

main.lua
function updateAll()
end

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 Collider and Grabbable on the SubItem(VCISDK) must be set in order for it to work.

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

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 Collider and Grabbable on the SubItem(VCISDK) must be set in order for it to work.

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

onTriggerEnter

onTriggerEnter is executed when VCI and Collider hit each other.
This is executed when the 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.

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

onTriggerExit

onTriggerExit is executed when a VCI and a Collider separate from each other.
This is executed when the 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.

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

onCollisionEnter

onTriggerEnter is executed when a VCI and a Collider (+Rigidbody) hit each other.
This is executed when the 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.

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

onCollisionExit

onCollisionExit is executed when a VCI and a Collider separate from each other.
This is executed when the 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.

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

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.

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

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).

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

About onGrab and onUngrab

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