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.

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.

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

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

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

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

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

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

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