TeamSpecBot: Level Editor: pickups scripting guide

2026-10-20T03:46:21Z

Level Editor: pickups scripting guide

New page

Pickups are things on the ground a player collects by walking over them: the level's own health and ammo packs, and anything a script drops (souls, ammo, health). This page covers both.

== Supply stations ==

A [[Level Editor/Entities/Supply Pickup|Supply Pickup]] from the Functional menu is a health or ammo pack that belongs to the level. Click to place it, then set it in the inspector:

* '''Pool''': health or ammo.
* '''Size''': small, medium or large. A small pack refills a quarter of the maximum, a medium half, a large all of it.
* '''Respawn Seconds''': how long after somebody takes the pack the next one appears.

Supply stations work with no script at all. A player who is already full does not take a pack, so it stays for somebody who needs it. To your script a station's pack is an ordinary pickup: <code>_can_collect</code> may refuse it and <code>_pickup_collected</code> hears it taken. Removing one with [[Level Editor/Scripting/Reference/GamemodeServerApi#despawn_pickup|api.despawn_pickup]] does not remove the station; its next pack comes back on the usual timer.

== Dropping pickups from a script ==

[[Level Editor/Scripting/Reference/GamemodeServerApi#spawn_pickup|api.spawn_pickup]]<code>(kind, position, team, lifetime, radius)</code> puts something on the ground and returns its '''handle''', a number that names it from then on.

* <code>kind</code> is one of: <code>soul</code>, <code>ammo_small</code>, <code>ammo_medium</code>, <code>ammo_large</code>, <code>health_small</code>, <code>health_medium</code>, <code>health_large</code>. A name outside this list shows nothing.
* The ammo and health kinds refill the player by themselves when collected. A <code>soul</code> does nothing by itself: it is worth whatever your <code>_pickup_collected</code> says.
* <code>team</code> is whose it is (0 for nobody's). Nothing reads it but your own <code>_can_collect</code>.
* <code>lifetime</code> is how many seconds it lasts untaken; 0 means it stays until somebody takes it.
* <code>radius</code> is how close a player has to come.

The game rests a drop on the floor below the position you give, so it does not hang in the air. To drop several around one spot, as when somebody dies carrying things, use [[Level Editor/Scripting/Reference/GamemodeServerApi#scatter_pickups|api.scatter_pickups]] at [[Level Editor/Scripting/Reference/GamemodeServerApi#death_position|api.death_position]]: it spreads them in a ring and keeps every one of them on the near side of any wall, which a loop of <code>spawn_pickup</code> cannot do.

<pre>
func _player_died(entity_id: int, _killer_id: int, default_seconds: float) -> void:
var carried: int = api.get_player(entity_id, &"carrying")
if carried > 0:
api.set_player(entity_id, &"carrying", 0)
api.scatter_pickups(&"soul", api.death_position(), carried, 1.2, api.team_of(entity_id), 30.0)
api.respawn_in(entity_id, default_seconds)
</pre>

== Collecting ==

When a living player comes within a pickup's radius it flies to them, and it is collected when it reaches them.

* <code>_can_collect(handle, entity_id)</code> is asked first, and again when it arrives. Return false to refuse; the default allows everyone. Check the kind first, so your rule for souls does not stop players taking ammo:

<pre>
func _can_collect(handle: int, entity_id: int) -> bool:
if api.pickup_kind(handle) != &"soul":
return true
return api.pickup_team(handle) != api.team_of(entity_id)
</pre>

* <code>_pickup_collected(handle, entity_id)</code> runs when it has been taken. During this hook the handle still answers [[Level Editor/Scripting/Reference/GamemodeServerApi#pickup_kind|api.pickup_kind]] and [[Level Editor/Scripting/Reference/GamemodeServerApi#pickup_team|api.pickup_team]]; afterwards it is gone.
* <code>_pickup_expired(handle)</code> runs when one runs out of lifetime untaken.

[[Level Editor/Scripting/Reference/GamemodeServerApi#pickups|api.pickups]] lists every handle on the ground, and [[Level Editor/Scripting/Reference/GamemodeServerApi#pickup_position|api.pickup_position]] says where one is.

== What every death drops ==

Whatever your mode does, every death drops a medium ammo pack where the player died, which lasts 30 seconds and belongs to nobody.

== Resupply zones ==

To refill players who stand in a zone, call [[Level Editor/Scripting/Reference/GamemodeServerApi#resupply|api.resupply]] from <code>_zone_entered</code> or <code>_zone_tick</code>. See [[Level Editor/Scripting/Teams and spawning#Spawn rooms|Spawn rooms]].

{{Level Editor nav}}

[[Category:Level Editor]]
[[Category:Gamemode scripting]]

Level Editor/Scripting/Pickups - Revision history

TeamSpecBot: Level Editor: pickups scripting guide