Level Editor/Scripting

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 outputs instead.

Guides

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

Reference: GamemodeServerScript (server hooks), GamemodeServerApi (the server api), GamemodeClientScript, GamemodeClientApi, GamemodeBotScript, and 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 (server.gd, starts with extends GamemodeServerScript): 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 api is a GamemodeServerApi. See Server rules.
• Client (client.gd, starts with extends GamemodeClientScript): 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 api is a GamemodeClientApi. See Client HUD.
• Bot (bot.gd, starts with extends GamemodeBotScript): what the bots should be doing. It runs on the server next to server.gd and works through the very same api object, so it sees exactly what the rules see. Keep the rules out of it; it is for orders. See Bots.

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

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

Where the scripts are kept

The scripts are saved in your map's folder as server.gd, client.gd and bot.gd, 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 extends 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 CapturePoint, 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 api.respawn_in, so keep a _player_died hook like the starter's unless your mode is an elimination round. See Server rules.

When things happen

On the server, for every match:

1. _declare() runs once, before anything else. Declare every counter and team here; nothing can be declared later.
2. _start() runs when the map is live. The level's supply packs are already out. Then the bot script's _start() runs.
3. When a player joins, _player_joined(entity_id) gives them a team (by default, the team with the fewest players) and the bot script's _player_joined runs; then the game places them at _spawn_position(entity_id) and they enter the match.
4. Every server tick, in this order: _track_marker for each marker a payload cart passed, the zone hooks (_zone_entered, _zone_exited, _left_world, _zone_tick), the pickup hooks (_pickup_expired, _can_collect, _pickup_collected), then _tick(delta), then the bot script's _tick(delta).
5. When a player dies, _player_died(entity_id, killer_id, default_seconds) runs. They stay dead until the script calls api.respawn_in. When they come back, _player_spawned(entity_id) runs.
6. When a player leaves, _player_left(entity_id) runs.
7. When the script calls api.declare_winner, 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 _start() runs once the server's counters have arrived, _counter_changed runs whenever a counter changes, and _match_ended(team) runs when the round is decided.

Next

• Read Server rules, then try a worked example: King of the Hill or Team Deathmatch.
• Testing a mode shows how to run your map and read what the scripts print.
• Sandbox limits lists what a map script cannot do.