Scenario Editing

In newer Glest versions (3.2.0 beta and newer) lua scripting gives opens a new possibility of scripted scenarios.

The game includes 2 tutorial scenarios and one scripted normal scenario(storming) now. These demo scenarios show a bit what's possible now. Have a look at them if you want to learn it.

Useful Links

• Omega's tutorial: tutorial.
• Programming in Lua
• lua tutorials
• Lua-Users.org Wiki

Language System

Each scenario is stored in its own folder. In this folder should be an xml file of the same name as the folder with xml as the extension. Glest also looks for a lng file (scenario_name_english.lng as default) to allow for translations of text.

Example

In advanced_tutorial.xml is :
showMessage('MagicBrief', 'GlestAdvancedTutorial')

In advanced_tutorial_english.lng is :
MagicBrief=You are in command of the Magic faction, which uses mages and summoned creatures to fight.

Coordinates are specified as an array of two elements, the 'x' coordinate in the first element, and the 'y' coordinate in the second.

The origin {0,0} is at the 'top left' (or north-west if you like) of the screen. A map's size is defined in 'Tiles', each of which is a block of 2x2 Cells. For technical reasons the last row & column of Tiles are not valid. So a 64 * 64 map is (64-1)*2 = 126 Cells wide and high. The co-ordinates you supply in LUA are Cell coordinates, not Tile coordinates, and are 'zero indexed' (the first one is 0, the last is NumCells - 1).

eg. A 128 x 128 Map has 254 x 254 Cells. The northwest corner is {0,0} and the southeast corner is {253,253}.

When a function returns a 'Vec2i' you can access the individual co-ordinates by sub-scripting the array,

myPos = someFunction ()

x = myPos[1]

y = myPos[2]

When ever there is a parameter requiring positions of type Vec2i you can use the format {x,y} (where x and y are number values within the required range, as defined above) to select a position on the map.

someFunction ( {x,y} )

Here 'x' and 'y' could be numbers, variables, or 'expressions'

For example, to create a unit at a position relative to a starting location you could do something like,

createUnit ( "someunit", 0, {startLocation(0)[1] + 5, startLocation(0)[2]} )

This would create the unit 5 cells east of startLocation 0.

You can of course also pass a 'pre created' array to these functions, which may be useful for advanced scripting.

Faction Index and Players

You need to specify the players like:

<players>
	<player control="human" faction="tech" team="1"/>
	<player control="cpu" faction="magic" team="2"/>
	<player control="closed"/>
	<player control="closed"/>		
</players>

The first player's factionIndex is 0. The second player's factionIndex is 1 and so on. There must be exactly 4 player tags.

Commands

WARNING: All of these functions return type void and should not be used as arguments for other functions.

showMessage ( string text, string header )

Displays a message box on the screen, that will have to be dismissed by the player.

Parameters:
text - a string identifying the text from a language file
header - a string identifying the title bar text from a language file

setDisplayText ( string text )

Displays a message at the top of the 'playing area'. Will remain until dismissed with clearDisplayText() or setDisplayText() is called again.

Parameters:
text - a string identifying the text from a language file

clearDisplayText()

Clears the message from the top of the playing area, previously set with setDisplayText().

setCameraPosition(Vec2i pos)

Move the camera to the coordinates of pos.

Parameters:
pos - an array of two elements, specifying the co-ordinates {x,y}

createUnit(string unitName, int factionIndex, Vec2i pos)

Spawn a unit of unitName belonging to a faction.

Parameters:
unitName - name of a unit in the loaded factions
factionIndex - the index of the faction this unit will belong to
pos - an array of two elements, specifying the co-ordinates {x,y}

giveResource(string resourceName, int factionIndex, int amount)

Give an amount of a specified resource to a player, negative values are valid and have the obvious effect.
Parameters:
resourceName - a corresponding resource in the tech tree
factionIndex - the number identifier of the faction to give the resource
amount - the amount of resourceName the faction will receive

givePositionCommand ( int unitId, string commandName, Vec2i pos )

Instruct a unit to carry out a command of type 'attack' or 'move'.

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

giveProductionCommand(int unitId, string producedName)

Instruct a unit to carry out a command of type 'produce'.

Parameters:
unitId - the id of a unit that is to produce the new unit.
producedName - the type of unit to create.

giveUpgradeCommand(int unitId, string upgradeName)

Instruct a unit to carry out a command of type 'attack' or 'move'.

Parameters:
unitId - the id of the unit to perform the upgrade.
commandName - the type of upgrade to perform.

disableAi(int factionIndex)

Disables a factions AI. None of the faction's units will move without command.

Parameters:
factionIndex - the index of the faction [0-3, Player1=0]

setPlayerAsWinner(int factionIndex)

Sets the faction with factionIndex as the winner, would typically be followed by endGame().

Parameters:
factionIndex- the index of the faction [0-3, Player1=0]

endGame()

End the scenario, usually would be called after setPlayerAsWinner() when victory conditions have been met.

Queries

These function return useful information that can be used in command functions.

Vec2i startLocation ( factionIndex )

Obtains the start location for a given faction. Note that factions are 'zero indexed', player 1 is faction 0.

int unitFaction ( unitId )

Returns the faction index of the unit with unitId.

Events

These are xml tags used to execute lua code on its specified event. Variables can be used across different events. (TODO: see if events can be nested [Ed: This wont end well ;) -silnarm])

<startup>
[insert code] <startup>

<unitCreatedOfType type="unitname">
[insert code]
</unitCreatedOfType>

<unitDied>
[insert code]
</unitDied>

<resourceHarvested>
[insert code]
</resourceHarvested>