ACE.Legal

ACE.Manufacturing

ACFM

ACE.Points

Starfall

ACF.Legal

_G (Global)

The **Proving Ground** (TPG) gamemode API — entities, objectives, player systems and gameplay code built on ACE. Parsed from the addon source; grouped by the source folders (Entities, Core, Systems, …).

Append a point to the running map's list and save immediately. No de-duplication: placing the same type/position twice yields two records, which for `"ctf"` matters because `TPG.Maps.GetCustomFlagPoint` always returns the first one in list order (the first ever placed), silently ignoring any later ones.

AddPoint

One of `"cp"`, `"koth"`, `"ctf"`, `"spawn"`.

ptype

Only meaningful for `"spawn"`; nil otherwise.

teamId

Optional label; falls back to a generated one when read.

name

Add to (or drain from) a team's ticket pool, clamped at zero. Scoring drains the *losing* side rather than adding to the winner, so in practice `amount` is negative. The pool never goes below zero, so a large overshoot is not carried into the next round. Does not itself end the round; `tpg.rounds.CheckWinCondition` notices.

AddScore

amount

Strip and re-kit a player: weapons, armor, movement speed and ammo. Not on a team (spectator): only the default weapons and building tools, no team kit, no speed changes. On a team: reads the saved Primary/Secondary/ Special/Armor PData picks (a legacy non-string save falls back to the default loadout), charges premium picks through `TPG.Gear.Claim` if that system is loaded (a denial swaps in the free equivalent and messages why), applies armor stats, computes and sets walk/run speed from the resulting armor + weapon penalties BEFORE handing out any weapon (ACE's weapon base snapshots the owner's speed on Deploy, so setting it after would let a weapon deploy against the stale pre-loadout speed), then gives the actual weapons, tops up their ammo, and hands out a consolation disposable AT only if the Special slot came up empty. Underdog perks (smoke, medkit) are added last. Finishes by publishing `pState.liveLoadout` (what the player is actually carrying, which can differ from the PData picks after a denial), clearing the `rekit` flag, restamping speed via `tpg.loadout.StampSpeed` for weapons that never got a fresh Deploy snapshot, and syncing the gear menu's cooldowns.

Apply

Set `ply`'s model, health and armor from the `armorId` tier's stats (`TPG.GetArmor`). Sets both current and max health to the tier's value, so an armor change also resets the health pool rather than merely capping it.

ApplyArmor

armorId

Overlay a map's admin-placed points onto a freshly-loaded map config. Called from `tpg.maps`' `Load` right after it merges the map's inline config over the defaults, so placed points always win over what is authored in `_loader.lua`. Mutates `config` in place; returns nothing. Each category is independent and only touched if something was placed for it: a map with only custom spawns leaves `config[GAMEMODE_CP]` and `config[GAMEMODE_KOTH]` exactly as the inline config or defaults left them. When there ARE placed `"cp"` or `"koth"` points, the whole objective list for that mode is replaced wholesale (not merged) with the placed ones.

ApplyCustomPoints

The merged map config to mutate (`TPG.Maps.Current`).

config

mapName

Apply admin enable/override state on top of the discovered weapon lists. Shape of `state`: { bases     = { [base] = bool }, weapons   = { [id]   = bool }, overrides = { [id]   = { speedBonus = n, cost = n, name = s } } } Precedence per weapon: a base-level disable turns `enabled` off, then an explicit per-weapon entry in `weapons` overrides that either way, so a single weapon can be re-enabled even when its whole base is off. The `"none"` entry in each category is never touched -- it is always enabled and always free, regardless of state. Mutates the entry tables in `TPG.Weapons.Primary/Secondary/Special` IN PLACE rather than replacing them, so any table reference a caller already holds from `TPG.GetWeapon` changes under it when this runs; nothing here hands back a snapshot. Stores `state` on `TPG.Weapons._state` unconditionally (even before doing anything else), which is what lets `TPG.Weapons.Discover` re-apply it after a rebuild -- but it also means a bad or partial state table is kept as "current" the moment this is called, not only once applied successfully.

ApplyState

state

Move a player onto a team, subject to the switch cooldown and balance check. A no-op (returns true without touching the cooldown) if they are already on `teamId`. Otherwise: voluntary switches onto an actual team (not spectator) are throttled by `TPG.Config.teamSwitchCooldown`, which admins bypass and which only applies once the player has switched at least once before (`ply.tpgLastTeamSwitch` unset on first join). Leaving to spectator is always allowed and never stamps the cooldown. Passing the cooldown still requires `CanJoin` to allow the move; either rejection sends a chat message and returns false without moving the player. On success this also respawns the player and applies team colour via the normal spawn path.

AssignPlayer

Force `ply` onto the weaker team if their own team outnumbers the other by more than one. Called (via a small delay) after every death, so the swap always lands between lives rather than mid-fight.

Autobalance

Announce and award one medal per category to that round's leader. For each entry in `TPG.Commendations.Types`, finds the highest `pState.stats[key]` across everyone in `TPG.State.players`, bumps their lifetime medal count in PData (`commType.pdataKey`) by one, and broadcasts it. Ties are not detected -- `pairs()` iteration order picks whichever player it reaches first among equal values. There is no bot exclusion here, unlike `tpg.stats`: `TPG.State.players` is not filtered by `IsPlayer()`/`IsBot()`, so if a bot ever leads a category it receives a PData medal write like anyone else. A leader with 0 in every category still wins that category, since the running best starts at -1 -- there is no "nobody qualifies" case as long as at least one tracked player exists. Meant to be called once, from the round-end flow.

Award

Start a Rush round, or clear Rush state if this round is something else. Called unconditionally from `tpg.rounds.Setup` every round -- the same pattern as `TPG.CTF.SpawnFlags` -- so the round loop does not have to know which modes need setting up. Runs AFTER `TPG.Objectives.SpawnAll` has already spawned the round's full objective list, and deliberately replaces it: Setup spawns whatever the map lists for the game type, and Rush wants one point rather than all of them.

Begin

Arm the prep window for a new round: clears any stale warn-throttle state and resets the clock to "waiting for both teams", but does not itself start the countdown (see the `Think` hook below for that). Must be called from `tpg.rounds.Setup` at the start of each round.

Open the skirmish gap before the next stage. Takes the point off the map first, through `SpawnAll` with an empty list -- the same call that would spawn one, so there is a single path by which objectives come and go. That removal IS the break: with nothing placed, there is nowhere to pre-position, and the next point is news when it lands rather than a destination people have been driving to for five minutes. A break of zero or less is not an error, it is the old behaviour, and it reveals the next stage immediately rather than leaving the map empty for a tick.

BeginBreak

Hold the first round of a map until players have finished loading in. Fast loaders used to join, take a team, and start burning the team budget (or earning economy income) while slow loaders were still on the loading screen. This waits `TPG.Config.waitBaseTime` as a floor, pushes the start `waitJoinExtend` further out whenever someone is mid-connect, and gives up at `waitMaxTotal` so one stuck client cannot hold the server hostage. A connection that goes quiet is forgotten after three minutes. While it runs, `TPG.State.waitingForPlayers` is true and building is blocked (`sv_duplication` and the `PlayerSpawnProp` check read that flag). `Setup` force-clears it, so no path can leave building blocked. Called once from `GM:Initialize`. It ends by calling `Setup` itself.

BeginInitialWait

Bottom of the compass block, for anything that stacks below it.

BelowCompass

Bottom of the point-pip row, for whatever stacks below it (the compass). Falls back to the bottom of the score panel when there are no points to show pips for at all -- checked against the cached objective count, so it reflects the same 0.5s-stale list `UpdateObjectiveCache` maintains.

BelowObjectives

Bottom of the centre stack including the overtime tag, for anything that stacks below it (the CTF banner). Returns the compass bottom when overtime isn't showing a persistent tag (either not in overtime, or still within the first `BANNER_TIME` seconds where the big banner is drawn instead), so nothing leaves a hole waiting for a tag that may never appear.

BelowOvertime

Why a class is restricted, or nil if it is not. Checks the exact-class table first, then the lowercase family patterns.

BlockReason

class

nil if the class is fine, else the human-readable reason.

Recompute the per-candidate vote counts from every player's live vote and send the tally to all clients.

BroadcastTally

(Re)create every named HUD/menu font at the current screen scale. Recomputes `TPG.UI.scale` from the screen height first, then rebuilds every entry in the local `FONTS` table via `surface.CreateFont`, and records each one's cap-centring correction into `TPG.UI.CapMid` (see `TPG.UI.TextInBox`) keyed by the SAME font name, so a caller that only has the font name string can still look up its correction. Runs once at load and again on `OnScreenSizeChanged`, so a font name is valid to use in `surface.SetFont` immediately after either of those, but NOT before the first run has happened.

BuildFonts

The points this round will reveal, in order. An authored `[GAMEMODE_RUSH]` block wins if the map has one -- that is the hand-tuned reveal order. Otherwise the control point list is borrowed and shuffled, so the same map does not open on the same point every round. Capped at whichever is smaller, `TPG.Config.rushStages` or what `MaxStages` says the time budget affords -- the ceiling and the clock, and the round obeys both. A map with fewer points than that runs fewer stages still, rather than revealing one twice: a stage whose point the losing team already learned is not the same stage.

BuildStages

Objective entries, `{ pos = Vector, name = string }`.

How fast a point captures, from who is standing on it. The signed head-count difference, clamped to `TPG.Config.capMaxPlayers` in both directions. Only the difference counts, so an evenly contested point returns 0 and does not move at all no matter how many are on it; and the clamp means stacking more than `capMaxPlayers` extra bodies buys nothing.

CalculateCaptureSpeed

greenCount

redCount

Signed speed; positive captures toward green.

Sum the movement-speed bonus/penalty from a full loadout's three weapon slots. An id that does not resolve to a known weapon (unknown category, unknown id, a stale saved loadout referencing a removed weapon) contributes 0 silently rather than erroring or warning, so a broken loadout reference shows up as a speed discrepancy, not as a visible failure. tier's `speedBonus` (see `TPG.Config.minSpeedPercent`).

CalculateSpeedBonus

primaryId

secondaryId

specialId

Combined speed bonus, added into the same sum as the armor

Can this player afford a cost, right now.

CanAfford

cost

Would `ply` joining `targetTeam` leave the teams unbalanced? Spectator is always allowed. Otherwise counts both teams, subtracts `ply` from their current team if they are already on one (so switching teams doesn't double-count them), and rejects a join that would make the target team strictly larger than the other.

CanJoin

targetTeam

Would spawning this add-on push the player's team over any shared limit. Not currently called anywhere in this codebase -- the actual spawn-time enforcement lives in `sv_duplication.lua`, split across two places that do not agree on the comparison: * its post-paste check (in the `AdvDupe_FinishPasting` handler) uses `>`, strictly over, for points, weight and props alike; * its `PlayerSpawnProp` gate uses `>=`, at-or-over, on props only. This function uses `>=` throughout, so if it is ever wired back in it will refuse a team at exactly the cap on all three axes, which matches the prop gate but is one build stricter than the paste check.

CanSpawn

additionalWeight

One fixed-size step of capture math: count who's standing on the point, move `CapProgress` toward whichever side outnumbers the other, and flip `CapOwnership` when it crosses `timeNeutral`/`-timeNeutral`. `dt` is the wall-clock duration of this step (seconds, defaulting to `TPG.Config.captureStep`). Progress is tracked in seconds, so `capTimeNeutral`/`capTimeMax` are real seconds regardless of tickrate or step size -- the old code added a whole `balance` per step instead, which made a point flip in ~0.75s no matter what `capTimeNeutral` said. Objective overtime (`TPG.Objectives.GetOvertime`) shrinks both time thresholds toward instant, and the SHRUNK ceiling (`timeMax`, stashed as `self.EffectiveCapTimeMax`) is what `ENT:UpdateColor` divides by -- using the configured, un-shrunk `CapTimeMax` there was a real bug this file documents fixing: a fully-held point in overtime read as ~10% progress and rendered near-black. An unbalanced point tops up toward the ceiling at a flat 0.5/second when nobody is contesting it; a neutral (0-owner), empty point decays exponentially toward zero (`* 0.5^dt`, ~halves per second) rather than holding still.

CaptureStep

Whether the current carrier is still a legitimate holder: valid, a player, alive, and on a team. Used by `ENT:Think` to decide whether to drop the flag every tick -- a carrier who disconnects, dies, or gets moved to spectate all fail this the same way.

CarrierStillValid

Record (or change) `ply`'s vote for a map-vote candidate and broadcast the new tally. `mapIndex` is whatever the client's `tpg_votemap` concommand sent -- an unchecked number from the player. It is safe here only because the lookup is bounds-checked: `TPG.State.voting.maps[mapIndex]` returns nil for anything out of range and the function returns immediately, so a forged index can neither crash the server nor vote for a map that isn't a candidate. No-ops entirely while no vote is active.

CastMapVote

Index into `TPG.State.voting.maps`, 1-based.

mapIndex

Deduct a cost if the player can afford it, and notify them of the charge. Unlike `ECON.Reward`/`ECON.Penalize`, this does NOT check `ECON.Active` itself -- every current call site (dupe purchases, gear, stock vehicles) already gates the call on the economy being active, but a future caller that forgets to check `ECON.Active` first would still successfully charge the player's wallet. the player is invalid or can't afford it.

Charge

reason

True if the charge succeeded; false (no state change) if

Lives left in this item's current run, before its cooldown timer starts. An item never taken reports its full allowance rather than 0, so the menu can show "6 lives" on something untouched without special-casing it.

ChargesLeft

kind

Send a chat line to everyone on the server.

ChatBroadcast

message

color

ChatMessage

Send a chat line, at most once every `interval` seconds per player. For messages driven by an event the player can fire dozens of times in a tick: a spawn-menu click held down, a paste of thirty props refused one prop at a time. Without this the refusal is technically correct and completely unreadable, and the useful line above it is gone from the chat box. `key` is what gets rate limited, not the text, so a message whose body carries a changing count still collapses to one line per interval. Different keys never suppress each other, so an unrelated warning arriving in the same second still gets through.

ChatMessageThrottled

Groups messages that should suppress one another.

interval

Send a chat line to every player on one team.

ChatTeam

End the round if either team's ticket pool has run out. Called from the scoring `Think` after each batch of steps, and does nothing unless a round is active. Both pools can cross zero in the same tick under the deathmatch overtime bleed, so that case is resolved by whoever has the higher remaining count, and an exact tie by coin flip.

CheckWinCondition

Take an item, paying whatever this round's price is. Free items (no `TPG.Gear.Price` entry) always succeed and cost nothing, so callers can run every pick through here without checking first. Already bought this life? Then it's yours, and re-spawning to change a different slot doesn't buy it again. This is what makes the loadout menu's respawn button safe to press: it used to charge once per SPAWN, which meant tweaking your sidearm and respawning billed you a second time for the Javelin you'd bought and never fired -- and in a team-budget round it denied the Javelin outright, because the cooldown it had started ten seconds earlier was still running. `pState.gearPaidThisLife` is what fixes that; it's cleared on a real death (see the `PlayerDeath` hook below), so it only ever covers the life actually paid for. `"invalid"` for an invalid player), absent on success. the cost, so the caller can say something useful instead of "denied".

Claim

Failure reason, `"cooldown"` or `"afford"` (also

The number that goes with the reason: seconds left, or

Clamp

Remove the flag, if one exists. Safe to call in any mode.

Cleanup

Clear the map between rounds, leaving spectators' builds standing. `game.CleanUpMap` has no per-entity opt-out -- its only filter is by class, and a spectator's props are the same `prop_physics` as everyone else's -- so exempting an owner means not calling it. That is a real cost: it also restores map entities to their starting state, and a hand-rolled sweep does not. So it is still the path taken whenever no spectator owns anything, which is nearly every round; the sweep is the exception, not the rule. The sweep fires `PreCleanupMap`/`PostCleanupMap` itself, because addons (ACE and CFW among them) drop cached state on those and would otherwise be left holding references to entities that have gone.

CleanupMap

Drop a player's state table. Called from `PlayerDisconnected`, after the carryover has been stashed.

CleanupPlayer

Clear every Rush global. Called when a non-Rush round starts, so the HUD does not keep drawing last round's stage counter over a CP round.

Clear

Delete every placed point for the running map and save the empty list.

ClearPoints

Top of the compass block, in screen pixels.

CompassY

Award a stage and move on, or finish the round if that was the last one. out with nobody holding it -- which costs neither side anything.

CompleteStage

TEAM_GREEN or TEAM_RED, or nil when the stage timed

winner

The current frame's top-HUD layout, computing it once per frame and caching the result for every subsequent caller that frame (see the file comment above `TPG.UI.Layout` for why memoisation-per-frame matters here). (corner boxes), `scoreX/scoreY/scoreW/scoreH` (centre score panel, width clamped to the real screen width) and `pipY/pipSize/pipGap` (point pips).

ComputeLayout

`TPG.UI.Layout`, with `margin`, `sideW/sideY/sideH`

Black or white, whichever survives on top of the given fill. Standard luminance-weighted formula; ignores `bg.a`, so a translucent panel fill is judged as if it were opaque against whatever it actually sits on.

Contrast

`C.TextDark` on light backgrounds, `C.Text` on dark ones.

How many points are placed on the running map.

CountPoints

The point-type table entry currently selected (`{ id, label, team, tint }`).

CurrentType

Print a player's contraptions, points, mass and prop count to console. Debug aid, wired to the `tpg_debug_ace` concommand below. Reads points without forcing a refresh, so a value can look stale immediately after an edit.

DebugPlayer

The fallback a slot uses when nothing has been chosen for it.

DefaultFallback

`"Primary"`, `"Secondary"` or `"Special"`.