TeamSpecBot: Scripting reference: GamemodeServerScript

2026-10-20T03:48:31Z

Scripting reference: GamemodeServerScript

New page

The base class of <code>server.gd</code>: the script starts with <code>extends GamemodeServerScript</code>.

The base class of a map's <code>server.gd</code>: the rules of its gamemode.

Override the hooks your mode needs and leave the rest; each one already does something sensible. Everything the script can do goes through <code>api</code>.

This script runs only on the server, so it is the one place that can change the match: counters, teams, respawns, pickups and the winner.

See [[Level Editor/Scripting/Reference]] for every class, and [[Level Editor/Scripting/Reference/Sandbox]] for the rest of GDScript a script may use.

__TOC__

== Properties ==

=== api ===
{{API member
|name=api
|kind=Property
|signature=api: GamemodeServerApi
|scripts=<code>server.gd</code>
|description=Everything this script can do goes through <code>api</code>. See [[Level Editor/Scripting/Reference/GamemodeServerApi|GamemodeServerApi]].

Everything this script can do, as a <code>GamemodeServerApi</code>.
}}

== Hooks ==

=== _declare ===
{{API member
|name=_declare
|kind=Hook
|signature=_declare() -> void
|scripts=<code>server.gd</code>
|returns=<code>void</code>
|description=Declare every counter and team the mode uses. Runs once, before anything else, and is the only place declarations work.
}}

=== _start ===
{{API member
|name=_start
|kind=Hook
|signature=_start() -> void
|scripts=<code>server.gd</code>
|returns=<code>void</code>
|description=The map is live. Set up the round here. The level's supply packs are already out.
}}

=== _player_joined ===
{{API member
|name=_player_joined
|kind=Hook
|signature=_player_joined(entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A player joined. Give them a team here with <code>api.set_team_of</code>; the default puts them on the smallest team. Once this returns, the game places them at <code>_spawn_position</code>. Their first spawn is observed here: <code>_player_spawned</code> runs only when they come back after dying.
}}

=== _assign_to_smaller_team ===
{{API member
|name=_assign_to_smaller_team
|kind=Hook
|signature=_assign_to_smaller_team(entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=Puts the player with their Steam party when it is already playing and its team has room, otherwise on whichever declared team has the fewest players, the lowest team on a tie. A player who already has a team is left where they are. Call it from your own <code>_player_joined</code> to keep the default for some players.
}}

=== _can_join_team ===
{{API member
|name=_can_join_team
|kind=Hook
|signature=_can_join_team(_entity_id: int, _team: int) -> bool
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
* <code>team</code>: <code>int</code>
|returns=<code>bool</code>
|description=May this player change to this team? Return false to refuse. Asked only after the game has checked that the team exists and is not full. The default allows everything.

Not asked when a player leaves to spectate: that is always allowed.
}}

=== _player_spawned ===
{{API member
|name=_player_spawned
|kind=Hook
|signature=_player_spawned(_entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A player came back to life after dying, at the position <code>_spawn_position</code> chose. Not called for the first spawn after joining; that is <code>_player_joined</code>.
}}

=== _player_died ===
{{API member
|name=_player_died
|kind=Hook
|signature=_player_died(_entity_id: int, _killer_id: int, _default_seconds: float) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
* <code>killer_id</code>: <code>int</code>
* <code>default_seconds</code>: <code>float</code>
|returns=<code>void</code>
|description=A player died. They stay dead until you call <code>api.respawn_in</code>: pass <code>default_seconds</code>, the player's normal respawn time, or a different number, or nothing at all for an elimination round.

<code>killer_id</code> is the player who gets the kill, or -1 when nobody earned it. <code>api.death_position()</code> is where they died.
}}

=== _player_left ===
{{API member
|name=_player_left
|kind=Hook
|signature=_player_left(_entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A player left the match for good. Forget anything you kept about them.
}}

=== _spawn_position ===
{{API member
|name=_spawn_position
|kind=Hook
|signature=_spawn_position(entity_id: int) -> Vector3
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
|returns=<code>Vector3</code>
|description=Where this player should appear, on joining and on every respawn. The default picks one of their team's spawn points at random.

Runs while the player is being placed, apart from the other hooks: only read through <code>api</code> here, change nothing, and always return a position.
}}

=== _zone_entered ===
{{API member
|name=_zone_entered
|kind=Hook
|signature=_zone_entered(_zone: StringName, _entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>zone</code>: <code>StringName</code>
* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A living player walked into a zone. Compare <code>api.zone_label(zone)</code> with the name you gave it in the editor.
}}

=== _zone_exited ===
{{API member
|name=_zone_exited
|kind=Hook
|signature=_zone_exited(_zone: StringName, _entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>zone</code>: <code>StringName</code>
* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A player is no longer in a zone: they walked out, died or left the match. Do not assume they are alive somewhere else.
}}

=== _zone_used ===
{{API member
|name=_zone_used
|kind=Hook
|signature=_zone_used(_zone: StringName, _entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>zone</code>: <code>StringName</code>
* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A player standing in a usable zone pressed the use key. A zone is usable when its Area Trigger has a Use Prompt, which the HUD shows to anyone inside it.
}}

=== _form_submitted ===
{{API member
|name=_form_submitted
|kind=Hook
|signature=_form_submitted(_entity_id: int, _form: StringName, _values: PackedInt32Array) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
* <code>form</code>: <code>StringName</code>
* <code>values</code>: <code>PackedInt32Array</code>
|returns=<code>void</code>
|description=A player applied a tile map you opened on them with <code>api.open_tile_map</code>. <code>form</code> is the name you gave it, and <code>values</code> holds one option index per tile, in the order you sent them. The game has already checked that the answer fits the map you sent, but a player can apply the same map again, so make applying it twice harmless.
}}

=== _left_world ===
{{API member
|name=_left_world
|kind=Hook
|signature=_left_world(entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A player fell out of the world: they went below the map's World Boundary. The default kills them, with nobody credited. Override it to do something else, such as putting them back.
}}

=== _zone_tick ===
{{API member
|name=_zone_tick
|kind=Hook
|signature=_zone_tick(_zone: StringName, _occupants: Array, _delta: float) -> void
|scripts=<code>server.gd</code>
|params=* <code>zone</code>: <code>StringName</code>
* <code>occupants</code>: <code>Array</code>
* <code>delta</code>: <code>float</code>
|returns=<code>void</code>
|description=Every server tick, for every zone, including empty ones, so a capture meter can drain when nobody is on the point. <code>occupants</code> are the living players inside, sorted. <code>delta</code> is the seconds since the last tick.
}}

=== _track_marker ===
{{API member
|name=_track_marker
|kind=Hook
|signature=_track_marker(_track: StringName, _marker: StringName, _forward: bool) -> void
|scripts=<code>server.gd</code>
|params=* <code>track</code>: <code>StringName</code>
* <code>marker</code>: <code>StringName</code>
* <code>forward</code>: <code>bool</code>
|returns=<code>void</code>
|description=The cart on <code>track</code> passed one of its markers (see <code>api.track_markers</code>). <code>forward</code> is true when it reached the marker going forward, and false when it rolled back past it. A cart standing exactly on a marker has reached it. Several markers passed in one tick arrive in the order the cart passed them. Called before <code>_tick</code>, so <code>_tick</code> already sees what you set here. A marker the cart starts the round on or behind is not passed.
}}

=== _can_collect ===
{{API member
|name=_can_collect
|kind=Hook
|signature=_can_collect(_handle: int, _entity_id: int) -> bool
|scripts=<code>server.gd</code>
|params=* <code>handle</code>: <code>int</code>
* <code>entity_id</code>: <code>int</code>
|returns=<code>bool</code>
|description=May this player take this pickup? Return false to refuse. Asked when they come close enough, and again when it reaches them. The default lets anybody take anything.
}}

=== _pickup_collected ===
{{API member
|name=_pickup_collected
|kind=Hook
|signature=_pickup_collected(_handle: int, _entity_id: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>handle</code>: <code>int</code>
* <code>entity_id</code>: <code>int</code>
|returns=<code>void</code>
|description=A player took a pickup. The handle still answers <code>api.pickup_kind</code>, <code>api.pickup_team</code> and <code>api.pickup_position</code> during this hook; afterwards it is gone. Health and ammo packs refill the player by themselves.
}}

=== _pickup_expired ===
{{API member
|name=_pickup_expired
|kind=Hook
|signature=_pickup_expired(_handle: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>handle</code>: <code>int</code>
|returns=<code>void</code>
|description=A pickup ran out of lifetime and vanished untaken.
}}

=== _entity_damaged ===
{{API member
|name=_entity_damaged
|kind=Hook
|signature=_entity_damaged(_entity: int, _amount: float, _attacker: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity</code>: <code>int</code>
* <code>amount</code>: <code>float</code>
* <code>attacker</code>: <code>int</code>
|returns=<code>void</code>
|description=A boss took damage. <code>entity</code> is its entity id (see <code>api.bosses</code>), <code>amount</code> the health it lost, and <code>attacker</code> the player who dealt it, or -1 for nobody. <code>api.entity_health</code> already reads what it has left.
}}

=== _entity_died ===
{{API member
|name=_entity_died
|kind=Hook
|signature=_entity_died(_entity: int, _killer: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity</code>: <code>int</code>
* <code>killer</code>: <code>int</code>
|returns=<code>void</code>
|description=A boss died. <code>killer</code> is the player who landed the last blow, or -1 for nobody. It sinks into its pool and stays dead; what that means for the match, killing the enemy's boss wins, say, is the mode's to decide.
}}

=== _door_changed ===
{{API member
|name=_door_changed
|kind=Hook
|signature=_door_changed(_door: StringName, _state: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>door</code>: <code>StringName</code>
* <code>state</code>: <code>int</code>
|returns=<code>void</code>
|description=A door moved to a new state: <code>api.DOOR_OPENING</code> when it starts to open, <code>api.DOOR_OPEN</code> once it is open, <code>api.DOOR_CLOSING</code> and <code>api.DOOR_CLOSED</code> the same way back. Whoever moved it, a player walking up, its own wait running out, or this script, the hook is the same.
}}

=== _logic_event ===
{{API member
|name=_logic_event
|kind=Hook
|signature=_logic_event(_entity: StringName, _event: StringName, _activator: int) -> void
|scripts=<code>server.gd</code>
|params=* <code>entity</code>: <code>StringName</code>
* <code>event</code>: <code>StringName</code>
* <code>activator</code>: <code>int</code>
|returns=<code>void</code>
|description=A logic entity the map places (a relay, timer, counter or button, by its name in the level editor) raised <code>event</code>: "OnTrigger", "OnTimer", "OutValue", "OnHitMin", "OnHitMax", "OnPressed" or "OnUseLocked". <code>activator</code> is the player who set it off, 0 for nobody. Its outputs fire whatever this does; this is where a mode reacts to a button press or a counter filling up.
}}

=== _tick ===
{{API member
|name=_tick
|kind=Hook
|signature=_tick(_delta: float) -> void
|scripts=<code>server.gd</code>
|params=* <code>delta</code>: <code>float</code>
|returns=<code>void</code>
|description=Every server tick, after the zone and pickup hooks. <code>delta</code> is the seconds since the last tick. Timers and win checks go here. Stops once a winner is declared.
}}

[[Category:Gamemode scripting]]
[[Category:Scripting reference]]

{{Level Editor nav}}

Level Editor/Scripting/Reference/GamemodeServerScript - Revision history

TeamSpecBot: Scripting reference: GamemodeServerScript