Modding MechCommander - MC ABL-Libraries file

****************************************************************************
--------------These are notes from Cmunsta's MCG Campaign Builders Guide II for ABL Scripting--------
****************************************************************************
#include
Include an .ABI (library) file into the current file.
This directive looks for the given file starting in the game's root folder.
#include_
Include an .ABI (library) file into the current file.
This directive looks for the given file starting in the \data\missions folder

TRUE and FALSE are pre-defined as integers 1 and 0 respectively

The abl scripting language is not case sensitive (THis, tHIs, ThIs and this are all treated the same)

// double slash begins a single comment line, this line will be commented out of the script

/*
Block comments. The slash-star begins the comment block and the star-slash
terminates the comment block. All text in between these symbols are considered
comments and are ignored by the ABL parser
*/

-Variable types-
boolean Can only hold true or false values.
(internally, the game stores these in byte size memory chunks).
integer Holds a 32-bit signed integer value. (Whole Number)
The ABL language does not appear to have an unsigned modifier. (1 is an integer ,1.1 is not ...)
real Holds a real or floating point value. (1.1 is okay, 1 is also okay as it will read as 1.0)
char This holds a single letter (character) but can be turned into an array to store a string of plain text


position This seems to define a real[3] array to hold xyz co-ordinates
I don't really see the difference between this and the type below...
worldposition I can only find examples of this in warriorbrain files
This seems unique to MCO, and appears to hold a set of xyz co-ordinates for a position on the game map
The same can be achieved with a real[3] array (real[0] =x real[1] = y real[2] = z)
PatrolState I can only find examples of this in warriorbrain files
This seems unique to MCO. It is part of the formula used to define patrol routes.
I can't find any more information than this.
PatrolPath I can only find examples of this in warriorbrain files
This seems unique to MCO. It appears to hold a set of xy co-ordinates for a waypoint used in patrol routes
I can't find any more information than this.

-Variable modifiers -
static The static modifier allow a variable to retain its value across multiple execution
calls of a function, module or library, but not between two separate files (eg mission.abl > warrior.abl)
eternal The eternal modifier creates the variable in a global memory space. Only one such
variable declaration is allowed (per mission) since they are globally defined. Attempting to declare a
second eternal variable of the same name will result in an error. (This is useful for having changes one file
effect another, eg mission.abl > warrior.abl to change a patrol route)
[x,y] Placing this after the type will create an array(table) of the information given with x columns and y rows
( Or y columns and x rows, I'm not really sure if it matters)

-Math and logics-
+ Addition
- Subtraction
* Multiplication
/ Division
= Assignment
mod Modulus
<> Not equal to
>= Greater or equal to
<= Less than or equal to
== Equal to
> Greater than
< Less than
not Logical inverse
and Logical AND
or Logical OR

if({condition}) then
// if code block
[else
// else code block ]
endif;

switch({variable})
case{constant}:
// case code block
endcase;
[{additional case statement blocks}]
endswitch;

while({condition})do
// while code block
endwhile;

for i=0 to 19 do
// for loop code block
endfor;

The ABL scripting language, does not use short-circuited logic.
All sections of a statement are processed before the result is decided

***************************************************************************
General include files and mission layout
***************************************************************************
module xxxthemissionxxx :integer;
const
#include_ "miscont.abi" // miscellaneous constants
#include_ "sndconst.abi" // sound/music constants
var
#include_ "sndvar.abi" // sound variable definitions
#include_ "ovar.abi" // object variable definitions
//-------------Initialization code is run once only
function init
code
#include_ "sndinit.abi" // initialise sound/music
endfunction;
//-------------
#include_ "miscfunc.abi"
// contains numerous useful functions,
// although no mission.abl seems to have this included they all refer to functions
// defined within this file (such as if (isAlive(partID)) then ??)
//---Main code
Code
blah stuff blah
return (ScenarioResult)
endmodule. // note the .period. not ;semi-colon; !!

***************************************************************************
-----These commands have been harvested from Magics mission.abls or the version.txt file-----
***************************************************************************

GetTime; // gets the current game time
GetID; // Gets the ID of the current/calling object
GetObjectPosition(PartID, position);
// get the world position of the PartID and store it in the array listed
GetUnitMates(SquadID, INT);
// get the vehicleUnitID for the Squad ID (from the editor/.fit) and store it in a predefined static integer

InHotSpot(TeamID,x co-ord,y co-ord, real RangeInMeters);
// object near a location TeamID can be PLAYER_FORCE, ALLIED_FORCE or CLAN_FORCE
IsWithinArea(UnitID, position Point, real Radius) : boolean;
// UnitID(from GetUnitMates(SquadID,Array); , 3-point array or worldposition with xyz, range in meters
ForceWithinArea(x co-ord,y co-ord,real range);
// Any unit in the area?

Isdead(UnitID) // Isdead(Building/UnitID)
Isalive(UnitID) // IsAlive(Building/UnitID)

ObjectRemove(UnitID); // remove (PartID/BuildingID)

SetObjectDamage(PartID,%); // damage an object to the % ammount, eg 25 will set the remaining health as 25

DestroyMechBodyLocation(MechID, locationID);
//MechID - part id for mover (getunitmates(squadID)) from squad ID.
//locationID - (0 - HEAD, 1 - CTORSO, 2 - LTORSO, 3 - RTORSO, 4 - LARM, 5 - RARM, 6 - LLEG, 7 - RLEG,)
//Effect: Destroy selected mech body location.
DamageMechArmor(MechID);
//MechID - part id for mover (getunitmates(squadID)) from squad ID.
//Effect: Random damage to all front mech armor locations.

SetMechGesture(MechID, gestureID);
//MechID - number from the editor for buildings, part id for mover (getunitmates(squadID)) from squad ID.
//gestureID - (0,1,2,3,4,5,6,7 (fallen backward),8,..)
//Effect: FOR DISABLED MECHS ONLY. set mech gesture to be fallen,...

SetCapturable(PartID,boolean); // sets an object as captureable
SetCaptured(PartID);

ObjectChangeSides(PartID, teamID);
//PartID - number from the editor for buildings, part id for mover (getunitmates(squadID)) from squad ID.
//teamID - (0, player, 2 ally, 1,3,... enemy)
//effect: change object side.
//works for MECHS, VEHICLES and BUILDINGS
-------
if (ObjectSide(PartID) == 500) then
// check alignment of PartID, 500 = Player_Force, 501 = Clan_Force, 502 = Allied_Force
// code
endif;
-------
if (CheckObjectiveStatus(INT) == SUCCESS) then
// check if objectiveINTX is 0- INCOMPLETE, 1- SUCCESS, 2- FAILED, -1 ERROR
// code
endif;
-------
SetObjectiveStatus (objective number, new status);
// objective number from mission.fit status 0- INCOMPLETE, 1- SUCCESS, 2- FAILED, -1 ERROR
SetObjectiveType(objectiveID, type);
// type (invisible/hidden -1, primary 1, secondary 2)
CheckObjectiveType(objectiveID);
// returns the same integers from above (invisible/hidden -1, primary 1, secondary 2)

AddMoverToPlayer(PartID, teamID, commanderID);
//PartID - part id for mover (getunitmates(squadID)) from squad ID. (OR use GetID if in a warriorbrain)
//teamID - (0,player, 2 ally 1,3,... enemy)
//commanderID = 0, player is 0 for Single player. Here for possible future multiplayer. 1 enemy, 2 ally
//Effect: switch enemy mech or vehicle to player and add that unit to player roster.

RemoveMoverFromPlayer(PartID, teamID, commanderID);
//PartID - number from the editor for buildings, part id for mover (getunitmates(squadID)) from squad ID.
//Effect: remove players mech or vehicle from roster.

SetBrain(getID, "brainstring"); // changes the brain of the unit

TeleportToPoint(PartID, position);
//number from the editor for buildings, part id for mover (getunitmates(squadID)) from squad ID.
//position is a worldposition or static real[3] with

• x co-ord, [1] y co-ord and [2] z co-ord

GetTargetRelativePosition(TargetID, range, angle);
//integer TargetID = gettarget(-1),
//real range, angle. set range and angle from the selected unit to target and store values to range and angle variables.

GetRelativePositionToTarget(TargetID, distance, flag = 2, newPoint)
//integer TargetID = gettarget(-1),
//real distance - distance you want from target,
//real[3] newPoint - coordinates for the new point.

ToggleAirstrike; // toggle airstrike in support options
ToggleSensorStrike; // toggle sensor probe in support options
ToggleArtilleryPiece; // toggle artillery in support options
ToggleRepairTruck; // toggle repair truck in support options
ToggleSalvageCraft; // toggle salvage craft in support options
//ToggleScoutCopter; // toggle copters in support options, not listed anywhere but follows the theme -- does not work --
//ToggleMineLayer; // toggle minelayer in support options, not listed anywhere but follows the theme -- does not work --

SetRepairTruckEnabled(boolean); // TRUE/FALSE to enable/disable repair truck in support options
SetSalavageCraftEnabled(boolean); // TRUE/FALSE to enable/disable salvage craft in support options

AddResourcePoints(int PointsToAdd); //in mission respoints ToAdd - can be + or -. (adds to c-bills post mission complete)
AddMoney(int PointsToAdd); //out of mission c-bill ToAdd - can be + or -.

SetTxtBuildingName(BuildingID, "BuildingName");
//BuildingID - number from the editor for building.
//"BuildingName" = "New text building name" - visible in mission
//Works for Buildings, Turrets and Gates

SetTextMsg(Type,"Message String to Display Is Here",TimeInSecondsToDisplayIfTimed);
// Type is 1=enterToContinue or 0 = timed

SetMissionTune(tuneID); //tuneID - music ID number from sound.snd

List of ALL NEW (or fixed) ABL COMMANDS

1.
setTextMsg(0,"PROBE",10);

first parameter can be 0 or 1.
0 - instant message for the duration of number of seconds (10),
1 - rollins message box with press enter to continue, in this case third parameter is not important.

Second parameter is text message. It should have no limit because it passes a pointer to string to underlying function.

Third is a number of seconds to display a message in case first is set to 0.

2.
objectchangesides(PartID, teamID); (FIXED existing command)

PartID - number from the editor for buildings, part id for mover (getunitmates(squadID)) from squad ID.
teamID - (0,2 player; 1,3,... enemy)

effect: change object side.
works for MECHS, VEHICLES and BUILDINGS

3.
addmovertoplayer(PartID, teamID, commanderID);

PartID - part id for mover (getunitmates(squadID)) from squad ID.
teamID - (0,2 player; 1,3,... enemy)
commanderID = 0, player is 0 for Single player. Here for possible future multiplayer.

Effect: switch enemy mech or vehicle to player and add that unit to player roster.

4.
setobjectivestatus(objective_number, newObjectiveStatus) (FIXED existing command)

objective_number - mission objective number.
newObjectiveStatus can be:
0 - undetermined,
1 - success,
2 - failed.

Effect:
Set objective status from main mission abl file.

5.
addresourcepoints(pointsToAdd);
pointsToAdd - number of Resource points, can be + or -.
Effect: Add resource points for the mission.

6.
addmoney(pointsToAdd);
pointsToAdd - amount of money, can be + or -.
Effect: In mission add money.

7.
togglerepairtruck;
Effect: Enable/Disable repair truck in support for the mission.

8.
togglesalvagecraft;
Effect: Enable/Disable salvage craft in support for the mission.

9.
settxtbuildingname(BuildingID, "BuildingName");

BuildingID - number from the editor for building.
"BuildingName" = "New text building name"

Effect: Display "BuildingName" text as building name in mission.
Works for Buildings, Turrets amd Gates

10.
teleporttopoint(PartID, position);

PartID - part id for mover, obtained from squadID from the editor using (getunitmates(squadID)) from squad ID.
position is real position[3], x,y and z coordinates from the editor.
example:
apoint[0] = -704;
apoint[1] = -5013;
apoint[2] = 128;
if (isalive(2050)) then
teleporttopoint(2050,apoint);
LopGGG = False;
endif;
Note - 2050 is part number of first player unit.
Effect: Teleport unit to position.
works for all movers.

11.
gettargetrelativeposition(TargetID, range, angle)

integer TargetID = gettarget(-1),
real range, angle.
set range and angle from the selected unit to target and store values to
range and angle variables.

12.
getrelativepositiontotarget(TargetID, distance, flag = 2, newPoint)

integer TargetID = gettarget(-1),
real distance - distance you want from target,
real[3] newPoint - coordinates for the new point.

13.
setbrain(PartID, brainName);

PartID - number from the editor for buildings, part id for mover (getunitmates(squadID)) from squad ID.
brainName - the name of the brain file without extension.

Effect: set new brain file to unit.

14.
setobjectivetype(objectiveID, type)

type (invisible -1, primary 1, secondary 2);

15.
checkobjectivetype(objectiveID)

16.
togglesensorstrike;
Effect: Enable/Disable sensor probe in support for the mission.

17.
toggleartillerypiece;
Effect: Enable/Disable artillery piece in support for the mission.

18.
toggleairstrike;
Effect: Enable/Disable air strike in support for the mission.

19.
New ABL command: setmissiontune(tuneID)
tuneID - music ID number from sound.snd

20.
setmechgesture(MechID, gestureID);

MechID - number from the editor for buildings, part id for mover (getunitmates(squadID)) from squad ID.
gestureID - (0,1,2,3,4,5,6,7 (fallen backward),8,..)

Effect: FOR DISABLED MECHS ONLY. set mech gesture to be fallen,...

21.
destroymechbodylocation(MechID, locationID);

MechID - part id for mover (getunitmates(squadID)) from squad ID.
locationID - ( 0 - HEAD, 1 - CTORSO, 2 - LTORSO, 3 - RTORSO, 4 - LARM, 5 - RARM, 6 - LLEG, 7 - RLEG,)

Effect: Destroy selected mech body location.

22.
damagemecharmor(MechID);

MechID - part id for mover (getunitmates(squadID)) from squad ID.

Effect: Random damage to all front mech armor locations.

23.
setrepairtruckenabled(state);
state can be True or False;
Effect: Enable/Disable repair truck in support for the mission.

24.
setsalvagecraftenabled(state);
state can be True or False;
Effect: Enable/Disable salvage craft in support for the mission.

25.
New ABL command - hirepilot(pilotFileName)
Effect: Add pilot to players roster; Example: hirepilot("pmwlynx");

26.
addnewpilot(MechID, "pilotFileName", "brainFileName");
MechID - part id for mover (getunitmates(squadID)) from squad ID.
pilotFileName - name of the pilot file (pmwlynx).
brainFileName - name of the brain file (pbrain, dredattack01,...)

Effect: Create new pilot from file and add to selected mech. It also sets the brain file.
If the pilot exists it will overwrite the pilot. DO NOT add pilots that are used in SP campaign before, it will erase
all accumulated experience. Use only to add new pilots. If the pilot is already on players roster, pilot icon will
not change. Must use script to remove mover from player then add it back after calling this command eg.:
addnewpilot(Commando, "pmwgator", "pbrain");
addmovertoplayer(Commando, 0, 2); //remove commando from player roster and add to allied team
addmovertoplayer(Commando, 0, 0); //add commando to player roster

27.
(the same as addnewpilot but can be used for players units only - sets pilot icon correctly)
addnewpilottoplayer(MechID, "pilotFileName", "brainFileName");
MechID - part id for mover (getunitmates(squadID)) from squad ID.
pilotFileName - name of the pilot file (pmwlynx).
brainFileName - name of the brain file (pbrain, dredattack01,...)

Effect: Create new pilot from file and add to selected mech. It also sets the brain file.
If the pilot exists it will overwrite the pilot. DO NOT add pilots that are used in SP campaign before, it will erase
all accumulated experience. Use only to add new pilots. Allied team must exist in mission and must have at least one unit.

28.
numfriendswithinradius(PartID, radius);

PartID - part id for mover (getunitmates(squadID)) from squad ID (or -1=self for use in warrior brain).
radius - radius around unit to look for friends.

example:
num_friends1 = numfriendswithinradius(Commando, 600.0);
-------------------------------------------------------------------------
29.
numenemieswithinradius(PartID, radius);

PartID - part id for mover (getunitmates(squadID)) from squad ID (or -1=self for use in warrior brain).
radius - radius around unit to look for enemies.

example:
num_enemies1 = numenemieswithinradius(Commando, 500.0);

30.
ablprint("FileName", AnyValue);

For debugging in ABL scripts.
FileName - Name of the file that will be created in data folder.
AnyValue - any variable or value you want ot print to file, chars or strings must be "example_text".

example:
ablprint("Friends1", num_friends1);
ablprint("Enemies1", num_enemies1);

31.
isrefit;

Return value: true if mover is refit vehicle. For use in warrior brain file.

32.
autorepairwithinradius(PartID, radius);

PartID - part id for mover (getunitmates(squadID)) from squad ID (or -1=self for use in warrior brain).
radius - radius around unit to look for friendy units that need repairs, if no enemies around.

Repair all damaged friendly mechs within radius if no enemies around.
example:
autorepairwithinradius(-1, 500.0);

33.
setunitforcegroup(PartID, new_force_group);

PartID - part id for mover (getunitmates(squadID)) from squad ID.
new_force_group - number between 1 and 9.

Assign selected unit to new force group.

34.
setcampaignglobalvar(VariableNumber, VariableValue);

VariableNumber - number of global avriable (5 for now = 0,1,2,3,4).
VariableValue - integer value to be set to selected variable.

example:
setcampaignglobalvar(0, 3);

35.
getcampaignglobalvar(VariableNumber);

VariableNumber - number of global avriable (5 for now = 0,1,2,3,4).
return value - value stored in selected global variable.

example:
GlobalVarValue0 = getcampaignglobalvar(0);

36.
setbrainNew(PartID, brainName);

PartID - part id for mover (getunitmates(squadID)) from squad ID or -1=self.
brainName - the name of the brain file without extension.

Effect: set new brain file to unit.

37.
needsrefit;
True if unit needs refit

38.
scanareacapture(radius)
radius - radius around unit to look for captureable buildings.

If idle players mechs will scan area for captureable buldings and capture if any.

39.
scanarearepair(radius)
radius - radius around unit to look for repair buildings.

If idle players mechs will scan area for repair bay and repair.

40.
setLargeMsg(0,"My Message",10);

first parameter can be 0 or 1.
0 - instant message for the duration of number of seconds (10),
1 - large message box (full screen) with press enter to continue, in this case third parameter is not important.

Effect: display "My Message" in full screen message box.

41.
isselected;
true if current unit is selected by player - for use in pbrain.

42.
setfixedbuildingrp(PartID, number_of_resource_points);

PartID - number from the editor for buildings,
number_of_resource_points - integer number of resource points.

Effect: Set Fixed number of RPs to any building and make it capturable. Works for buildings.
Any building set with this command will have fixed number of RPs when captured.

43.
gettimeoflaststep;

Return: (float) Time of last move step.

44.
iscurtacordermoveorder;

Return: True if current tacorder is move order.

45.
getcurtacordertime;

Return: (float) Time when current tacorder was given.

46.
clearmoveorders;

Effect: Clear all move orders.

Keep in mind that the common abl list above was used for MC2 modding. It is basically coming from MC1 but may include some orders that where not implemented into the MC1 built. Some may be possible to be introduced - some not cause it may be more limit than MC2 in general and based on the fact that completely usable source always only ever existed for MC2!

(c) by RizZen 2020