BSL:Inventory management

Giving items to characters

Weapons

You can choose from four commands when giving a weapon to a character :

• void chr_giveweapon(string ai_name, string weapon_name)
• void chr_giveweapon(int script_id, string weapon_name)
• void chr_weapon(int chr_index, string weapon_name)
• void chr_weapon(int chr_index, int weapon_num)

All those have the effect of giving a new weapon to a character. The first argument can be :

• the "AI name", most often used for spawned AI, but also applicable to AI-less characters, such as Konoko (the name has then to be looked up).
• the "script ID", used for characters without an AI (Konoko and some cutscene puppets). Konoko's script ID is always 0.
• the "character index", used for any character : it's related to the position of the characters in memory (basically to the order in which they were spawned, Konoko's character index is thus always 0)

The second argument can be :

• the "weapon name", a string
• the "weapon number" an integer

A table summing up the weapon names and IDs :

Weapon	name	ID (+/- 12)
Campbell Equalizer	w1_tap	3
Hughes Black Adder	w2_sap	4
Hughes Black Adder	w3_sap	5
Phase Stream Projector	w4_psm	6
Super Ball Gun	w5_sbg	7
Van de Graaff Pistol	w6_vdg	8
Scram Cannon	w7_scc	9
Mercury Bow	w8_mbo	10
Screaming Cannon	w9_scr	11
Homing Red Balls :D	w10_sni	0
Wave Motion Cannon	w11_ba1	1
	w12_ba2	2
	w13_muro	NONE
	w14_muro	NONE
	w0_sec	NONE

• By (+/- 12) I mean that you can e.g. use chr_weapon(0, -11) or chr_weapon(0, 13) to give Konoko a Wave Motion Cannon.
• w12_ba2 is like w10_sni except it doesn't shoot... w13_muro, w14_muro and w0_sec don't work at all.

Powerups

You can choose from a few commands when giving powerups to a character :

• void chr_givepowerup(string ai_name, string powerup_name, int amount)
• void chr_givepowerup(string ai_name, string powerup_name)
• void chr_giveweapon(int script_id, string powerup_name, int amount)
• void chr_giveweapon(int script_id, string powerup_name)
• void give_powerup(string powerup_name, int amount, int character)
• void give_powerup(string powerup_name, int amount)
• void give_powerup(string powerup_name)

All those have the effect of giving a powerup to a character. The character is referred to by one of the following :

• the "AI name", same as in the case of weapons (see above)
• the "script ID", same as in the case of weapons (see above)
• the "character" index, same as "character index" in the case of weapons (see above)

The new thing here is that there is no "powerup ID", and some of the arguments are optional.
In fact, those arguments have a default value, and omitting the argument is the same as providing that default value :

• the default value of "character" for the give_powerup command is 0 (Konoko's "character ID"). If you specify "character", you can't omit "amount".
• the default "amount" of powerups are summed up in the following table.

Powerup	name	Default amount	Max amount
Ballistic Ammo	ammo	1	65535
Energy Cell	cell	1	65535
Hypo Spray	hypo	1	65535
Special	lsi	?	?
Force Shield	shield	100	65535
Phase Cloak	invis	1800	65535

• Giving negative amounts means taking away. Taking away more than you can means giving a lot. If you have 1 clip of ammo and use give_powerup(ammo, -3), you'll have 65534 ammo clips.
• Phase Cloak decays by 1 point every frame (1 second = 60 frames), so default is 30 seconds, max is 65534/60=1000 seconds
• When the Phase Cloak amount is set to 65535, there is no decay (moonshadow effectively sets this amount to either -1=65535 and 0)
• "Special" aka lsi can be one of the following : Datapad, Rappelling Harness, Laser Torch, Zip Line Rider, Truck Keys. Depending on the level.
• "amount" seems to be ignored in the case of lsi, as the associated variable is a boolean. In particular, you can't take an lsi item away.

Spawning loose items

It's less complicated that giving items... or spawning characters.

Spawning a weapon

void weapon_spawn(string weapon_name, int flag_id)

• The first argument is a valid weapon name (see table above)
• The second argument is the index of a flag (preset position + orientation).

Spawning a powerup

void powerup_spawn(string powerup_name, int flag_id)

• The first argument is a valid powerup name (see table above)
• The second argument is the index of a flag (preset position + orientation).

Associated stuff

Commands

chr_inv_reset

• this takes all items away from a character (weapons, ammo, hypos, Force Shield, Phase Cloak, lsi)
• as for most "character" commands, valid arguments are an "AI name" and a "script ID"
• chr_inv_reset(0) resets the inventory of the character with script ID 0 i.e. Konoko.
• chr_inv_reset(SomeAI) would reset the inventory of an AI called SomeAI.

chr_disarm

• doesn't seem to work...

Predicates

i.e. small functions returning a boolean (YES/NO) value informing you on the current state of the characters' inventory

chr_has_lsi

• this one lets you know e.g. if the player character has found and picked up an lsi item.

chr_has_empty_weapon

• this one lets you know if the character has run out of ammo for his weapon (and has nothing to reload with)

Variables

wp_disable_fade

• setting this to 1 will make dropped weapons not fade i.e. stay on the ground forever.

wp_fade_time

• should specify the time (in frames) over which weapons disappear, but setting it doesn't seem to have an effect

ai2_barabbas_run

• setting this variable to 0 will prevent the AI from running with the Wave Motion Cannon. The player character can never run with a WMC.