TeamSpecBot: Level Editor: scripting a gamemode overview

2026-10-20T03:46:19Z

Level Editor: scripting a gamemode overview

New page

A map's '''gamemode''' is its rules, its HUD and what its bots do. It is up to three small GDScript files that belong to your map. You write them inside the editor: click '''Map Config''' in the top bar, open the '''Gamemode''' tab, and pick '''Server''', '''Client''' or '''Bot'''. The '''Scripting Docs''' button there opens the guide for the tab you are on.

Many maps need no scripting at all beyond the starter scripts: doors, buttons, relays, timers and counters can be wired up with [[Level Editor/Workflows/Outputs and logic|outputs]] instead.

== Guides ==
{| class="wikitable"
! Page !! Covers
|-
| [[Level Editor/Scripting/Server rules|Server rules]] || <code>server.gd</code>: counters, deaths and respawns, winning, messages, acting on players.
|-
| [[Level Editor/Scripting/Client HUD|Client HUD]] || <code>client.gd</code>: reading counters and the HUD widgets.
|-
| [[Level Editor/Scripting/Bots|Bots]] || <code>bot.gd</code>: giving bots their jobs.
|-
| [[Level Editor/Scripting/Teams and spawning|Teams and spawning]] || Declaring teams, choosing players' teams, spawn points and spawn rooms.
|-
| [[Level Editor/Scripting/Zones|Zones]] || Zone hooks, names and labels, the world boundary.
|-
| [[Level Editor/Scripting/Pickups|Pickups]] || Supply stations and dropping pickups from a script.
|-
| [[Level Editor/Scripting/Payload tracks|Payload tracks]] || Driving the cart, markers, the push zone and dispenser.
|-
| [[Level Editor/Scripting/Map entities|Map entities]] || Doors, logic, markers, switchable parts, bosses, buildings and map bots.
|-
| [[Level Editor/Scripting/Sandbox limits|Sandbox limits]] || What a map script cannot do.
|-
| [[Level Editor/Scripting/Testing|Testing a mode]] || Running the map and reading what scripts print.
|-
| Examples || [[Level Editor/Scripting/Examples/King of the Hill|King of the Hill]], [[Level Editor/Scripting/Examples/Team Deathmatch|Team Deathmatch]].
|}

'''Reference:''' [[Level Editor/Scripting/Reference/GamemodeServerScript|GamemodeServerScript]] (server hooks), [[Level Editor/Scripting/Reference/GamemodeServerApi|GamemodeServerApi]] (the server <code>api</code>), [[Level Editor/Scripting/Reference/GamemodeClientScript|GamemodeClientScript]], [[Level Editor/Scripting/Reference/GamemodeClientApi|GamemodeClientApi]], [[Level Editor/Scripting/Reference/GamemodeBotScript|GamemodeBotScript]], and [[Level Editor/Scripting/Reference/Sandbox|what a script may use]]. The reference comes from the same description the script editor's autocomplete uses, so every signature on it is the one the game expects.

== The three scripts ==

* '''Server''' (<code>server.gd</code>, starts with <code>extends GamemodeServerScript</code>): the rules. It runs only on the server and it is the only script that can change the match: counters, teams, respawns, pickups and the winner. Its <code>api</code> is a [[Level Editor/Scripting/Reference/GamemodeServerApi|GamemodeServerApi]]. See [[Level Editor/Scripting/Server rules|Server rules]].
* '''Client''' (<code>client.gd</code>, starts with <code>extends GamemodeClientScript</code>): the HUD. It runs on every player's machine and can only read. It puts widgets on screen that show the counters the server keeps. Its <code>api</code> is a [[Level Editor/Scripting/Reference/GamemodeClientApi|GamemodeClientApi]]. See [[Level Editor/Scripting/Client HUD|Client HUD]].
* '''Bot''' (<code>bot.gd</code>, starts with <code>extends GamemodeBotScript</code>): what the bots should be doing. It runs on the server next to <code>server.gd</code> and works through the very same <code>api</code> object, so it sees exactly what the rules see. Keep the rules out of it; it is for orders. See [[Level Editor/Scripting/Bots|Bots]].

Each pane completes as you type against its own API: type <code>api.</code> to see everything that script may call, and {{Key|Ctrl}}+click a name to read its documentation. A client pane never offers a server call.

Your code overrides '''hooks''': functions such as <code>_tick</code> or <code>_player_died</code> that the game calls at the right moment. Override only the ones you need. Every hook and every <code>api</code> call is listed in the reference pages above.

== Where the scripts are kept ==

The scripts are saved in your map's folder as <code>server.gd</code>, <code>client.gd</code> and <code>bot.gd</code>, and they go into the map whenever you export it or run it.

* '''An empty pane is replaced by the starter script''' when you export or run. To have a script that does nothing, leave only its <code>extends</code> line.
* '''Reset to Default''' under each pane puts the starter script back (after asking).
* If you edit a script file in another program while the editor has unsaved edits to it, the editor asks which version to keep (''Script Changed on Disk'').

== The starter scripts ==

A new map starts with a small working mode: the server script scores a point for your team each time you walk into a zone named <code>CapturePoint</code>, declares a winner at 10, and brings the dead back on their normal timer; the client script shows the team score; and the bot script sets every bot's skill to 0.6 and sends every bot roaming.

A player who dies stays dead until a script calls [[Level Editor/Scripting/Reference/GamemodeServerApi#respawn_in|api.respawn_in]], so keep a <code>_player_died</code> hook like the starter's unless your mode is an elimination round. See [[Level Editor/Scripting/Server rules#Deaths and respawns|Server rules]].

== When things happen ==

On the server, for every match:

# <code>_declare()</code> runs once, before anything else. Declare every counter and team here; nothing can be declared later.
# <code>_start()</code> runs when the map is live. The level's supply packs are already out. Then the bot script's <code>_start()</code> runs.
# When a player joins, <code>_player_joined(entity_id)</code> gives them a team (by default, the team with the fewest players) and the bot script's <code>_player_joined</code> runs; then the game places them at <code>_spawn_position(entity_id)</code> and they enter the match.
# Every server tick, in this order: <code>_track_marker</code> for each marker a payload cart passed, the zone hooks (<code>_zone_entered</code>, <code>_zone_exited</code>, <code>_left_world</code>, <code>_zone_tick</code>), the pickup hooks (<code>_pickup_expired</code>, <code>_can_collect</code>, <code>_pickup_collected</code>), then <code>_tick(delta)</code>, then the bot script's <code>_tick(delta)</code>.
# When a player dies, <code>_player_died(entity_id, killer_id, default_seconds)</code> runs. They stay dead until the script calls <code>api.respawn_in</code>. When they come back, <code>_player_spawned(entity_id)</code> runs.
# When a player leaves, <code>_player_left(entity_id)</code> runs.
# When the script calls <code>api.declare_winner</code>, the round is decided. The game shows the result and players vote for the next map. From then on no zone, pickup or tick hook runs and deaths are no longer reported to the script.

On every player's machine, the client script's <code>_start()</code> runs once the server's counters have arrived, <code>_counter_changed</code> runs whenever a counter changes, and <code>_match_ended(team)</code> runs when the round is decided.

== Next ==

* Read [[Level Editor/Scripting/Server rules|Server rules]], then try a worked example: [[Level Editor/Scripting/Examples/King of the Hill|King of the Hill]] or [[Level Editor/Scripting/Examples/Team Deathmatch|Team Deathmatch]].
* [[Level Editor/Scripting/Testing|Testing a mode]] shows how to run your map and read what the scripts print.
* [[Level Editor/Scripting/Sandbox limits|Sandbox limits]] lists what a map script cannot do.

{{Level Editor nav}}

[[Category:Level Editor]]
[[Category:Gamemode scripting]]

Level Editor/Scripting - Revision history

TeamSpecBot: Level Editor: scripting a gamemode overview