Level Editor/Scripting/Examples/Conquer

From TeamSpec Wiki
Jump to navigation Jump to search

A glowing area starts in the middle of a long lane. When the living players standing in it are all from one team, it moves away from that team's spawn, faster the more of them there are; with both teams in it, or nobody, it stays where it is. Pushing it all the way into the enemy's spawn wins. When the clock runs out, the team that has the area on the enemy's half wins, and an area still in the middle is a draw.

The map

  • A Payload Track (Functional > Payload Track) with its Kind set to Conquer. Lay it straight from team 1's spawn (its first anchor) to team 2's (its last), and set the Marker of the anchor in the middle to start: the area starts there, and the script splits the two halves there. Area Width, Area Height and Area Depth size the area; make it as wide as the lane.
  • Spawn points for team 1 at the start of the lane, and for team 2 at its end.
  • A spawn room door for each team (Functional > Door (from Selection)), named Team1Door and Team2Door in the scene tree. Tick Starts Locked, set Team to the door's team and tick Team Only.
  • A World Boundary below the map.

server.gd

extends GamemodeServerScript

## The area stays locked, and the spawn doors shut, while this counts down.
const SETUP_SECONDS := 20.0
const ROUND_SECONDS := 600.0
## Area speed in meters a second by how many players of one team stand in it, the
## last entry for that many or more.
const PUSH_SPEEDS := [0.0, 1.0, 1.3, 1.55, 1.75]
## The area's position as the HUD reads it: thousandths of the lane.
const PROGRESS_SCALE := 1000
## The spawn room doors, which the map starts locked.
const SPAWN_DOORS := [&"Team1Door", &"Team2Door"]

## The lane the round is played on. bot.gd reads it too.
var lane: StringName = &""
var _zone: StringName = &""
var _length: float = 0.0
var _middle: float = 0.0
var _clock: float = SETUP_SECONDS
var _setup: bool = true
## Living players in the area this tick, by team: [nobody, team 1, team 2].
var _on: Array[int] = [0, 0, 0]


func _declare() -> void:
	api.declare_global_counter(&"time_left", ceili(SETUP_SECONDS), 0, 3600)
	api.declare_global_counter(&"setup", 1, 0, 1)
	api.declare_global_counter(&"area_progress", PROGRESS_SCALE / 2, 0, PROGRESS_SCALE)
	# The area's glow colors itself from these two, by these names.
	api.declare_global_counter(&"area_team", 0, 0, 2)
	api.declare_global_counter(&"area_contested", 0, 0, 1)
	api.declare_global_counter(&"area_pushers", 0, 0, 64)


func _start() -> void:
	var names: PackedStringArray = api.tracks()
	if names.is_empty():
		api.log("no conquer lane in this map")
		return
	lane = StringName(names[0])
	_zone = api.track_zone(lane)
	_length = api.track_length(lane)
	_middle = api.track_marker(lane, &"start")
	if _middle < 0.0:
		api.log("the lane has no anchor marked start")


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
	_on[1] = 0
	_on[2] = 0
	for entity_id in occupants:
		var team: int = api.team_of(entity_id)
		if team == 1 or team == 2:
			_on[team] += 1


func _tick(delta: float) -> void:
	if lane == &"":
		return
	_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)
		for door in SPAWN_DOORS:
			api.door_unlock(door)
		api.notify_all("The area is unlocked", "Stand in it to push it toward the enemy spawn.")

	var at: float = api.track_progress(lane)
	if at >= _length - 0.05:
		api.declare_winner(1, "pushed the area into the enemy spawn")
		return
	if at <= 0.05:
		api.declare_winner(2, "pushed the area into the enemy spawn")
		return
	if _clock <= 0.0:
		_time_up(at)
		return

	var pushing: int = 0
	if _on[1] > 0 and _on[2] == 0:
		pushing = 1
	elif _on[2] > 0 and _on[1] == 0:
		pushing = 2
	var speed: float = 0.0
	if pushing != 0:
		speed = float(PUSH_SPEEDS[mini(_on[pushing], PUSH_SPEEDS.size() - 1)])
	# Team 1 pushes toward the lane's end, team 2 back toward its start.
	api.set_track_speed(lane, speed if pushing == 1 else -speed)
	api.set_global(&"area_progress", roundi(at / _length * PROGRESS_SCALE))
	api.set_global(&"area_team", pushing)
	api.set_global(&"area_pushers", _on[pushing] if pushing != 0 else 0)
	api.set_global(&"area_contested", 1 if _on[1] > 0 and _on[2] > 0 else 0)


## Time is up: the team whose enemy's half the area stands on wins.
func _time_up(at: float) -> void:
	api.set_track_speed(lane, 0.0)
	if at > _middle + 0.05:
		api.declare_winner(1, "held the area on the enemy's half")
	elif at < _middle - 0.05:
		api.declare_winner(2, "held the area on the enemy's half")
	else:
		api.declare_winner(0, "the area never left the middle")

What it uses:

  • A conquer lane is driven exactly like a payload track (see Payload tracks): api.track_progress is how far the area is from team 1's end, and its push zone is api.track_zone. A positive speed moves the area toward team 2's spawn and a negative one back toward team 1's. A lane has no checkpoints, and nothing here rolls the area back.
  • api.track_marker reads the start anchor's distance once, in _start, to tell the halves apart when time runs out.
  • The glow on the floor colors itself from two global counters, by these names: area_team (the team pushing, 0 for nobody) and area_contested (1 while both teams stand in it). Declare them with these names and keep them current, and the area shows the pushing team's color and pulses while it is contested.
  • _on is an Array[int] indexed by team, so _on[pushing] is the number of pushers without an if per team.
  • The spawn doors start locked in the editor; the script only unlocks them when setup ends, with api.door_unlock. See Doors.
  • api.declare_winner with team 0 is a draw.

client.gd

extends GamemodeClientScript


func _start() -> void:
	api.show_widget(&"round_timer", {
		"counter": "time_left",
		"warn_at": 30,
		"setup": "setup",
	})
	api.show_widget(&"conquer_progress", {
		"counter": "area_progress",
		"scale": api.counter_maximum(api.SCOPE_GLOBAL, &"area_progress"),
		"team": "area_team",
		"pushers": "area_pushers",
		"contested": "area_contested",
	})

The conquer_progress bar has team 1's end on the left and team 2's on the right, and says which team is pushing, how many, or that the area is contested. See conquer_progress.

bot.gd

extends GamemodeBotScript

const REVIEW_SECONDS := 0.5
## Bots in the area spread across the lane, this many meters apart, so one
## explosion does not clear them all.
const SPACING := 5.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.lane == &"":
		return
	_review = REVIEW_SECONDS
	var at: float = api.track_progress(server.lane)
	var area: Vector3 = api.track_point(server.lane, at)
	var length: float = api.track_length(server.lane)
	var along: Vector3 = api.track_point(server.lane, minf(at + 1.0, length)) \
		- api.track_point(server.lane, maxf(at - 1.0, 0.0))
	var across: Vector3 = along.cross(Vector3.UP).normalized()
	var spots: Array[int] = [0, 0, 0]
	for bot in api.bots():
		var team: int = api.team_of(bot)
		if not api.is_alive(bot) or team < 1 or team > 2:
			continue
		if api.bot_role(bot) == &"sniper":
			api.bot_roam(bot)
			continue
		# Spots 0, 1, -1, 2, -2: the middle of the lane first, then either side.
		var spot: int = spots[team]
		spots[team] += 1
		var offset: float = SPACING * float((spot + 1) / 2) * (1.0 if spot % 2 == 1 else -1.0)
		api.bot_defend(bot, area + across * offset, 3.0)

Standing in the area is the whole game, so every bot except the snipers is posted in it, every half second as it moves. The bots of a team spread across the lane, 5 meters apart, rather than standing on its line where one explosion would clear them. The direction across the lane is the direction along it, from two api.track_point calls, crossed with up. api.bots is sorted, so each bot keeps the same spot from one review to the next.

Going further

The base game's Conquer on Centralia also has:

  • Overtime. When time runs out while the trailing team has somebody in the area, the round goes on until they leave it. The Payload example shows the pattern, and the round_timer's overtime setting shows it on the HUD.
  • A draw only for an area nobody ever pushed. An area pushed away and back to the middle goes to overtime instead.
  • Spawn rooms with immunity, class changes and a refill (see Spawn rooms), and sinkholes: zones whose _zone_entered calls api.kill.
  • Bots by kit. A support kit follows a teammate in the area with api.bot_escort, and when its team is ahead a defense kit holds the ground beyond the area that the enemy comes from.
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