Level Editor/Scripting/Examples/Payload

From TeamSpec Wiki
Jump to navigation Jump to search

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_tick runs before _tick on every tick, so _tick always 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_SPEEDS adds 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 while loop 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. cart is 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_position picks 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_marker switches the ride on and off; see Markers.
  • A hazard. A zone over open water whose _zone_entered calls 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.
TeamSpec Level Editor
Basics Getting started · Interface · Viewport and camera · Selecting and hiding · Keyboard shortcuts · Settings · Map Config · Troubleshooting
Menus File · Edit · View · Tools · Functional
Panels Scene tree · Inspector · Materials · Props · Snapping · UV editor · Displacement · Terrain
Tools Move, Rotate and Scale · Box · Sphere · Cylinder · Prism · Stairs · Spiral Stairs · Spiral Tower · Arch · Path Brush · Plane · Terrain · Clip · Duplicate · Ruler and Cordon · Edit Vertex and Edge · Edit Face · Loop Cut · Material Brush · Vertex Color Brush · Displacement · Prop Path
Entities Brush · Zone · Group · Mirror Node · Prop · Spawn Point · Supply Pickup · World Boundary · Lights · Fog Volume · Water · Sounds · Anchor Platform · Payload Track · Boss Spawn · Map Marker · World Text · Decal · Door · Button · Logic entities · 3D Skybox · Nav Region
Workflows Your first map · Brushes and CSG · Materials and UVs · Lighting and lightmaps · Bots and navigation · Mirrored maps · Outputs and logic · Custom assets · Playtesting · Exporting and publishing · Importing Source maps
Scripting Overview · Server rules · Client HUD · Bots · Teams and spawning · Zones · Pickups · Payload tracks · Map entities · Language · Sandbox limits · Testing · King of the Hill · Team Deathmatch · Payload · Conquer · Soul Banking · Service · Training Range · API reference · What a script may use