10. FinalAlert2: YRTM User Scripts

FinalAlert 2 TM: Yuri's Revenge introduces a completely new user script interpreter. These scripts are not the same like Scripttypes, but they are used solely by FinalAlert2: Yuri's RevengeTM directly. They allow you to add new functionality to the editor!

To access the script editor, select Maptools->Tool Scripts. You can select the script you want to execute and click Run. The scripts already shipped with the editor are all safe and wonīt cause any problems. However, if you run a self-made script or run a script you get from somewhere else, you should really save your map before running it, although FA2:YRīs interpreter is quite safe.

A good script to start with is "Add Reveal Map Debug Trigger". Run it, and then close the script interpreter again. Then go into Edit->Triggers, and check out the new trigger. Easy, isnīt it?

Every script should have a descriptive name. Try around with the different scripts, but save your map first.

Weīll now take a look at making own scripts. You should really know some programming before doing this, as the Script language is quite similar to programming. If you donīt know any programming, it might be difficult for you to understand the script language. Also, you should know about INI editing for maps, if you want to implement extended functionality.

At first, you should try to open a already existing script file. Use Windows Explorer to the Scripts subdirectory in your FA2:YR directory. The double click on "Add Reveal Map Debug Trigger.fscript". Select notepad as editor.

Youīll now see a typical script. Itīs a small script to get you started. As you may have noticed, // is used for comments: The rest of the line is ignored. This is similar to C++. Any script contains only function calls and jumplines (no jumpline in this script however). There is no explicit variable declaration, but there are variables (example: %TriggerID% is filled with the ID of the trigger that has been added through the AddTrigger(); function). Note that for every function call, all parameters must be enclosed in ", and divided by commas. Now what does this script do?
AskContinue(); displays a Message Box and asks if the user wants to continue. If the user presses no, the script will quit. The AddTrigger(); call does the obvious: In the first parameter we specify a variable that will be filled with the trigger ID, in the second parameter we specify the trigger INI line, in the third the event INI line, and in the fourth the action INI line. Now what are those INI lines? You can retrieve them if you make a new Trigger in the trigger editor, exactly as you want it to be. Then, you start FA2:YRīs INI editor in Edit->INI Editor and go to the Triggers section. There you search for your trigger (using the name you gave to it). Note the ID (the key name), and copy the content of the ID to the clipboard. You now have the trigger INI key, but not yet the events and actions INI keys. To retrieve those, go to the Events and Actions sections and copy the key values for the ID you noted. Thatīs it!

Another feature are Jumplines. You define them using
:NameOfJumpline:
The JumpTo function is used to jump to this point of the script, which can be used to create loops.

Every function in FA2:YRīs script language except And(); and Or(); has a certain parameter count. For example, the AddTrigger function has 4 parameters. However, you may specify a 5th parameter! Now what does this mean? Well, it describes a boolean value (true/false, yes/no, 1/0). If this additional parameter is set, FA2:YR will only execute the function if this parameter is true (again, this does not apply to And(); and Or();). Very useful, especially for loops. You can of course use a variable for this parameter, which will be the case in most circumstances.

If you have read up to this point, you should now know about the basics of scripting FA2:YR. Be aware that some things might not work out exactly as you want because of FA2:YRTMīs internal technical circumstances regarding Infantry, Structures, etc. If you look at the shipped scripts, you should find out how to do certain things, though.


List of predefined Variables (those cannot be overwritten using SetVariable(); or any other function!):

%WaypointCount% - Number of waypoints
%InfantryCount% - Number of infantry
%AircraftCount% - Number of aircraft
%UnitCount% - Number of vehicles
%TerrainCount% - Number of terrain objects
%Theater% - Map theater
%Width% - Map width
%Height% - Map height
%IsoSize% - equals width+height of map
%PlayerCount% - 1 for singleplayer maps, number of players for multiplayer maps
%HousesCount% - Number of houses defined
%CountriesCount% - Number of countries defined
%DeleteAllowed% - Is deleting currently allowed?
%AddAllowed% - Is adding objects & triggers currently allowed?
%SafeMode% - Is SafeMode enabled?


List of functions FA2:YRTM supports (reminder: as you know, every function except And(); and Or(); can have an additional boolean parameter as described above):

All normal parameters are written inversed, parameters that only take a variable are written underlined. Underlined parameters are usually filled with function output.


Script specific:

JumpTo(Jumpline);
Script jumps to Jumpline. Be careful with this function! You may cause infinite loops if you are not! Remember the possible boolean parameter!

SetSafeMode(Enabled, Reason);
Sets safe mode to Enabled which is "TRUE" or "FALSE". If you set safe mode to FALSE, which is required for setting INI keys and other functions, the script will ask the user if he wants that and will display your Reason.

AllowDelete();
If your script wants to delete objects or triggers, you need to call this function. The script will, like SetSafeMode(); ask the user.

AllowAdd();
If your script wants to add objects or triggers, you need to call this function. The script will, like SetSafeMode(); ask the user.

SetAutoUpdate(Enabled);
Set AutoUpdate to FALSE for faster script execution. This will prevent FA2:YR to update the report window after every function call.

RequiresMP();
This script requires a multiplayer map. If the map is no multiplayer map, script will cancel.

RequiresSP();
This script requires a singleplayer map. If the map is no singleplayer map, script will cancel.

Cancel();
Cancels script. Usually used with a boolean parameter.


Output:

AskContinue(Message);
Shows a message box and exits script if user presses No, else continues.

Message(Message, Caption);
Shows a message box with specified Message and Caption

Print(Text);
Prints the specifed text into the report window.


User Input:

Ask(Variable,Message, Caption);
Shows a message box sets Variable to "0" if user presses No, else sets Variable to "1".
UInputGetInteger(Variable,Message, Min, Max);
Shows a input box with specified Message. If Min and/or Max are not "", they specify the minimum and maximum value necessary. Variable will be filled.
UInputGetString(Variable,Message);
Shows a input box with specified Message. Variable will be filled.
UInputGetHouse(Variable,Message);
Shows a dialog that allows the user to select a house. Variable will be filled.
UInputGetCountry(Variable,Message);
Shows a dialog that allows the user to select a country. Variable will be filled.
UInputGetTrigger(Variable,Message);
Shows a dialog that allows the user to select a trigger. Variable will be filled.
UInputGetTag(Variable,Message);
Shows a dialog that allows the user to select a tag. Variable will be filled.


Variable modification:

SetVariable(Variable,Value);
Sets the specifed Variable to Value.

Add(Variable,Number);
Adds Number to Variable

Substract(Variable,Number);
Substracts Number from Variable

Multi(Variable,Number);
Multiplies Variable with Number

Divide(Variable,Number);
Divides Variable through Number

Mod(Variable,Number);
Divides Variable through Number, and puts the rest into Variable

Insert(Variable, Text, Position);
Inserts Text at Position into Variable

Remove(Variable,Start, Length);
Removes Length characters beginning Start from Variable

Replace(Variable,Old, New);
Replaces Old with New for Variable

Trim(Variable);
Removes spaces at the left and right of Variable

Not(Variable);
If Variable is true, Variable will be set to false. If Variable is false, Variable will be set to true.

And(Variable, Value1, ...);
This function can take any amount of parameters, at least 2. Variable will be set if all of the following parameters are set to true.

Or(Variable, Value1, ...);
This function can take any amount of parameters, at least 2. Variable will be set if any of the following parameters is set to true.

Length(Length,String);
Retrieves the Length of a string

GetChar(Char,String, Pos);
Retrieves a specific char from a string at Pos.

Is(Value1,Comparison,Value2,IsTrue);
Compares Value1 and Value2 and sets IsTrue if the comparison is true. Comparison modes:
< Is Value1 smaller than Value2
<= Is Value1 smaller than or equal to Value2
= Is Value1 equal to Value2
>= Is Value1 bigger than or equal to Value2
> Is Value1 bigger than Value2
!= Is Value1 not equal to Value2

ToUpper(Variable);
Changes Variable to upper case

ToLower(Variable);
Changes Variable to lower case

GetRandom(Variable);
Sets Variable to a random value between 0 and 32767.


Support for Param type variables (example Variable="Param1, Param2, Param3"), like Trigger INI values etc.:

GetParam(Param,ParamString, Pos);
Retrieves parameter Pos of ParamString, and puts it into Param

SetParam(ParamStringVariable,Pos, Value);
Changes parameter Pos of ParamStringVariable to Value.

GetParamCount(Count,ParamString);
Counts Parameter count of ParamString and puts it into Count.


Map Editing functions:

SetIniKey(Section,Key,NewValue);
Sets Key in Section to NewValue. Requires SetSafeMode(); to be called with Enabled=FALSE, and the user agreeing.

GetIniKey(Value,Section,Key);
Retrieves value from Key in Section and puts it into Value.

GetHouse(House,Index);
Retrieves House ID and puts it into House.

GetCountry(Country,Index);
Retrieves Country ID and puts it into Country.

Resize(Left, Top, Width, Height);
Resizes map. Max for Width and Height is 200. User is prompted before resizing map. Similar to the Resize Map dialog.

AddTrigger(NewTriggerID,TriggerINI, EventINI, ActionINI, AddTag);
Adds a trigger to the map using TriggerINI, EventINI and ActionINI, as they are saved in the map files. NewTriggerID will be set to the ID of the created trigger. Set AddTag to "no" or "false" if you donīt want that a Tag is created automatically. AllowAdd(); must be called before.

AddAITrigger(NewAITriggerID,AITriggerINI);
Adds an AI trigger to the map using AITriggerINI, as it is saved in the map files. NewAITriggerID will be set to the ID of the created trigger. AllowAdd(); must be called before.

AddTag(NewTagID,TagINI);
Adds a tag to the map using TagINI, as it is saved in the map files. NewTagID will be set to the ID of the created tag. AllowAdd(); must be called before.

SetWaypoint(ID, X, Y);
Sets the waypoint ID to the map position X,Y. If you donīt give an explicit ID but an empty ID, FA2:YR will automatically select a free ID. If you set the ID to a already existing waypoint ID, SetWaypoint(); will fail except you called SetSafeMode(); with Enabled set to FALSE, and the user agreeing.

GetWaypointPos(ID,X, Y);
Sets X and Y to the position values of Waypoint ID. If the waypoint ID does not exist, X and Y are both set to 0.

GetFreeWaypoint(ID);
Sets ID to the first free waypoint ID.

AddTerrain(Type, X, Y);
Adds new terrain to the map.
AllowAdd(); must be called before.

AddSmudge(Type, X, Y);
Adds a smudge to the map.
AllowAdd(); must be called before.

AddInfantry(INIString);
Adds a new infantry unit to the map. INIString must have 14 parameters. They are: House, Type, Strength, Y, X, SubPos, Action, Direction, Tag, Veteran, Group, On Bridge, Recruitable, AI Recruitable
Itīs best to copy the INIString out of a map using the List Objects script that is shipped with FA2:YR.
AllowAdd(); must be called before.

AddVehicle(INIString);
Adds a new vehicle unit to the map. INIString must have 14 parameters. They are: House, Type, Strength, Y, X, Direction, Action, Tag, Veteran, Group, On Bridge, Follow ID, Recruitable, AI Recruitable
Itīs best to copy the INIString out of a map using the List Objects script that is shipped with FA2:YR.
AllowAdd(); must be called before.

AddAircraft(INIString);
Adds a new aircraft unit to the map. INIString must have 12 parameters. They are: House, Type, Strength, Y, X, Direction, Action, Tag, Veteran, Group, Recruitable, AI Recruitable
Itīs best to copy the INIString out of a map using the List Objects script that is shipped with FA2:YR.
AllowAdd(); must be called before.

AddStructure(INIString);
Adds a new structure to the map. INIString must have 17 parameters. They are: House, Type, Strength, Y, X, Direction, Tag, Sellable, Rebuild, Energy, Upgrade Count, Spotlight mode, Upgrade 1, Upgrade 2, Upgrade 3, AI Repairs, Show Name
Itīs best to copy the INIString out of a map using the List Objects script that is shipped with FA2:YR.
AllowAdd(); must be called before.

DeleteTerrain(Index);
Deletes terrain object. Index must be between 0 and %TerrainCount%-1.
AllowDelete(); must be called before.

DeleteInfantry(Index);
Deletes infantry. Index must be between 0 and %InfantryCount%-1.
AllowDelete(); must be called before.

DeleteAircraft(Index);
Deletes aircraft. Index must be between 0 and %AircraftCount%-1.
AllowDelete(); must be called before.

DeleteVehicle(Index);
Deletes vehicles. Index must be between 0 and %VehicleCount%-1.
AllowDelete(); must be called before.

DeleteStructure(Index);
Deletes structure. Index must be between 0 and %StructureCount%-1.
AllowDelete(); must be called before.

IsInfantryDeleted(Deleted,Index);
Sets Deleted to true if Infantry Index is deleted.

IsTerrainDeleted(Deleted,Index);
Sets Deleted to true if Terrain Index is deleted.

GetInfantry(Data,Index);
Retrieves INI data of Infantry Index. Use IsInfantryDeleted(); to check if this infantry is deleted before (this is necessary because of internal implementation details)! You can use data of deleted infantry though, although this might not be senseful.

GetAircraft(Data,Index);
Retrieves INI data of Aircraft Index.

GetStructure(Data,Index);
Retrieves INI data of Structure Index.

GetVehicle(Data,Index);
Retrieves INI data of Vehicle Index.