Mode descriptor

Stability: Stable.

A descriptor is the plain-data table you pass to registerMode. It fully describes a mode: its team structure, loadouts, timings, and win condition. Data-only modes need no functions; advanced modes may add hooks.

Two principles shape the contract:

• Structure only, no identity. A mode declares how many teams (teamCount) of how many players (perTeam). Teams have no names, colors, or forced models — they are anonymous, and the engine renders every match egocentrically (you vs the enemy, battle-royale style). The runtime team objects are private to the engine and never appear in this contract.
• Maps live in battlegrounds. A mode carries no spawn data. Battlegrounds register a modes.<id> block via exports.sdk:registerBattleground, and your mode automatically draws from every battleground that supports it. See the battleground SDK.

local MODE = {
    id         = 'duel',
    apiVersion = 1,
    label      = '1v1 Duel',
    teamCount  = 2,
    perTeam    = 1,
    maxRound   = 5,
    rules = {
        structure = 'rounds',
        phases    = { live = 90, post = 4 },
        roundEnd  = { 'elimination', 'timeLimit' },
        win       = { roundWins = 5 },
    },
    armor   = 100,
    loadout = { { 'WEAPON_PISTOL', 999 }, { 'WEAPON_COMBATPISTOL', 999 } },
}

Authoring with defineMode (recommended)

You can pass a raw table straight to registerMode, but the SDK ships a builder that validates the descriptor at your mode's own load and gives your editor autocomplete. Opt in by including the SDK's descriptor library, then wrap your table:

-- fxmanifest.lua
shared_scripts {
    '@sdk/shared/kit.lua',         -- SDK helpers the contract uses (load first)
    '@sdk/shared/criteria.lua',    -- the criterion contract `defineMode` delegates to (required)
    '@sdk/shared/descriptor.lua',  -- defineMode + the RfxMode types
}

All three are required: defineMode validates criteria through the criterion contract whether or not your descriptor declares any. Omit one and the SDK refuses the descriptor with a message naming the missing file.

-- config.lua (or main.lua)
Config.mode = defineMode{
    id = 'duel', label = '1v1 Duel',
    teamCount = 2, perTeam = 1,
    -- ...
}

• Validation runs here, tied to your resource — a malformed descriptor prints a precise diagnostic and aborts the load instead of failing silently at runtime.
• Defaults are filled (perTeam, minToStart, maxRound, timings; teamCount = 2 when rules is present), so the table you get back is the resolved one.
• Autocomplete + type-checking come from the RfxMode LuaCATS class — a LuaLS-aware editor suggests fields and flags type errors as you type.

registerMode validates too; defineMode just moves the check earlier, to where you're working. Without the include, exports.sdk:defineMode(spec) does the same from your registration thread.

Versioning

The descriptor shape is a contract with a version. The SDK implements one (exports.sdk:modeApiVersion(), currently 1), and your mode pins the version it was written against:

defineMode{ id = 'mygame', apiVersion = 1, ... }

Validation compares the two so the contract can evolve without breaking modes silently:

A breaking change to the descriptor shape bumps the SDK's version; pinning yours turns "my mode mysteriously misbehaves" into a clear, actionable line at startup.

Top-level fields

Teams are indices. Everywhere a team appears across the platform — arena spawn arrays, the hook snapshot's counts/alive/wins, a player's team field — it is the team number (1..teamCount). There are no role names to keep in sync.

timings

Phase durations in seconds. The rules runtime prefers rules.phases (live / post / respawn); this top-level timings table is the fallback block, and its ['end'] value also sets the post-round / post-match pause. Each key has a built-in fallback if both are omitted.

end is a Lua reserved word — always write it as ['end'].

Spawns: battlegrounds, indexed by team

This section is about battlegrounds, not the match container. It covers the SDK battleground registry (registerBattleground / battleground_pack_*) — the pool of maps + spawn data a mode draws from. The match Arena players join and fight in (the lobby contract) is a different entity; it picks one of these maps for its scene.

A mode carries no spawn data. A battleground (map) registers a modes.<id> block whose areas (drop-in circles) and spawns (static points) are arrays indexed by team number — entry 1 is where team 1 enters, entry 2 team 2:

-- in a battleground pack (resources/[packs]/battleground_pack_*), not the mode:
defineBattleground{
    id = 'warehouse', apiVersion = 1, label = 'Warehouse',
    modes = {
        duel = {
            areas = {
                { x = 1209.0, y = -3115.0, z = 5.5, r = 8.0, face = 'center' },  -- team 1
                { x = 1234.0, y = -3115.0, z = 5.5, r = 8.0, face = 'center' },  -- team 2
            },
        },
    },
}

See the battleground SDK for the full contract. The engine round-robins compatible battlegrounds as it creates scenes; the arena creator picks one in the Create form. If no loaded battleground supports the mode, scenes fall back to a placeholder labelled Arena with no spawn points — so always ship at least one compatible battleground. Spawn z need not be exact either way — a ground spawn re-probes the ground under the point, and a drop comes from high above and lands the player on whatever ground is there.

menu (NUI card)

Optional presentation data for the NUI lobby menu's mode card. It is plain design data — gameplay never reads it. The engine copies it into each mode's entry in the lobby snapshot (with safe defaults for any omitted field), and the menu builds the card from there.

The card identity — title, sub, rgb, desc, hero — is not in menu: it lives in the shared present block (the same block a cosmetic pack uses). The engine flattens present onto the snapshot's top-level name/sub/rgb/desc for the NUI. menu carries only the rail/routing fields that are mode-specific:

-- rail/routing (mode-specific)
menu = {
    short    = '1V1',
    flow     = '1v1',
    category = 'Duels',
    tagline  = 'One arena. One opponent. Settle it.',
},
-- card identity + showcase (shared RfxPresent — see presentation.mdx)
present = {
    title = '1v1 Duel',
    sub   = 'Solo · Best of',
    rgb   = '34 211 230',
    desc  = 'Pick a map and a loadout, then create an arena or join an open duel.',
    -- hero/info/buy optional
},

Notes

• Appearance never carries team identity. Every combatant keeps the skin they equipped in the lobby (the customization resource); the engine never forces a model. PvP damage is enabled by friendly-fire settings (NetworkSetFriendlyFireOption / SetCanAttackFriendly), not by GTA teams — see the internal buckets notes.
• Behaviour precedence: tick hook > rules runtime > named driver. A tick hook makes rules/driver irrelevant; a mode with none of them does not tick. Systems are orthogonal: they tick alongside whichever runtime the mode uses — including none — and never replace it. See Systems.
• Only perTeam, minToStart, maxRound, timings (and teamCount when rules is present) are defaulted at registration.
• The runtime supplies its own phase fallback values (round/end/respawn), used only when your descriptor omits the key. The shipped example mode also resolves some descriptor values from server.cfg convars in its own config.lua — that's a project convention, not part of this contract. A descriptor is just a table; how you build it is up to you.

See also

• registerMode · Drivers · Hooks · Build your first mode