Faction
Comprehensive faction (team) management and registration system for the Lilia framework.
Overview
lia.faction.register(uniqueID, data)
Purpose
Registers a new faction with the specified unique ID and data table, setting up team configuration and model caching.
When Called
Called during gamemode initialization to register factions programmatically, typically in shared files or during faction loading.
Parameters
string uniqueID The unique identifier for the faction.
table data A table containing faction configuration data including name, description, color, models, etc.
Returns
number, table Returns the faction index and the faction data table.
Example Usage
local index, faction = lia.faction.register("citizen", {
name = "Citizen",
desc = "A regular citizen",
color = Color(100, 150, 200),
models = {"models/player/group01/male_01.mdl"}
})
lia.faction.cacheModels(models)
Purpose
Precaches model files to ensure they load quickly when needed, handling both string model paths and table-based model data.
When Called
Called automatically during faction registration to precache all models associated with a faction.
Parameters
table models A table of model data, where each entry can be a string path or a table with model information.
Example Usage
local models = {"models/player/group01/male_01.mdl", "models/player/group01/female_01.mdl"}
lia.faction.cacheModels(models)
lia.faction.loadFromDir(directory)
Purpose
Loads faction definitions from Lua files in a specified directory, registering each faction found.
When Called
Called during gamemode initialization to load faction definitions from organized directory structures.
Parameters
string directory The path to the directory containing faction definition files.
Example Usage
lia.faction.loadFromDir("gamemode/factions")
lia.faction.getAll()
Purpose
Retrieves all registered factions as a table.
When Called
Called whenever all faction information needs to be accessed by other systems or scripts.
Returns
table A table containing all faction data tables.
Example Usage
local allFactions = lia.faction.getAll()
for _, faction in ipairs(allFactions) do
print("Faction: " .. faction.name)
end
lia.faction.get(identifier)
Purpose
Retrieves faction data by either its unique ID or index number.
When Called
Called whenever faction information needs to be accessed by other systems or scripts.
Parameters
string|number identifier The faction's unique ID string or numeric index.
Returns
table The faction data table, or nil if not found.
Example Usage
local faction = lia.faction.get("citizen")
-- or
local faction = lia.faction.get(1)
lia.faction.getModelCustomizationAllowed(client, faction, context)
Purpose
Determines whether a faction allows skin and bodygroup customization for a given client.
When Called
Called when checking if a player can customize their character model with skins and bodygroups, typically during character creation or model selection.
Parameters
Player client The player whose customization permissions are being checked.
number/string/table faction The faction identifier - can be a faction ID, unique ID, or faction table.
any context Additional context data that might be used by hooks to determine permissions.
Returns
boolean, boolean First value: Whether skin customization is allowed. Second value: Whether bodygroup customization is allowed.
Example Usage
local skinAllowed, bodygroupsAllowed = lia.faction.getModelCustomizationAllowed(client, faction, "character_creation")
lia.faction.getBodygroupNameToIndex(modelPath)
Purpose
Builds a lookup table of bodygroup name -> bodygroup index for a specific model path.
When Called
Called when bodygroup whitelist rules are defined by bodygroup name, and we need to resolve those names to numeric indices for a given model.
Parameters
string modelPath The model path to inspect.
Returns
table A map where keys are lowercase bodygroup names and values are numeric bodygroup indices. Returns an empty table if the model is invalid or cannot be inspected.
Example Usage
local map = lia.faction.getBodygroupNameToIndex("models/player/group01/male_01.mdl")
local headgearIndex = map.headgear
lia.faction.isSkinAllowedForFaction(faction, skin)
Purpose
Checks if a skin ID is allowed for a faction when a skin whitelist is defined. If the whitelist is missing or empty, this function treats it as unrestricted.
When Called
Called during character creation/adjustment when `skinAllowed` is enabled and the player attempts to pick a specific skin.
Parameters
table|string|number faction The faction table, uniqueID, or numeric index.
number skin The desired skin ID.
Returns
boolean True if allowed, false otherwise.
Example Usage
if lia.faction.isSkinAllowedForFaction("citizen", 0) then
print("Allowed")
end
lia.faction.getDefaultAllowedSkinForFaction(faction, fallback)
Purpose
Returns the first allowed skin from a faction whitelist to use as a fallback.
When Called
Called when a player-selected skin is not allowed and we need to clamp it back to a valid value. If no whitelist exists (or it has no numeric entries), the provided fallback is used.
Parameters
table|string|number faction The faction table, uniqueID, or numeric index.
number fallback The fallback skin to use if there is no usable whitelist value.
Returns
number A valid skin ID.
Example Usage
local skin = lia.faction.getDefaultAllowedSkinForFaction("citizen", 0)
lia.faction.getBodygroupWhitelistRule(faction, modelPath, bodygroupIndex, bodygroupName)
Purpose
Resolves the whitelist rule for a specific bodygroup for a faction. Supports looking up rules by numeric bodygroup index or by bodygroup name.
When Called
Called when validating a requested bodygroup change during character creation/adjustment.
Parameters
table|string|number faction The faction table, uniqueID, or numeric index.
string modelPath The model used to resolve bodygroup name to index when needed.
number bodygroupIndex The numeric bodygroup index.
string bodygroupName optional Optional bodygroup name override.
Returns
any The rule value stored in `FACTION.allowedBodygroups` for this bodygroup. - nil means no restriction. - table means a whitelist of allowed numeric values. - true/false explicitly allows/denies.
Example Usage
local rule = lia.faction.getBodygroupWhitelistRule("citizen", mdl, 1)
lia.faction.isBodygroupValueAllowed(faction, modelPath, bodygroupIndex, value, bodygroupName)
Purpose
Checks if a specific bodygroup value is allowed for a faction. If there is no rule (or the allowedBodygroups table is missing/empty), this is unrestricted.
When Called
Called during character creation/adjustment when `bodygroupsAllowed` is enabled and the player attempts to pick bodygroup values.
Parameters
table|string|number faction The faction table, uniqueID, or numeric index.
string modelPath The model path used to resolve bodygroup names when needed.
number bodygroupIndex The numeric bodygroup index.
number value The requested bodygroup value.
string bodygroupName optional Optional bodygroup name override.
Returns
boolean True if allowed, false otherwise.
Example Usage
if lia.faction.isBodygroupValueAllowed("citizen", mdl, 0, 1) then
print("Allowed")
end
lia.faction.getIndex(uniqueID)
Purpose
Retrieves the numeric team index for a faction given its unique ID.
When Called
Called when the numeric team index is needed for GMod team functions or comparisons.
Parameters
string uniqueID The unique identifier of the faction.
Returns
number The faction's team index, or nil if the faction doesn't exist.
Example Usage
local index = lia.faction.getIndex("citizen")
if index then
print("Citizen faction index: " .. index)
end
lia.faction.getClasses(faction)
Purpose
Retrieves all character classes that belong to a specific faction.
When Called
Called when needing to display or work with all classes available to a faction.
Parameters
string|number faction The faction identifier (unique ID or index).
Returns
table An array of class data tables that belong to the specified faction.
Example Usage
local classes = lia.faction.getClasses("citizen")
for _, class in ipairs(classes) do
print("Class: " .. class.name)
end
lia.faction.getPlayers(faction)
Purpose
Retrieves all players who are currently playing characters in the specified faction.
When Called
Called when needing to iterate over or work with all players belonging to a specific faction.
Parameters
string|number faction The faction identifier (unique ID or index).
Returns
table An array of player entities who belong to the specified faction.
Example Usage
local players = lia.faction.getPlayers("citizen")
for _, player in ipairs(players) do
player:ChatPrint("Hello citizens!")
end
lia.faction.getPlayerCount(faction)
Purpose
Counts the number of players currently playing characters in the specified faction.
When Called
Called when needing to know how many players are in a faction for UI display, limits, or statistics.
Parameters
string|number faction The faction identifier (unique ID or index).
Returns
number The number of players in the specified faction.
Example Usage
local count = lia.faction.getPlayerCount("citizen")
print("There are " .. count .. " citizens online")
lia.faction.isFactionCategory(faction, categoryFactions)
Purpose
Checks if a faction belongs to a specific category of factions.
When Called
Called when determining if a faction is part of a group or category for organizational purposes.
Parameters
string|number faction The faction identifier to check.
table categoryFactions An array of faction identifiers that define the category.
Returns
boolean True if the faction is in the category, false otherwise.
Example Usage
local lawFactions = {"police", "sheriff"}
if lia.faction.isFactionCategory("police", lawFactions) then
print("This is a law enforcement faction")
end
lia.faction.jobGenerate(index, name, color, default, models)
Purpose
Generates a basic faction configuration programmatically with minimal required parameters.
When Called
Called for quick faction creation during development or for compatibility with other systems.
Parameters
number index The numeric team index for the faction.
string name The display name of the faction.
Color color The color associated with the faction.
boolean default Whether this is a default faction that doesn't require whitelisting.
table models Array of model paths for the faction (optional, uses defaults if not provided).
Returns
table The created faction data table.
Example Usage
local faction = lia.faction.jobGenerate(5, "Visitor", Color(200, 200, 200), true)
lia.faction.formatModelData()
Purpose
Formats and standardizes model data across all factions, converting bodygroup configurations to proper format.
When Called
Called after faction loading to ensure all model data is properly formatted for use.
Example Usage
-- Called automatically during faction initialization
lia.faction.formatModelData()
lia.faction.getCategories(teamName)
Purpose
Retrieves all model categories defined for a faction (string keys in the models table).
When Called
Called when needing to display or work with faction model categories in UI or selection systems.
Parameters
string teamName The unique ID of the faction.
Returns
table An array of category names (strings) defined for the faction's models.
Example Usage
local categories = lia.faction.getCategories("citizen")
for _, category in ipairs(categories) do
print("Category: " .. category)
end
lia.faction.getModelsFromCategory(teamName, category)
Purpose
Retrieves all models belonging to a specific category within a faction.
When Called
Called when needing to display or select models from a particular category for character creation.
Parameters
string teamName The unique ID of the faction.
string category The name of the model category to retrieve.
Returns
table A table of models in the specified category, indexed by their position.
Example Usage
local models = lia.faction.getModelsFromCategory("citizen", "male")
for index, model in pairs(models) do
print("Model " .. index .. ": " .. (istable(model) and model[1] or model))
end
lia.faction.getDefaultClass(id)
Purpose
Retrieves the default character class for a faction (marked with isDefault = true).
When Called
Called when automatically assigning a class to new characters or when needing the primary class for a faction.
Parameters
string|number id The faction identifier (unique ID or index).
Returns
table The default class data table for the faction, or nil if no default class exists.
Example Usage
local defaultClass = lia.faction.getDefaultClass("citizen")
if defaultClass then
print("Default class: " .. defaultClass.name)
end
lia.faction.hasWhitelist(faction)
Purpose
Checks if the local player has whitelist access to the specified faction on the client side.
When Called
Called on the client when determining if a faction should be available for character creation.
Parameters
string|number faction The faction identifier (unique ID or index).
Returns
boolean True if the player has access to the faction, false otherwise.
Example Usage
if lia.faction.hasWhitelist("citizen") then
-- Show citizen faction in character creation menu
end
lia.faction.hasWhitelist(faction)
Purpose
Checks whitelist access for a faction on the server side (currently simplified implementation).
When Called
Called on the server for faction access validation, though the current implementation is restrictive.
Parameters
string|number faction The faction identifier (unique ID or index).
Returns
boolean True only for default factions, false for all others including staff.
Example Usage
-- Server-side validation
if lia.faction.hasWhitelist("citizen") then
-- Allow character creation
end