MissionScriptsDynamic - LauraRozier/kam_remake GitHub Wiki

Missions can be easily extended with custom scripts to add special events to them. Each missions script is located in \Maps\map_name\map_name.script file, which can be opened in any plain text editor (e.g. Notepad). Scripts are written in !PascalScript language (syntax is very similar to usual Pascal).

Script has 3 ways of interacting with the game - Events, States and Actions. Events get called by the game when they happen. States are values that can be queried from the game. Actions are way to tell the game what to do. Scripts get verified on mission load and any errors are output in a message to a player.

Script file consists of several parts:

//Global constants section,  accessible from any place in the script.
//Useful to make parameters easy to change in one place.
const MY_CONSTANT = 7; //by convention constants are written in upper case
//Global variables section, accessible from any place in the script and stored in game memory
var
	I: Integer; //variable number
	A: array [0..3] of Boolean; //array of 4 booleans accessible as A[0], A[1] etc.

//Event handler, when the event happens ingame this function gets called
procedure OnHouseBuilt(..); //Each event has different input parameters list
var //Local variables, they exist only within this procedure
	L: Integer; //variable number 
begin
	//Event code
	L := 7; //assignment of number to a variable
	Actions.ShowMsg(L,'hello'); //Calling a games action with 2 parameters: L and a string 'hello'
end;

//Event handler for "tick" event, which happens 10 times per second (on each game logic update).
procedure OnTick;
begin
	//Code here
	if States.GameTime = 60 then //Check game time and show a message
		Actions.ShowMsg(0,'<>'); //<> is markup to fetch text ID 3 from LIBX translation file
end;

Here is Battle Tutorial script explained:

procedure OnPlayerDefeated(aIndex: Integer);
begin
	if aIndex = 2 then Actions.ShowMsg(0, '<>');
	if aIndex = 3 then Actions.ShowMsg(0, '<>');
	if aIndex = 4 then Actions.ShowMsg(0, '<>');
end;

procedure OnTick;
begin
	if States.GameTime = 20 then 
		Actions.ShowMsg(0, '<>');
end;

Above line means that when PlayerDefeated event comes from the game, we check the index of the player that was defeated (aIndex) and issue a command to show certain message to specified player (0, who is human). Also, each tick we check the games time and on tick 20 (2 seconds from mission starting) we show another message. Message text is retrieved from the mission's .LIBX file using the markup <$123> (fetches text ID 123 from LIBX), meaning it will be in the player's own language if a translation has been made.

####Global campaign data This feature allows you to store data between missions in a campaign. First, create a file in your campaign folder campaigndata.script. In that file you must put the definition of the data you want to store. We recommend using a record so you can easily add more data in the future. Here is an example campaigndata.script:

record
	Mission1: record
		SoldiersRemaining: Integer;
		TimeOfVictory: Integer;
	end;
	Mission2: record
		Army: array of record
			UnitType, X, Y: Integer;
		end;
		TimeOfVictory: Integer;
	end;
end;

The data can then be accessed and modified with the global variable CampaignData (the type is TCampaignData), for example: CampaignData.Mission1.TimeOfVictory. The data is stored in the user's campaign progress file (Saves\Campaigns.dat).

• The data will be loaded when a campaign mission is started, and saved whenever the user exits, regardless of whether they won the mission. This allows you to record information about failed attempts. If you only want to record data when the user wins the mission, you should only save data into the global variable CampaignData within the event OnPlayerVictory.
• The user may go back and play an earlier mission, so it is advised to separate the data which each mission will modify, as shown in the above example. In other words, don't reuse the same structures in every mission since missions might be played out of order.

####Other resources

• Lookup tables (unit/house/ware types): MissionScriptsLookups
• Scripting tutorial: MissionScriptsDynamicTutorial
• Scripting hints: MissionScriptsHints
• Language reference: http://www.delphibasics.co.uk/ (note: our scripts don't have all the features of Delphi, but this is still a useful reference)

####Events

procedure OnHouseBuilt(aHouseID: Integer);
begin
	//code
end;

####States All states parameters are numeric and get mapped to unit/house types according to default tables used in DAT scripts.

States are queried in a form States.STATE_NAME(STATE_PARAMETERS) like so:

`if States.PlayerCount > 5 then
	A := States.UnitCount(1);

####Actions All action parameters are numeric and get mapped to unit/house types according to default tables used in DAT scripts.

Actions are placed in a form Actions.ACT_NAME(ACT_PARAMETERS); like so:

if States.GameTime = 300 then
	Actions.PlayerDefeat(0); //Defeat 1st player