Author Topic: ABL Scripting Library  (Read 20202 times)

0 Members and 1 Guest are viewing this topic.

I'm not sure if anyone else will find this useful, but I've put together a list of all the (added) ABL commands I could find, as well as some basic knowledge/syntax of ABL scripting. For a list of other commands that seem to work with MCO search google for
"Cmunsta's MCG Campaign Builders Guide II". Some of the commands there don't work, and some have been altered for MCO, but this gives mission designers a place to start looking for creating some truly inspired maps, to keep MCO fresh with new content..... ...


****************************************************************************
--------------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


EDIT :: I've edited this list to add the same color tags as Magic's entries below, this helps find the actual commands against all the comments... :)
« Last Edit: September 28, 2015, 11:11:47 am by magic »

 

Offline magic

  • Moderator
  • 211
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.
« Last Edit: May 04, 2016, 02:14:00 am by magic »

 
Re: ABL Scripting Library
This is great, thanks - have been picking at it almost totally on my own, this will  help me hugely. Thanks Rusty for this!

 
Re: ABL Scripting Library
Yeah, I was mostly picking at it all by myself too, that is the whole reason I put this together. I'm really glad that someone else will benefit from this list too.

Keep up the good work!

 
Re: ABL Scripting Library
RustyDios:
 your list is good. Unfortunately not all of the original commands listed here are fully implemented or working in MC2.
Some may be remainders in the code from former MC games (this code was not completely fresh coded for MC2).
Some commands are not working in scripts nor brain files; some are not fully implemented or just working for units but not buildings, etc.

Just an additional information for those who might want to use this list and trust it. :shaking:

Magic's list works as outlined because these commands were added after the source code release. :)

 
Re: ABL Scripting Library
Hello Wolfman-x !

Which commands in this list don't work ?
Every command I've highlighted in red was pulled from Magic's version.txt, Magic's mission.abl's and/or Magic's warriorbrains.abl's. All of which are currently in-use throughout Magic's campaign in some form, for MCO.

Some commands (as noted in most places) are for specific use within a mission or a warriorbrain only.

If you are referring to "Cmunsta's MCG Campaign Builders Guide II", then please re-read my opening statement, I've already said that some of those commands might not work as intended in MCO, it being a guide for MCG... but it has been a great source of information for me that I thought deserved an honourable mention.

If you could point out what isn't working as intended then I can adjust/edit the original post to stop the spread of mis-information, because I really don't like my list being slated as "for those who might want to use this list and trust it. :shaking: " .

Maybe I'm just not a keen fan of the panic/shaking emote.... ....

Cheers :)

 
Re: ABL Scripting Library
For example try to remove a building using

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

..and CUMSTA"s work was focused on MC1: that is what I referred to with my comments on former MC versions.
The code is partially MC1 code.

This was no criticism in your listing more an additional information for other potential users from my own experience.

 
Re: ABL Scripting Library
Thanks for the sticky ! I feel honoured !

 

Offline magic

  • Moderator
  • 211
Re: ABL Scripting Library
Second post above is updated with all my up-to-date ABL commands.

 
Re: ABL Scripting Library
Wow !.. Thanks for the awesome list Magic !

That is some seriously cool scripting/abl commands for builders/editors/creators to add some spice to their maps....

 

Offline Karl

  • 211
Re: ABL Scripting Library
RD, have you considered turning this list into a series of applied tutorials?

 

Offline Karl

  • 211
Re: ABL Scripting Library
Also, a question...

Does anyone know how to get the UnitIDs for the players force?
eg;
If I take 5 mechs on a mission and I want one of those mechs to change sides halfway through the mission because of... reasons...
how would I determine the UnitID?

GetUnitMates(SquadID, INT); doesnt seem to work and that probably makes sense as the mechs/units the player takes on the mission are not in the .FIT and therefore probably dont have a SquadID.

Thoughts?

 
Re: ABL Scripting Library
RD, have you considered turning this list into a series of applied tutorials?

No, sorry, I haven't thought of doing any applied tutorials and I'm not sure I'd have the time or resources to make anything worthwhile. I'm not sure where to start with making tutorials and have never done anything like that to the depth I think it would need to be a comprehensive guide/tutorial. (It's still going my to-do list though, thanks for the idea! )...


 

Offline magic

  • Moderator
  • 211
Re: ABL Scripting Library
First players unit is 2050 - fixed.
Second is 2051, etc.

 

Offline Karl

  • 211
Re: ABL Scripting Library
YUS!!! Thanks Magic

 

Offline Karl

  • 211
Re: ABL Scripting Library
Maybe I should do a tutorial map series...

I am thinking a single map with as many potenital scenarios on it as possible.

The idea would be that a would be mission artist would open the map at part 1, look at the units, record the vital details (partIDs, map coordinates) then basically have to uncomment  sections of the abl, add the details.

This way they could be introduce to the abl commands a couple at a time, learning the coding philosophy at the sametime as how to combine commands to get an advanced affect in game, while then being able to play their changes immediately.

The tutorial would walk them through uncommenting eventually a whole scenario.

Thoughts community?

The goal would be to take away the major hurdle of abl coding for your average user, helping them turn basic missions into good missions via recyclable code blocks and concepts

 

Offline magic

  • Moderator
  • 211
Re: ABL Scripting Library
List updated in second post...

 

Offline zzc

  • 26
Re: ABL Scripting Library
Is there a command to get every unit on the AI team to attack nearest target? Aside from giving every unit the same brain/squad number...

 

Offline magic

  • Moderator
  • 211
Re: ABL Scripting Library
No, they will try to attack the nearest target, based on their weapon ranges by default.