Steeveeo: Added "Next Steps" section and some minor cleanup and code highlighting to previous commits.

2024-02-14T01:06:48Z

Added "Next Steps" section and some minor cleanup and code highlighting to previous commits.

Steeveeo: Initial tutorial writeup.

2024-02-13T08:39:40Z

Initial tutorial writeup.

New page

[[Category:VTI]]
[[Category:VTI Tutorials]]

The [[VTI World Kit]] is designed to be easily extensible by both world designers and programmers alike. To this end, custom Drivers are highly recommended and are built to be fairly simple to create. This article serves as a tutorial on how to create a custom Driver. It will assume basic knowledge of UdonSharp.

In this tutorial, we will be replicating the [[VTIObjectToggle]] Driver as it demonstrates all the core tenets of how [[VTI Drivers]] function.

== Create the Script ==
Create a new U# script and open it in your IDE of choice. Change the inherited class from UdonSharpBehaviour to VTIDriverBase.

<syntaxhighlight lang="csharp">
public class CustomDriver : VTIDriverBase
</syntaxhighlight>

Next, we need our control variables so the script can function. As we are turning a GameObject on for a period of time, and then off after it, add a public property for a GameObject a float for the time it will take to reset. For sanity's sake, also add a call in the Start() method to turn the Target off, to make sure it won't fire when the level loads.

<syntaxhighlight lang="csharp">
public class CustomDriver : VTIDriverBase
{
public GameObject Target;
public float ResetTime = 5.0f;

void Start()
{
Target.SetActive(false);
}
}
</syntaxhighlight>

== Add Core Functionality ==
The simplest possible [[VTI Drivers|Driver]] only needs to implement the <syntaxhighlight lang="csharp" inline>VTIEventPlay()</syntaxhighlight> method. This is what is called when an [[VTI Events|Event]] is received, all checks have passed, and [[VRChat Twitch Integration|VTI]] is attempting to Fire this Driver's [[VTI Targets|Target]].

Add a public override void method called VTIEventPlay(). Clear out the <syntaxhighlight lang="csharp" inline>base.VTIEventPlay();</syntaxhighlight> line if your IDE added it automatically.

<syntaxhighlight lang="csharp">
public override void VTIEventPlay()
{

}
</syntaxhighlight>

Next, we need to make the Driver actually do the thing we want it to do, which is to turn on a GameObject, wait, and then turn it off. The first thing we'll need is to call <syntaxhighlight lang="csharp" inline>Target.SetActive(true)</syntaxhighlight> in our new method. Then, create another method that will do the exact opposite and call <syntaxhighlight lang="csharp" inline>Target.SetActive(false)</syntaxhighlight>.

<syntaxhighlight lang="csharp">
public override void VTIEventPlay()
{
Target.SetActive(true);
}

public void ResetTarget()
{
Target.SetActive(false);
}
</syntaxhighlight>

For the core of our functionality, we only need to do one more thing: make <syntaxhighlight lang="csharp" inline>VTIEventPlay()</syntaxhighlight> call <syntaxhighlight lang="csharp" inline>ResetTarget()</syntaxhighlight> after a delay. We can do this simply by utilizing the built-in <syntaxhighlight lang="csharp" inline>SendCustomEventDelayedSeconds()</syntaxhighlight> method. Add that into <syntaxhighlight lang="csharp" inline>VTIEventPlay()</syntaxhighlight> and have it wait for <syntaxhighlight lang="csharp" inline>ResetTime</syntaxhighlight> seconds.

<syntaxhighlight lang="csharp">
SendCustomEventDelayedSeconds(nameof(ResetTarget), ResetTime);
</syntaxhighlight>

As an aside, note the usage of <syntaxhighlight lang="csharp" inline>nameof</syntaxhighlight> instead of just putting <syntaxhighlight lang="csharp" inline>"ResetTarget"</syntaxhighlight> in the first argument. This allows for a measure of safety when maintaining projects later on, as if you need to rename <syntaxhighlight lang="csharp" inline>ResetTarget()</syntaxhighlight> for whatever reason, you can utilize something like Visual Studio's Rename function and not have to worry about manually typing the name change into all the Custom Event calls.

At this end of this section, this is how our script looks:

<syntaxhighlight lang="csharp">
using UnityEngine;

public class CustomDriver : VTIDriverBase
{
public GameObject Target;
public float ResetTime = 5.0f;

void Start()
{
Target.SetActive(false);
}

public override void VTIEventPlay()
{
Target.SetActive(true);
SendCustomEventDelayedSeconds(nameof(ResetTarget), ResetTime);
}

public void ResetTarget()
{
Target.SetActive(false);
}
}
</syntaxhighlight>

== Dealing With Readiness ==
For the most basic of Drivers, the Cooldown timer is automatically handled by [[VTI Targets|VTITarget]]. However, in this case, we're turning an object on and telling VRChat to turn it back off after an arbitrary delay. In some circumstances, you may want your Drivers to be able to overlap themselves when triggered multiple times. But in this case, we have a Custom Event running on a timer, which can cause some level of havoc if we don't tell the parent [[VTI Targets|VTITarget]] that we're not ready to Fire again.

There are two ways to do this: The <syntaxhighlight lang="csharp" inline>IsReady</syntaxhighlight> variable, and adding in a custom <syntaxhighlight lang="csharp" inline>VTICheckReady()</syntaxhighlight> method. The former method is exceptionally simple, and all we really need for this tutorial, so we'll cover that first.

==== The IsReady Boolean ====
The <syntaxhighlight lang="csharp" inline>IsReady</syntaxhighlight> boolean serves as a bit of a "Green Light" to signal the [[VTI World Kit]] that this [[VTI Drivers|Driver]] is ready to go or not. Right now, we need to turn that light "red" while we wait for the Custom Event timer to elapse, and then turn it back to "green" when we're done. To do this, simply set <syntaxhighlight lang="csharp" inline>IsReady = false;</syntaxhighlight> in <syntaxhighlight lang="csharp" inline>VTIEventPlay()</syntaxhighlight>, and set it back to <syntaxhighlight lang="csharp" inline>true</syntaxhighlight> in <syntaxhighlight lang="csharp" inline>ResetTarget()</syntaxhighlight>.

<syntaxhighlight lang="csharp">
public override void VTIEventPlay()
{
IsReady = false;

Target.SetActive(true);
SendCustomEventDelayedSeconds(nameof(ResetTarget), ResetTime);
}

public void ResetTarget()
{
IsReady = true;

Target.SetActive(false);
}
</syntaxhighlight>

And that's it! By default, <syntaxhighlight lang="csharp" inline>VTICheckReady()</syntaxhighlight> will simply return the value of <syntaxhighlight lang="csharp" inline>IsReady</syntaxhighlight> unless overridden, so for the purposes of this script, we don't even need to do anything more than this!

==== VTICheckReady() ====
However, what if we need to be more complex in our checks to see if we can Fire again or not? In this case, a simple boolean may not be enough. For the purposes of this tutorial, this step is optional, and will only serve as an example of how this can be done in another way.

There's not really much we need to check in a Driver as simple as this, so let's just be super paranoid about the state of the Target GameObject and ensure that it got turned off before allowing [[VRChat Twitch Integration|VTI]] to Fire this again. To do this, first add in an override for <syntaxhighlight lang="csharp" inline>VTICheckReady()</syntaxhighlight>.

Next, replace the auto-generated "base" call (if your IDE made one) with a simple expression to return <syntaxhighlight lang="csharp" inline>true</syntaxhighlight> if both <syntaxhighlight lang="csharp" inline>IsReady</syntaxhighlight> is <syntaxhighlight lang="csharp" inline>true</syntaxhighlight> and Target is not currently active. This can look like the below:

<syntaxhighlight lang="csharp">
public override bool VTICheckReady()
{
return IsReady && !Target.activeSelf;
}
</syntaxhighlight>

== Closing ==
And that's basically it! This Driver can now be attached to a [[VTI Targets|VTITarget]] like any of the base Drivers that came with the [[VTI World Kit]]. At a very rough estimate, there are about seven times more words in this tutorial than there are in all of the base Drivers in the Kit combined. Our simple Driver code should now look like this:

<syntaxhighlight lang="csharp">
using UnityEngine;

public class CustomDriver : VTIDriverBase
{
public GameObject Target;
public float ResetTime = 5.0f;

void Start()
{
Target.SetActive(false);
}

public override void VTIEventPlay()
{
IsReady = false;

Target.SetActive(true);
SendCustomEventDelayedSeconds(nameof(ResetTarget), ResetTime);
}

public void ResetTarget()
{
IsReady = true;

Target.SetActive(false);
}
}
</syntaxhighlight>

== Next Steps ==
This is not all that can be done with a Driver. To continue on, read the next tutorial: [[User Messaging On Custom VTI Drivers]].

Creating Custom VTI Drivers - Revision history

Steeveeo: Added "Next Steps" section and some minor cleanup and code highlighting to previous commits.

Steeveeo: Initial tutorial writeup.