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.

Coordinate System

The origin {0,0} is at the 'top left' (or north-west if you like) of the screen. A map's size defined in 'Tiles', each of which is a block of 2*2 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.

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.

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

showMessage(string text, string header)

Display a message on the screen.

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

clearDisplayText()

Clears all message boxes from the screen, allowing space for the user to play, or for another message box to appear.

setCameraPosition(Vec2i pos)

Move the camera to the coordinates of pos.

Parameters:
pos - an {x,y} position

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 - a number identifier of the faction this unit will belong to
pos - an {x,y} position

giveResource(string resourceName, int factionIndex, int amount)

Give an amount of a specified resource to a player.
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.

Parameters:
unitId - the id of a unit that is on the map
commandName - the type of command to carry out (eg 'attack', 'move')
pos - an {x,y} position

disableAi(int factionIndex)

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

Parameters:
factionIndex - the number identifier of the faction

Queries

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

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)

<startup>
[insert code] <startup>

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

<unitDied>
[insert code]
</unitDied>

<resourceHarvested>
[insert code]
</resourceHarvested>

The available functions

As there is no list of the possible commands now, here a copy of some things from script_manager.h (from the glest sourcecode) which should contain/show all possible Glest lua-commands.

Message Box Functions

bool getMessageBoxEnabled() const {return !messageQueue.empty();}

GraphicMessageBox* getMessageBox() {return &messageBox;}

string getDisplayText() const {return displayText;}

bool getGameOver() const {return gameOver;}

const PlayerModifiers *getPlayerModifiers(int factionIndex) const {return &playerModifiers[factionIndex];}

Events

void onMessageBoxOk();

void onResourceHarvested();

void onUnitCreated(const Unit* unit);

void onUnitDied(const Unit* unit);

private:

string wrapString(const string &str, int wrapCount);

Wrappers, Commands

void showMessage(const string &text, const string &header);

void clearDisplayText();

void setDisplayText(const string &text);

void setCameraPosition(const Vec2i &pos);

void createUnit(const string &unitName, int factionIndex, Vec2i pos);

void giveResource(const string &resourceName, int factionIndex, int amount);

void givePositionCommand(int unitId, const string &producedName, const Vec2i &pos);

void giveProductionCommand(int unitId, const string &producedName);

void giveUpgradeCommand(int unitId, const string &upgradeName);

void disableAi(int factionIndex);

void setPlayerAsWinner(int factionIndex);

void endGame();

Wrappers, Queries

Vec2i getStartLocation(int factionIndex);

Vec2i getUnitPosition(int unitId);

int getUnitFaction(int unitId);

int getResourceAmount(const string &resourceName, int factionIndex);

const string &getLastCreatedUnitName();

int getLastCreatedUnitId();

const string &getLastDeadUnitName();

int getLastDeadUnitId();

int getUnitCount(int factionIndex);

int getUnitCountOfType(int factionIndex, const string &typeName);

Callbacks, Commands

static int showMessage(LuaHandle* luaHandle);

static int setDisplayText(LuaHandle* luaHandle);

static int clearDisplayText(LuaHandle* luaHandle);

static int setCameraPosition(LuaHandle* luaHandle);

static int createUnit(LuaHandle* luaHandle);

static int giveResource(LuaHandle* luaHandle);

static int givePositionCommand(LuaHandle* luaHandle);

static int giveProductionCommand(LuaHandle* luaHandle);

static int giveUpgradeCommand(LuaHandle* luaHandle);

static int disableAi(LuaHandle* luaHandle);

static int setPlayerAsWinner(LuaHandle* luaHandle);

static int endGame(LuaHandle* luaHandle);

Callbacks, Queries

static int getStartLocation(LuaHandle* luaHandle);

static int getUnitPosition(LuaHandle* luaHandle);

static int getUnitFaction(LuaHandle* luaHandle);

static int getResourceAmount(LuaHandle* luaHandle);

static int getLastCreatedUnitName(LuaHandle* luaHandle);

static int getLastCreatedUnitId(LuaHandle* luaHandle);

static int getLastDeadUnitName(LuaHandle* luaHandle);

static int getLastDeadUnitId(LuaHandle* luaHandle);

static int getUnitCount(LuaHandle* luaHandle);

static int getUnitCountOfType(LuaHandle* luaHandle);