HTNFW Developer Documentation

The documentation explains how to use the HTNFW Framework's export functions to manage and access player character data. It details how to retrieve complete character information, specific data fields, utility data like server IDs, and lists of active or recent players. The docs provide syntax, parameters, return values, and example code snippets for each function, guiding developers on how to efficiently interact with character data for gameplay, UI, and server management tasks.

Character Data Structure

Character data is stored in a structured table with the following fields:

• id: Character ID (integer).
• source: Player's server ID (integer).
• steam_id: Player's Steam identifier (string).
• first_name: Character's first name (string).
• last_name: Character's last name (string).
• dob: Date of birth (string, format: "YYYY-MM-DD").
• phone_number: Character's phone number (string).
• job: Job details (table with name, rank, lable, header, duty, isPolice).
• currency: Cash and bank balance (table with cash and bank).
• licenses: License data (table, e.g., { driver = true, weapon = false }).
• gender: Character gender (string).
• tier: Character tier level (integer).
• new: Indicates if the character is new (boolean).
• accountId: Associated account ID (integer).
• BagStatus: State bag usage status (boolean).

Exported Functions

1. CharacterInformation

Purpose

Retrieves character data for a specific player by their server ID, either returning all data or a specific field.

Syntax

local character = exports['htn-framework']:CharacterInformation(source, returning)

Parameters

• source (integer): The player's server ID.
• returning (string): Specifies the data to retrieve:
  • "all": Returns the full character data table.
  • Specific field (e.g., "first_name", "job", "currency"): Returns that field's value.

Return Values

• Full Data: If returning is "all", returns the complete character data table.
• Specific Field: If a specific field is requested, returns its value.
• No Data: Returns nil if no character data exists for the source or the field is invalid.

Example

-- Fetch all character data
local character = exports['htn-framework']:CharacterInformation(source, "all")

if (character) then
    print("Character: " .. character.first_name .. " " .. character.last_name)
    print("Job: " .. character.job.name .. ", Cash: $" .. character.currency.cash)
end

-- Fetch specific field
local firstName = exports['htn-framework']:CharacterInformation(source, "first_name")

if (firstName) then
    print("First Name: " .. firstName)
end

Example Output

Character: John Doe
Job: police, Cash: $5000
First Name: John

Sample Data Structure (for "all")

{
    id = 123,
    source = 1,
    steam_id = "steam:110000112345678",
    first_name = "John",
    last_name = "Doe",
    dob = "1990-01-01",
    phone_number = "1234567890",
    job = {
        name = "police",
        rank = "officer",
        lable = "Officer",
        header = "LSPD",
        duty = false,
        isPolice = true
    },
    currency = { cash = 5000, bank = 10000 },
    licenses = { driver = true, weapon = false },
    gender = "male",
    tier = 1,
    new = false,
    accountId = 456,
    BagStatus = false
}

2. GetPlayerFromCid

Purpose

Retrieves character data by character ID (cid), useful for finding a player's data without knowing their current server ID.

Syntax

local player = exports['htn-framework']:GetPlayerFromCid(cid)

Parameters

• cid (integer): The character ID.

Return Values

• Returns the full character data table if found, or nil if no player is associated.

Example

local player = exports['htn-framework']:GetPlayerFromCid(123)

if (player) then
    print("Player: " .. player.first_name .. " " .. player.last_name)
end

Example Output

Player: John Doe

3. GetPlayerFromNumber

Purpose

Retrieves character data by phone number, useful for in-game communication systems.

Syntax

local player = exports['htn-framework']:GetPlayerFromNumber(num)

Parameters

• num (string or integer): The character's phone number.

Return Values

• Returns the full character data table if found, or nil if no match.

Example

local player = exports['htn-framework']:GetPlayerFromNumber("1234567890")

if (player) then
    print("Player: " .. player.first_name .. " " .. player.last_name)
end

Example Output

Player: John Doe

4. GetFXPlayers

Purpose

Retrieves character data for all currently active players on the server.

Syntax

local players = exports['htn-framework']:GetFXPlayers()

Return Values

• Returns a table of all active players' character data, indexed by server ID.

Example

local players = exports['htn-framework']:GetFXPlayers()

for source, data in pairs(players) do
    print("Player " .. source .. ": " .. data.first_name .. " " .. data.last_name)
end

Example Output

Player 1: John Doe
Player 2: Jane Smith

5. GetRecentPlayers

Purpose

Retrieves data for recently connected players, useful for tracking recent activity.

Syntax

local recentPlayers = exports['htn-framework']:GetRecentPlayers()

Return Values

• Returns a table of recently connected players' data, indexed by Steam ID.

Example

local recentPlayers = exports['htn-framework']:GetRecentPlayers()
for steamId, data in pairs(recentPlayers) do
    print("Recent Player: " .. steamId)
end

6. Currency Update

Purpose

Allows updating a character’s currency (like cash or bank) by adding or removing a specified amount. This function updates the database, the player's in-game state, and triggers client-side events to reflect the change.

Syntax

exports['htn-framework']:CurrencyUpdate(stateId, currency, payload)

Parameters

• stateId (integer): The character ID.
• currency (string): The type of currency to update (e.g., "cash", "bank").
• payload (table): Contains update details:
  • _source (integer): The player's server ID.
  • update (integer): The amount to add or remove.
  • status (boolean): true to add, false to remove.

Return Values

No return value; the function updates the database, the player's state, and triggers client events (banking:updateBalance and htn-framework:UpdateClient).

Example

-- Add $1000 to a character's cash
local payload = { _source = 1, update = 1000, status = true }
exports['htn-framework']:CurrencyUpdate(123, "cash", payload)

-- Remove $500 from a character's bank
local payload = { _source = 1, update = 500, status = false }
exports['htn-framework']:CurrencyUpdate(123, "bank", payload)

Example Output

• For adding $1000 to cash, client receives events updating the balance.
• For removing $500 from bank, client receives events reflecting the new balance.