Scripting in Shadow Armada

-First note:  If you modify a script, you MUST RELOAD AND RESAVE MAPS THAT USE THE SCRIPT in the mission editor for the changes to take effect!

Also, you may refer to Scripts\ShieldGame.txt for an example.  It is the script used, oddly enough, for ShieldGame.mis

Anyway, the scripting system is based around Groups of objects.  To change between different groups the funcion SetActive(char*) is used.  Note that all functions are shown in C++ syntax here.  For instance, a valid call for SetActive would be SetActive("GREEN");  This would select all green ships as the target of subsequent scripting actions.  Now say you have two green squads, and you want those labelled "KILLME".  You would then say IsAlso("GREEN", "KILLME");  This will change the currently selected group to the union of what is already selected ("GREEN" in this case) and the newly specified group ("KILLME").  So now if the command S_Injure(999); is issued, then any ships that are both in team "GREEN" and in group "KILLME" will be dealt 999 damage!  Also note that some functions (Such as IsAlso) will create a temporary group that can further be narrowed down.

One more important thing to note is that the functions (With the exception of EveryTurn, which, strangely enough, is called every turn) will need a group name in them.  For instance, the OnWarp function, called for wormholes when something warps through them, and called for any other object when it enters the wormhole, will need a name after OnWarp to have any effect.  I.E. while in the list of events it shows up as OnWarpNAME, you would want to enter OnWarpKILLME or OnWarpGREEN.  The function will then be called when an object of group KILLME or a green ship enters the portal.

Note: To assign a name such as KILLME to an object in the map editor, simply right click the desired object and select Assign ID.  Then type the name, and press return when finished.

Another note: Using Editor.exe, you may make ships that are specific to a script.  To do this, pick the "Ships" tab, and make your ship.  Then click the "Export" button, and hit ctrl+v (Paste) where you want the function in your script.  Note that if your ship name had spaces, you will need to unspace the function name.  Then use call-script MakeSHIPNAME(); elsewhere in your script in order to transform another ship into your ship.

======================================================================
Default Groups
======================================================================
These are groups that will exist no matter what you do:
GREEN, RED, BLUE, YELLOW, PURPLE, TURQ, ORANGE, GRAY
Those refer to their respective team ships.

SHIPS - Refers to absolutely every ship in the map.

First 8 letters of any ship name - UPPERCASE - Refers to the type of ship.

======================================================================
EVENTS
======================================================================


OnHitNAME()
	Groups Made: COLLIDER and COLLIDED.  COLLIDER refers to the member of group NAME that is doing the colliding, and COLLIDED refers to the object struck.
	Called when: An object of group NAME strikes any other object.

OnDamageNAME(Amount)
	Groups Made: INJURED.  INJURED refers to the ship/asteroid/whatever that was damaged.
	Called when: An object of group NAME is injured.  Amount is the amount of damage that was dealt.  Changing Amount's value will change the actual amount of damage inflicted.  A scripting invincibility can be made by the line: Amount = 0;

OnDestroyNAME()
	Groups Made: DESTROYD.  Refers to the object of group NAME that was destroyed.
	Called when: An object of group NAME is destroyed.

OnWarpNAME()
	Groups Made: WARPED and WARP.  Note that NAME may either be the wormhole OR the warped object's group.  REGARDLESS, WARPED will be the object that has been warped, and WARP is the object that is doing the warping.
	Called when: An object of group NAME is warped or a wormhole of group NAME warps an object.

OnSpawnNAME()
	Groups Made: SPAWNED.  SPAWNED refers to the member of group NAME that was created.
	Called when: An object of group NAME is created/warped in.

EveryTurn(Turn)
	Groups Made: None.
	Called when: Called every single turn before the turn.  If Turn == 1 then it is pregame initialization code.  For instance, you may make a ship in one group another ship class (See ShieldGame.txt's MakeSG and MakeReactor).

OnTrigEnterNAME()
	Groups Made: TRIG.  TRIG refers to the object interacting with the trigger.
	Called when: An object first enters the trigger with name NAME.

OnTrigExitNAME()
	Groups Made: TRIG.  TRIG refers to the object that has just left the trigger.
	Called when: An object leaves a trigger with name NAME's area.

OnTriggerNAME()
	Groups Made: TRIG.  TRIG refers to the object in the trigger's space.
	Called when: Every frame where an object is inside the trigger's zone.

=========================================================================
Standard Functions
=========================================================================

if prefixed with void, the function stands alone.  If float, then it returns something that you can use in another function, or in a variable.


	void ForEachTeam(char* F)
		Calls the function F for every team in the map.
	void Destroy()
		Destroys every object in the active group
	float Exists()
		Returns 1 if there is a current group, 0 if it does not exist
	float IsShip()
		Returns 1 if there is a ship in group.  Otherwise 0
	float NumMembers(char* Group)
		Returns the number of members in Group
	void IsAlso(char* Group1, char* Group2)
		Creates group SHARED that contains all shared members of Group1 and Group2.
	void RandomMembers(float F)
		Creates group RANDOM that contains F members of the currently active group.  Note that if there is less than F members of the group, then there will be less in RANDOM.
	void DisableSD()
		Disables sudden death (Asteroids)
	void Event_Text(char* Text, float Team)
		Sets up a text event.  Look at ShieldGame.txt
	void Event_Graphic(float Pic)
		Sets up a graphic event.  Look at ShieldGame.txt
	void Event_Do()
		Shows the event.  Look at shieldGame.txt
	void OpenWormhole(char* ID, float X, float Y, char* Color)
		Opens a wormhole at (X, Y).  Notice that the color is THE SAME AS TEAMS, HOWEVER WHAT TEAM ENTERS WHAT WORMHOLE DOES NOT MATTER!  ID is a string for the ID of the wormhole like in the mission editor.
	void WarpinShips(char* ID, float X, float Y, float Rotation, char* Team, float NumShips, char* ShipNames)
		Warps in a squad of ships.  Number of ships = NumShips, ShipNames = names of ships, separated by semicolons.  ID is a string for their ID (like Assign ID in mission editor) and may be "" for none.  X and Y are the coordinates, and Rotation is in degrees.  NOTE: If Team is invalid, then the ships will be green by default.
	void SpawnUpgrade(float X, float Y, char* UpgrName, float, float, float, float, float)
		Spawns a pickupable upgrade at (X, Y) of type UpgrName.  Last five params = magic.


=========================================================================
Typed Functions
=========================================================================

Note: S_ means it only affects ships, B_ only barriers, T_ only triggers.

if prefixed with void, the function stands alone.  If float, then it returns something that you can use in another function, or in a variable.

	void S_SetName(char* Name)
		Sets the ship's name.  AKA Archer, Fighter, etc
	void S_SetGraphic(char*)
		Sets the ship's graphic.  
	void S_SetBaseMass(float Mass)
		Sets the ship's unloaded mass
	void S_SetSize(float)
		Sets the ship's size, in pixels.
	float S_GetSize()
		Returns the ship's size, in pixels.
	void S_SetBaseScan(float)
		Sets the ship's scan range.
	float S_GetBaseScan()
		Returns the ship's scanning range.
	void S_SetCollClass(float)
		Sets the ship's coll class.  Refer to editor for values.
	void S_GiveCloak(float)
		Gives the ship X turns of cloaking.
	void S_SetCloak(float)
		Sets the ship for X turns of cloaking.
	void S_GiveFade(float)
		Gives the ship X turns of Phase out.
	void S_SetFade(float)
		Sets the ship for X turns of Phase out.
	void S_GiveInvincibility(float)
		Gives the ship invincibility for X turns.
	void S_SetInvincibility(float)
		Sets the ship invincible for X turns.
	void S_Injure(float)
		Deals the ship X damage (If negative, it will heal)
	void S_Replenish()
		Replenishes the ship's missiles
	void S_WarpTo(float X, float Y)
		Warps the ship to coordinates X, Y.  X and Y can be obtained from editor.
	void S_GiveComp(float Side, float Comp, float, float, float, float, float)
		Gives the ship a component.  Last 5 params denote magic.
	void S_GiveMiss(float Miss, float, float, float, float, float)
		Gives the ship a missile.  Last 5 = magic
	void S_SetMiss(float Pos, float Miss, float, float, float, float, float)
		Sets a specific slot in armory.  Last 5 = magic
	void S_GiveUpgr(float Upgr, float, float, float, float, float)
		Gives the ship an upgrade.  Last 5 = magic
	void S_SetUpgr(float Pos, float Upgr, float, float, float, float, float)
		Sets a specific upgrade.  Last 5 = magic
	void S_StripComp()
		Removes all components from ship.
	void S_StripCompType(float)
		Removes all components of type X (Look in editor for #'s) from ship.
	void S_StripArmory()
		Removes all missiles from ship.
	void S_StripUpgr()
		Removes all upgrades from ship.
	void S_GiveDrop(float)
		Gives the player controller of ship an item with opponent level X.
	void S_Bump()
		"Bumps" a ship.  Prohibits ship from moving.
	void S_Limit(float)
		Limits the number of ships in group to X.  Destroys excess
	float S_GetTeamID()
		Returns the group of the ship's team.
	float S_GetGraphic()
		Returns the ship's graphic...  Not useful outside of events.
	void B_SetSpinning(float)
		Sets the rate at which a barrier spins.
	void T_Attach(char* Group)
		Attaches trigger to CLOSEST member of Group.  May be used for multiple triggers and ships.
	void T_Activate()
		Activates the trigger.
	void T_Deactivate()
		Deactivates the trigger.
	float T_IsActive()
		Returns 1 if active, 0 if not.