Level Editor/Scripting/Examples/Soul Banking

From TeamSpec Wiki
Jump to navigation Jump to search

Kill someone and their souls fall to the floor. Enemies pick them up, up to five at a time, and carry them home to their team's deposit zone to bank them. Standing on the enemy's deposit zone takes their banked souls back out, one a second. The first team to hold a full bank of 100 for three seconds wins, so a last-second robbery can still save the round.

The map

  • Two zones labeled Deposit Zone, one in each base: a brush with Is Zone ticked, Zone Label set to Deposit Zone and Zone Team set to 1 for one and 2 for the other.
  • Spawn points for team 1 and team 2.
  • A World Boundary below the map.

server.gd

extends GamemodeServerScript

## How many souls a player can carry, and how many a full bank holds.
const CARRY_CAP := 5
const BANK_CAPACITY := 100
## A full bank has to stay full this long to win.
const HOLD_SECONDS := 3.0
## Standing on the enemy's deposit zone takes a soul out of their bank this often.
const STEAL_SECONDS := 1.0
const DEPOSIT_ZONE := &"Deposit Zone"

## entity id -> seconds on the enemy's deposit zone toward the next soul.
var _stealing: Dictionary = {}
## team -> seconds its bank has been full.
var _full_for: Dictionary = {}


func _declare() -> void:
	api.declare_player_counter(&"souls_carried", 0, 0, CARRY_CAP)
	api.declare_team_counter(&"bank", 0, 0, BANK_CAPACITY)


func _start() -> void:
	if api.zones_labeled(DEPOSIT_ZONE).is_empty():
		api.log("no zone labeled Deposit Zone in this map")


func _player_died(entity_id: int, _killer_id: int, default_seconds: float) -> void:
	# What they carried, and one soul of their own, fall where they died.
	var dropped: int = api.get_player(entity_id, &"souls_carried") + 1
	api.set_player(entity_id, &"souls_carried", 0)
	api.scatter_pickups(&"soul", api.death_position(), dropped, 1.2, api.team_of(entity_id), 30.0)
	api.respawn_in(entity_id, default_seconds)


## Whether this player may take this soul: only an enemy's, and only with room
## to carry it. bot.gd asks this too.
func may_take(handle: int, entity_id: int) -> bool:
	return api.pickup_team(handle) != api.team_of(entity_id) \
		and api.get_player(entity_id, &"souls_carried") < CARRY_CAP


func _can_collect(handle: int, entity_id: int) -> bool:
	if api.pickup_kind(handle) != &"soul":
		return true
	return may_take(handle, entity_id)


func _pickup_collected(handle: int, entity_id: int) -> void:
	if api.pickup_kind(handle) == &"soul":
		api.add_player(entity_id, &"souls_carried", 1)


func _zone_exited(zone: StringName, entity_id: int) -> void:
	if api.zone_label(zone) == DEPOSIT_ZONE:
		_stealing.erase(entity_id)


func _zone_tick(zone: StringName, occupants: Array, delta: float) -> void:
	if api.zone_label(zone) != DEPOSIT_ZONE or api.zone_team(zone) == 0:
		return
	var team: int = api.zone_team(zone)
	for entity_id in occupants:
		if api.team_of(entity_id) != team:
			_steal(entity_id, team, delta)
			continue
		var carried: int = api.get_player(entity_id, &"souls_carried")
		if carried > 0:
			# Bank what fits; whatever does not stays in their hands.
			var moved: int = api.transfer_team(team, &"bank", carried)
			api.add_player(entity_id, &"souls_carried", -moved)


func _steal(entity_id: int, victim: int, delta: float) -> void:
	var seconds: float = minf(_stealing.get(entity_id, 0.0) + delta, STEAL_SECONDS)
	if seconds >= STEAL_SECONDS and api.get_team(victim, &"bank") > 0 \
			and api.get_player(entity_id, &"souls_carried") < CARRY_CAP:
		seconds = 0.0
		api.add_team(victim, &"bank", -1)
		api.add_player(entity_id, &"souls_carried", 1)
	_stealing[entity_id] = seconds


func _tick(delta: float) -> void:
	for team in api.teams():
		if api.get_team(team, &"bank") < BANK_CAPACITY:
			_full_for[team] = 0.0
			continue
		var held: float = _full_for.get(team, 0.0) + delta
		_full_for[team] = held
		if held >= HOLD_SECONDS:
			api.declare_winner(team, "held a full bank for %d seconds" % int(HOLD_SECONDS))
			return

What it uses:

  • souls_carried is a player counter with a maximum of 5. Every write is held between a counter's minimum and maximum, so the cap is the rule, not a safety net. See Counters.
  • A death drops what the player carried and one soul of their own with api.scatter_pickups, at api.death_position: a ring of souls to fight over rather than one pile, each kept on the near side of any wall. The souls belong to the dead player's team and vanish after 30 seconds. The extra soul means souls keep coming into the match even when nobody banks.
  • _can_collect checks the kind first, so the rule for souls never stops anybody picking up the map's health and ammo packs. See Collecting.
  • Both deposit zones share one label and are told apart by api.zone_team. See Names, keys and labels.
  • api.transfer_team adds as much as fits in the bank and returns how much it moved, so a bank near full takes what it can and the rest stays in the carrier's hands.
  • The time each thief has spent on the enemy's zone is kept in a Dictionary keyed by entity id. _zone_exited forgets it, and it also runs when the player dies or leaves the match inside the zone, so stepping off and back on starts again.
  • A full bank has to stay full for HOLD_SECONDS: a bank that drops below full, even for a tick, starts over.
  • may_take is the one place that says which soul a player may take: _can_collect asks it, and so does bot.gd.

client.gd

extends GamemodeClientScript


func _start() -> void:
	var capacity: int = api.counter_maximum(api.SCOPE_TEAM, &"bank")
	api.show_widget(&"team_score", {
		"counter": "bank",
		"threshold": capacity,
		"warn_at": capacity - 15,
	})
	api.show_widget(&"carry_pips", {
		"counter": "souls_carried",
		"maximum": api.counter_maximum(api.SCOPE_PLAYER, &"souls_carried"),
		"label": "SOULS",
	})

team_score shows both banks and the winning number, lit up for the last stretch, and carry_pips shows the souls the player is carrying. Both read their numbers from the counters' declared maximums. See Widgets.

bot.gd

extends GamemodeBotScript

const REVIEW_SECONDS := 1.0

var _review: float = 0.0
## team -> where its deposit zone is.
var _home: Dictionary = {}


func _start() -> void:
	for zone in api.zones_labeled(server.DEPOSIT_ZONE):
		_home[api.zone_team(zone)] = api.zone_position(zone)


func _tick(delta: float) -> void:
	_review -= delta
	if _review > 0.0:
		return
	_review = REVIEW_SECONDS
	for bot in api.bots():
		var team: int = api.team_of(bot)
		if not api.is_alive(bot) or not _home.has(team):
			continue
		var carried: int = api.get_player(bot, &"souls_carried")
		var soul: int = -1 if carried >= server.CARRY_CAP else _nearest_soul(bot)
		if soul >= 0:
			api.bot_collect(bot, soul)
		elif carried > 0:
			api.bot_move_to(bot, _home[team])
		elif api.bot_role(bot) == &"defense":
			api.bot_defend(bot, _home[team], 10.0)
		else:
			api.bot_roam(bot)


## The nearest soul the rules would let this bot take, or -1.
func _nearest_soul(bot: int) -> int:
	var at: Vector3 = api.position_of(bot)
	var best: int = -1
	var best_distance: float = INF
	for handle in api.pickups():
		if api.pickup_kind(handle) != &"soul" or not server.may_take(handle, bot):
			continue
		var distance: float = at.distance_to(api.pickup_position(handle))
		if distance < best_distance:
			best = handle
			best_distance = distance
	return best

A soul a player has picked up is no longer a pickup, so the bots read what everybody carries from the souls_carried counter. Once a second, a bot that can carry more goes for the nearest soul the rules let it take with api.bot_collect. A bot with nothing left to collect takes what it carries home, a bot with a defense kit guards its own deposit zone, and the rest roam: a roaming bot hunts, and every kill puts souls on the floor.

Going further

The base game's Soul Banking on Soulhouse also has:

  • A limit per visit. A thief takes at most five souls before they have to step off the zone and back on, so one player cannot empty a bank by standing still.
  • Spawn rooms with immunity, class changes and a refill; see Spawn rooms.
  • Bots dealt into jobs: a share of each team guards the way into its own bank once it holds something, a share robs the enemy's, a support kit stays with whoever carries the most with api.bot_escort, and the rest pick up souls within reach.
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