Server

This page documents all available server-side exports for SD-Horde. These exports allow you to interact with the horde system from other server-side scripts, integrate with custom group systems, create admin commands, and more.

---

Game Management

IsPlayerInHorde

Check if a player is currently in a horde game.

local inGame, game, gameId = exports['sd-horde']:IsPlayerInHorde(source)

Parameters

Name	Type	Description
source	number	Player server ID

Returns

Name	Type	Description
inGame	boolean	Whether the player is in a horde game
game	table|nil	The game session data (if in game)
gameId	string|nil	The game ID (if in game)

Example

local inGame, game, gameId = exports['sd-horde']:IsPlayerInHorde(source)
if inGame then
    print("Player is in game: " .. gameId)
    print("Current round: " .. game.currentRound)
    print("Map: " .. game.map)
end

---

StartHordeGame

Start a horde game for a player. This creates a pending game and shows the entry location.

local gameId = exports['sd-horde']:StartHordeGame(source, mapName, difficultyId)

Parameters

Name	Type	Description
source	number	Player server ID (host)
mapName	string	Map name from Maps config
difficultyId	string	Difficulty ID from map.difficulties

Returns

Name	Type	Description
gameId	string|nil	The created game ID, or nil on failure

Example

local gameId = exports['sd-horde']:StartHordeGame(source, 'warehouse', 'normal')
if gameId then
    print("Game started! ID: " .. gameId)
else
    print("Failed to start game")
end

---

ForceStartHordeGame

Start a horde game immediately, skipping the entry location requirement. Uses the player's existing group if they have one.

local gameId = exports['sd-horde']:ForceStartHordeGame(source, mapName, difficultyId)

Parameters

Name	Type	Description
source	number	Player server ID (host)
mapName	string	Map name from Maps config
difficultyId	string	Difficulty ID from map.difficulties

Returns

Name	Type	Description
gameId	string|nil	The created game ID, or nil on failure

Example

-- Start a game immediately without entry location
local gameId = exports['sd-horde']:ForceStartHordeGame(source, 'warehouse', 'hard')
if gameId then
    TriggerClientEvent('chat:addMessage', source, {
        args = { "Game started immediately!" }
    })
end

---

StartHordeWithPlayers

The most flexible way to start a horde game. Accepts a custom list of players in various formats, bypassing the internal group system. This is the recommended export for integrating with custom group/party systems.

local gameId, error = exports['sd-horde']:StartHordeWithPlayers(players, mapName, difficultyId, options)

Parameters

Name	Type	Description
players	table	Array of players (see formats below)
mapName	string	Map name from Maps config
difficultyId	string	Difficulty ID from map.difficulties
options	table|nil	Optional settings (see options below)

Supported Player Formats

The export is designed to work with any group system. It accepts players in multiple formats:

-- Simple array of source IDs
{1, 2, 3}

-- Array of objects with 'source' key
{{source = 1}, {source = 2}, {source = 3}}

-- Various key names are supported
{{serverId = 1}, {server_id = 2}, {id = 3}, {src = 4}, {player = 5}}

-- With optional names (used for display)
{{source = 1, name = "John"}, {source = 2, name = "Jane"}}
{{serverId = 1, playerName = "John"}, {serverId = 2, player_name = "Jane"}}

-- Mix and match formats
{1, {source = 2}, {serverId = 3, name = "Player3"}}

Options

Option	Type	Default	Description
skipEntry	boolean	false	Skip entry location, start immediately
immediate	boolean	false	Alias for skipEntry
skip_entry	boolean	false	Alias for skipEntry
host	number	first player	Server ID of the host player

Returns

Name	Type	Description
gameId	string|nil	The created game ID, or nil on failure
error	string|nil	Error message if failed

Examples

-- Simple usage with source IDs
local gameId, err = exports['sd-horde']:StartHordeWithPlayers(
    {1, 2, 3},
    'warehouse',
    'normal'
)

-- Start immediately (skip entry location)
local gameId, err = exports['sd-horde']:StartHordeWithPlayers(
    {1, 2, 3},
    'warehouse',
    'normal',
    { skipEntry = true }
)

-- Specify a different host
local gameId, err = exports['sd-horde']:StartHordeWithPlayers(
    {1, 2, 3},
    'warehouse',
    'normal',
    { host = 2, skipEntry = true }
)

-- Integration with your custom group system
local myGroupMembers = MyGroupSystem.GetMembers(source)
-- Example: { {id = 1, name = "John"}, {id = 2, name = "Jane"} }

local gameId, err = exports['sd-horde']:StartHordeWithPlayers(
    myGroupMembers,
    'warehouse',
    'hard',
    { skipEntry = true }
)

-- Error handling
local gameId, err = exports['sd-horde']:StartHordeWithPlayers(players, 'warehouse', 'normal')
if not gameId then
    print("Failed to start horde: " .. err)
    return
end
print("Game started: " .. gameId)

---

ForceEndGame

Force end the game that a player is currently in. This ends the game for all players in that session.

local success = exports['sd-horde']:ForceEndGame(source)

Parameters

Name	Type	Description
source	number	Player server ID

Returns

Name	Type	Description
success	boolean	Whether the game was ended

Example

local success = exports['sd-horde']:ForceEndGame(source)
if success then
    print("Game ended successfully")
end

---

RemovePlayerFromGame

Remove a specific player from their current game without ending the game for others.

local success = exports['sd-horde']:RemovePlayerFromGame(source)

Parameters

Name	Type	Description
source	number	Player server ID

Returns

Name	Type	Description
success	boolean	Whether the player was removed

Example

-- Remove a player (others continue playing)
local success = exports['sd-horde']:RemovePlayerFromGame(source)
if success then
    TriggerClientEvent('chat:addMessage', source, {
        args = { "You have been removed from the horde game" }
    })
end

---

GetActiveGames

Get information about all currently active horde games.

local games = exports['sd-horde']:GetActiveGames()

Returns

Name	Type	Description
games	table	Array of game info objects

Game Info Object

Field	Type	Description
gameId	string	Unique game identifier
map	string	Map name
difficulty	string	Difficulty ID
playerCount	number	Number of players
players	table	Array of player source IDs
currentRound	number	Current round number
state	string	Game state
money	number	Shared money pool

Example

local games = exports['sd-horde']:GetActiveGames()
print("Active games: " .. #games)

for _, game in ipairs(games) do
    print(string.format("Game %s: %d players on %s (Round %d)",
        game.gameId,
        game.playerCount,
        game.map,
        game.currentRound
    ))
end

---

GetPlayerGameInfo

Get detailed information about a player's current game.

local info = exports['sd-horde']:GetPlayerGameInfo(source)

Parameters

Name	Type	Description
source	number	Player server ID

Returns

Name	Type	Description
info	table|nil	Game info, or nil if not in game

Info Object

Field	Type	Description
gameId	string	Unique game identifier
map	string	Map identifier
mapLabel	string	Display name of map
difficulty	string	Difficulty ID
difficultyLabel	string	Display name of difficulty
currentRound	number	Current round number
maxRounds	number	Maximum rounds for this difficulty
state	string	Game state
money	number	Shared money pool
playerCount	number	Number of players
players	table	Array of player source IDs
isDead	boolean	Whether this player is dead

Example

local info = exports['sd-horde']:GetPlayerGameInfo(source)
if info then
    print(string.format("Playing %s on %s - Round %d/%d",
        info.mapLabel,
        info.difficultyLabel,
        info.currentRound,
        info.maxRounds
    ))

    if info.isDead then
        print("Player is currently dead")
    end
end

---

GetAvailableMaps

Get all available maps and their difficulties.

local maps = exports['sd-horde']:GetAvailableMaps()

Returns

Name	Type	Description
maps	table	Array of map info objects

Map Info Object

Field	Type	Description
id	string	Map identifier
label	string	Display name
difficulties	table	Array of difficulty info

Difficulty Info Object

Field	Type	Description
id	string	Difficulty identifier
label	string	Display name
maxRounds	number	Number of rounds

Example

local maps = exports['sd-horde']:GetAvailableMaps()
for _, map in ipairs(maps) do
    print("Map: " .. map.label .. " (" .. map.id .. ")")
    for _, diff in ipairs(map.difficulties) do
        print("  - " .. diff.label .. ": " .. diff.maxRounds .. " rounds")
    end
end

---

Player Progression

GetPlayerStats

Get a player's horde statistics and progression.

local stats = exports['sd-horde']:GetPlayerStats(source)

Parameters

Name	Type	Description
source	number	Player server ID

Returns

Name	Type	Description
stats	table|nil	Player stats, or nil if unavailable

Stats Object

Field	Type	Description
level	number	Player's horde level
xp	number	Current XP
stats	table	Detailed statistics
completedMaps	table	Map completion records

Stats Details

The stats table typically contains:

• kills - Total enemy kills

• deaths - Total deaths

• rounds - Total rounds survived

• gamesCompleted - Games finished

• gamesStarted - Games started

• And more depending on configuration

Example

local stats = exports['sd-horde']:GetPlayerStats(source)
if stats then
    print(string.format("Level %d with %d XP", stats.level, stats.xp))
    print(string.format("Total kills: %d", stats.stats.kills or 0))
    print(string.format("Deaths: %d", stats.stats.deaths or 0))
    print(string.format("Games completed: %d", stats.stats.gamesCompleted or 0))
end

---

AddPlayerXP

Add XP to a player's horde progression.

local success, newLevel = exports['sd-horde']:AddPlayerXP(source, amount)

Parameters

Name	Type	Description
source	number	Player server ID
amount	number	Amount of XP to add (must be positive)

Returns

Name	Type	Description
success	boolean	Whether XP was added
newLevel	number|nil	New level if player leveled up, otherwise nil

Example

-- Reward XP for an external achievement
local success, newLevel = exports['sd-horde']:AddPlayerXP(source, 500)
if success then
    if newLevel then
        TriggerClientEvent('chat:addMessage', source, {
            args = { "You leveled up to level " .. newLevel .. "!" }
        })
    else
        TriggerClientEvent('chat:addMessage', source, {
            args = { "You gained 500 XP!" }
        })
    end
end

---

SetPlayerLevel

Set a player's horde level directly. XP is automatically adjusted to match the level.

local success = exports['sd-horde']:SetPlayerLevel(source, level)

Parameters

Name	Type	Description
source	number	Player server ID
level	number	Level to set (must be >= 1)

Returns

Name	Type	Description
success	boolean	Whether level was set

Example

-- Admin command to set player level
RegisterCommand('hordesetlevel', function(source, args)
    if not IsPlayerAceAllowed(source, 'admin') then return end

    local targetId = tonumber(args[1])
    local level = tonumber(args[2])

    if targetId and level then
        local success = exports['sd-horde']:SetPlayerLevel(targetId, level)
        if success then
            print("Set player " .. targetId .. " to level " .. level)
        end
    end
end, false)

---

Cooldown Management

IsPlayerOnCooldown

Check if a player is on horde cooldown.

local onCooldown, remainingSeconds, formattedTime = exports['sd-horde']:IsPlayerOnCooldown(source)

Parameters

Name	Type	Description
source	number	Player server ID

Returns

Name	Type	Description
onCooldown	boolean	Whether player is on cooldown
remainingSeconds	number|nil	Remaining seconds (if on cooldown)
formattedTime	string|nil	Human-readable time, e.g., "1h 30m"

Example

local onCooldown, remaining, formatted = exports['sd-horde']:IsPlayerOnCooldown(source)
if onCooldown then
    TriggerClientEvent('chat:addMessage', source, {
        args = { "You are on cooldown for " .. formatted }
    })
else
    print("Player can start a horde game")
end

---

SetPlayerCooldown

Set a player's horde cooldown.

local success = exports['sd-horde']:SetPlayerCooldown(source, minutes)

Parameters

Name	Type	Description
source	number	Player server ID
minutes	number	Cooldown duration in minutes (0 or negative to clear)

Returns

Name	Type	Description
success	boolean	Whether cooldown was set

Example

-- Set 30 minute cooldown
exports['sd-horde']:SetPlayerCooldown(source, 30)

-- Clear cooldown
exports['sd-horde']:SetPlayerCooldown(source, 0)

---

ClearPlayerCooldown

Clear a player's horde cooldown.

local success = exports['sd-horde']:ClearPlayerCooldown(source)

Parameters

Name	Type	Description
source	number	Player server ID

Returns

Name	Type	Description
success	boolean	Whether cooldown was cleared

Example

-- Admin command to clear cooldown
RegisterCommand('hordeclearcooldown', function(source, args)
    if not IsPlayerAceAllowed(source, 'admin') then return end

    local targetId = tonumber(args[1]) or source
    exports['sd-horde']:ClearPlayerCooldown(targetId)
    print("Cleared cooldown for player " .. targetId)
end, false)

---

Perks System

ApplyPerkToAllPlayers

Apply a perk to all players in a specific game.

exports['sd-horde']:ApplyPerkToAllPlayers(gameId, perkId)

Parameters

Name	Type	Description
gameId	string	The game ID
perkId	string	The perk identifier to apply

---

ClearAllPerksForAllPlayers

Clear all perks from all players in a specific game.

exports['sd-horde']:ClearAllPerksForAllPlayers(gameId)

Parameters

Name	Type	Description
gameId	string	The game ID

---

GetActivePerks

Get active perks for a specific game.

local perks = exports['sd-horde']:GetActivePerks(gameId)

Parameters

Name	Type	Description
gameId	string	The game ID

Returns

Name	Type	Description
perks	table	Table of active perk IDs

---

ProcessWinningPerk

Process a perk that won the vote and apply it to all players.

exports['sd-horde']:ProcessWinningPerk(gameId, perkId)

Parameters

Name	Type	Description
gameId	string	The game ID
perkId	string	The perk identifier that won

---

GetServerLootValueMultiplier

Get the server-side loot value multiplier for a game (affected by perks).

local multiplier = exports['sd-horde']:GetServerLootValueMultiplier(gameId)

Parameters

Name	Type	Description
gameId	string	The game ID

Returns

Name	Type	Description
multiplier	number	The loot value multiplier

---

Mystery Box

CleanupMysteryBoxForGame

Clean up mystery box data for a specific game.

exports['sd-horde']:CleanupMysteryBoxForGame(gameId)

Parameters

Name	Type	Description
gameId	string	The game ID