Level Editor/Scripting/Pickups

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 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: _can_collect may refuse it and _pickup_collected hears it taken. Removing one with api.despawn_pickup does not remove the station; its next pack comes back on the usual timer.

Dropping pickups from a script

api.spawn_pickup(kind, position, team, lifetime, radius) puts something on the ground and returns its handle, a number that names it from then on.

• kind is one of: soul, ammo_small, ammo_medium, ammo_large, health_small, health_medium, health_large. A name outside this list shows nothing.
• The ammo and health kinds refill the player by themselves when collected. A soul does nothing by itself: it is worth whatever your _pickup_collected says.
• team is whose it is (0 for nobody's). Nothing reads it but your own _can_collect.
• lifetime is how many seconds it lasts untaken; 0 means it stays until somebody takes it.
• radius 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 api.scatter_pickups at 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 spawn_pickup cannot do.

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)

Collecting

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

• _can_collect(handle, entity_id) 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:

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)

• _pickup_collected(handle, entity_id) runs when it has been taken. During this hook the handle still answers api.pickup_kind and api.pickup_team; afterwards it is gone.
• _pickup_expired(handle) runs when one runs out of lifetime untaken.

api.pickups lists every handle on the ground, and 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 api.resupply from _zone_entered or _zone_tick. See Spawn rooms.