Faction Hooks

This document describes all FACTION function hooks defined within the codebase.

Use these to customize default naming, descriptions, and lifecycle events when characters are created, spawned, or transferred within a faction.

Each hook is defined on a faction table and receives the table itself as self when invoked.

---

Overview

Hooks belong to tables under schema/factions.

They are most often used to set up characters when they first join the faction.

All hooks are optional — if you omit a hook, default behaviour applies.

---

NameTemplate

Purpose

Generates a custom character name before defaults are applied.

Parameters

• client (Player): The player creating the character.

Realm

Shared

Returns

• string, boolean: Generated name and whether to bypass default naming.

Example Usage

function FACTION:NameTemplate(client)
    -- Prefix a random callsign with the faction name.
    local id = math.random(100, 999)
    return string.format("%s-%03d", self.name, id), true
end

---

GetDefaultName

Purpose

Retrieves the default character name for this faction.

Parameters

• client (Player): The client requesting the name.

Realm

Shared

Returns

• string: The generated name.

Example Usage

function FACTION:GetDefaultName(client)
    -- Base the callsign on the player's account ID for consistency.
    return "Recruit-" .. client:AccountID()
end

---

GetDefaultDesc

Purpose

Provides the default description for a newly created character.

Parameters

• client (Player): The client for whom the description is generated.

Realm

Shared

Returns

• string, boolean: The description text and whether to override the user input.

Example Usage

function FACTION:GetDefaultDesc(client)
    -- Use the name as part of a simple biography.
    local callsign = self:GetDefaultName(client)
    -- Returning true overrides any description entered by the player.
    return string.format("%s recently enlisted and is eager for duty.", callsign), true
end

---

OnSpawn

Purpose

Executes whenever a faction member spawns during load-out.

Parameters

• client (Player): The player who has just spawned.

Realm

Server

Returns

• nil: This function does not return a value.

Example Usage

function FACTION:OnSpawn(client)
    -- Restore stats and hand out default weapons.
    client:SetHealth(client:GetMaxHealth())
    client:SetArmor(self.armor or 0)

    for _, wep in ipairs(self.weapons or {}) do
        client:Give(wep)
    end
end

---

OnTransferred

Purpose

Runs after a player is moved into this faction from another.

Parameters

• client (Player): The player that was transferred.

• oldFaction (number): Index of the previous faction.

Realm

Server

Returns

• nil: This function does not return a value.

Example Usage

function FACTION:OnTransferred(client, oldFaction)
    local char = client:getChar()
    if char and istable(self.models) then
        -- Choose a random uniform for the new faction.
        char:setModel(self.models[math.random(#self.models)])
    end

    -- Notify the player about the transfer.
    client:notify(string.format("Joined %s from faction #%d", self.name, oldFaction))
end

---

OnCheckLimitReached

Purpose

Determines if the faction has reached its player limit.

Parameters

• character (Character): The character attempting to join.

• client (Player): The owner of that character.

Realm

Shared

Returns

• boolean: Whether the limit is reached.

Example Usage

function FACTION:OnCheckLimitReached(character, client)
    -- Allow admins to bypass the limit.
    if client:IsAdmin() then
        return false
    end

    local maxMembers = self.limit or 10
    return lia.faction.getPlayerCount(self.index) >= maxMembers
end

---