Level Editor/Scripting/Examples/Training Range

From TeamSpec Wiki
Jump to navigation Jump to search

A practice map with no clock and no winner. Its targets are bots that belong to the map: two training dummies that stand and take it, a strafer that dodges about and never shoots, and a patient under fire from a shooter, for healers to keep alive. A console next to the dummies lets anybody change the dummies' weapons. Players join the Students; anybody may swap to the Faculty to spar.

The map

  • Five Map Markers (Functional > Map Marker) with their Marker Name set to Dummy 1, Dummy 2, Strafer, Patient and Shooter. Turn each dummy to face where players shoot from. Give the strafer 5 meters of open floor all round. Put the shooter a few meters from the patient, with a clear line between them.
  • A zone by the dummies: a brush with Is Zone ticked, Zone Label set to Dummy Console and Use Prompt set to Change the dummies' weapons. Leave Zone Team at 0.
  • Spawn points for team 1 and team 2.
  • A World Boundary below the map.

server.gd

extends GamemodeServerScript

const STUDENTS := 1
const FACULTY := 2
const LOADOUT := "Shotgun,Pistol,Cast Iron Pan"
## Each target: the Map Marker it stands on, its name on the scoreboard, its team
## and its drill. The patient comes before the shooter that fires at it.
const TARGETS := [
	["Dummy 1", "Training Dummy", FACULTY, &"idle"],
	["Dummy 2", "Training Dummy", FACULTY, &"idle"],
	["Strafer", "Strafer", FACULTY, &"dodge"],
	["Patient", "Patient", STUDENTS, &"idle"],
	["Shooter", "Lane Shooter", FACULTY, &"shoot"],
]
## The usable zone that changes the dummies' weapons.
const DUMMY_CONSOLE := &"Dummy Console"
const PLAYER_RESPAWN := 2.0
const TARGET_RESPAWN := 1.0
## The shooter does not refill its own ammo, so the script does, this often.
const SHOOTER_RESUPPLY := 4.0

## Marker name -> the bot standing on it.
var _bot_on: Dictionary = {}
## Targets whose bot has not taken its drill yet.
var _undrilled: Array = []
var _resupply_in: float = 0.0


func _declare() -> void:
	api.declare_team("Students")
	api.declare_team("Faculty")


func _start() -> void:
	var placed: PackedStringArray = api.markers()
	for target in TARGETS:
		if not placed.has(target[0]):
			api.log("no marker named %s; that target is left out" % target[0])
			continue
		var bot: int = api.spawn_bot(target[1], target[2], LOADOUT, api.marker(target[0]))
		if bot != 0:
			_bot_on[target[0]] = bot
			_undrilled.append(target)


## Players join the Students. Bots somebody adds to spar with go to the smaller
## team; the targets already have theirs.
func _player_joined(entity_id: int) -> void:
	if api.is_bot(entity_id):
		_assign_to_smaller_team(entity_id)
	elif api.team_of(entity_id) == 0:
		api.set_team_of(entity_id, STUDENTS)


func _player_died(entity_id: int, _killer_id: int, _default_seconds: float) -> void:
	api.respawn_in(entity_id, TARGET_RESPAWN if api.is_map_bot(entity_id) else PLAYER_RESPAWN)


func _zone_used(zone: StringName, entity_id: int) -> void:
	if api.zone_label(zone) != DUMMY_CONSOLE:
		return
	var dummies: Array = []
	for mark in ["Dummy 1", "Dummy 2"]:
		if _bot_on.has(mark):
			dummies.append(_bot_on[mark])
	if not dummies.is_empty():
		api.edit_bot_loadout(entity_id, dummies, true)


func _tick(delta: float) -> void:
	# A new bot cannot take an order the moment it is made: try again every tick
	# until it does. A drill lasts through every death, so each is given once.
	for i in range(_undrilled.size() - 1, -1, -1):
		if _drill(_undrilled[i]):
			_undrilled.remove_at(i)
	_resupply_in -= delta
	if _resupply_in <= 0.0 and _bot_on.has("Shooter"):
		_resupply_in = SHOOTER_RESUPPLY
		api.resupply(_bot_on["Shooter"])


func _drill(target: Array) -> bool:
	var mark: String = target[0]
	var bot: int = _bot_on[mark]
	match target[3]:
		&"dodge":
			return api.bot_dodge(bot, api.marker(mark), 4.5)
		&"shoot":
			return api.bot_shoot(bot, _bot_on.get("Patient", 0))
	return api.bot_idle(bot, api.marker(mark) + api.marker_facing(mark) * 10.0)

What it uses:

  • api.spawn_bot puts a bot of the map's own on each marker, from _start. It names the bot on the scoreboard, puts it on a team, gives it a loadout (items by slot, slot 1 first) and brings it back to the same spot every time it spawns. The map's own bots take no player's seat, nobody can kick them, and they are not in api.bots. See The map's own bots.
  • The drills are api.bot_idle, api.bot_dodge and api.bot_shoot. Each returns false until the new bot is ready to take it, so _tick tries again every tick until it is taken. A drill lasts through every death, so each target is drilled once.
  • A shooter does not refill its own ammo, so the script does it every few seconds with api.resupply.
  • api.marker and api.marker_facing place and aim the targets, so moving a marker in the editor moves its target without touching the script. A missing marker is named in the log and its target left out, so a half-built range still runs.
  • _player_joined puts players on the Students and any bots somebody adds on the smaller team. The targets' teams are set by spawn_bot before this hook runs. See Putting players on teams.
  • api.is_map_bot gives the targets a shorter respawn than the players.
  • Pressing the use key in the console calls _zone_used, which opens the loadout editor on the dummies with api.edit_bot_loadout. Passing true changes only their weapons, and the permission lasts while the player stands in the zone.
  • Nothing calls declare_winner, so the match never ends.

client.gd

extends GamemodeClientScript

A range keeps no score and runs no clock, so there is nothing to put on the HUD. Leave only the extends line: an empty pane is replaced by the starter script when you export.

bot.gd

No bot script is needed. The starter bot script sends every bot in api.bots() roaming, which is right for bots somebody adds to spar with, and the map's own bots are never in that list, so their drills are left alone.

Going further

The base game's Training Range on Academy also has:

  • Strafers of three builds, slim to heavy, so each has a different sized hitbox: the last argument of spawn_bot spreads the spec points the loadout leaves free.
  • A building range: a console opens a grid plan with api.open_tile_map, and _form_submitted puts up sentries and dispensers with api.place_building and switches cover on and off with api.set_part_enabled. See Tile maps.
  • A practice cart that goes back to the start a few seconds after it is delivered, and a practice boss that _entity_died brings back with api.revive_boss.
  • A spawn room with no team, which serves both.
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