Editing MG/Lua

[[Lua]] is the scripting language used in [[MegaGlest]]'s [[scenarios]]. It allows scenarios to expand and do things not normally possible in regular games of Glest. This page lists all the Lua commands available in MegaGlest. For information on how to create scenarios and working with Lua in general, see [[Lua]].

==Text==
=== showMessage(text, header) ===
Displays a message box on the screen, that will have to be dismissed by the player.

Parameters:<br />
'''text''' - a string identifying the'' text'' from a language file.<br />
'''header''' - a string identifying the'' title bar text ''from a language file.

=== addConsoleText(text) ===
Displays a message in the game console messages area. Will remain until the user-specified message timeout has elapsed.

Parameters:<br />
'''text''' - a string identifying the'' text'' from a language file.

=== addConsoleLangText(text)===
Displays a message in the game console messages area. Will remain until the message timeout has elapsed. Works like <tt>displayFormattedText()</tt> besides the fact that <tt>addConsoleLangText()</tt> uses the language-file for resolving the format of the text.

Parameters:<br />
'''text''' - a string identifying the ''text'' from a language file.

=== setDisplayText(text) ===
Displays a message at the top of the screen. Will remain until dismissed with <tt>clearDisplayText()</tt> or <tt>setDisplayText()</tt> is called again.

Parameters:<br />
'''text''' - a string identifying the ''text'' from a language file.

===displayFormattedText (fmt, ...)===
Works like <tt>setDisplayText()</tt> but allows formatting of text.

Parameters:<br />
'''fmt''' - a string identifying the format of text ''(like in printf)''.<br />
'''...''' - variable parameter list to pass values to fmt ''(like in printf)''.

===displayFormattedLangText (fmt, ...)===
Works like <tt>displayFormattedText()</tt> but uses the language-file for resolving the format of the text.

Parameters:<br />
'''fmt''' - a string identifying the format of text ''(like in printf)''.<br />
'''...''' - variable parameter list to pass values to fmt ''(like in printf)''.

=== clearDisplayText() ===
Clears the message from the top of the screen previously set with <tt>setDisplayText()</tt>.

==Unit==
=== createUnit(unitID, faction, pos) ===
Creates a unit. If ''pos'' is occupied, a nearby cell will be chosen. The game attempts to keep a 2 cell 'border' between the new unit and other units or objects (eg, trees). If a position can not be found, the game crashes.

Parameters:<br />'''unit''' - name of a unit in the loaded factions.<br />'''faction''' - the index of the faction this unit will belong to.<br />'''pos''' - an array of two elements, specifying the co-ordinates {x,y}.
=== createUnitNoSpacing(unitID, faction, pos) ===
Same as above, but position is exact.


===destroyUnit(unitID)===
Destroys a unit.

Parameters:<br />
'''unitID''' - the ID of the unit to destroy.

=== morphToUnit(unitID, morphName, ignoreRequirements) ===
Morphs a unit into another unit of type morphName. If ignoreRequirements is set to 1 then the morph is executed even if the unit does not satisfy the morph requirements.

Parameters:<br />
'''unitID''' - the ID of a unit.<br />
'''morphName''' - the name of the morph to execute.<br />
'''ignoreRequirements''' - a 0 or 1 value indicating whether to respect morph requirements (0) or not (1)

===setUnitPosition(unitId, pos)===
"Teleports" unit to the given position (places the unit there instantly, no move animation).

Parameters:<br />
'''unitID''' - the ID of the unit to move.<br />
'''pos''' - the x and y coordinates of the location you wish to move the unit to (note the exact position may not be the supplied position, as the unit may be slightly staggered, particularly if a unit already exists in the given location).

=== moveToUnit(unitID, destUnitID) ===
Move unitID to the location of destUnitID.

Parameters:<br />
'''unitID''' - the ID of the unit to move (starting location).<br />
'''destUnitID''' - the ID of the unit to move to (ending location of unitID). This would essentially make unitID 'follow' destUnitID until it arrives at the location of destUnitID.

===giveStopCommand(unitID)===
Gives a stop command to a specific unit.

Parameters:<br />
'''unitID''' - the ID of a unit that has a stop command.

===giveAttackCommand(unitID, unitToAttackID)===
Instruct a unit to carry out a command of type 'attack' on a specific unit.

Parameters:<br />
'''unitID''' - the ID of a unit that has an attack command.
'''unitToAttackID''' - the ID of a unit that should be attacked.

=== giveAttackStoppedCommand(unitID, valueName, ignoreRequirements) ===
Executes the attack stopped command for a unit specified by 'valueName'. If ignoreRequirements is set to 1 then the command is executed even if the unit does not satisfy the command requirements.

Parameters:<br />
'''unitID''' - the ID of a unit.<br />
'''valueName''' - the name of the attack stopped command to execute.<br />
'''ignoreRequirements''' - a 0 or 1 value indicating whether to respect command requirements (0) or not (1).

=== giveResource(resource, faction, amount) ===
Give an amount of a specified resource to a player, negative values are valid and have the obvious effect.

Parameters:<br />
'''resource''' - a corresponding resource in the techtree.<br />
'''faction''' - the index of the faction to give the resource.<br />
'''amount''' - the amount of resource the faction will receive.

=== givePositionCommand(unitID, command, pos) ===
Instruct a unit to carry out a command of type 'attack' or 'move'. The unit being given the command must have such a command available.

Parameters:<br />
'''unitID''' - the ID of a unit that has an attack and/or move command.<br />
'''command''' - the type of command to carry out ('attack' or 'move')<br />
'''pos''' - an array of two elements, specifying the co-ordinates {x,y}.

=== giveProductionCommand(unitID, produced) ===
Instruct a unit to carry out a command of type 'produce'. The unit being given the command must have such a command available.

Parameters:<br />
'''unitID''' - the ID of a unit that is to produce the new unit.<br />
'''produced''' - the name of the unit to produce.

=== giveUpgradeCommand(unitID, upgrade) ===
Instruct a unit to carry out a command of type 'upgrade'. The unit being given the command must have such a command available.

Parameters:<br />
'''unitID''' - the ID of the unit to perform the upgrade.<br />
'''upgrade '''- the name of the upgrade to perform.

===giveKills(unitID, amount)===
Gives a specified unit a certain number of kills (which can be used to level them up).

Parameters:<br />
'''unitID''' - The ID of the unit to give the kills to.<br />
'''amount''' - The number of kills given.

===selectUnit(unitID)===
Selects the specified unit.

Parameters:<br />
'''unitID''' - The ID of the unit to select.

===unselectUnit(unitID)===
Unselects the specified unit (provided it's already selected).

Parameters:<br />
'''unitID''' - The ID of the unit to unselect.

===addUnitToGroupSelection(unitID, groupIndex)===
Adds the unit to a group, assigned a user defined group index.

Parameters:<br />
'''unitID''' - The ID of the unit to select.<br />
'''groupIndex''' - A number to identify the group.

===removeUnitFromGroupSelection(unitID, groupIndex)===
Removes the unit from a group of the defined group index.

Parameters:<br />
'''unitID''' - The ID of the unit to select.<br />
'''groupIndex''' - The previously assigned index of the group.

===recallGroupSelection(groupIndex)===
Reselects a previously defined group by its group index.

Parameters:<br />
'''groupIndex''' - The previously assigned index of the group.

===highlightUnit(unitID, radius, thickness, colour)===
Places a coloured circle around a unit.

Parameters:<br />
'''unitID''' - unit ID of the target unit.<br />
'''radius''' - the radius, in Glest tiles, of the circle.<br />
'''thickness''' - thickness of the circle.<br />
'''colour''' - the colour of the circle.

===unhighlightUnit(unitID)===
Removes a previously placed highlight from a unit.

Parameters:<br />
'''unitID''' - unit ID of the target unit.

==Game==
=== setCameraPosition(pos) ===
Move the camera to the coordinates of pos.

Parameters:<br />
'''pos''' - an array of two elements, specifying the co-ordinates {x,y}.

===togglePauseGame(pauseStatus)===
Toggle the pause state of the existing game.

Parameters:<br />
'''pauseStatus''' - 0 indicates normal game play, 1 indicates a paused game

=== setPlayerAsWinner(factionID) ===
Sets the player with index faction ID as the winner. Would typically be followed by <tt>endGame()</tt>.

Parameters:<br />
'''faction '''- the index of the faction.

=== endGame() ===
Ends the scenario, bringing up the "you win" screen and asking the player if they want to leave the game. Usually would be called after <tt>setPlayerAsWinner()</tt> when victory conditions have been met.

=== loadScenario(scenario, keepFactions) ===
Loads another scenario from inside an existing scenario. The new scenario must have the same techtree and factions, but map, tileset can change. 

Parameters:<br />
'''scenario''' - the name of the scenario to be loaded.<br />
'''keepFactions''' - True to call the next scenario with existing factions or false to call the next scenario with only newly defined factions in the new scenario

===setAttackWarningsEnabled(enabled)===
Enables or disables the attack warning system for the player.

Parameters:<br />
'''enabled''' - A boolean true or false value, with true enabling the attack warning system and false disabling it.

===getAttackWarningsEnabled()===
Returns the current status of the attack warnings system (true if enabled, false if disabled).

==AI==
===enableAi(faction)===
Enables a factions AI. All of the faction's units will move with this command.

Parameters:<br />
'''faction '''- the index of the faction.

===disableAi(faction)===
Disables a factions AI. None of the faction's units will move with this command.

Parameters:<br />
'''faction '''- the index of the faction.

===getAiEnabled(faction)===
Checks the enabled status of a factions AI. Returns 0 if the AI is disabled, and 1 if enabled.

Parameters:<br />
'''faction '''- the index of the faction.

===enableConsume(faction)===
Enables a factions requirement to consume resources like food. All of the faction's units will consume food type resources with this command.

Parameters:<br />
'''faction '''- the index of the faction.

===disableConsume(faction)===
Disbles a factions requirement to consume resources like food. All of the faction's units will not consume food type resources with this command.

Parameters:<br />
'''faction '''- the index of the faction.

===getConsumeEnabled(faction)===
Checks the consume status of a factions AI. Returns 0 if disabled, and 1 if enabled.

Parameters:<br />
'''faction '''- the index of the faction.

==Sound==
===playStaticSound(soundFile)===
Play a static sound file specified by 'soundFile'.

Parameters:<br />
'''soundFile''' - the filename of the sound file to play.

===playStreamingSound(soundFile)===
Play a streaming sound file (background music) specified by 'soundFile'.

Parameters:<br />
'''soundFile''' - the filename of the sound file to play.

===stopStreamingSound(soundFile)===
Stop playing a streaming sound file (background music) specified by 'soundFile'.

Parameters:<br />
'''soundFile''' - the filename of the sound file to play.

===stopAllSound()===
Stop playing all sounds

==Events==
===registerCellTriggerEventForUnitToUnit(sourceUnitID, destUnitID)===
Register a cell 'trigger' event. Any time sourceUnit comes next to destUnit the eventID returned by this function will be triggered inside an event called '<cellTriggerEvent>'.

Parameters:<br />
'''sourceUnitID''' - the ID of a unit moves next to destUnit.<br />
'''destUnitID''' - the ID of a unit that source moves next to.

Example:
<syntaxhighlight lang="lua">
<startup>
	unitA = 'guard';
	unitB = 'castle';

	createUnit(unitB, 1, startLocation(2));
	castleUnit= lastCreatedUnit();
	createUnit(unitA, 0, startLocation(2));
	guard= lastCreatedUnit();

	cell_event1 = registerCellTriggerEventForUnitToUnit(guard, castleUnit);
</startup>
<cellTriggerEvent>   
	if triggeredCellEventId() == cell_event1 then 
		clearDisplayText();
		displayFormattedText('You captured the flag!');
		unregisterCellTriggerEvent(cell_event1);
	end
</cellTriggerEvent>
</syntaxhighlight>

===registerCellTriggerEventForUnitToLocation(sourceUnitID, pos)===
Register a cell 'trigger' event. Any time sourceUnit comes into the cell co-ordinates specified by pos, the event called '<cellTriggerEvent>' is triggered using the eventID returned by this function.

Parameters:<br />
'''sourceUnitID''' - the ID of a unit moves next to destUnit.<br />
'''pos''' - the x and y cell coordinates that will trigger the event when sourceUnitID enters the cell

===registerCellTriggerEventForFactionToUnit(sourceFactionID, destUnitID)===
Register a cell 'trigger' event. Any time a unit from sourceFaction comes next to destUnit the eventID returned by this function will be triggered inside an event called '&lt;cellTriggerEvent>'.

Parameters:<br />
'''sourceFactionID''' - the ID of a faction who has at least one unit that moves next to destUnit.<br />
'''destUnitID''' - the ID of a unit that source moves next to.

===registerCellTriggerEventForFactionToLocation(sourceFactionID, pos)===
Register a cell 'trigger' event. Any time a unit from sourceFaction comes into the cell co-ordinates specified by pos, the event called '<cellTriggerEvent>' is triggered using the eventID returned by this function.

Parameters:<br />
'''sourceFactionID''' - the ID of a faction who has at least one unit that moves next to destUnit.<br />
'''pos''' - the x and y cell co-ordinates that will trigger the event when a unit from sourceFactionID enters the cell.

===registerCellAreaTriggerEvent(pos)===
Registers a bounding rectangle as a trigger event. This will be triggered by ANY unit moving in or out of the area. To know which unit, use <tt>triggeredEventAreaEntryUnitId()</tt>.

Parameters:<br />
'''pos''' - the x and y coordinate of the top left point then the bottom right point (eg, {10,10,5,5} would create a box from points (10,10) to (5,5)).

===triggeredEventAreaEntryUnitId()===
Returns the unit ID of the unit who entered a registered cell area trigger event.

===triggeredEventAreaExitUnitId()===
Returns the unit ID of the unit who exited a registered cell area trigger event.

===getCellTriggerEventCount(eventID)===
Returns the number of times the event specified by eventID has been triggered.

Parameters:<br />
'''eventID''' - the ID of a previously registered event

===triggeredCellEventUnitId()===
Can be called in a '&lt;cellTriggerEvent>' to return the unit ID of the unit whom triggered the event.

===unregisterCellTriggerEvent(eventID)===
Unregister the event specified by eventID.

Parameters:<br />
'''eventID''' - the ID of a previously registered event.

===startTimerEvent()===
Registers a timer and returns its unqiue ID, which can later be compared within a '<timerTriggerEvent>' event.

Example:
<syntaxhighlight lang="lua">
<timerTriggerEvent>
	if triggeredTimerEventId() == timer_event1 then
		if timerEventSecondsElapsed(triggeredTimerEventId()) >= captureTheFlagSeconds then
			clearDisplayText();
			displayFormattedText('Your time ran out of time to capture the flag!');
			stopTimerEvent(timer_event1);
			unregisterCellTriggerEvent(cell_event1);
		end
	end
</timerTriggerEvent>
</syntaxhighlight>

===resetTimerEvent(eventID)===
Reset the timer specified by eventID. This function also returns the number of seconds elapsed since the timer started.

Parameters:<br />
'''eventID''' - the ID of a previously registered timer.

===stopTimerEvent(eventID)===
Stop the timer specified by eventID. This function also returns the number of seconds elapsed since the timer started.

Parameters:<br />
'''eventID''' - the ID of a previously registered timer.

===timerEventSecondsElapsed(eventID)===
This function returns the number of seconds elapsed since the timer started.

Parameters:<br />
'''eventID''' - the ID of a previously registered timer.

===triggeredCellEventId()===
This function returns the eventID that is currently triggering a '<cellTriggerEvent>'.

===triggeredTimerEventId()===
This function returns the eventID that is currently triggering a '<timerTriggerEvent>'.

===startEfficientTimerEvent(triggerSecondsElapsed)===
This function creates a timer that will only trigger the timer event after <tt>triggerSecondsElapsed</tt> seconds, then remove the timer.

==Queries==
=== unitPosition(unitID) ===
Returns the current location of a given unit.

Parameters:<br />
'''unitID - '''the unitID of the unit whose position you wish to know.

Example:
<syntaxhighlight lang="lua">
if (unitPosition(myUnit)[1] > 47 and 75 > unitPosition(myUnit)[1] and  unitPostion(myUnit)[2] > 95 ) then
	-- The unit's x co-ord is between 47 and 75, and its y cord is larger than 95.
end
</syntaxhighlight>

=== unitFaction(unitID)===
Returns the faction index of the unit with unitID.

Parameters:<br />
'''unitID''' - The ID of the unit whose faction you wish you check.

=== resourceAmount(resource, faction) ===
Returns the amount of a given resource is possessed by a faction.

Parameters:<br />
'''resource''' - The name of the resource you wish you check.<br />
'''faction''' - The index of the faction to check.

===unitName(unitId)===
Returns the name of the unit whose unit ID was passed into the function.

Parameters:<br />
'''unitID''' - the ID of the unit whose name you wish to know.

=== lastCreatedUnitName() ===
Returns the unit name of the last created unit.

=== lastCreatedUnit() ===
Returns the unit ID of the last created unit.

=== lastDeadUnitName() ===
Returns the name of the last unit to die.

=== lastDeadUnit()===
Returns the ID of the last unit to die.

===lastDeadUnitCauseOfDeath()===
Returns the following depending on how the last unit died:
:None = 0
:Attacked = 1
:Attack boost = 2
:Starved resource = 3
:Negative regeneration = 4

=== lastDeadUnitKillerName() ===
Returns the name of the killer of the last dead unit. Returns empty if the cause of death was not from an attacker (attacked).

=== lastDeadUnitKiller()===
Returns the ID of the killer of the last dead unit. Returns -1 if the cause of death was not from an attacker (attacked).

===lastAttackedUnit()===
Returns the ID of the last unit which was attacked.

===lastAttackedUnitName()===
Returns the name of the last unit which was attacked.

===lastAttackingUnit()===
Returns the ID of the last unit to attack.

===lastAttackingUnitName()===
Returns the name of the last unit to attack.

===getSystemMacroValue(key) ===
Returns the value of the SystemMacro in C++ (e.g. $SCENARIO_PATH, $APPLICATIONPATH, $GAMEVERSION). At the moment it is primary used to get the path to the loaded scenario.

Parameters:<br />
'''key - ''' The name of the SystemMacro you want to get. Usually starts with "$". (e.g. $SCENARIO_PATH, $APPLICATIONPATH, $GAMEVERSION)

Example (will load the file filename.lua in the folder of your scenario):
<syntaxhighlight lang="lua">
dofile(getSystemMacroValue("$SCENARIO_PATH") .. "filename.lua")
</syntaxhighlight>

=== scenarioDir() ===
Does the same as '''getSystemMacroValue("$SCENARIO_PATH")'''. Exist for GAE compatibility.


=== getPlayerName(faction) ===
Returns the name of the player of a given faction.

=== playerName(faction) ===
Does the same as '''getPlayerName(faction)'''. Exist for GAE compatibility.

Parameters:<br />
'''faction''' - The index of the faction you wish to check.

=== unitCount(faction) ===
Returns the number of units a given faction has.

Parameters:<br />
'''faction''' - The index of the faction you wish to check.

=== unitCountOfType(faction, name) ===
Returns the number of units of a specific name a given faction has.

Parameters:<br />
'''faction''' - The index of the faction you wish to check.<br />
'''name''' - The name of the specific unit you wish to check.

===gameWon()===
Returns true if the human player won the game, and false if they did not.

===isGameOver()===
Returns true if the game is over (either by the default game over criteria being met or by calling <tt>endGame()</tt>). Returns false otherwise.

===startLocation(faction) ===
Returns the start location for a given faction as a set of coordinates.

Parameters:<br />
'''faction '''- the index of the faction.

Example:
<syntaxhighlight lang="lua">
createUnit ( "someunit", 0, {startLocation(0)[1] + 5, startLocation(0)[2]} )
</syntaxhighlight>
This would create a unit 5 cells east of startLocation 0.

===setRandomGenInit(seed)===
Generates a random number based on the supplied seed.

===getRandomGen(minVal, maxVal)===
Used with <tt>setRandomGenInit</tt> to get a random number inbetween <tt>minVal</tt> and <tt>maxVal</tt>.

===getWorldFrameCount()===
Retrieves the world frame count, which can be used in seeding random numbers.

===getUnitsForFaction(factionIndex, commandTypeName, field)===
Returns an array (table) of units in the specified faction which:
*If only the commandTypeName is specified, the table will be a list of all units which have that command (such as <tt>attack</tt>).
*If the commandTypeName is empty and only the field is specified (<tt>0</tt> = land, <tt>1</tt> = air), the table will list all units which are in that specific field.
*If both commandTypeName and the field are specified, the table will list all units which have the specified command can can use it on the specified field (such as being able to attack air units).

===getUnitCurrentField(unitId)===
For the specified unit, returns <tt>0</tt> if they are land and <tt>1</tt> if they are in the air field.

==Network==
===networkShowMessageForFaction(text, header, factionIndex)===
Works the same was as <tt>showMessage()</tt>, but only displays the message to the specific faction. Good for network scenarios where it may be beneficial to display different messages to each player.

===networkShowMessageForTeam(text, header, teamIndex)===
Works the same was as <tt>networkShowMessageForFaction()</tt> above, but displays to all players in the specified team.

===showMarker(flashCount, factionIndex, note, textureFile, pos)===
Places a marker on the map at a given location.

Parameters:<br />
'''flashCount''' -  <br />
'''factionIndex''' - index of the faction who "placed" the marker.<br />
'''note''' - note on the marker.<br />
'''textureFile''' - path of texture file to use for marker.<br />
'''pos''' - the x and y cell coordinates of the marker.

===networkSetCameraPositionForFaction(factionIndex, pos)===
Set the camera position for a specific faction.

Parameters:<br />
'''factionIndex''' -  index of the faction whose camera you wish to move.<br />
'''pos''' - x and y coordinates for the camera's position.

===networkSetCameraPositionForTeam(teamNumber, pos)===
Set the camera position for all factions on a team.

Parameters:<br />
'''teamNumber''' -  team number whose camera you wish to move.<br />
'''pos''' - x and y coordinates for the camera's position.

== XML events ==
These are XML tags used to execute Lua code on its specified event. Variables can be used across different events.

<syntaxhighlight lang="xml"><startup>
	<!--
		Code here will be executed once on startup.
	-->
<startup>
<unitCreatedOfType type="unitname">
	<!--
		Code here will be executed every time a unit of the specified
		type is created.
	-->
</unitCreatedOfType>
<unitDied>
	<!--
		Code here will be executed every time a unit dies.
	-->
</unitDied>
<unitAttacked>
	<!--
		Code here will be executed every time a unit gets attacked. 
	-->
</unitAttacked>
<unitAttacking>
	<!--
		Code here will be executed every time a unit is attacking. 
	-->
</unitAttacking>
<resourceHarvested>
	<!--
		Code here will be executed every time a resource is harvested.
	-->
</resourceHarvested>
<gameOver>
	<!--
		Code here will be executed when the game ends.
	-->
</gameOver>
<cellTriggerEvent>
	<!--
		Code here will be executed when cell events activate.
	-->
</cellTriggerEvent>
<timerTriggerEvent>
	<!--
		Code here will be executed when timer events acivate.
	-->
</timerTriggerEvent>
</syntaxhighlight>

==See Also==
*[[Engines#Lua_scripting|Comparison of Lua functions in the engines]]
*[[Lua]]
*[[Scenarios]]

==External Links==
*[http://www.lua.org/pil/ Programming in Lua]
*[http://lua-users.org/wiki/TutorialDirectory Lua tutorials]
*[http://lua-users.org/wiki Lua-Users.org Wiki]
[[Category:MG]]
[[Category:Scenarios]]
[[Category:Lua]]
@@ Line 1: / Line 1: @@
 [[Lua]] is the scripting language used in [[MegaGlest]]'s [[scenarios]]. It allows scenarios to expand and do things not normally possible in regular games of Glest. This page lists all the Lua commands available in MegaGlest. For information on how to create scenarios and working with Lua in general, see [[Lua]].
-Notice: You can’t use the <-operator in within the XML-events. You can use an external script instead or invert the logic.
 ==Text==
@@ Line 140: / Line 138: @@
 '''unitID''' - The ID of the unit to give the kills to.<br />
 '''amount''' - The number of kills given.
-===getUnitProperty(unitId,typeId)===
-Returns the value of the type of the unit.
-The type can be a number between 1 and 5.
-=hp
-=ep
-=level
-=field
-=skill
-getUnitProperty is dedicated for hp,ep and field. For skill and level see getUnitPropertyName(unitId,typeId).
-===getUnitPropertyName(unitId,typeId)===
-Returns the name of the type of the unit.
-The type can be a number between 1 and 5.
-=hp
-=ep
-=level
-=field
-=skill
-getUnitPropertyName is dedicated for skill and level. For hp,ep and field see getUnitProperty(unitId,typeId).
 ===selectUnit(unitID)===
@@ Line 216: / Line 192: @@
 Parameters:<br />
 '''pos''' - an array of two elements, specifying the co-ordinates {x,y}.
-=== shakeCamera(intensity, duration) ===
-Causes the camera to shake.
-Parameters:<br />
-'''intensity''' - Intensity of the shaking effect<br />
-'''duration''' - Duration of the shaking effect in update frames (40 equals one second)
-=== shakeCameraOnUnit(intensity, duration, unitId) ===
-Same as above, but the shake intensity is affected by the distance between camera and unit.
-Useful if the camera should only shake, when the unit is in sight.
-Parameters:<br />
-'''intensity''' - Intensity of the shaking effect<br />
-'''duration''' - Duration of the shaking effect in update frames (40 equals one second)<br />
-'''unitId''' - Unit ID of the unit, which should influence the shake intensity
 ===togglePauseGame(pauseStatus)===
@@ Line 249: / Line 209: @@
 === loadScenario(scenario, keepFactions) ===
 Loads another scenario from inside an existing scenario. The new scenario must have the same techtree and factions, but map, tileset can change.
 Parameters:<br />
@@ Line 263: / Line 223: @@
 ===getAttackWarningsEnabled()===
 Returns the current status of the attack warnings system (true if enabled, false if disabled).
-===getIsDayTime()===
-Returns if it is day ingame. ( 1 is day and 0 is night )
-===getIsNightTime()===
-Returns if it is night ingame. ( 1 is night and 0 is day )
-===getTimeOfDay()===
-Returns the ingame time of the day.
-=== storeSaveGameDate(key, value) ===
-Stores ''value'' at ''key'' in the savegame.<br />
-'''''Only available in the onSave-tag!'''''
-Parameters:<br />
-'''key''' - a key string<br />
-'''value''' - a string that is stored
-=== loadSaveGameDate(key) ===
-Returns the ''value'' stored at ''key'' in the savegame.<br />
-'''''Only available in the onLoad-tag!'''''
-Parameters:<br />
-'''key''' - a key string
-[[Category:MG]]
-[[Category:Scenarios]]
-[[Category:Lua]]
 ==AI==
@@ Line 406: / Line 339: @@
 Parameters:<br />
 '''pos''' - the x and y coordinate of the top left point then the bottom right point (eg, {10,10,5,5} would create a box from points (10,10) to (5,5)).
-===registerDayNightEvent()===
-Enables the Day/Night Event which will be triggered when night or day starts.
-Example:
-<syntaxhighlight lang="lua">
-<startup>
-	registerDayNightEvent()
-</startup>
-<dayNightTriggerEvent>
-	if getIsDayTime() == 1 then
-		setDisplayText('It is day time, a safer time to roam!')
-    else
-		setDisplayText('**It is night time, WATCH OUT!**')
-    end
-</dayNightTriggerEvent>
-</syntaxhighlight>
-===unregisterDayNightEvent()===
-Disables the Day/Night Event.
 ===triggeredEventAreaEntryUnitId()===
@@ Line 433: / Line 345: @@
 ===triggeredEventAreaExitUnitId()===
 Returns the unit ID of the unit who exited a registered cell area trigger event.
-===lastUnitTriggerEventUnit()===
-Returns the ID of the Unit which triggered the UnitTriggerEvent.
-===lastUnitTriggerEventType()===
-Returns the ID of property which changed.
-=hp
-=ep
-=level
-=field
-=skill
 ===getCellTriggerEventCount(eventID)===
@@ Line 459: / Line 360: @@
 Parameters:<br />
 '''eventID''' - the ID of a previously registered event.
-===registerUnitTriggerEvent(unitId)===
-Registers a unit trigger event for a unit which will be triggered if one of his properties changes.
-Example:
-<syntaxhighlight lang="lua">
-<startup>
-    createUnit('battle_machine', 1, startLocation(1))
-    player2_battlemachine= lastCreatedUnit()
-    registerUnitTriggerEvent(player2_battlemachine)
-</startup>
-<unitTriggerEvent>
-    if player2_battlemachine == lastUnitTriggerEventUnit() then
-        if lastUnitTriggerEventType() == 1 then -- hp changed
-            print('Unit hp is now: ' .. getUnitProperty(lastUnitTriggerEventUnit(),lastUnitTriggerEventType()))
-        elseif lastUnitTriggerEventType() == 2 then -- ep changed
-            print('Unit ep is now: ' .. getUnitProperty(lastUnitTriggerEventUnit(),lastUnitTriggerEventType()))
-        elseif lastUnitTriggerEventType() == 3 then -- level changed
-            print('Unit level is now: ' .. getUnitPropertyName(lastUnitTriggerEventUnit(),lastUnitTriggerEventType()))
-        elseif lastUnitTriggerEventType() == 4 then -- field changed
-            print('Unit field is now: ' .. getUnitProperty(lastUnitTriggerEventUnit(),lastUnitTriggerEventType()))
-        elseif lastUnitTriggerEventType() == 5 then -- skill changed
-            print('Unit skill is now: ' .. getUnitPropertyName(lastUnitTriggerEventUnit(),lastUnitTriggerEventType()))
-        end
-    end
-</unitTriggerEvent>
-</syntaxhighlight>
-===unregisterUnitTriggerEvent(unitId)===
-Unregisters the unit trigger event for a unit.
 ===startTimerEvent()===
@@ Line 672: / Line 541: @@
 ===getUnitsForFaction(factionIndex, commandTypeName, field)===
-Returns an array (table) of units in the specified faction which lists all units which have the specified command and can use it on the specified field (such as being able to attack air units).<br />
+Returns an array (table) of units in the specified faction which:
-<tt>0</tt> for land and <tt>1</tt> for air field.
+*If only the commandTypeName is specified, the table will be a list of all units which have that command (such as <tt>attack</tt>).
-[[Category:MG]]
+*If the commandTypeName is empty and only the field is specified (<tt>0</tt> = land, <tt>1</tt> = air), the table will list all units which are in that specific field.
-[[Category:Scenarios]]
+*If both commandTypeName and the field are specified, the table will list all units which have the specified command can can use it on the specified field (such as being able to attack air units).
-[[Category:Lua]]
 ===getUnitCurrentField(unitId)===
@@ Line 692: / Line 560: @@
 Parameters:<br />
-'''flashCount''' -<br />
+'''flashCount''' -  <br />
 '''factionIndex''' - index of the faction who "placed" the marker.<br />
 '''note''' - note on the marker.<br />
@@ Line 702: / Line 570: @@
 Parameters:<br />
-'''factionIndex''' - index of the faction whose camera you wish to move.<br />
+'''factionIndex''' -  index of the faction whose camera you wish to move.<br />
 '''pos''' - x and y coordinates for the camera's position.
@@ Line 709: / Line 577: @@
 Parameters:<br />
-'''teamNumber''' - team number whose camera you wish to move.<br />
+'''teamNumber''' -  team number whose camera you wish to move.<br />
 '''pos''' - x and y coordinates for the camera's position.
@@ Line 715: / Line 583: @@
 These are XML tags used to execute Lua code on its specified event. Variables can be used across different events.
-<syntaxhighlight lang="xml"><global>
+<syntaxhighlight lang="xml"><startup>
 	<!--
-		Code here will be executed whenever the scenario is started.
+		Code here will be executed once on startup.
 	-->
-</global>
-<onSave>
-	<!--
-		Code here will be executed when the game is about to save.
-	-->
-</onSave>
-<onLoad>
-	<!--
-		Code here will be executed when the savegame got loaded.
-	-->
-</onLoad>
 <startup>
-	<!--
-		Code here will be executed once on startup.
-	-->
-</startup>
 <unitCreatedOfType type="unitname">
 	<!--
@@ Line 790: / Line 643: @@
 [[Category:Scenarios]]
 [[Category:Lua]]
-[[Category:XMLs]]