Faction¶
Faction helpers for registering factions, loading faction definitions, resolving models, validating character customization, and querying faction membership data.
Overview
lia.faction.register(uniqueID, data)View Source
Purpose
Registers or updates a faction and creates its team entry.
Realm
Shared
Parameters
string uniqueID Stable identifier used to store the faction and create the global FACTION_* constant.
table data Faction data such as name, description, color, models, weapons, index, and customization settings.
Returns
number, table The faction index and registered faction table.
Example Usage
local index, faction = lia.faction.register("citizen", {
name = "@citizen",
desc = "@citizenDesc",
color = Color(150, 150, 150),
models = {"models/player/group01/male_01.mdl"}
})
lia.faction.cacheModels(models)View Source
lia.faction.isModelUsable(modelPath)View Source
Purpose
Checks whether a model path is usable for faction model handling.
Realm
Shared
Parameters
string modelPath Model path to validate.
Returns
boolean True when the value is a non-empty string and passes `util.IsValidModel` when available, otherwise false.
Example Usage
if lia.faction.isModelUsable(modelPath) then
util.PrecacheModel(modelPath)
end
lia.faction.normalizeSkinValue(skin, fallback)View Source
Purpose
Converts a skin value into a numeric skin index with a fallback.
Realm
Shared
Parameters
number|string skin optional Skin value to normalize.
number|string fallback optional Fallback skin index used when the provided value is empty, default, or invalid.
Returns
number The normalized skin index.
Example Usage
local skin = lia.faction.normalizeSkinValue(data.skin, 0)
lia.faction.getModelData(modelKey, modelData)View Source
Purpose
Parses supported faction model entry formats into a consistent model data table.
Realm
Shared
Parameters
any modelKey Model table key, which may also be the model path for keyed model definitions.
string|table modelData Raw model entry data to parse.
Returns
table|nil Parsed model data containing `model`, `skin`, `bodygroups`, `allowedSkins`, and `allowedBodygroups`, or nil when the entry is not a model definition.
Example Usage
local parsed = lia.faction.getModelData(modelKey, modelData)
if parsed then
print(parsed.model)
end
lia.faction.loadFromDir(directory)View Source
lia.faction.getAll()View Source
Purpose
Returns every registered faction as an array.
Realm
Shared
Returns
table Sequential table containing all registered faction tables.
Example Usage
for _, faction in ipairs(lia.faction.getAll()) do
print(faction.name)
end
lia.faction.get(identifier)View Source
Purpose
Finds a registered faction by numeric index or unique ID.
Realm
Shared
Parameters
number|string identifier Faction index or unique ID.
Returns
table|nil The matching faction table, or nil when no faction exists for the identifier.
Example Usage
local faction = lia.faction.get(FACTION_CITIZEN)
lia.faction.getModelCustomizationAllowed(client, faction, context)View Source
Purpose
Determines whether skin and bodygroup customization are allowed for a faction.
Realm
Shared
Parameters
Player client Player whose customization permissions are being checked.
number|string|table faction Faction index, unique ID, or faction table.
any context Optional caller-provided context passed to customization override hooks.
Returns
boolean, boolean Whether skin customization and bodygroup customization are allowed.
Example Usage
local canSkin, canBodygroups = lia.faction.getModelCustomizationAllowed(client, faction, "creation")
lia.faction.getBodygroupNameToIndex(modelPath)View Source
Purpose
Builds and caches a lowercase bodygroup-name-to-index map for a model.
Realm
Shared
Parameters
string modelPath Model path whose bodygroups should be inspected.
Returns
table Table mapping lowercase bodygroup names to numeric bodygroup indexes. Returns an empty table when the model is unusable.
Example Usage
local map = lia.faction.getBodygroupNameToIndex(modelPath)
local headIndex = map.head
lia.faction.getAllowedSkins(faction, modelData, modelKey)View Source
Purpose
Gets the skin whitelist for a model entry or its owning faction.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
string|table modelData optional Optional model entry data that may define `allowedSkins`.
any modelKey Optional model entry key used when parsing model data.
Returns
table|nil Allowed skin values from the model entry or faction, or nil when no skin whitelist exists.
Example Usage
local allowedSkins = lia.faction.getAllowedSkins(faction, modelData, modelKey)
lia.faction.getAllowedBodygroups(faction, modelData, modelKey)View Source
Purpose
Gets the bodygroup whitelist rules for a model entry or its owning faction.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
string|table modelData optional Optional model entry data that may define `allowedBodygroups`.
any modelKey Optional model entry key used when parsing model data.
Returns
table|nil Allowed bodygroup rules from the model entry or faction, or nil when no bodygroup whitelist exists.
Example Usage
local allowedBodygroups = lia.faction.getAllowedBodygroups(faction, modelData, modelKey)
lia.faction.isSkinAllowedForFaction(faction, skin, modelData, modelKey)View Source
Purpose
Checks whether a skin value is permitted by a faction or model skin whitelist.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
number|string skin Skin value being checked.
string|table modelData optional Optional model entry data that may define `allowedSkins`.
any modelKey Optional model entry key used when parsing model data.
Returns
boolean True when the skin is allowed or no whitelist exists, otherwise false.
Example Usage
if lia.faction.isSkinAllowedForFaction(faction, skin, modelData, modelKey) then
character:setData("skin", skin)
end
lia.faction.getDefaultAllowedSkinForFaction(faction, fallback, modelData, modelKey)View Source
Purpose
Returns the first allowed skin for a faction or model, falling back when no usable whitelist value exists.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
number fallback Skin value returned when no whitelist value is available.
string|table modelData optional Optional model entry data that may define `allowedSkins`.
any modelKey Optional model entry key used when parsing model data.
Returns
number First numeric allowed skin value, or the fallback value.
Example Usage
local skin = lia.faction.getDefaultAllowedSkinForFaction(faction, 0, modelData, modelKey)
lia.faction.getBodygroupWhitelistRule(faction, modelPath, bodygroupIndex, bodygroupName, modelData, modelKey)View Source
Purpose
Finds the whitelist rule that applies to a bodygroup by index or name.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
string modelPath Model path used to resolve bodygroup names when needed.
number|string bodygroupIndex optional Bodygroup index being checked.
string bodygroupName optional Optional bodygroup name being checked.
string|table modelData optional Optional model entry data that may define `allowedBodygroups`.
any modelKey Optional model entry key used when parsing model data.
Returns
table|boolean|nil Whitelist rule for the bodygroup, true or false for unconditional allow or deny, or nil when no rule applies.
Example Usage
local rule = lia.faction.getBodygroupWhitelistRule(faction, modelPath, bodygroupIndex, bodygroupName, modelData, modelKey)
lia.faction.isBodygroupValueAllowed(faction, modelPath, bodygroupIndex, value, bodygroupName, modelData, modelKey)View Source
Purpose
Checks whether a bodygroup value is permitted by the applicable whitelist rule.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
string modelPath Model path used to resolve bodygroup names when needed.
number|string bodygroupIndex optional Bodygroup index being checked.
number|string value Bodygroup value being checked.
string bodygroupName optional Optional bodygroup name being checked.
string|table modelData optional Optional model entry data that may define `allowedBodygroups`.
any modelKey Optional model entry key used when parsing model data.
Returns
boolean True when the value is allowed or no rule applies, otherwise false.
Example Usage
if lia.faction.isBodygroupValueAllowed(faction, modelPath, index, value, name, modelData, modelKey) then
entity:SetBodygroup(index, value)
end
lia.faction.getIndex(uniqueID)View Source
Purpose
Gets a faction index from its unique ID.
Realm
Shared
Parameters
string uniqueID Faction unique ID.
Returns
number|nil Faction index, or nil when the unique ID is not registered.
Example Usage
local index = lia.faction.getIndex("citizen")
lia.faction.getClasses(faction)View Source
lia.faction.getPlayers(faction)View Source
Purpose
Returns all connected players whose current character belongs to a faction.
Realm
Shared
Parameters
number faction Faction index to match against character faction data.
Returns
table Sequential table containing matching Player objects.
Example Usage
for _, ply in ipairs(lia.faction.getPlayers(FACTION_CITIZEN)) do
print(ply:Name())
end
lia.faction.getPlayerCount(faction)View Source
Purpose
Counts connected players whose current character belongs to a faction.
Realm
Shared
Parameters
number faction Faction index to match against character faction data.
Returns
number Number of connected players in the faction.
Example Usage
local count = lia.faction.getPlayerCount(FACTION_CITIZEN)
lia.faction.isFactionCategory(faction, categoryFactions)View Source
Purpose
Checks whether a faction value is included in a faction category list.
Realm
Shared
Parameters
any faction Faction value being searched for.
table categoryFactions Table of faction values that make up the category.
Returns
boolean True when the faction exists in the category table, otherwise false.
Example Usage
if lia.faction.isFactionCategory(faction, categoryFactions) then
return true
end
lia.faction.getCharacterCreationClass(faction, class)View Source
Purpose
Resolves the class used for character creation and verifies it belongs to the selected faction.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
number|string|table class optional Class identifier or class table. When omitted or invalid, the faction default class is used when available.
Returns
table|nil Resolved class table, or nil when no valid class exists for the faction.
Example Usage
local classData = lia.faction.getCharacterCreationClass(faction, selectedClass)
lia.faction.getCharacterCreationModelSource(faction, class)View Source
Purpose
Finds the model source used during character creation from class data, faction data, or defaults.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
number|string|table class optional Optional class identifier or class table.
Returns
string|table, table|nil, boolean Model path or model table, the owner table that provided it, and whether the source is a forced single model.
Example Usage
local source, owner, forced = lia.faction.getCharacterCreationModelSource(faction, class)
lia.faction.getCharacterCreationModelChoices(faction, class)View Source
Purpose
Returns the selectable model choices for character creation.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
number|string|table class optional Optional class identifier or class table.
Returns
table, table|nil, boolean Model choices table, the owner table that provided the models, and whether the choice is a forced single model.
Example Usage
local choices, owner, forced = lia.faction.getCharacterCreationModelChoices(faction, class)
lia.faction.getCharacterCreationModelInfo(faction, class, selectedModel)View Source
Purpose
Returns the selected character creation model entry and its source owner.
Realm
Shared
Parameters
number|string|table faction Faction index, unique ID, or faction table.
number|string|table class optional Optional class identifier or class table.
number selectedModel optional Selected model index. Defaults to 1 when omitted.
Returns
string|table|nil, table|nil, boolean Selected model entry, the owner table that provided it, and whether the source is a forced single model.
Example Usage
local modelData, owner, forced = lia.faction.getCharacterCreationModelInfo(faction, class, selectedModel)
lia.faction.jobGenerate(index, name, color, default, models)View Source
Purpose
Creates and registers a faction table from job-style data.
Realm
Shared
Parameters
number index Faction index to assign.
string name Faction name and storage key.
Color color Team color for the faction.
boolean default Whether the faction should be treated as default.
table models optional Optional model list. Defaults to the library default models when omitted.
Returns
table Generated faction table.
Example Usage
local faction = lia.faction.jobGenerate(10, "Worker", Color(125, 125, 125), true, models)
lia.faction.formatModelData()View Source
Purpose
Normalizes bodygroup data for every registered faction model entry where bodygroup names must be converted to indexes.
Realm
Shared
Returns
nil This function does not return a value.
Example Usage
lia.faction.formatModelData()
lia.faction.getCategories(teamName)View Source
lia.faction.getModelsFromCategory(teamName, category)View Source
Purpose
Returns all model entries from a named faction model category.
Realm
Shared
Parameters
string teamName Faction storage key used in `lia.faction.teams`.
string category Model category name to read.
Returns
table Table containing model entries from the requested category.
Example Usage
local models = lia.faction.getModelsFromCategory("citizen", "male")
lia.faction.getDefaultClass(id)View Source
Purpose
Finds the default class assigned to a faction index.
Realm
Shared
Parameters
number id Faction index used by class definitions.
Returns
table|nil Default class table, or nil when none is registered for the faction.
Example Usage
local defaultClass = lia.faction.getDefaultClass(FACTION_CITIZEN)
lia.faction.hasWhitelist(faction)View Source
Purpose
Checks whether the local player is allowed to create or use a faction.
Realm
Client
Parameters
number faction Faction index to check.
Returns
boolean True when the faction is default, when the local player has staff character creation privilege for the staff faction, or when local whitelist data contains the faction.
Example Usage
if lia.faction.hasWhitelist(FACTION_CITIZEN) then
print("allowed")
end
lia.faction.hasWhitelist(faction)View Source
Purpose
Checks whether a faction is available by default on the server.
Realm
Server
Parameters
number faction Faction index to check.
Returns
boolean True only for default factions in this implementation, otherwise false.
Example Usage
if lia.faction.hasWhitelist(FACTION_CITIZEN) then
print("default faction")
end
Hooks
Library-specific hooks documented for this library.
OverrideFactionDesc(uniqueID, desc)View Source
Purpose
Allows plugins or modules to override a faction's resolved description while it is registered or loaded from disk.
Realm
Shared
Parameters
string uniqueID The faction unique ID being registered or loaded.
string desc The resolved faction description before the override is applied.
Returns
string|nil Return a string to replace the faction description. Return nil to keep the current description.
OverrideFactionModelCustomization(client, faction, context, skinAllowed, bodygroupsAllowed)View Source
Purpose
Allows plugins or modules to override whether skins and bodygroups can be customized for a faction model selection context.
Realm
Shared
Parameters
Player client The player whose customization permissions are being checked.
table faction The faction data being checked.
any context Optional caller-provided context for the customization check.
boolean skinAllowed Whether skin customization is currently allowed by faction data.
boolean bodygroupsAllowed Whether bodygroup customization is currently allowed by faction data.
Returns
table|boolean|nil, boolean|nil Return a table with `skinAllowed` and/or `bodygroupsAllowed` fields, or return two booleans to override each value separately. Return nil values to keep the current permissions.
OverrideFactionModels(uniqueID, models)View Source
Purpose
Allows plugins or modules to override the model list assigned to a faction while it is registered or loaded from disk.
Realm
Shared
Parameters
string uniqueID The faction unique ID being registered or loaded.
table models The faction model table before the override is applied.
Returns
table|nil Return a model table to replace the faction models. Return nil to keep the current models.
OverrideFactionName(uniqueID, name)View Source
Purpose
Allows plugins or modules to override a faction's resolved display name while it is registered or loaded from disk.
Realm
Shared
Parameters
string uniqueID The faction unique ID being registered or loaded.
string name The resolved faction name before the override is applied.
Returns
string|nil Return a string to replace the faction name. Return nil to keep the current name.