VoidExpanse/Consumable scripting

	This article is a draft and may contain incomplete or even incorrect information. You can help by expanding it.

Consumables Scripting

In most cases the standard xml-structures are more than enough to implement consumable effects. However, if we need to do something special, for example, restock ammo, self-destruct, teleport or kill all ships in front of the player, you will need scripts.

There are no hard rules for scripting consumables, here are just a couple of tips. For example, if we need to create a consumable that refills ammo in all of the players ballistic weapons. First of all, we need to create a basic consumable xml, with an empty effects node.

	<effects>
		<!-- no effects here -->
	</effects>

Then, you create a new global script in folder /scripts/globals/, in which you hook some function to a special trigger:

function OnInit()
{
	actions.BindToTrigger("onConsumableUsed", "onBallisticAmmoConsumableUsed",
		{id: "consumable_ballistic_ammo"});
}

(Please note: OnInit() method is executed only for Global and Internal scripts)

After that, every time a player uses a consumable with the xml-id "consumable_ballistic_ammo", function "onBallisticAmmoConsumableUsed" will be called.

Now, all that's left is to implement the actual ammo refill:

function onBallisticAmmoConsumableUsed( args )
{
	var ballisticWeapons = ship.GetWeaponsOfType( args.ship_id, 2 );
	if(ballisticWeapons == null) return;
	
	for(var i =0; i < ballisticWeapons.length; i++)
	{
		ship.RefillAmmoForWeapon( args.ship_id, ballisticWeapons[i] );
	}
}

That's all, now we have a consumable that refills ammo the of all ballistic weapons!

VoidExpanse Modding (Edit template)

Using mods: Installing and using mods Overview articles: Modding (main article), Package files structure Topic specific articles: Assets modding, Content Modding, Scripting overview, Scripting API, Scripting Events system, Localization Detailed scripting articles: Internal scripts, Global scripts, object scripts, Device scripts, Consumable scripting Tools: VE Physics Adjuster, VE Mod Uploader (Steam), AT Localization Utility