VTI Targets: Difference between revisions

From WaffleSlapper's Project Wiki
(More fleshing out of VTITarget.)
(Added section about network ownership.)
 
(One intermediate revision by the same user not shown)
Line 4: Line 4:


The VTITarget component is one of the core scripts for the [[VTI World Kit]]. It is used to identify a GameObject as something that can be interacted with  by Twitch viewers when running [[VRChat Twitch Integration]].
The VTITarget component is one of the core scripts for the [[VTI World Kit]]. It is used to identify a GameObject as something that can be interacted with  by Twitch viewers when running [[VRChat Twitch Integration]].
== Event Firing ==
When the [[VTI Event Handler]] receives an [[VTI Events|Event]] from the [[VTI Companion App]], it will enqueue it under the ID of the triggered Target. Once that Event is at the top of the Queue, the Event Handler will attempt to dispatch the Event data to the Target and then call <syntaxhighlight lang="csharp" inline>VTIFire()</syntaxhighlight>.
Once Fired, the VTITarget will forward the Event data to each [[VTI Drivers|Driver]] component within the same GameObject as the VTITarget component, and then call <syntaxhighlight lang="csharp" inline>VTIEventPlay()</syntaxhighlight> on each Driver.
=== Readiness Validation ===
Before firing, the [[VTI Event Handler]] will call <syntaxhighlight lang="csharp" inline>VTICheckCanFire()</syntaxhighlight> against the queued VTITarget. This will first check the current time against the Cooldown property, and then will loop through all attached [[VTI Drivers|Driver]] component and call <syntaxhighlight lang="csharp" inline>VTICheckReady()</syntaxhighlight> on each. If any Driver returns <syntaxhighlight lang="csharp" inline>false</syntaxhighlight>, or the Cooldown has not yet elapsed, the Event is skipped and the process repeats for the next in line.


== Properties ==
== Properties ==
Line 45: Line 37:
|-
|-
| VTIFire() || void || Trigger this Target. Forwards [[VTI Events|Event]] data to all attached [[VTI Drivers|Drivers]] and calls <syntaxhighlight lang="csharp" inline>Driver.VTIEventPlay()</syntaxhighlight> on each.
| VTIFire() || void || Trigger this Target. Forwards [[VTI Events|Event]] data to all attached [[VTI Drivers|Drivers]] and calls <syntaxhighlight lang="csharp" inline>Driver.VTIEventPlay()</syntaxhighlight> on each.
|}
== Event Firing ==
When the [[VTI Event Handler]] receives an [[VTI Events|Event]] from the [[VTI Companion App]], it will enqueue it under the ID of the triggered Target. Once that Event is at the top of the Queue, the Event Handler will attempt to dispatch the Event data to the Target and then call <syntaxhighlight lang="csharp" inline>VTIFire()</syntaxhighlight>.
Once Fired, the VTITarget will forward the Event data to each [[VTI Drivers|Driver]] component within the same GameObject as the VTITarget component, and then call <syntaxhighlight lang="csharp" inline>VTIEventPlay()</syntaxhighlight> on each Driver.
==== Readiness Validation ====
Before firing, the [[VTI Event Handler]] will call <syntaxhighlight lang="csharp" inline>VTICheckCanFire()</syntaxhighlight> against the queued VTITarget. This will first check the current time against the Cooldown property, and then will loop through all attached [[VTI Drivers|Driver]] component and call <syntaxhighlight lang="csharp" inline>VTICheckReady()</syntaxhighlight> on each. If any Driver returns <syntaxhighlight lang="csharp" inline>false</syntaxhighlight>, or the Cooldown has not yet elapsed, the Event is skipped and the process repeats for the next in line.
==== Network Ownership ====
As a final step before firing, the [[VTI World Kit]] will attempt to take [https://creators.vrchat.com/worlds/udon/networking/ Ownership] of the GameObject. In order to prevent desynced cooldowns from double-firing or overriding another Streamer's [[VTI Events|Events]], the VTITarget script will also refuse ownership transfer if it is still in use. Objects that the [[VTI World Kit]] cannot take Ownership of will stay on the queue until Ownership can be obtained. If this results in an [[VTI Events|Event]] that never fires, check to make sure you don't have other things trying to keep Ownership of that object, e.g. scripts on a Pickup with the VRCObjectSync component attached.
== User Messaging ==
[[VRChat Twitch Integration|VTI]] supports Twitch viewers sending messages into the VRChat World through [[VTI Events]]. When the Allow Message Input property is enabled, [[VRChat Twitch Integration|VTI]] will automatically handle several aspects on the backend (see below), and VTITarget will ingest these messages to be passed onto any attached [[VTI Drivers|Drivers]].
==== Bits ====
In CHEER mode, the user's entire message with the cheered Bits is transmitted in the Message value.
==== Subscriptions ====
'''ISSUE''': Resubscription User Messaging is not yet supported. This is due to some strangeness in how the Twitch API handles returning Subscriber messages. The <syntaxhighlight lang="csharp" inline>channel.subscribe</syntaxhighlight> event doesn't contain message data, and the <syntaxhighlight lang="csharp" inline>channel.subscribe.message</syntaxhighlight> event fires alongside the former, duplicating triggers. Update 1 is slated to correct this and implement Subscription messages properly.
==== Channel Point Rewards ====
In CHANNEL_POINT_REDEEM mode, [[VRChat Twitch Integration|VTI]] will automatically set the Channel Point Reward to require the user to input a message with the redemption.
==== Chat Commands ====
When the Event Type is bound to <syntaxhighlight lang="csharp" inline>CHAT_COMMAND</syntaxhighlight>, the Message value will be set in one of two ways.
===== Exact =====
In EXACT mode, the first word of the user's string is treated as the Command (ex: <syntaxhighlight lang="csharp" inline>!fire</syntaxhighlight>). When Messaging is allowed, everything after the first word is transmitted as the Message value.
===== CONTAINS =====
In CONTAINS mode, or partial string matching, the [[VTI Events|Event]] is fired whenever the trigger string is found in a user's chat message. In this mode, when Messaging is allowed, the entire chat string is transmitted as the Message value, including the trigger string.
== Target Prefabs ==
The [[VTI World Kit]] comes with several pre-made Targets to both demonstrate the capabilities of [[VRChat Twitch Integration|VTI]] as well as speed up World integration by handling some common events.
{| class="wikitable"
|+ Prefabs
|-
! Prefab Name !! Usage
|-
| [[VTI Target - Event Firework]] || A firework fountain that lights when the specified Event Type is triggered. Handles User Messaging and Event Type Rebinding dynamically.
|-
| [[VTI Target - Rocket Command]] || Adds a Chat Command to launch the Streamer into the air. User Messaging is used to determine the "power" of the launch.
|-
| [[VTI Target - Anim Trigger]] || Demonstrates how animations can be triggered by VTI.
|-
| [[VTI Target - Tripmine]] || A mine that explodes when the Streamer gets near. Demonstrates how Events can be used to "Arm" an effect and play it later. Handles User Messaging and Event Type Rebinding dynamically.
|-
| [[VTI Target - Hydrate]] || Plays a shower of water particles and shows a message reminding the Streamer to drink some water. Mimics the incredibly common Channel Point Reward in use by many streamers.
|-
| [[VTI Target - Chat Panel]] || A "Q&A" style panel that accepts User Messaging, queuing up any sent messages to be manually displayed by the Streamer. Demonstrates VTI's usefulness in Panel-style talk shows.
|}
|}

Latest revision as of 10:47, 16 February 2024


VTITarget's Inspector

The VTITarget component is one of the core scripts for the VTI World Kit. It is used to identify a GameObject as something that can be interacted with by Twitch viewers when running VRChat Twitch Integration (For Worlds!).

Properties

Properties
Property Usage
ID The Unique Identifier for this Target. Used internally to dispatch Events. Must not match any other VTITargets in the scene or a warning will be thrown.
Display Name The User-Friendly name for this Target. Used in the VTI Companion App's Target editor and when generating Channel Point Rewards. Does not need to be unique.
Description A short sentence describing the usage of this Target. Used in the VTI Companion App's Target editor and when generating Channel Point Rewards.
Cooldown The number of seconds to wait before this Target can be fired again. Set this to at least as long as the events run by any attached VTI Drivers unless they are capable of being interrupted or overlapped.
Allow Message Input Enable this when any attached VTI Drivers expect User Messaging in order to function.
Allow Event Type Rebinding If any attached VTI Drivers are specifically tailored to one specific event, disable this. For example: a Driver that expects a chat command with a specific argument will likely not work when set to SUBCRIBE_GIFT.
Default Event Type What Twitch Event this Target should be fired on. This presents as a dropdown for all EventSub Subscription Types currently supported by VTI.
Default Twitch Binding Settings This section is dynamically displayed based on which Event Type is selected. Use this area to tune exactly what parameters are required to fire this Target.

Methods

Methods
Method Return Usage
VTICheckCanFire() bool Check whether or not this Target is off cooldown and all attached Drivers are reporting Ready.
VTIFire() void Trigger this Target. Forwards Event data to all attached Drivers and calls Driver.VTIEventPlay() on each.

Event Firing

When the VTI Event Handler receives an Event from the VTI Companion App, it will enqueue it under the ID of the triggered Target. Once that Event is at the top of the Queue, the Event Handler will attempt to dispatch the Event data to the Target and then call VTIFire().

Once Fired, the VTITarget will forward the Event data to each Driver component within the same GameObject as the VTITarget component, and then call VTIEventPlay() on each Driver.

Readiness Validation

Before firing, the VTI Event Handler will call VTICheckCanFire() against the queued VTITarget. This will first check the current time against the Cooldown property, and then will loop through all attached Driver component and call VTICheckReady() on each. If any Driver returns false, or the Cooldown has not yet elapsed, the Event is skipped and the process repeats for the next in line.

Network Ownership

As a final step before firing, the VTI World Kit will attempt to take Ownership of the GameObject. In order to prevent desynced cooldowns from double-firing or overriding another Streamer's Events, the VTITarget script will also refuse ownership transfer if it is still in use. Objects that the VTI World Kit cannot take Ownership of will stay on the queue until Ownership can be obtained. If this results in an Event that never fires, check to make sure you don't have other things trying to keep Ownership of that object, e.g. scripts on a Pickup with the VRCObjectSync component attached.

User Messaging

VTI supports Twitch viewers sending messages into the VRChat World through VTI Events. When the Allow Message Input property is enabled, VTI will automatically handle several aspects on the backend (see below), and VTITarget will ingest these messages to be passed onto any attached Drivers.

Bits

In CHEER mode, the user's entire message with the cheered Bits is transmitted in the Message value.

Subscriptions

ISSUE: Resubscription User Messaging is not yet supported. This is due to some strangeness in how the Twitch API handles returning Subscriber messages. The channel.subscribe event doesn't contain message data, and the channel.subscribe.message event fires alongside the former, duplicating triggers. Update 1 is slated to correct this and implement Subscription messages properly.

Channel Point Rewards

In CHANNEL_POINT_REDEEM mode, VTI will automatically set the Channel Point Reward to require the user to input a message with the redemption.

Chat Commands

When the Event Type is bound to CHAT_COMMAND, the Message value will be set in one of two ways.

Exact

In EXACT mode, the first word of the user's string is treated as the Command (ex: !fire). When Messaging is allowed, everything after the first word is transmitted as the Message value.

CONTAINS

In CONTAINS mode, or partial string matching, the Event is fired whenever the trigger string is found in a user's chat message. In this mode, when Messaging is allowed, the entire chat string is transmitted as the Message value, including the trigger string.

Target Prefabs

The VTI World Kit comes with several pre-made Targets to both demonstrate the capabilities of VTI as well as speed up World integration by handling some common events.

Prefabs
Prefab Name Usage
VTI Target - Event Firework A firework fountain that lights when the specified Event Type is triggered. Handles User Messaging and Event Type Rebinding dynamically.
VTI Target - Rocket Command Adds a Chat Command to launch the Streamer into the air. User Messaging is used to determine the "power" of the launch.
VTI Target - Anim Trigger Demonstrates how animations can be triggered by VTI.
VTI Target - Tripmine A mine that explodes when the Streamer gets near. Demonstrates how Events can be used to "Arm" an effect and play it later. Handles User Messaging and Event Type Rebinding dynamically.
VTI Target - Hydrate Plays a shower of water particles and shows a message reminding the Streamer to drink some water. Mimics the incredibly common Channel Point Reward in use by many streamers.
VTI Target - Chat Panel A "Q&A" style panel that accepts User Messaging, queuing up any sent messages to be manually displayed by the Streamer. Demonstrates VTI's usefulness in Panel-style talk shows.