Editing MG/Lua
Jump to navigation
Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
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]]. | [[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== | ==Text== | ||
Line 17: | Line 15: | ||
'''text''' - a string identifying the'' text'' from a language file. | '''text''' - a string identifying the'' text'' from a language file. | ||
− | === addConsoleLangText( | + | === addConsoleLangText(const char *fmt, ...)=== |
− | 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. | + | Available in rev 2813. 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 /> | Parameters:<br /> | ||
Line 29: | Line 27: | ||
'''text''' - a string identifying the ''text'' from a language file. | '''text''' - a string identifying the ''text'' from a language file. | ||
− | ===displayFormattedText (fmt, ...)=== | + | ===displayFormattedText (const char *fmt, ...)=== |
− | Works like <tt>setDisplayText()</tt> but allows formatting of text. | + | Available in rev 2767. Works like <tt>setDisplayText()</tt> but allows formatting of text. |
Parameters:<br /> | Parameters:<br /> | ||
Line 36: | Line 34: | ||
'''...''' - variable parameter list to pass values to fmt ''(like in printf)''. | '''...''' - variable parameter list to pass values to fmt ''(like in printf)''. | ||
− | ===displayFormattedLangText (fmt, ...)=== | + | ===displayFormattedLangText (const char *fmt, ...)=== |
− | Works like <tt>displayFormattedText()</tt> but uses the language-file for resolving the format of the text. | + | Available in rev 2767. Works like <tt>displayFormattedText()</tt> but uses the language-file for resolving the format of the text. |
Parameters:<br /> | Parameters:<br /> | ||
Line 43: | Line 41: | ||
'''...''' - variable parameter list to pass values to fmt ''(like in printf)''. | '''...''' - variable parameter list to pass values to fmt ''(like in printf)''. | ||
− | === clearDisplayText() === | + | === clearDisplayText () === |
Clears the message from the top of the screen previously set with <tt>setDisplayText()</tt>. | Clears the message from the top of the screen previously set with <tt>setDisplayText()</tt>. | ||
==Unit== | ==Unit== | ||
=== createUnit(unitID, faction, pos) === | === 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. | + | 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). '''Warning''': 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} | + | 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}. | ||
− | + | === destroyUnit(unitID) === | |
− | ===destroyUnit(unitID)=== | ||
Destroys a unit. | Destroys a unit. | ||
Line 69: | Line 67: | ||
'''ignoreRequirements''' - a 0 or 1 value indicating whether to respect morph requirements (0) or not (1) | '''ignoreRequirements''' - a 0 or 1 value indicating whether to respect morph requirements (0) or not (1) | ||
− | + | === moveToUnit ( unitID, destUnitID ) === | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | === moveToUnit(unitID, destUnitID) === | ||
Move unitID to the location of destUnitID. | Move unitID to the location of destUnitID. | ||
Line 82: | Line 73: | ||
'''unitID''' - the ID of the unit to move (starting location).<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. | '''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. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
===giveAttackCommand(unitID, unitToAttackID)=== | ===giveAttackCommand(unitID, unitToAttackID)=== | ||
Line 134: | Line 119: | ||
'''upgrade '''- the name of the upgrade to perform. | '''upgrade '''- the name of the upgrade to perform. | ||
− | ===giveKills( | + | ===giveKills(unit, amount)=== |
− | Gives a specified unit a certain number of kills (which can be used to level them up). | + | Available in rev 2823. Gives a specified unit a certain number of kills (which can be used to level them up). |
Parameters:<br /> | Parameters:<br /> | ||
− | ''' | + | '''unit''' - The ID of the unit to give the kills to.<br /> |
'''amount''' - The number of kills given. | '''amount''' - The number of kills given. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==Game== | ==Game== | ||
Line 216: | Line 132: | ||
Parameters:<br /> | Parameters:<br /> | ||
'''pos''' - an array of two elements, specifying the co-ordinates {x,y}. | '''pos''' - an array of two elements, specifying the co-ordinates {x,y}. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
===togglePauseGame(pauseStatus)=== | ===togglePauseGame(pauseStatus)=== | ||
Line 247: | Line 147: | ||
=== endGame() === | === 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. | 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. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==AI== | ==AI== | ||
Line 388: | Line 245: | ||
===registerCellTriggerEventForFactionToUnit(sourceFactionID, destUnitID)=== | ===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 ' | + | 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 '<cellTriggerEvent>'. |
Parameters:<br /> | Parameters:<br /> | ||
Line 400: | Line 257: | ||
'''sourceFactionID''' - the ID of a faction who has at least one unit that moves next to destUnit.<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. | '''pos''' - the x and y cell co-ordinates that will trigger the event when a unit from sourceFactionID enters the cell. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
===getCellTriggerEventCount(eventID)=== | ===getCellTriggerEventCount(eventID)=== | ||
Line 450: | Line 263: | ||
Parameters:<br /> | Parameters:<br /> | ||
'''eventID''' - the ID of a previously registered event | '''eventID''' - the ID of a previously registered event | ||
− | |||
− | |||
− | |||
===unregisterCellTriggerEvent(eventID)=== | ===unregisterCellTriggerEvent(eventID)=== | ||
Line 459: | Line 269: | ||
Parameters:<br /> | Parameters:<br /> | ||
'''eventID''' - the ID of a previously registered event. | '''eventID''' - the ID of a previously registered event. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
===startTimerEvent()=== | ===startTimerEvent()=== | ||
Line 533: | Line 311: | ||
This function returns the eventID that is currently triggering a '<timerTriggerEvent>'. | This function returns the eventID that is currently triggering a '<timerTriggerEvent>'. | ||
− | === | + | ==Queries== |
− | + | ===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. | ||
− | |||
=== unitPosition(unitID) === | === unitPosition(unitID) === | ||
Returns the current location of a given unit. | Returns the current location of a given unit. | ||
Line 554: | Line 341: | ||
Parameters:<br /> | Parameters:<br /> | ||
− | '''unitID''' - The ID of the unit | + | '''unitID''' - The ID of the unit who's faction you wish you check. |
=== resourceAmount(resource, faction) === | === resourceAmount(resource, faction) === | ||
Line 562: | Line 349: | ||
'''resource''' - The name of the resource you wish you check.<br /> | '''resource''' - The name of the resource you wish you check.<br /> | ||
'''faction''' - The index of the faction to check. | '''faction''' - The index of the faction to check. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== lastCreatedUnitName() === | === lastCreatedUnitName() === | ||
Line 575: | Line 356: | ||
Returns the unit ID of the last created unit. | Returns the unit ID of the last created unit. | ||
− | === lastDeadUnitName() === | + | === lastDeadUnitName () === |
Returns the name of the last unit to die. | Returns the name of the last unit to die. | ||
− | === lastDeadUnit()=== | + | === lastDeadUnit ()=== |
Returns the ID of the last unit to die. | Returns the ID of the last unit to die. | ||
===lastDeadUnitCauseOfDeath()=== | ===lastDeadUnitCauseOfDeath()=== | ||
− | Returns the following depending on how the last unit died: | + | Available in rev 2824. Returns the following depending on how the last unit died: |
:None = 0 | :None = 0 | ||
:Attacked = 1 | :Attacked = 1 | ||
Line 590: | Line 371: | ||
=== lastDeadUnitKillerName() === | === 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). | + | Available in rev 2835. 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()=== | === 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). | + | Available in rev 2835. 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()=== | ===lastAttackedUnit()=== | ||
− | Returns the ID of the last unit which was attacked. | + | Available in rev 2823. Returns the ID of the last unit which was attacked. |
===lastAttackedUnitName()=== | ===lastAttackedUnitName()=== | ||
− | Returns the name of the last unit which was attacked. | + | Available in rev 2823. Returns the name of the last unit which was attacked. |
===lastAttackingUnit()=== | ===lastAttackingUnit()=== | ||
− | Returns the ID of the last unit to attack. | + | Available in rev 2823. Returns the ID of the last unit to attack. |
===lastAttackingUnitName()=== | ===lastAttackingUnitName()=== | ||
− | Returns the name of the last unit to attack. | + | Available in rev 2823. Returns the name of the last unit to attack. |
===getSystemMacroValue(key) === | ===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. | + | Available in rev 3040. 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 /> | Parameters:<br /> | ||
Line 617: | Line 398: | ||
dofile(getSystemMacroValue("$SCENARIO_PATH") .. "filename.lua") | dofile(getSystemMacroValue("$SCENARIO_PATH") .. "filename.lua") | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | |||
− | |||
− | |||
− | |||
=== getPlayerName(faction) === | === getPlayerName(faction) === | ||
− | Returns the name of the player of a given faction | + | Available in rev 3040. Returns the name of the player of a given faction. |
− | |||
− | |||
− | |||
Parameters:<br /> | Parameters:<br /> | ||
Line 641: | Line 415: | ||
Parameters:<br /> | Parameters:<br /> | ||
− | '''faction''' - The index of the faction you wish to check. | + | '''faction''' - The index of the faction you wish to check. |
'''name''' - The name of the specific unit you wish to check. | '''name''' - The name of the specific unit you wish to check. | ||
===gameWon()=== | ===gameWon()=== | ||
Returns true if the human player won the game, and false if they did not. | Returns true if the human player won the game, and false if they did not. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== XML events == | == XML events == | ||
These are XML tags used to execute Lua code on its specified event. Variables can be used across different events. | These are XML tags used to execute Lua code on its specified event. Variables can be used across different events. | ||
− | <syntaxhighlight lang="xml">< | + | <syntaxhighlight lang="xml"><startup> |
<!-- | <!-- | ||
− | Code here will be executed | + | Code here will be executed once on startup. |
--> | --> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<startup> | <startup> | ||
− | |||
− | |||
− | |||
− | |||
<unitCreatedOfType type="unitname"> | <unitCreatedOfType type="unitname"> | ||
<!-- | <!-- | ||
Line 749: | Line 443: | ||
<!-- | <!-- | ||
Code here will be executed every time a unit gets attacked. | Code here will be executed every time a unit gets attacked. | ||
+ | Works with SVN rev 2823. | ||
--> | --> | ||
</unitAttacked> | </unitAttacked> | ||
Line 754: | Line 449: | ||
<!-- | <!-- | ||
Code here will be executed every time a unit is attacking. | Code here will be executed every time a unit is attacking. | ||
+ | Works with SVN rev 2823. | ||
--> | --> | ||
</unitAttacking> | </unitAttacking> | ||
Line 790: | Line 486: | ||
[[Category:Scenarios]] | [[Category:Scenarios]] | ||
[[Category:Lua]] | [[Category:Lua]] | ||
− |