4. Creating a Plugin
Only UdonSharp is supported when creating your own plugins. Although it might be possible to use the node system to create plugins , No official support will be given to non-UdonSharp scripts. However you can always as in the community help sections in our server.
To start creating a plugin right click in your Project tab and click
DisBridge Plugin under /UdonVR/ in your context menu.
This makes a new UdonSharp Script with most of the basics needed filled in for you.
The template will have a few things already created for you.
Your plugin will be pre-namespaced to UdonVR.DisBridge.Plugins
It's recommended to add your username to the end of the namespace so any plugin you create won't conflict with anyone else's.
namespace UdonVR.DisBridge.Plugins.YourUsernameHere
{As an example,
If you username is Tupper, your namespace should look like this:
namespace UdonVR.DisBridge.Plugins.Tupper
{It's not required to do this, but is strongly recommended.
You'll notice that your plugin already has a Variable setup. This is the Reference to the PluginManager which is where you'll be interacting with out API. you can read more about the API in the API section of this doc.
There will be 3 methods included with the template. They are:
private void Start()
{
disBridge.AddPlugin(gameObject);
}public void _UVR_Init()
{
}and
private void _UVR_Update()
{
}Start() is not recommend to use when creating DisBridge plugins.
This is because of how it pulls the roles into VRChat. If you try access the PluginManager too early your plugin will crash when trying to access stuff that hasn't been initialized yet.
It's recommend to use _UVR_Init() instead as the PluginManager will call _UVR_Init() on your plugin when it's ready for your plugin to start accessing the role information.
Make sure this method is public. if this method isn't public it cannot be initialized by the PluginManager.
make sure you have our namespace referenced using UdonVR.DisBridge and the PluginManager referenced.
If you're using our template, these are done for you.
DisBridge has it's own Scripting Define Symbol UVR_DISBRIDGE
To start using the API, you can use the pre-setup Variable in the template called disBridge.
Events are Methods in your plugin that get called by the Plugin Manager.
You can choose to include these in your plugin, or leave them out.
_UVR_Init - Gets called when the PluginManager is finished Initializing. Used for Initializing your own plugins.
_UVR_Update - Gets called when the PluginManager detects there's been a change to any of the RoleContainer's user lists.
_UVR_VersionMismatch - Gets called when the version of the DisBridge Bot doesn't match the version of DisBridge inside of Unity.
The template inherits from and existing class called DisBridgePlugin
this automatically adds variables and methods for you to use with your plugin.
disBridge - the PluginManager
_roleContainers - your RoleContainers
useStaff - default generic staff check used in IsMemberInRoles
useSupporters - default generic supporter check used in IsMemberInRoles
TryGetPlayerRoleContainer(VRCPlayerApi, out RoleContainer) - Grabs the highest role that player has in the plugin. Returns a bool depending on if the player has roles or not.
TryGetPlayerRoleContainer(VRCPlayerApi, ref RoleContainer[]) - Grabs all the roles that player has in the plugin Returns a bool depending on if the player has roles or not.
IsMemberInRoles(_player) Returns a bool depending if the player is included in the plugin's role checks.
All of the public methods inside of the PluginManager have tooltips and comments so your IDE should tell you what they do as you reference them. Despite that we've made a list of methods that you can access from the PluginManager here and lightly go over what they do.
All of the Is methods return a bool.
IsMember(int,VRCPlayerApi) - Checks to see if the target player is a member of the specified role.
IsSupporter() - Checks to see if the Local player is a Supporter
IsSupporter(VRCPlayerApi) - Checks to see if the target player is a Supporter
IsStaff() - Checks to see if the Local player is a Staff member
IsStaff(VRCPlayerApi) - Checks to see if the target player is a Staff member
IsBooster() - Checks to see if the Local player is a Server Booster
IsBooster(VRCPlayerApi) - Checks to see if the target player is a Server Booster
GetRoleDisplaynames(int) - Returns a string array of player display names based of the selected Index.
GetSupporterDisplaynames() - Returns a string array with all of your supporter's display names.
GetStaffDisplaynames() - Returns a string array with all of your staff's display names.
GetBoosterDisplaynames() - Returns a string array of player Display Names.
GetRole(int) - Returns a list of player display names based of the selected Index.
GetRoles() - Returns a list of all the Role Containers.
AddPlugin(GameObject) - Registers your plugin into the PluginManager for Initialization. Should be used with the local GameObject gameObject.
HasInit() - Returns a Bool based on Initialization state of the PluginManager.
log(string) - Prints a debug log to the Console and to the Debugger if attached to the PluginManager.
logWarning(string) - Prints a warning debug log to the Console and to the Debugger if attached to the PluginManager.
logError(string) - Prints a error debug log to the Console and to the Debugger if attached to the PluginManager.
GetMember() - Returns a string array with all the members in this role.
GetMemberCount() - Returns how many members are in the role.
AddMembersToArray(string[]) - Adds the members to bottom of the target string array and returns the merged string array.
All of the Is methods return a bool.
IsMember(VRCPlayerApi) - Used to check if the player is a member of this role.
IsRoleStaff() - returns if the role is a Staff role.
IsRoleBooster() - returns if the role is your Booster role. -- !!YOU CAN ONLY HAVE ONE OF THESE!!
IsRoleSupporter() - returns if the role is a Supporter role.
if you have any recommendations for the API, you can DM @childofthebeast through Discord.
My DM's are open so if we share a server (we should if you're using this bot) you can just DM me.
I do not accept random friends requests, but will respond to DMs.
The PluginManager has debugging built into it.
Use the built-in method log(string) to print a debug log into the console and into the world if the debugging log is in use.
The debugging log is a plugin that you attach to the PluginManager just like any plugin and is found in your Hierarchy's Context menu.
DisBridge has it's own Scripting Define Symbol that can be used for your Prefabs. The symbol is: UVR_DISBRIDGE
If you've never heard of Scripting Define Symbols before, they're flags that Unity uses to include or exclude blocks of code.
This allows you to add in optional support for DisBridge in your prefabs where you can tell Unity to automatically include or exclude blocks of code so your script can still compile if DisBridge is missing.
You can read more about Scripting Define Symbols here: https://docs.unity3d.com/Manual/PlatformDependentCompilation.html
This will create a bool and set it to either True or False depending if DisBridge is in your project.
#if UVR_DISBRIDGE
// this code will be included if DisBrodge is included
private bool hasDisBridge = true
#else
// this code will be included if DisBridge is missing
private bool hasDisBridge = false
#endif
//If DisBridge is in your project, hasDisBridge will be true.
//If DisBridge is missing, hasDisBridge will be false
This script will only compile as a single variable if DisBridge is missing.
public class ScriptingDefineExample : UdonSharpBehaviour
{
#if !UVR_DISBRIDGE
[Header("DisBridge not detected. Please import it into your project.")]
public string DisBridgeUrl = "https://github.com/UdonVR/DisBridge/wiki";
#else
[SerializeField] private PluginManager manager;
//Built-in Start method. It's recommended to use "_UVR_Init()" instead of "Start" when making a DisBridge Plugin.
private void Start()
{
manager.AddPlugin(gameObject);
}
//Runs when DisBridge finishes pulling the roles.
//This is required to be Public for the PluginManager to Initialize your plugin
public void _UVR_Init()
{
}
#endif
}This will check to see if the Local Player is a member of your highest role.
if (manager.IsMember(0,Networking.LocalPlayer))
{
}
This will check to see if the Local Player is in ANY role you have marked as a supporter role.
if (manager.IsSupporter(Networking.LocalPlayer))
{
}Manual setup is not recommended. we supply you a template to use that has all of this setup for you. This is just for explaining what everything does in the template.
If you're using the template this is done for you.
The first thing you want to do is reference our namespace with using UdonVR.DisBridge.
You then want to make a new variable for the PluginManager.
Add the line [SerializeField] private PluginManager manager; to reference the PluginManager.
After you have the PluginManager referenced, you'd want to register yourself as a Plugin with the PluginManager.
You can do that by adding manager.AddPlugin(gameObject); into your Start() method.
private void Start()
{
manager.AddPlugin(gameObject);
}This is telling the PluginManager "This Object has a plugin on it" so it knows to tell it when the lists are ready and your plugin should start Initializing.
When creating a plugin, you need to have our system tell your plugin when to start.
This is because the system takes time to initialize so if you try to access the user
list too early your plugin will break.
To do this all you need to do is have a public method called _UVR_Init.
public void _UVR_Init()
{
//your code here
}Here's the current template as of writing the docs for reference.
The template may have been updated since writing. you can always make yourself the Up-To-Date Plugin template from within Unity.
using System;
using UdonSharp;
using UnityEngine;
using VRC.SDKBase;
using VRC.Udon;
using UdonVR.DisBridge;
namespace UdonVR.DisBridge.Plugins
{
public class <TemplateClassName> : DisBridgePlugin
{
// Built in Variables:
// - PluginManager disBridge
// - RoleContainer[] _roleContainers
// - bool useStaff
// - bool useSupporters
// Built in Methods:
// - bool TryGetPlayerRoleContainer(VRCPlayerApi _player, out RoleContainer _roleContainer)
// - bool TryGetPlayerRoleContainer(VRCPlayerApi _player, ref RoleContainer[] _playersRoles)
// - bool IsMemberInRoles(VRCPlayerApi _player)
//Built-in Start method. It's recommended to use "_UVR_Init()" instead of "Start" when making a DisBridge Plugin.
private void Start()
{
disBridge.AddPlugin(gameObject);
}
//Runs when DisBridge finishes pulling the roles.
public override void _UVR_Init()
{
}
//Runs when a RoleContainer's user list has updated.
public override void _UVR_Update()
{
}
}
}Enjoy our stuff? Please consider supporting us so we can provide more free content to everyone!
PLUS you get some benefits.