Saltar al contenido principal

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

nota

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

Example:

public UdonBehaviour securityKeypad;

void GetSpecificRole()
{
    KeyPadRol adminRole = securityKeypad.GetRoleByName("admin");
    
    if (adminRole != null)
    {
        Debug.Log("Found admin role!");
        Debug.Log("Admin color: " + adminRole.color);
        
        // Check if local player has this role
        bool isAdmin = securityKeypad.HasRole(adminRole);
        Debug.Log("I am admin: " + isAdmin);
    }
    else
    {
        Debug.Log("Admin role not found in keypad configuration");
    }
}

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