FrameworkZ API - FrameworkZ.Roles

Home / FrameworkZ.Roles Module

FrameworkZ.Roles

module

Roles module for FrameworkZ. Provides role-based permission system.

0
Functions
30
Methods
1
Fields

📋 On This Page

Fields

1
FrameworkZ.Roles 📋 table
Roles module for FrameworkZ. Provides role-based permission system.
Initial value: {}

Methods

30

FrameworkZ.Roles:AssignRole(username, roleId)

method
Assign exactly one role to a player, replacing any previous assignment.

Parameters

username ❓ unknown
\string
roleId ❓ unknown
\string

Returns

✅ boolean
Success

FrameworkZ.Roles:CachePermission(username, permission, result)

method
Store a permission-check result in the per-player cache.

FrameworkZ.Roles:ClearPermissionCache(username)

method
Invalidate permission cache for one player, or for all players when username is nil.

FrameworkZ.Roles:CountAssignedPlayers()

method
Number of players with an explicit role assignment.

Returns

❓ unknown
\integer

FrameworkZ.Roles:EnsurePlayerRole(username)

method
Ensure a player has a role. If none is recorded, assign the default role.
Safe to call for both brand-new players and returning players.

Parameters

username ❓ unknown
\string

Returns

📝 string
The player's roleId (existing or newly assigned default)

FrameworkZ.Roles:GetAllGroups()

method
Return all registered group definitions.

Returns

❓ unknown
\table

FrameworkZ.Roles:GetAllPermissions(username)

method
Collect all permissions for a player by walking role inheritance.

Parameters

username ❓ unknown
\string

Returns

📋 table
Map of permission string -> true

FrameworkZ.Roles:GetAllRoles()

method
Return the full RegisteredRoles table.

FrameworkZ.Roles:GetDefaultRole()

method
Return the role marked as default (isDefault = true).
When more than one default is registered the one with the highest priority wins. Falls back to DEFAULT_ROLES.PLAYER if nothing is found.

Returns

📋 table
Role data table

FrameworkZ.Roles:GetFormattedRoleName(roleId)

method
Return the display name for a roleId, falling back to the raw id.

FrameworkZ.Roles:GetGroup(groupId)

method
Return the group definition for a given id, or nil.

Parameters

groupId ❓ unknown
\string

Returns

❓ unknown
\table|nil

FrameworkZ.Roles:GetGroupMembership(groupId)

method
Derive live membership for every role in a group from the current PlayerRoles table.

Parameters

groupId ❓ unknown
\string

Returns

❔ table?
{ roleId -> { username, ... } }, or nil if the group does not exist.

FrameworkZ.Roles:GetPlayerRole(username)

method
Return the roleId assigned to a player, or the default player role.

Parameters

username ❓ unknown
\string

Returns

📝 string
roleId

FrameworkZ.Roles:GetPlayersWithRole(roleId)

method
Return all players currently assigned to a specific role.

Parameters

roleId ❓ unknown
\string

Returns

📋 table
Array of username strings

FrameworkZ.Roles:GetPrimaryRole(username)

method
Return the full role data table for a player's assigned role.

Parameters

username ❓ unknown
\string

Returns

📋 table
role data

FrameworkZ.Roles:GetRole(roleId)

method
Return the role data table for a given roleId.

FrameworkZ.Roles:GetRoleColor(roleId)

method
Return the { r, g, b } color table for a roleId, or nil.

FrameworkZ.Roles:GetRoleCount()

method
Return the number of registered roles.

FrameworkZ.Roles:HasPermission(username, permission)

method
Check whether a player has a given permission (wildcard-aware).

Parameters

username 📝 string
or IsoPlayer
permission ❓ unknown
\string

Returns

❓ unknown
\boolean

FrameworkZ.Roles:HasRole(username, roleId)

method
Check whether a player is assigned a specific role.

Parameters

username ❓ unknown
\string
roleId ❓ unknown
\string

Returns

❓ unknown
\boolean

FrameworkZ.Roles:LoadCustomRoles()

method
Hook point for custom role files to self-register.

FrameworkZ.Roles:LoadPlayerRoles()

method
Load player role assignments from persistent storage.

FrameworkZ.Roles:MatchesWildcard(permission, pattern)

method
Test whether a permission string matches a wildcard pattern (e.g. "chat.*").

FrameworkZ.Roles:OnInitGlobalModData()

method
Registers the Roles namespace and seeds roles/data on game init.

FrameworkZ.Roles:RegisterDefaultRoles()

method
Register the four built-in default roles.

FrameworkZ.Roles:RegisterGroup(groupData)

method
Register a group.

Parameters

groupData 📋 table
{ id \string, name \string, roles \table }

Returns

✅ boolean
Success

FrameworkZ.Roles:RegisterRole(roleData)

method
Register a new role.

Parameters

roleData 📋 table
{ id, name, description?, color?, permissions?, inherits?, priority?, isDefault?, metadata? }

Returns

✅ boolean
Success

FrameworkZ.Roles:RemoveRole(username, roleId)

method
Remove the role assignment from a player.
If roleId is supplied the removal only proceeds when the player currently holds that exact role.

Parameters

username ❓ unknown
\string
roleId (optional) 📝 string
Optional guard — only remove if this is their current role.

Returns

✅ boolean
Success

FrameworkZ.Roles:SavePlayerRoles()

method
Persist player role assignments.

FrameworkZ.Roles:UnregisterRole(roleId)

method
Unregister a custom role. Default roles cannot be removed.
Any player holding the unregistered role has their assignment cleared.

Parameters

roleId ❓ unknown
\string

Returns

✅ boolean
Success