Level Editor/Scripting/Examples/Payload
The attackers push a cart along a track while the defenders try to run out the clock. Attackers standing at the cart move it, faster the more of them there are, and one defender at the cart stops it. Left alone, it rolls back, but never past a checkpoint it has reached. Each checkpoint adds time, and the cart reaching the end of the track wins the round. If time runs out while an attacker is on the cart, the round goes to overtime.
The map
- A Payload Track (Functional > Payload Track) from the attackers' spawn to the goal, with its Kind left at Payload. Tick Checkpoint on two or three anchors along the way. The script plays on the first track in the map, so its name does not matter.
- Spawn points for team 1 (the attackers) near the start of the track, and for team 2 (the defenders) further along it.
- A World Boundary below the map.
server.gd
extends GamemodeServerScript
const ATTACKERS := 1
const DEFENDERS := 2
## The cart stays locked while this counts down.
const SETUP_SECONDS := 30.0
## The clock once the cart unlocks, and what each checkpoint adds to it.
const ROUND_SECONDS := 600.0
const CHECKPOINT_BONUS := 180.0
## Cart speed in meters a second by how many attackers push it, the last entry
## for that many or more.
const PUSH_SPEEDS := [0.0, 1.0, 1.4, 1.7, 2.0]
## Left alone this long, the cart rolls back toward its last checkpoint.
const ROLLBACK_DELAY := 20.0
const ROLLBACK_SPEED := 0.5
## The cart's progress as the HUD reads it: thousandths of the track.
const PROGRESS_SCALE := 1000
## The track the round is played on. bot.gd reads it too.
var track: StringName = &""
var _zone: StringName = &""
var _length: float = 0.0
var _checkpoints := PackedFloat32Array()
var _next: int = 0
var _floor: float = 0.0
var _clock: float = SETUP_SECONDS
var _setup: bool = true
var _overtime: bool = false
var _attackers_on: int = 0
var _defenders_on: int = 0
var _unattended: float = 0.0
func _declare() -> void:
api.declare_team("Attackers")
api.declare_team("Defenders")
api.declare_global_counter(&"time_left", ceili(SETUP_SECONDS), 0, 3600)
api.declare_global_counter(&"setup", 1, 0, 1)
api.declare_global_counter(&"overtime", 0, 0, 1)
api.declare_global_counter(&"cart", 0, 0, PROGRESS_SCALE)
api.declare_global_counter(&"pushers", 0, 0, 32)
api.declare_global_counter(&"blocked", 0, 0, 1)
api.declare_global_counter(&"rollback", 0, 0, 1)
func _start() -> void:
var names: PackedStringArray = api.tracks()
if names.is_empty():
api.log("no payload track in this map")
return
track = StringName(names[0])
_zone = api.track_zone(track)
_length = api.track_length(track)
_checkpoints = api.track_checkpoints(track)
api.set_track_dispenser(track, ATTACKERS)
func _player_died(entity_id: int, _killer_id: int, default_seconds: float) -> void:
api.respawn_in(entity_id, default_seconds)
func _zone_tick(zone: StringName, occupants: Array, _delta: float) -> void:
if zone != _zone:
return
_attackers_on = 0
_defenders_on = 0
for entity_id in occupants:
var team: int = api.team_of(entity_id)
if team == ATTACKERS:
_attackers_on += 1
elif team == DEFENDERS:
_defenders_on += 1
func _tick(delta: float) -> void:
if track == &"":
return
if not _overtime:
_clock -= delta
api.set_global(&"time_left", maxi(ceili(_clock), 0))
if _setup:
if _clock > 0.0:
return
_setup = false
_clock += ROUND_SECONDS
api.set_global(&"setup", 0)
api.notify_all("The cart is unlocked", "Attackers push it to the end. Defenders hold it back.")
var at: float = api.track_progress(track)
if at >= _length - 0.05:
api.declare_winner(ATTACKERS, "delivered the payload")
return
while _next < _checkpoints.size() and at >= _checkpoints[_next] - 0.05:
_floor = _checkpoints[_next]
_next += 1
api.set_track_floor(track, _floor)
_clock += CHECKPOINT_BONUS
_overtime = false
api.notify_all("Checkpoint %d of %d" % [_next, _checkpoints.size()],
"+%d seconds on the clock" % int(CHECKPOINT_BONUS))
_unattended = 0.0 if _attackers_on > 0 else _unattended + delta
if _clock <= 0.0 and not _overtime:
if _attackers_on == 0:
api.declare_winner(DEFENDERS, "held the cart until time ran out")
return
_overtime = true
_clock = 0.0
api.notify_all("Overtime", "It ends when the attackers leave the cart.", true)
if _overtime and _unattended >= 0.5:
api.declare_winner(DEFENDERS, "held the cart through overtime")
return
var speed: float = 0.0
if _attackers_on > 0 and _defenders_on == 0:
speed = float(PUSH_SPEEDS[mini(_attackers_on, PUSH_SPEEDS.size() - 1)])
elif _attackers_on == 0 and _unattended >= ROLLBACK_DELAY:
speed = -ROLLBACK_SPEED
api.set_track_speed(track, speed)
api.set_global(&"overtime", 1 if _overtime else 0)
api.set_global(&"cart", roundi(maxf(at, _floor) / _length * PROGRESS_SCALE))
api.set_global(&"pushers", _attackers_on)
api.set_global(&"blocked", 1 if _attackers_on > 0 and _defenders_on > 0 else 0)
api.set_global(&"rollback", 1 if speed < 0.0 and at > _floor + 0.05 else 0)
What it uses:
- Declaring the teams makes the attackers team 1 and the defenders team 2, in the order they are declared. See Declaring teams.
- The cart carries its own zone, api.track_zone.
_zone_tickruns before_tickon every tick, so_tickalways acts on this tick's count of who is at the cart. Only living players are counted, so a body on the cart neither pushes nor blocks it. - The speed is set every tick from who is at the cart right now with api.set_track_speed, so nothing has to remember to stop the cart. Each extra pusher in
PUSH_SPEEDSadds less than the one before, so piling the whole team onto the cart leaves nobody to clear the way ahead. - Each checkpoint reached raises the cart's floor with api.set_track_floor and adds time. The checks allow 5 cm, because a cart can stop a hair short of an exact distance. The
whileloop counts two checkpoints passed in one tick as two. - Rolling back is just a negative speed. The cart stops at its floor by itself, so the rollback needs no end condition.
- Overtime keeps the round going while an attacker is on the cart, and ends half a second after the last one leaves, so stepping across the edge of the push area does not lose the round. A checkpoint reached in overtime puts time back on the clock.
- The round is decided by api.declare_winner: the attackers when the cart reaches the end, the defenders when the clock or overtime runs out.
- api.set_track_dispenser heals and resupplies the attackers pushing the cart.
- The counters are written every tick. A counter is only sent to players when its value changes, so writing the same value again costs nothing.
cartis the progress in thousandths of the track, fine enough for the HUD's bar.
client.gd
extends GamemodeClientScript
func _start() -> void:
api.show_widget(&"round_timer", {
"counter": "time_left",
"warn_at": 30,
"setup": "setup",
"overtime": "overtime",
})
var names: PackedStringArray = api.tracks()
if names.is_empty():
return
var track := StringName(names[0])
var length: float = api.track_length(track)
var checkpoints: Array = []
for distance in api.track_checkpoints(track):
checkpoints.append(distance / length)
api.show_widget(&"payload_progress", {
"counter": "cart",
"scale": api.counter_maximum(api.SCOPE_GLOBAL, &"cart"),
"checkpoints": checkpoints,
"pushers": "pushers",
"blocked": "blocked",
"rollback": "rollback",
})
The round_timer shows SETUP while setup is 1 and OVERTIME while overtime is 1. The payload_progress bar takes each checkpoint as a share of the track's length, which the client can read for itself, and reads the scale from the counter's declared maximum, so none of the server's numbers are copied here. See payload_progress.
bot.gd
extends GamemodeBotScript const REVIEW_SECONDS := 0.5 ## The defenders hold the track this many meters ahead of the cart. const POST_AHEAD := 15.0 var _review: float = 0.0 func _player_joined(entity_id: int) -> void: if api.is_bot(entity_id): api.bot_set_skill(entity_id, 0.6) func _tick(delta: float) -> void: _review -= delta if _review > 0.0 or server.track == &"": return _review = REVIEW_SECONDS var at: float = api.track_progress(server.track) var cart: Vector3 = api.track_point(server.track, at) var post: Vector3 = api.track_point(server.track, minf(at + POST_AHEAD, api.track_length(server.track))) var moving: bool = api.get_global(&"pushers") > 0 for bot in api.bots(): if not api.is_alive(bot): continue if api.team_of(bot) == server.ATTACKERS: api.bot_defend(bot, cart, 2.5) elif moving and api.bot_role(bot) == &"assault": api.bot_defend(bot, cart, 3.0) else: api.bot_defend(bot, post, 10.0)
Every half second each bot gets a post relative to the cart: the attackers on it, close enough to be in its push area, and the defenders on the track 15 meters ahead of it. While the cart is moving, the defenders with an assault kit step onto it, since one defender at the cart stops it. api.track_point turns a distance along the track into a position. The bots read the track and the attackers' team from server.gd through server, so the two scripts cannot disagree; see Reading server.gd from bot.gd.
Going further
The base game's Payload on Kraken Pier also has:
- Spawn rooms that move up. Each checkpoint hands the defenders' forward room to the attackers.
_spawn_positionpicks a spawn point inside the room the team holds now (api.zone_contains), and the room's doors change team with api.set_door_team. See Spawn rooms. - A stretch the cart rides by itself. Two track markers bound it, and
_track_markerswitches the ride on and off; see Markers. - A hazard. A zone over open water whose
_zone_enteredcalls api.kill. - Bots by kit. A support kit follows whoever is pushing with api.bot_escort, and a defense kit holds the ground the cart is about to roll into. See Skill and kits.