Skip to main content

API

The Security Keypad system provides a public API that allows you to check player roles and permissions from your own Udon scripts.

Understanding Role Tags​

The Security Keypad system uses two types of role tags:

Explicit Roles: Tags from roles the player has explicitly logged into, be by inputing a code, autologin or manually given by any system.

Implicit Roles: Tags given because you have been explicitly assigned to one of its parents. For example, if you have the VIP+ role assigned and said role has VIP as a child role, you will be given the VIP implicit tag.

These 2 lists combine into a single Roles list which is synchronized to remote users. This division its used internally to determine if you need to be logged out of a role, and can also be used by external systems to perform all kinds of checks depending on your needs.

Public Events​

To recive events on your own Udon scripts, you need to first add your UdonBehaviour to the SecurityKeypad's Event Receivers list. You can do so manually in the inspector or by using the methods:

RegisterListener(UdonBehaviour listener)
UnregisterListener(UdonBehaviour listener)

Once registered, your Udon script can implement the following event methods:

- OnUserLogin(string playername, string rolename)
- OnUserLogout(string playername, string rolename)
- OnUserExplicitLogin(string playername, string rolename)
- OnUserExplicitLogout(string playername, string rolename)

Public API Methods​

HasRole​

The HasRole method checks if a player has one or more roles. This method has multiple overloads to provide flexibility in how you check roles.

Returns:

  • true if the role condition is met
  • false otherwise

Examples:

public SecurityKeypad keypad;
bool isAdmin = false;

void Start(){
    //Check if the keypad reference is valid
    if(!Utilities.IsValid(keypad)) return;

    //Check if local player is admin
    isAdmin = keypad.HasRole("Admin")
}

HasRole(KeyPadRol role)​

Checks if the local player has logged into a specific role.

Signature:

public bool HasRole(KeyPadRol role)

Parameters:

  • role - The KeyPadRol component to check

HasRole(KeyPadRol[] roles, bool ImplicitOnly, bool All)​

Checks if the local player has one or more roles from an array of KeyPadRol components.

Signature:

public bool HasRole(KeyPadRol[] roles, bool ImplicitOnly = false, bool All = false)

Parameters:

  • roles - Array of KeyPadRol components to check
  • ImplicitOnly - If true, only checks implicit role tags (default: false)
  • All - If true, requires all roles to match; if false, requires at least one (default: false)

HasRole(string role, bool ImplicitOnly)​

Checks if the local player has a role by role name.

Signature:

public bool HasRole(string role, bool ImplicitOnly = false)

Parameters:

  • role - The role name or tag to check
  • ImplicitOnly - If true, only checks implicit role tags (default: false)

HasRole(VRCPlayerApi player, string role, bool ImplicitOnly)​

Checks if a specific player has a role by role name.

Signature:

public bool HasRole(VRCPlayerApi player, string role, bool ImplicitOnly = false)

Parameters:

  • player - The player to check
  • role - The role name or tag to check
  • ImplicitOnly - If true, only checks implicit role tags (default: false)

HasRole(string[] roles, bool ImplicitOnly, bool All)​

Checks if the local player has one or more roles from an array of role names/tags.

Signature:

public bool HasRole(string[] roles, bool ImplicitOnly = false, bool All = false)

Parameters:

  • roles - Array of role names/tags to check
  • ImplicitOnly - If true, only checks implicit role tags (default: false)
  • All - If true, requires all roles to match; if false, requires at least one (default: false)

HasRole(VRCPlayerApi player, string[] roles, bool ImplicitOnly, bool All)​

Checks if a specific player has one or more roles from an array of role names/tags.

Signature:

public bool HasRole(VRCPlayerApi player, string[] roles, bool ImplicitOnly = false, bool All = false)

Parameters:

  • player - The player to check
  • roles - Array of role names/tags to check
  • ImplicitOnly - If true, only checks implicit role tags (default: false)
  • All - If true, requires all roles to match; if false, requires at least one (default: false)

GetRoles​

The GetRoles methods retrieve the role tags assigned to a player. These methods have multiple overloads for different use cases.

Returns:

  • DataList containing only explicit role tags for the player
  • Empty DataList if system is not initialized or player data not found

GetRoles()​

Gets all role tags assigned to the local player.

Signature:

public DataList GetRoles()

GetRoles(VRCPlayerApi player)​

Gets all role tags assigned to a specific player.

Signature:

public DataList GetRoles(VRCPlayerApi player)

Parameters:

  • player - The player to get roles from

Behavior:

  • Returns empty list if called before initialization (logs warning)
  • Returns empty list if player data is not found

GetExplicitRoles()​

Gets only the explicit role tags assigned to the local player (roles they logged into).

Signature:

public DataList GetExplicitRoles()

GetExplicitRoles(VRCPlayerApi player)​

Gets only the explicit role tags assigned to a specific player.

Signature:

public DataList GetExplicitRoles(VRCPlayerApi player)

Parameters:

  • player - The player to get explicit roles from

Behavior:

  • Returns empty list if called before initialization (logs warning)
  • Returns empty list if player data is not found
  • Only includes roles the player actively logged into, not passive/automatic roles

GetImplicitRoles()​

Gets only the implicit role tags assigned to the local player (automatically assigned roles).

Signature:

public DataList GetImplicitRoles()

GetImplicitRoles(VRCPlayerApi player)​

Gets only the implicit role tags assigned to a specific player.

Signature:

public DataList GetImplicitRoles(VRCPlayerApi player)

Parameters:

  • player - The player to get implicit roles from

Behavior:

  • Returns empty list if called before initialization (logs warning)
  • Returns empty list if player data is not found
  • Only includes automatically assigned roles, not roles requiring explicit login

GetHighestRole​

The GetHighestRole methods retrieve the highest priority role assigned to a player based on the role hierarchy.

note

Highest role is determined by the order in the hierarchy the roles are placed in, from top to bottom.

Returns:

  • KeyPadRol component of the highest priority role
  • null if player has no roles or system is not initialized

Example:

public KeyPad securityKeypad;

public void DisplayPlayerHighestRole(VRCPlayerApi targetPlayer)
{
    KeyPadRol highestRole = securityKeypad.GetHighestRole(targetPlayer);
    
    if (highestRole != null)
    {
        Debug.Log(targetPlayer.displayName + "'s highest role is: " + highestRole.rolName);
        
        // Access role properties
        string roleName = highestRole.rolName;
        Color roleColor = highestRole.color;
    }
    else
    {
        Debug.Log(targetPlayer.displayName + " has no roles");
    }
}

GetHighestRole()​

Gets the highest role assigned to the local player.

Signature:

public KeyPadRol GetHighestRole()

GetHighestRole(VRCPlayerApi player)​

Gets the highest role assigned to a specific player.

Signature:

public KeyPadRol GetHighestRole(VRCPlayerApi player)

Parameters:

  • player - The player to get the highest role from

GetRoleByName​

Gets a KeyPadRol component by its role name.

Signature:

public KeyPadRol GetRoleByName(string roleName)

Parameters:

  • roleName - The name of the role to retrieve

Returns:

  • KeyPadRol component with matching role name
  • null if role not found or system is not initialized

Behavior:

  • Returns null if called before initialization (logs warning)
  • Searches through all role objects to find a matching name
  • Case-sensitive name matching

GetRoleColor​

The GetRoleColor methods retrieve the color of a player's highest role.

Returns:

  • Color of the highest priority role.
  • Color.white if player has no roles, system is not initialized, or player data not found.

Example:

public KeyPad securityKeypad;
public MeshRenderer playerNameplate;

void UpdateMyNameplateColor()
{
    Color myRoleColor = securityKeypad.GetRoleColor();
    
    // Apply role color to nameplate
    playerNameplate.material.color = myRoleColor;
    
    Debug.Log("My role color is: " + myRoleColor);
}

GetRoleColor()​

Gets the color of the highest role assigned to the local player.

Signature:

public Color GetRoleColor()

GetRoleColor(VRCPlayerApi player)​

Gets the color of the highest role assigned to a specific player.

Signature:

public Color GetRoleColor(VRCPlayerApi player)

Parameters:

  • player - The player to get the role color from

GetPlayersWithRole(KeyPadRol role, bool implicitOnly)​

Gets a list of players who have a specific role.

Signature:

public VRCPlayerApi[] GetPlayersWithRole(KeyPadRol role, bool implicitOnly = false)

Parameters:

  • role - The KeyPadRol component to check
  • implicitOnly - If true, only considers implicit role tags (default: false)

Returns:

  • Array of VRCPlayerApi players who have the specified role
  • Empty array if no players have the role or system is not initialized