Skip to content

ax.currencies

Source: gamemode/modules/currencies/libraries/sh_currencies.lua

Character-based currency system for managing multiple currencies in roleplay scenarios.

Documented functions: 9

Functions

ax.currencies:Find(query)

Find a currency by its uniqueID, name, symbol, singular, or plural form.

Performs a case-insensitive search with fallback from exact match → prefix match → substring match.

Realm: shared

Parameters

Name Type Description
query string The uniqueID, name, symbol, singular, or plural to search for

Returns

  • table|nil: The currency data table if a match is found, nil otherwise

Usage

local currency = ax.currencies:Find("default") -- Finds by uniqueID

local currency = ax.currencies:Find("req")     -- Finds "requisition" by prefix

local currency = ax.currencies:Find("$")       -- Finds by symbol

ax.currencies:Format(amount, uniqueID, useText)

Format a currency amount using the currency's formatter.

Falls back to basic formatting if currency is not found or invalid.

Realm: shared

Parameters

Name Type Description
amount number The amount to format
uniqueID string The unique identifier of the currency

Returns

  • string: Formatted currency string (e.g., "$ 1,234 Dollars")

Usage

local formatted = ax.currencies:Format("default", 1000)
-- Returns: "$ 1,000 Dollars"

ax.currencies:FormatWithSymbol(amount, uniqueID, useSymbol, symbolPosition, useText)

Format a currency amount with symbol prefix or suffix.

Realm: shared

Parameters

Name Type Description
amount number The amount to format
uniqueID string The unique identifier of the currency
useSymbol boolean Whether to include the currency symbol (default: false)
symbolPosition string "prefix" or "suffix" to position the symbol (default: "prefix")

Returns

  • string: Formatted currency string with symbol (e.g., "$ 1,000 Dollars" or "1,000$ Dollars")

Usage

local formatted = ax.currencies:FormatWithSymbol(1000, "default", true, "prefix")
-- Returns: "$ 1,000 Dollars"

ax.currencies:Get(uniqueID)

Get a registered currency by its unique ID.

Realm: shared

Parameters

Name Type Description
uniqueID string The unique identifier of the currency

Returns

  • table|nil: The currency data table if found, nil otherwise

Usage

local default = ax.currencies:Get("default")

ax.currencies:GetAll()

Get all registered currencies.

Realm: shared

Returns

  • table: Table of all registered currencies keyed by their unique IDs

Usage

for id, currencyData in pairs(ax.currencies:GetAll()) do
    print(id, currencyData.name)
end

ax.currencies:IsPhysical(uniqueID)

Check if a currency supports physical interactions like dropping or direct handoffs.

Realm: shared

Parameters

Name Type Description
uniqueID string The unique identifier to check

Returns

  • bool: True if the currency is physical, false otherwise

ax.currencies:IsValid(uniqueID)

Check if a currency is valid and registered.

Realm: shared

Parameters

Name Type Description
uniqueID string The unique identifier to check

Returns

  • bool: True if the currency exists, false otherwise

Usage

if (ax.currencies:IsValid("default")) then
    print("Dollars currency is registered")
end

ax.currencies:Register(uniqueID, data)

Register a new currency type.

Creates a currency definition that can be used for character money management.

Automatically registers a character variable for storing the currency value.

Realm: shared

Parameters

Name Type Description
uniqueID string The unique identifier for the currency (e.g., "default", "tokens")
data table Currency configuration table with the following fields: - name (string): Display name of the currency - symbol (string): Currency symbol (e.g., "$", "¥", "₹") - default (number): Default starting amount (defaults to 0) - singular (string): Singular form of currency name (e.g., "dollar") - plural (string): Plural form of currency name (e.g., "default") - symbolPosition (string): "prefix" or "suffix" for how the symbol is placed in formatted text - symbolSpacing (boolean): Whether to add a space between the symbol and amount in formatted text - model (string): Inventory/world preview model used for this currency - description (string): Description shown in UI panels - physical (boolean): Whether the currency can exist as a world entity or be directly handed over - format (function): Optional custom formatting function(amount) -> string

Returns

  • bool: True if registration succeeded, false otherwise

Usage

ax.currencies:Register("default", {
    name = "Dollars",
    symbol = "$",
    default = 100,
    singular = "dollar",
    plural = "default"
})

ax.currencies:Spawn(amount, uniqueID, position, angle)

Register default currency immediately

Spawn a currency entity in the world (server only).

Creates a physical entity representing dropped currency that players can pick up.

Realm: server

Parameters

Name Type Description
amount number The amount of currency to spawn
uniqueID string The unique identifier of the currency (defaults to "default")
position vector\|Player The position to spawn at, or a player (spawns at their drop position)
angle Angle Optional angle for the entity (defaults to random)

Returns

  • Entity|nil: The spawned currency entity, or nil if invalid parameters

Usage

local money = ax.currencies:Spawn(500, "default", player:GetPos() + Vector(0, 0, 32))