Level Editor/Scripting/Examples/Soul Banking
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 toDeposit Zoneand 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_carriedis 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_collectchecks 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_exitedforgets 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_takeis the one place that says which soul a player may take:_can_collectasks it, and so doesbot.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.