Difference between revisions of "Lua"

From MegaGlest
Jump to navigation Jump to search
m (→‎Basics: adding link to MG/Lua commands)
(Reworked the whole page; Removed GAE)
Line 1: Line 1:
−
'''Lua''' is the scripting language used by [[MegaGlest]] for all scripted [[scenarios]] and tutorials. It allows dialogue with the player, and allows you control over the enemy, such as to make a scenario where you must destroy the enemy villages in order, or something were you must survive a special enemy attack with different starting [[units]]. It can be made so you can have missions where your goal is to protect a certain unit, such as a [[summoner]] or an allies [[castle]]. You have full control over what the foe does, and this is very handy for making a unique scenario. All tutorials are scripted. They are simply easy scenarios that teach you as they go.
+
'''Lua''' is the scripting language used by [[MegaGlest]] for all scripted [[scenarios]] and tutorials. It allows you to add custom gameplay and interact with the player by showing messages or displaying a custom objective. One example of a scripted scenario is Amazones, where you need to survive multiple waves of attacking enemies. The ingame tutorials are scripted scenarios as well.
 +
 
 +
There are many possibilities to interact with the gameplay. You can react to unit deaths, have timer events, create units at custom spawn points, highlight units and much more.
  
 
==Basics==
 
==Basics==
−
The best part about lua is that the lua used in MegaGlest is very easy to learn, only a bit harder than the XMLs, and easier than learning to model. lua script is placed in between the scripts tag of the scenario XML, and should have an included .lng file in the same directory if dialogue is used (more on this later).
+
To enable scripting in a scenario set the <tt>external</tt> attribute of the <tt>scripts</tt> node to true in the [[XML/Scenario]]. If enabled, a file with the name <tt>script.lua</tt> needs to be placed inside the scenario folder. This file will contain the Lua code of the scenario.
 +
 
 +
Scripting in [[MegaGlest]] is event based. When an event happens during the game, a function with the corresponding name in the Lua script file will be called. For example, when a unit dies, a function with the name <tt>unitDied</tt> will be called if present in the <tt>script.lua</tt> file.
 +
This table contains all possible events that are currently supported.
  
−
Lua is a straight forward language in MegaGlest, existing simply of [[MG/Lua|commands]], many which check to see if event A has occured, then event B can start.
+
{| class="wikitable"
 +
!Function name
 +
!Description
 +
|-
 +
|global()
 +
|Called whenever the scenario will be started or loaded from a savegame.
 +
|-
 +
|startup()
 +
|Called ''once'' at the start of the scenario.
 +
|-
 +
|onSave()
 +
|Called when the scenario gets saved. Here you can store variables you when the savegame gets loaded.
 +
|-
 +
|onLoad()
 +
|Called when the savegame of the scenario is started. Here you can also restore saved variables.
 +
|-
 +
|unitCreated()
 +
|Called each time any player creates a new unit. Use <tt>lastCreatedUnit()</tt> to get the unit ID.
 +
|-
 +
|resourceHarvested()
 +
|Called whenever a resource is harvested. Use <tt>resourceAmount(resource, faction)</tt> to get the current amount of a resource.
 +
|-
 +
|unitCreatedOfType_''unitname''()
 +
|Called when a unit of the specified name is created by any player.
 +
|-
 +
|unitDied()
 +
|Called every time a unit from any player dies. Use <tt>lastDeadUnit()</tt> to get the unit ID of the unit that died.
 +
|-
 +
|unitAttacked()
 +
|Called when any unit is attacked. Use <tt>lastAttackedUnit()</tt> to get the unit ID.
 +
|-
 +
|unitAttacking()
 +
|Called when any unit is attacking. Use <tt>lastAttackingUnit()</tt> to get the unit ID.
 +
|-
 +
|gameOver()
 +
|Called when the game is over.
 +
|-
 +
|timerTriggerEvent()
 +
|Called when a second has elapsed for any timer event or when a efficient timer event triggers. Use <tt>triggeredTimerEventId()</tt> to get the timer ID.
 +
|-
 +
|cellTriggerEvent()
 +
|Called when a cell event triggers. Cell events are triggered when a unit enters a defined region. Use <tt>triggeredCellEventUnitId()</tt> to get the unit that triggered the event.
 +
|-
 +
|unitTriggerEvent()
 +
|Called when a unit event triggers. Unit events are triggered if a property of a registered unit changes. Use <tt>lastUnitTriggerEventUnit()</tt> to get the unit that triggered the event.
 +
|-
 +
|dayNightTriggerEvent()
 +
|Called when it gets day or night if enabled by <tt>registerDayNightEvent()</tt>
 +
|}
  
−
The basics of lua are simple. In MegaGlest, a command does a certain function to a certain unit, faction, team, or the screen. Comments can be placed with --, where everything after the -- is commented out until the end of the line. The most important thing to remember is that the faction numbers are 0, 1, 2, and 3. NOT 1, 2, 3, 4. Player 1 is known as player 0 here. This is called the faction index, and is used in many functions that affect a faction/player. Lastly, remember that lua is case sensitive. createUnit is not the same as CreateUnit.
+
Inside of these function any lua code can be used. There are many [[MG/Lua|functions]] that can be used to interact with the game itself.
 +
This table contains some of the most important functions. A list of all functions can be found [[MG/Lua|here]].
  
−
==Unit IDs==
+
{| class="wikitable"
−
First of all, an important concept to understand is that all units in MegaGlest have a unique number assigned to them, and lua needs to use this number to control the units. However, you don't have to directly know the numbers, and you'll never use the number itself. We will always use variables and functions to get these unit IDs. The best way to get a unit ID is right after we create the unit (with createUnit()) by using the command lastCreatedUnit(), which gives the unit ID of the last created unit.
+
!Function name
 +
!Description
 +
|-
 +
|global()
 +
|Called whenever the scenario will be started or loaded from a savegame.
 +
|-
 +
|startup()
 +
|Called ''once'' at the start of the scenario.
 +
|-
 +
|onSave()
 +
|Called when the scenario gets saved. Here you can store variables you when the savegame gets loaded.
 +
|-
 +
|onLoad()
 +
|Called when the savegame of the scenario is started. Here you can also restore saved variables.
 +
|-
 +
|unitCreated()
 +
|Called each time any player creates a new unit. Use <tt>lastCreatedUnit()</tt> to get the unit ID.
 +
|-
 +
|resourceHarvested()
 +
|Called whenever a resource is harvested. Use <tt>resourceAmount(resource, faction)</tt> to get the current amount of a resource.
 +
|-
 +
|unitCreatedOfType_''unitname''()
 +
|Called when a unit of the specified name is created by any player.
 +
|-
 +
|unitDied()
 +
|Called every time a unit from any player dies. Use <tt>lastDeadUnit()</tt> to get the unit ID of the unit that died.
 +
|-
 +
|unitAttacked()
 +
|Called when any unit is attacked. Use <tt>lastAttackedUnit()</tt> to get the unit ID.
 +
|-
 +
|unitAttacking()
 +
|Called when any unit is attacking. Use <tt>lastAttackingUnit()</tt> to get the unit ID.
 +
|-
 +
|gameOver()
 +
|Called when the game is over.
 +
|-
 +
|timerTriggerEvent()
 +
|Called when a second has elapsed for any timer event or when a efficient timer event triggers. Use <tt>triggeredTimerEventId()</tt> to get the timer ID.
 +
|-
 +
|cellTriggerEvent()
 +
|Called when a cell event triggers. Cell events are triggered when a unit enters a defined region. Use <tt>triggeredCellEventUnitId()</tt> to get the unit that triggered the event.
 +
|-
 +
|unitTriggerEvent()
 +
|Called when a unit event triggers. Unit events are triggered if a property of a registered unit changes. Use <tt>lastUnitTriggerEventUnit()</tt> to get the unit that triggered the event.
 +
|-
 +
|dayNightTriggerEvent()
 +
|Called when it gets day or night if enabled by <tt>registerDayNightEvent()</tt>
 +
|}
  
−
So if we use a variable, such as myVar (variables in lua are loosely typed and do not need to be declared in any way), we can say myVar=lastCreatedUnit(), so now the unit ID of the last created unit is stored in 'myVar'. Note that we can only get the unit ID of a unit when we create them, so we cannot get IDs of units later.
+
==IDs==
 +
An important concept to scripting in MegaGlest are IDs. IDs are handles that can be used to reference to things such as a factions/players, units, timer events and more. You can store an ID in a variable to access the same thing on a later occasion.
  
−
==Coordinates==
+
===Faction IDs===
−
You can use lua coordinates for anything that needs a position. These are in the format of {x,y}, and replace common queries such as startLocation() and unitPosition(). Firstly, lets look at how they work. Maps are split into tiles. Each tile is 2 x 2 cells. So a 128 x 128 map is measured in tiles. However, glest uses CELLS instead of tiles for lua positions, so that means a 128 x 128 map is actually 256 x 256 cells. However, these are INDEXED, like many lua functions and arrays, meaning they start at 0. Also, the very last row and very last column (in TILES) cannot be used to place things, since there is not enough room. So in short, the map starts at 0,0: the first top left cell. The last useable cell is 254,254 here, at the bottom righthand corner.
+
All players get an ID ranging from 0 to one less then the max number of players in the game. For example if the scenario has 4 players, valid faction IDs are 0, 1, 2, 3 NOT 1, 2, 3, 4. This is called the faction index, and is used in many functions that affect a faction/player. Closed slots do not count when determining the faction ID.
  
−
So that's how cells work. Now, let's look at how we can use attributes from queries for positions. We know that the startLocation(0) command would get faction 0's start location's {x,y} coordinates, but suppose we wanted to have it appear 20 tiles (40 cells) north of the start location. How would we do that? Simple. The startLocation() query will return both the x and y in the braces. However, startLocation(0)[1] will return JUST the x value, and startLocation(0)[2] will return JUST the y value. So if we wanted 40 cells north of the startLocation (y axis, starting from the top), we'd use {startLocation(0)[1],startLocation(0)[2]-40}. All location queries will return the x value if a [1] is placed after it, and a y value if a [2] is placed after it.
+
===Unit IDs===
 +
All units in MegaGlest have a unique number assigned to them. This number can be used to reference a unit in the Lua code. There are multiple functions to get the ID of a certain unit. The most used one is the <tt>lastCreatedUnit()</tt> function, which will return the ID of the last unit that was spawned. The ID will always stay the same for the same unit.
 +
A typical usage of this feature is to store the ID of an important unit in a variable and check if it survives using the <tt>lastDeadUnit()</tt> function in the unitDied event.
  
−
==Timers==
+
==Coordinates==
−
[[GAE]] v0.2.13 and later can use lua timers. To use one, you must first call setTimer('timer_name', 'game', #, true). The first value is the timer name, which lets you reference it. The second value is either game or real. Game is recommended, because it changes based on the player's game speed (ie: if the player increases the speed, the timer ticks by faster. This keeps players from cheating by slowing down the game speed and giving themselves more time). Real is simply miliseconds. If you use game, then bear in mind that it is '''world refreshes'''. The world refreshes '''40''' times per second on normal speed.
+
Coordinates can be used for anything that needs a position. These are in the format of {x,y}, and replace common queries such as startLocation() and unitPosition(). Maps are split into tiles. Each tile is 2 x 2 cells. So a 128 x 128 map acutally has 256 x 256 cells. Lua uses the CELLS instead of tiles for positions. Also, like the faction IDs, the positions start at {0,0} instead of {1,1}.
  
−
So if you want the timer to be set for 5 seconds, you'll need 5*40=200 as a value, which brings us to the third attribute, which is the value (seconds in real, refreshes in game). The last value is whether or not the timer is an interval (repeating) timer. If true, it keeps doing the timer over and over (ie: to create a unit every X seconds), and if false, its a one time timer (such as to create something just once after a certain amount of time).
+
There are multiple commands which query for positions. These can be used to generate a relative position. For example, if we wanted to have a unit appear 20 tiles (40 cells) north of the start location we'd use <tt>createUnit('worker', 0, {startLocation(0)[1],startLocation(0)[2]-40})</tt>. All location queries will return the x value if a [1] is placed after it, and a y value if a [2] is placed after it.
  
−
To tell Lua what we want the game to do when the timer reaches zero, we need a &lt;timer name=&quot;timer_name&quot;&gt;&lt;/timer&gt; tag somewhere in the XML (remember that XML tags must be outside of the Lua code, meaning, say, after the closing tag of &amp;lt;unit-died&amp;gt;, NOT inside of those tags (only lua goes inside). This XML tag can contain whatever Lua code you want to be executed when the timer runs up.
+
==Translation files==
 +
If you want to have dialog or objectives in the scenario, .lng files can be used for the different messages. Their advantage is that they can be translated into other languages. They should be in the format &lt;scenario_name&gt;_&lt;language&gt;.lng. For example, if the scenario is called storming, then the english lng file will be called storming_english.lng. English should be the priority, while other languages are optional.
  
−
To stop a timer, we simply use stopTimer('timer_name'), which will stop the selected timer. Note that there is no way to restart a timer, though you can create a new one.
+
The lng files are in the same format as an ini, and lines that start with ; are comments.
  
−
==Events and Triggers==
+
Lines in the .lng file are simply &lt;tagName&gt;=text string.
−
GAE 0.2.12 and later supports events in lua. Events are blocks of code executed when certain conditions (the trigger) become true. For example, you might set an event so once a unit enters a certain area, he would get ambushed. Events first need to be named with registerEvent(). All lua code for events must also be stored in a XML block called &lt;unitEvent name=&quot;event_name&quot;&gt;&lt;/unitEvent&gt;. If the event is going to be triggered by entering an area, you must also register that area with registerRegion().
 
  
−
Now for the trigger, you can use either setUnitTrigger(), which applies to a single unit, but offers more conditions (triggers), including when they are attacked, when they enter an area, when their HP is below a certain value, etc. OR, setFactionTrigger() is currently limited to just when a unit enters a region. When the condition is fullfilled, the XML block for that event will be executed.
+
The tagName is the name used to refer to the lng in the lua script, such as showMessage('message-tag', 'message-topic'). This lng file would need two tags, message-tag and message-topic. Note that text strings are unrestricted, and can contain any ASCII characters and punctuation. They can have capital letters as well, and go until the end of the line. Note that if you go too long, the dialogue box may not have room to fit the message. If that's the case, split it down into separate messages.
  
−
==LNG files==
+
==Example==
−
.lng or language files hold all the dialogue for scenarios, their advantage is that they can be translated into other languages. They should be in the format &lt;scenario_name&gt;_&lt;language&gt;.lng. For example, if the scenario is called storming, then the english lng file will be called storming_english.lng. English should be the priority, while other languages are optional.
 
  
−
The lng files are in the same format as an ini, and lines that start with ; are comments.
+
The best way to learn is by looking at an example. In this example a player needs to defend a defense_tower in the middle of the map against a CPU. He looses when the tower dies and wins if he successfully defended the tower for 10 minutes. The scenario is called '''protect_the_tower'''.
 +
===protect_the_tower.xml===
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" standalone="yes" ?>
 +
<scenario>
 +
<difficulty value="2"/>
 +
<players>
 +
<player control="human" faction="tech" team="1"/>
 +
<player control="closed"/>
 +
<player control="cpu-ultra" faction="romans" team="2"/>
 +
<player control="closed"/>
 +
</players>
 +
<map value="conflict"/>
 +
<tileset value="autumn"/>
 +
<tech-tree value="megapack"/>
 +
<default-resources value="true"/>
 +
<default-units value="true"/>
 +
    <!-- default victory conditions are turned of because we implement custom conditions in the lua code -->
 +
<default-victory-conditions value="false"/>
 +
    <!-- (external) scripts need to be turned on to load the lua code -->
 +
    <scripts external="true"/>
 +
</scenario>
 +
</syntaxhighlight>
 +
===script.lua===
 +
<syntaxhighlight lang="lua">
 +
-- This is called when the scenario starts
 +
function startup()
 +
    -- create the tower in the middle of the map
 +
    -- the first parameter is the unit name
 +
    -- the second parameter is the faction id - the player has ID 0 here
 +
    -- the third parameter are the coordinates where to the tower
 +
    -- Note: 64,64 is the middle of the map even though conflict is a 64x64 map
 +
createUnit('defense_tower', 0, {64,64})
 +
    -- save the id of the tower that was just created to the 'importantTower' variable
 +
importantTower=lastCreatedUnit()
 +
    -- highlight the tower so the player can see what he needs to protect
 +
    -- parameters are unitID, radius, thickness, colour
 +
    highlightUnit(importantTower, 1, 0.2, {1,1,1,0.7})
 +
    -- start the ten minute timer
 +
    -- we also save the timer ID for later
 +
    timerEventID=startEfficientTimerEvent(10*60)
 +
    -- Displays an objective on the top of the screen
 +
    -- The text is taken from tag 'ProtectTheTower' in the .lng file
 +
    setDisplayText('ProtectTheTower')
 +
end
  
−
Lines in the .lng file are simply &lt;tagName&gt;=text string.
+
-- This is called whenever a unit dies
 +
function unitDied()
 +
    -- compare the unit ID of the last unit that died with the importantTower ID
 +
if lastDeadUnit()==importantTower then
 +
        -- the tower died
 +
        -- clear objective
 +
clearDisplayText()
 +
        -- set the CPU as winner
 +
        -- Note: the faction ID is 1 and not 2 because closed slots do not count
 +
setPlayerAsWinner(1)
 +
        -- end the game
 +
endGame()
 +
end
 +
end
  
−
The tagName is the name used to refer to the lng in the lua script, such as showMessage('message-tag', 'message-topic'). This lng file would need two tags, message-tag and message-topic. Note that text strings are unrestricted, and can contain any ASCII characters and punctuation. They can have capital letters as well, and go until the end of the line. Note that if you go too long, the dialogue box may not have room to fit the message. If that's the case, split it down into seperate messages.
+
-- Triggered whenever an efficient timer event runs out
 +
-- or every second for normal timer events
 +
function timerTriggerEvent()
 +
    -- check whether this event was triggered by the ten minute timer
 +
    -- (in this case we only have one timer event so this will always be true)
 +
    if triggeredTimerEventId()==timerEventID then
 +
        -- the player survived long enough
 +
        -- clear objective
 +
clearDisplayText()
 +
        -- set the Player as winner
 +
setPlayerAsWinner(0)
 +
        -- end the game
 +
endGame()
 +
    end
 +
end
 +
</syntaxhighlight>
 +
===protect_the_tower_english.lng===
 +
<syntaxhighlight lang="ini">
 +
; This message could be translated to different languages
 +
; You can use \n for line breaks in the messages
 +
ProtectTheTower=Protect the highlighted Tower for five minutes!
 +
</syntaxhighlight>
  
 
==List of Lua Commands==
 
==List of Lua Commands==
−
For Lua commands shared by all engines, including regular Glest, please see [[Lua/Commands]]. For [[MegaGlest]], see [[MG/Lua]]. For GAE, see [[GAE/Lua]].
+
{{See|MG/Lua}}
 +
Click the link to see all [[MG/Lua|available lua commands]] in MegaGlest.
  
 
==External Links==
 
==External Links==
−
*[http://glestguide.co.cc/lua.php Glest Guide's Lua Page]
 
 
*[http://www.lua.org/pil/ Programming in Lua]
 
*[http://www.lua.org/pil/ Programming in Lua]
 
*[http://lua-users.org/wiki/TutorialDirectory List of Lua tutorials]
 
*[http://lua-users.org/wiki/TutorialDirectory List of Lua tutorials]

Revision as of 01:29, 5 March 2025

Lua is the scripting language used by MegaGlest for all scripted scenarios and tutorials. It allows you to add custom gameplay and interact with the player by showing messages or displaying a custom objective. One example of a scripted scenario is Amazones, where you need to survive multiple waves of attacking enemies. The ingame tutorials are scripted scenarios as well.

There are many possibilities to interact with the gameplay. You can react to unit deaths, have timer events, create units at custom spawn points, highlight units and much more.

Basics

To enable scripting in a scenario set the external attribute of the scripts node to true in the XML/Scenario. If enabled, a file with the name script.lua needs to be placed inside the scenario folder. This file will contain the Lua code of the scenario.

Scripting in MegaGlest is event based. When an event happens during the game, a function with the corresponding name in the Lua script file will be called. For example, when a unit dies, a function with the name unitDied will be called if present in the script.lua file. This table contains all possible events that are currently supported.

Function name Description
global() Called whenever the scenario will be started or loaded from a savegame.
startup() Called once at the start of the scenario.
onSave() Called when the scenario gets saved. Here you can store variables you when the savegame gets loaded.
onLoad() Called when the savegame of the scenario is started. Here you can also restore saved variables.
unitCreated() Called each time any player creates a new unit. Use lastCreatedUnit() to get the unit ID.
resourceHarvested() Called whenever a resource is harvested. Use resourceAmount(resource, faction) to get the current amount of a resource.
unitCreatedOfType_unitname() Called when a unit of the specified name is created by any player.
unitDied() Called every time a unit from any player dies. Use lastDeadUnit() to get the unit ID of the unit that died.
unitAttacked() Called when any unit is attacked. Use lastAttackedUnit() to get the unit ID.
unitAttacking() Called when any unit is attacking. Use lastAttackingUnit() to get the unit ID.
gameOver() Called when the game is over.
timerTriggerEvent() Called when a second has elapsed for any timer event or when a efficient timer event triggers. Use triggeredTimerEventId() to get the timer ID.
cellTriggerEvent() Called when a cell event triggers. Cell events are triggered when a unit enters a defined region. Use triggeredCellEventUnitId() to get the unit that triggered the event.
unitTriggerEvent() Called when a unit event triggers. Unit events are triggered if a property of a registered unit changes. Use lastUnitTriggerEventUnit() to get the unit that triggered the event.
dayNightTriggerEvent() Called when it gets day or night if enabled by registerDayNightEvent()

Inside of these function any lua code can be used. There are many functions that can be used to interact with the game itself. This table contains some of the most important functions. A list of all functions can be found here.

Function name Description
global() Called whenever the scenario will be started or loaded from a savegame.
startup() Called once at the start of the scenario.
onSave() Called when the scenario gets saved. Here you can store variables you when the savegame gets loaded.
onLoad() Called when the savegame of the scenario is started. Here you can also restore saved variables.
unitCreated() Called each time any player creates a new unit. Use lastCreatedUnit() to get the unit ID.
resourceHarvested() Called whenever a resource is harvested. Use resourceAmount(resource, faction) to get the current amount of a resource.
unitCreatedOfType_unitname() Called when a unit of the specified name is created by any player.
unitDied() Called every time a unit from any player dies. Use lastDeadUnit() to get the unit ID of the unit that died.
unitAttacked() Called when any unit is attacked. Use lastAttackedUnit() to get the unit ID.
unitAttacking() Called when any unit is attacking. Use lastAttackingUnit() to get the unit ID.
gameOver() Called when the game is over.
timerTriggerEvent() Called when a second has elapsed for any timer event or when a efficient timer event triggers. Use triggeredTimerEventId() to get the timer ID.
cellTriggerEvent() Called when a cell event triggers. Cell events are triggered when a unit enters a defined region. Use triggeredCellEventUnitId() to get the unit that triggered the event.
unitTriggerEvent() Called when a unit event triggers. Unit events are triggered if a property of a registered unit changes. Use lastUnitTriggerEventUnit() to get the unit that triggered the event.
dayNightTriggerEvent() Called when it gets day or night if enabled by registerDayNightEvent()

IDs

An important concept to scripting in MegaGlest are IDs. IDs are handles that can be used to reference to things such as a factions/players, units, timer events and more. You can store an ID in a variable to access the same thing on a later occasion.

Faction IDs

All players get an ID ranging from 0 to one less then the max number of players in the game. For example if the scenario has 4 players, valid faction IDs are 0, 1, 2, 3 NOT 1, 2, 3, 4. This is called the faction index, and is used in many functions that affect a faction/player. Closed slots do not count when determining the faction ID.

Unit IDs

All units in MegaGlest have a unique number assigned to them. This number can be used to reference a unit in the Lua code. There are multiple functions to get the ID of a certain unit. The most used one is the lastCreatedUnit() function, which will return the ID of the last unit that was spawned. The ID will always stay the same for the same unit. A typical usage of this feature is to store the ID of an important unit in a variable and check if it survives using the lastDeadUnit() function in the unitDied event.

Coordinates

Coordinates can be used for anything that needs a position. These are in the format of {x,y}, and replace common queries such as startLocation() and unitPosition(). Maps are split into tiles. Each tile is 2 x 2 cells. So a 128 x 128 map acutally has 256 x 256 cells. Lua uses the CELLS instead of tiles for positions. Also, like the faction IDs, the positions start at {0,0} instead of {1,1}.

There are multiple commands which query for positions. These can be used to generate a relative position. For example, if we wanted to have a unit appear 20 tiles (40 cells) north of the start location we'd use createUnit('worker', 0, {startLocation(0)[1],startLocation(0)[2]-40}). All location queries will return the x value if a [1] is placed after it, and a y value if a [2] is placed after it.

Translation files

If you want to have dialog or objectives in the scenario, .lng files can be used for the different messages. Their advantage is that they can be translated into other languages. They should be in the format <scenario_name>_<language>.lng. For example, if the scenario is called storming, then the english lng file will be called storming_english.lng. English should be the priority, while other languages are optional.

The lng files are in the same format as an ini, and lines that start with ; are comments.

Lines in the .lng file are simply <tagName>=text string.

The tagName is the name used to refer to the lng in the lua script, such as showMessage('message-tag', 'message-topic'). This lng file would need two tags, message-tag and message-topic. Note that text strings are unrestricted, and can contain any ASCII characters and punctuation. They can have capital letters as well, and go until the end of the line. Note that if you go too long, the dialogue box may not have room to fit the message. If that's the case, split it down into separate messages.

Example

The best way to learn is by looking at an example. In this example a player needs to defend a defense_tower in the middle of the map against a CPU. He looses when the tower dies and wins if he successfully defended the tower for 10 minutes. The scenario is called protect_the_tower.

protect_the_tower.xml

<?xml version="1.0" standalone="yes" ?>
<scenario>
	<difficulty value="2"/>
	<players>
		<player control="human" faction="tech" team="1"/>
		<player control="closed"/>
		<player control="cpu-ultra" faction="romans" team="2"/>
		<player control="closed"/>
	</players>
	<map value="conflict"/>
	<tileset value="autumn"/>
	<tech-tree value="megapack"/>
	<default-resources value="true"/>
	<default-units value="true"/>
    <!-- default victory conditions are turned of because we implement custom conditions in the lua code -->
	<default-victory-conditions value="false"/>
    <!-- (external) scripts need to be turned on to load the lua code -->
    <scripts external="true"/>
</scenario>

script.lua

-- This is called when the scenario starts
function startup()
    -- create the tower in the middle of the map
    -- the first parameter is the unit name
    -- the second parameter is the faction id - the player has ID 0 here
    -- the third parameter are the coordinates where to the tower
    -- Note: 64,64 is the middle of the map even though conflict is a 64x64 map
	createUnit('defense_tower', 0, {64,64})
    -- save the id of the tower that was just created to the 'importantTower' variable
	importantTower=lastCreatedUnit()
    -- highlight the tower so the player can see what he needs to protect
    -- parameters are unitID, radius, thickness, colour
    highlightUnit(importantTower, 1, 0.2, {1,1,1,0.7})
    -- start the ten minute timer
    -- we also save the timer ID for later
    timerEventID=startEfficientTimerEvent(10*60)
    -- Displays an objective on the top of the screen
    -- The text is taken from tag 'ProtectTheTower' in the .lng file
    setDisplayText('ProtectTheTower')
end

-- This is called whenever a unit dies
function unitDied()
    -- compare the unit ID of the last unit that died with the importantTower ID
	if lastDeadUnit()==importantTower then
        -- the tower died
        -- clear objective
		clearDisplayText()
        -- set the CPU as winner
        -- Note: the faction ID is 1 and not 2 because closed slots do not count
		setPlayerAsWinner(1)
        -- end the game
		endGame()
	end
end

-- Triggered whenever an efficient timer event runs out
-- or every second for normal timer events
function timerTriggerEvent()
    -- check whether this event was triggered by the ten minute timer
    -- (in this case we only have one timer event so this will always be true)
    if triggeredTimerEventId()==timerEventID then
        -- the player survived long enough
        -- clear objective
		clearDisplayText()
        -- set the Player as winner
		setPlayerAsWinner(0)
        -- end the game
		endGame()
    end
end

protect_the_tower_english.lng

; This message could be translated to different languages
; You can use \n for line breaks in the messages
ProtectTheTower=Protect the highlighted Tower for five minutes!

List of Lua Commands

See MG/Lua

Click the link to see all available lua commands in MegaGlest.

External Links

Retrieved from "https://docs.megaglest.org/index.php?title=Lua&oldid=12469"