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 then has 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
Campbell Equalizer	w1_tap	3
Hughes Black Adder	w2_sap	4
Plasma Rifle	w3_phr	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

• w10_sni is also known as the "fireworks" weapon because of the appearance of the projectile it shoots, but it's the same particle as Mukade's "Devilstar" attack ("sni" stands for "superninja").
• 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(1)	lsi	?(2)	?
Force Shield	shield	100	65535
Phase Cloak	invis	1800	65535(3)

Giving negative amounts means taking away. Since inventory amounts can only be positive numbers, taking away more than the character originally had will have the effect of giving them a lot. If you have 1 clip of ammo and use give_powerup(ammo, -2), the "-1" result will wrap around to the max value of the 16 bits allotted for the clip count, giving them 65535 ammo clips.

⁽¹⁾"Special" items, AKA LSIs, can be one of the following, depending on the level: Datapad, Rappelling Harness, Laser Torch, Zip Line Rider, or Truck Keys.

⁽²⁾The "amount" to give/take seems to be ignored in the case of LSIs, as the associated variable is a Boolean. In particular, you can't take an LSI away.

⁽³⁾The phase cloak decays by 1 point every frame (1 second = 60 frames), so the default value of 1800 is 30 seconds of cloak time. The maximum value for a temporary cloak is 65534 (1092 seconds, or 18.2 minutes), because when the value is set to 65535, there is no decay and the cloak lasts forever (the same effect as using "moonshadow").

Spawning loose items

It's less complicated than 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

These are 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 if the player character has found and picked up an LSI.

chr_has_empty_weapon

This one lets you know if the character has run out of ammo for his weapon (and has no clips to reload it with).

Variables

wp_disable_fade

Setting this to 1 will make dropped weapons stay on the ground forever instead of fading away.

wp_fade_time

This 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 to 0 will prevent the AI from running with the Wave Motion Cannon. The player character can never run with a WMC.