LUA SCRIPTING IN GLEST

Lua is a relatively simple language to learn, but is very powerful none-of-the-less. Lua
means Moon in Porteguesse. In Lua script, anything behind -- is not used. The text behind
this is generally just comments and headers so you know what each section is when creating
the script. For this document Black text means that's how it appears in the script, red
text describes the black, and green text is just ordinary text that can be explaining
or talking about anything.

Command List (Normal):
These commands can be used right in the game. Some areas will have to be filled in, of
course, but asside from that, this is EXACTLY how they would appear normally!

showMessage('message-tag', 'message-topic')  -- shows a message in a pop-up box, this links to the scenarios .lng file

setDisplayText('Objective') -- Sets an objective that stays on the top of the screen until changed or removed

clearDisplayText() -- Clears the display text

setCameraPosition(unitPosition(lastCreatedUnit())) -- Sets the camera position. Can also be set to a tagged unit

nameUnit= lastCreatedUnit() -- Tags a name to a unit. Can be used to command that unit to use a command, position the camera over that unit, or command the game to end if that unit dies. Replace name with whatever you wish

createUnit('unit_name', 0, startLocation(0)) -- Creates a unit. Enter the unit name, the first number is the team. Remember the team numbers are 0,1,2, and 3. The second number is where the unit starts, 0 is at team 0's base (starting location)

giveResource('resource_name', 0, 1000) -- Gives resources to a player. Enter the resource name, the first number is the team, the second number is the ammount

givePositionCommand(lastCreatedUnit(), 'type', startLocation(0)) -- Gives a command to either attack or move to a position. Can be used on a tagged unit or the last created unit. Instead of type, it should say either move or attack. The start location is the starting location it will move/attack to.

giveProductionCommand(lastCreatedUnit(), 'unit_name') -- Gives command to a unit to produce another unit. Can also be assigned to tagged units. Put in the name of the unit you are producing. I could only get this to work for units such as the summoner, and not buildings. Not sure why... You can just use createUnit

giveUpgradeCommand(lastCreatedUnit(), 'upgrade_name') -- Gives command to a unit to start an upgrade. Can also be assigned to tagged units. Insert the upgrade name.

disableAi(0) -- Disables the AI so that they do nothing. Highly recommended to ensure that the AI doesn't screw anything up. This makes it easier to use the commands properly as well. Have this at the start-up area of the scenario's xml

setPlayerAsWinner(0) -- Sets a player as the winner. Usually used after defeating a certain foe. The number is the player that is set as winner. Multiple players can be set as winners. If you want the game to end after one of your units dies, you need to tell the game to make the computer the winner if that unit dies

endGame() -- I think this one is pretty obvious. This ends the game, use it after setting a player as the winner and clearing the display text.

if lastDeadUnit()==nameUnit then -- This is used primarily for making things happen after a unit dies. This can be used to end the game if a certain one of your units dies, it can make a new enemy village if one is destroyed, and can make reinforcements come. The unit MUST be tagged.

unitCount(0)==0 -- This is primarily used for making things happen when there is a certain ammount of units left for a faction. The first number is the faction, the second number is the ammount left. This could be used for sending reinforcements when there is only 1 unit left, or ending the game when there is 0 foes

lastCreatedUnit() -- This is used often, mainly for giving a command to the last unit you created. It can be used to command the unit you just made to attack, move, do an upgrade or simular command. This is also used in tagging

resourceAmount('resource_name', 0)>=100 -- This is usually used to allow something to happen after you get enough of a certain resource. Fill in the resource name in the first area, the number is parathesis is the faction, and > =100 means greater than 100. For example, more than 100 gold

unitFaction(lastCreatedUnit())==0 -- This isn't the most useful, but allows you to have something happen if the last unit created was from a certain faction. The number is the team number

(unitPosition(lastCreatedUnit())) -- Makes the a unit (namely the camera) position itself at a units position. Can be used with tagged units

unitCountOfType(0, 'unit_name')>=3 then -- This is used generally to have something happen after creating a number of the same units. The first number is the team number, then you put in the unit's name. The last number is the number you need to make.


Command List (Tagged):
This part has lists of commands in a tagged format. Tagging a unit means you slap name
on it. For example, in storming, the summoner is tagged as summonerUnit. You can tag
units as whatever you'd like, just make it something like xxxUnit and best if its
alpha-numeric (only letters and numbers) To tag a unit, type
nameUnit= lastCreatedUnit() after creating a unit. (In which nameUnit is the tag. It can
be testUnit, or ILikePieUnit. Anything. Tagged commands are exactly the same, but with
the tag name instead of lastCreatedUnit (or whatever)

setCameraPosition(unitPosition(nameUnit))

givePositionCommand(nameUnit, 'type', startLocation(0))

giveProductionCommand(nameUnit, 'unit_name')

giveUpgradeCommand(nameUnit, 'upgrade_name')

if lastDeadUnit()==nameUnit then

(unitPosition(nameUnit))


Sample Bits of Script:
This section will have samples of script and will tell the use of it.

givePositionCommand(lastCreatedUnit(), 'attack', startLocation(0)) -- This is used to attack a base. It can be used to send enemies to attack the player, or to have the player (or ally) attack the foe

givePositionCommand(lastCreatedUnit(), 'move', startLocation(0)) -- WHile not as useful as the above attack location line, this allows you to move a unit without attacking. Good for sending you new units, but that can also be done with the above script...

disableAi(0) -- Put this on every script. Otherwise the computer will screw things up. Unless you want the computer to be it's normal self, use this.

for i=1, 3 do
       createUnit('unit_name', 0, startLocation(0)) -- These 3 lines must be together to work. This basically creates a group of units, either yours, your ally's, or the enemies. It can create groups of any number of units. It can also use just one GivePositionCommand line to have all units attack a location.
end                                                          In this, i MUST always equal 1, 3 do means it'll make 3 units. This can be changed to any number. The next line needs the unit's name, the number after is it's team, and the last number in parathesis is the startLocation

for i=1, 3 do
       createUnit('unit_name', 0, startLocation(0)) 
       givePositionCommand(lastCreatedUnit(), 'attack', startLocation(1)) -- This is an edit of the above line, but with an attack location line added on. This will spwan the three units just like above, but the difference is that this will also have them attack location 1
end

if lastDeadUnit()==nameUnit then --This is the script for having a unit that if it dies, the game ends. Just tag that unit and change the nameUnit in this line into whatever you tagged the unit, Then in the number for setting player as winner, put the foe's team number in there. Now if that unit dies, the enemy wins
       clearDisplayText()
       setPlayerAsWinner(0)                                
       endGame()
end

How to make a simple scenario:
We are going to create a simple scenario. Just a simple one, to show you how to
get the basics. We are going to start, after you kill the scout, a big wave of foes
will come. Kill them to win the scenario. That's nice and simple. In a more complexe one,
you may have to defeat waves of foes coming from all sides while ensuring a certain unit
is not killed. But we're just going to do a nice and easy one. This can be made on any
text editor, such as notepad or notepad++. I'm going to use Notepad++ and we'll start with
no template. This is completely playable, there is no need to change it. If wanted, you can
copy and paste into a xml, then make the lng file. [NOTE: It'll take a moment once the game
starts for the food to add up, until then, you won't be able to make any units]

<?xml version="1.0" standalone="yes" ?>
<scenario>
       <difficulty value="2"/>
       <players>
               <player control="human" faction="tech" team="1"/>
               <player control="cpu-ultra" faction="magic" team="2"/>        
               <player control="closed"/>
               <player control="closed"/>
       </players>
       <map value="mountains"/>
       <tileset value="winter_forest"/>
       <tech-tree value="magitech"/>
       <default-resources value="false"/>
       <default-units value="false"/>
       <default-victory-conditions value="false"/>
       <scripts>
               <startup>
               
                       --disable AI
                       disableAi(3) --see, we just disabled the foe so they don't screw anything up

                       --allied units
                       createUnit('castle', 0, startLocation(0))        -- Here's our main building
                       giveResource('gold', 0, 1200); -- We'll give ourself some resource, we won't have much time before the enemy attack us
                       giveResource('wood', 0, 1200);
                       giveResource('stone', 0, 1000);
                       createUnit('farm', 0, startLocation(0)) -- We'll start with a farm, this way we don't have to waste time building one
                       createUnit('barracks', 0, startLocation(0)) -- Now we can make units, but not very powerful ones. We don't want that extra power, we need to get units quick!
                       createUnit('swordman', 0, startLocation(0))        
                       createUnit('swordman', 0, startLocation(0))        
                       createUnit('archer', 0, startLocation(0))        
                       createUnit('archer', 0, startLocation(0))
                       createUnit('guard', 0, startLocation(0))        
                       createUnit('cow', 0, startLocation(0)) -- Can't forget food!
                       createUnit('cow', 0, startLocation(0))                

                       --create enemy attackers
                       createUnit('summoner', 1, startLocation(1)) -- This is the enemy scout
                       foeUnit=lastCreatedUnit() -- Now we tagged her, so when she dies, the rest of the foe can come
                       givePositionCommand(lastCreatedUnit(), 'attack', startLocation(0)) -- Now she'll attack our base. We set her to start far away from us so it'll take her mor time to reach us

                       --objectives
                       objective='survive'
                       showMessage('survive', 'Survival') -- These'll link to the corresponding text in the lng file. We'll get on to that later
                       setDisplayText('ObjectiveOne')
               </startup>
                       
               <unitCreated>        

               </unitCreated>        


               <unitDied>

                       --check for scout slain
                       if lastDeadUnit()==foeUnit then -- We check to see if the scout is dead
                               
                               --create final barrage
                               for i=1, 8 do -- we need some daemons to run ahead and keep the player busy...
                                       createUnit('daemon', 1, startLocation(1))
                                       givePositionCommand(lastCreatedUnit(), 'attack', startLocation(0))        
                               end
                               for i=1, 6 do -- Now some battlemages, nothing too hard, this is a simple scenario
                                       createUnit('battlemage', 1, startLocation(1))
                                       givePositionCommand(lastCreatedUnit(), 'attack', startLocation(0))
                               end
                               createUnit('behemoth', 1, startLocation(1)) -- And one big baddy to finish off with
                               givePositionCommand(lastCreatedUnit(), 'attack', startLocation(0))
                       end        

                       --check to see if player won
                       if objective=='survive' and unitCount(1)==0 then -- If there is no foes left, the player wins!
                               clearDisplayText()
                               setPlayerAsWinner(0)                                
                               endGame()
                       end

               </unitDied>
       </scripts>
</scenario>

But wait, we aren't done yet! We still gotta make a english.lng file! The lng file is a
language file which tells the game what to say in Objectives and text boxes. It can be
changed per language, so that the scenario is in multiple languages. Make a text file,
but save as scenario_name_english.lng. If we call this scenario winter_survival, the lng
will have to be called winter_survival_english.lng (scenario_language.lng, in that order)
Now our lng will look like this:

;message headers
Survival=Survival

;message strings
survive=The winter climate is very dangerous, in more ways than one...

;objective strings
ObjectiveOne=Objective: Survive the harsh winters of the north...

Now place all this in a folder named winter_survival and place that in the scenarios folder
of Glest and we're good to go!

There, now we learned all the basics and all the functions of Lau, now go make some

scenarios!
Questions?
Comments?
Errors?

Email me at Omega99999@gmail.com