Scenario League Wiki - User contributions [en]

Sci-Fi Units

2023-01-12T17:27:10Z

Prof. Garfield: Removed curtsibling category, since he requested his art be removed from this page.

[[Category:Units]]
[[Category:Fairline]]
[[Category:Reno]]
[[Category:Hans99]]
== Dune ==

[[File:Reno_Dune_Units.gif]]

Author: [[Reno]].

[[File:Hans99_Dune2_units.png]]

Author: [[Hans99]].

== Star Wars ==

[[File:Fairline_sw6.png]]

Author: [[Fairline]].

== Star Control ==

[[File:Hans99_StarControl2.png]]

Author: [[Hans99]].

Main Page

2023-01-12T17:16:52Z

Prof. Garfield: Removed references to curtsibling work, since he requested his work be removed.

[[File:CIV2TITLE.png|center]]

'''Hi! The Scenario League is alive and well. Be sure to check back regularly as we rebuild the wiki. If you would like to help please let us know in this thread [http://forums.civfanatics.com/showthread.php?t=409484| SL Wiki Upload List]'''

== NEWS ==

[[Image:OTRpreview.png]] '''9th February 2020''' - John Petroski & Prof. Garfield release [https://forums.civfanatics.com/resources/over-the-reich.27172/ Over the Reich 4 ToTPP and Lua]

[[Image:Techumseh_avatar.png ]] '''19th January 2020''' - Techumseh re-releases all his scenarios for Test of Time! [http://sleague.civfanatics.com/index.php?title=User:Techumseh]

[[Image:OTRpreview.png]] '''20th December 2018''' - John Petroski & Prof. Garfield release [https://forums.civfanatics.com/threads/over-the-reich-a-multiplayer-scenario-for-totpp-and-lua-released.639907/#post-15313097 Over the Reich ToTPP and Lua]

[[Image:Napoleon Icon.gif]] '''21st November 2018''' - Tootall_2012 releases [https://forums.civfanatics.com/threads/napol%C3%A9on-i-1805-1815-totpp-and-lua-scenario-released.638700/ Napoléon I 1805 - 1815 ToTPP and Lua]

[[Image:Sealion.png]] '''19th June 2018''' - Techumseh releases [https://forums.civfanatics.com/threads/operation-seelowe-released.633642/ Operation Seelowe ToTPP]

[[Image:Caesar1.png]] '''16th April 2018''' - John Petroski & Grishnach release [https://forums.civfanatics.com/threads/caesars-gallic-wars.628330//Caesar's Gallic Wars ToTPP and Lua]

[[Image:4KOR.gif]] '''12th June 2017''' - Patine & McMonkey release [https://forums.civfanatics.com/threads/korean-war-revisited.452059//The_Korean_War_Redux_ToTPP_v1 The Korean War Redux ToTPP]

[[Image:Nam65_Icon.png]] '''20th June 2017''' - Tootall_2012 releases [https://forums.civfanatics.com/threads/vietnam-war-development-thread.534783/ Vietnam 1965- 1975 ToTPP]

[[Image:Anarchist.png]] '''30th March 2015''' - McMonkey releases [http://sleague.civfanatics.com/index.php/The_Spanish_Civil_War_ToTPP Spanish Civil War ToTPP]

[[Image:Numidian.png]] '''12th November 2013''' - Nicheal releases [http://sleague.civfanatics.com/index.php/Ancient_Steel Ancient Steel]

[[Image:Speeder.png]] '''12th November 2013''' - Nicheal releases [http://sleague.civfanatics.com/index.php/SubWar Sub War Deluxe]

[[Image:RomBr.png]] '''5th November 2013''' - committed hero (aka Michael Daumen) releases [http://forums.civfanatics.com/showthread.php?t=513967 Roman Britain]

[[Image:WWIB.png]] '''1st October 2013''' - Bultro releases [http://forums.civfanatics.com/downloads.php?do=file&id=21851 Worldwar - In the Balance]

[[Image:ToT1.png]] '''March to October 2013''' - Petit's ToT Mods include Menilek II of Ethiopia, Unity of Italy, Fire and Roses, Four Sea Republic, Star Wars: Insurrection (version 1.3), Star Contact: Part 1 The Star Wars, Cold War Crisis, Timur, Spanish Civil War: The Defence of Madrid (version 2.1), Mamluks, Sparta, Hellenis, World War One, American Civil War, Komnenai, The Thirty Years War and Carolus [http://forums.civfanatics.com/showthread.php?t=410838&page=6 Petit's ToT Mods thread]

[[Image:AHD.png]] '''13th July 2013''' - Tootall_2012 releases [http://sleague.civfanatics.com/index.php/A_House_Divided_1861_-1865 A House Divided 1861 - 1865]

[[Image:STM.png]] '''24th June 2013''' - Metro Polis releases [http://forums.civfanatics.com/showthread.php?t=466004 Star Trek Mod for ToT]

[[Image:LDoE.png]] '''19th April 2013''' - Dadais releases [http://forums.civfanatics.com/downloads.php?do=file&id=21113 Last Days Of Empire]

[[Image:ToT1.png]] '''16th March 2013''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #79).
They include: The Peloponnesian War, Struggle for Empire, The Seven Years War, The Spanish-American War: The Carribean, Crises of the New World Order, 2013: A Union Divided, Moria A Journey in the Dark and The Lord of the Rings by Harlan Thompson.

[[Image:ToT1.png]] '''26th September 2012''' - Techumseh releases [http://forums.civfanatics.com/downloads.php?do=file&id=20137 TechMod]

[[Image:Blood.png]] '''7th October 2012''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=477405 Blood and Sieges]

[[Image:TechMod.png]] '''26th September 2012''' - Techumseh releases [http://forums.civfanatics.com/showthread.php?t=476516 TechMod]

[[Image:SpaceMod.png]] '''18th September 2012''' - Skulb releases [http://forums.civfanatics.com/showthread.php?t=475802 Space Mod for ToT]

[[Image:IwoJima.png]] '''8th September 2012''' - Tootall_2012 releases [http://forums.civfanatics.com/showthread.php?t=474972 Battle of Iwo Jima 1945]

[[Image:Curzan.png]] '''18th August 2012''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=459580 The Cruzan Colony (See post #12)]

[[Image:SciFi.png]] '''24th June 2012''' - Metro Polis releases [http://forums.civfanatics.com/showthread.php?t=466004 Star Trek Mod for ToT]

[[Image:BoF44DD.png]] '''12th February 2012''' - Tootall_2012 releases [http://sleague.civfanatics.com/index.php/Battle_of_France_1944 Battle for France 1944]

[[Image:SilmarilSL.png]] '''3rd October 2011''' - Nicheal releases [http://forums.civfanatics.com/downloads.php?do=file&id=17697 The Silmarillion]

[[Image:Sobieski.png]] '''12th September 2011''' - Nikoagonistes (aka Ghost of Disco) releases [http://forums.civfanatics.com/showthread.php?t=428221 Jan III Sobieski v.1.0 (See post #11)]

[[Image:ToT1.png]] '''24th June 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?t=410838&page=3 Modified Scenarios Workshop thread] at the SL Forum (post #53).
They include:
Age of Crusades, In Nomine, Medium Aevum and Drole de Guerre

[[Image:WSilverSkullSL.png]] '''15th March 2011''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=415363 The Lord of the Silver Skull]

[[Image:ToT1.png]] '''25th February 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #11).
They include:
The Great War: Highway to Hell, How Few Remain, The War of Cuba and The Mongols: From Genghis to Kublai Khan.

[[Image:BeachAssault.png]] '''16th February 2011''' - Harry Tuttle re-releases [[Beach Assault]] [http://forums.civfanatics.com/showthread.php?t=412144 SL Thread]

[[Image:wMoscowSL.png]] '''15th February 2011''' - Keu releases a modified ToT version of Micheal Daumen's [http://forums.civfanatics.com/showthread.php?t=410764 Moscow - The Third Rome (post #17)]

[[Image:wGermanicusSL.png]] '''13th February 2011''' - John Petroski releases [[Germanicus on the Rhine]] [http://forums.civfanatics.com/showthread.php?p=10213254#post10213254 SL Thread]

[[Image:ToT1.png]] '''12th February 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #7).
They include: The Age of Crusades, The Anglo-Boer War, Bonaparte II, Congo!, First Strike, The Lord of the Rings IV, The Russian Revolution and Yugoslavia: Suicide of a European Nation.

[[Image:wKoSSL.png]] '''12th February 2011''' - Custsibling re-releases [[Kingdoms of Steel]] [http://forums.civfanatics.com/showthread.php?p=10210185#post10210185 SL Thread]

[[Image:ToT1.png]] '''11th February 2011''' - Petit releases a collection of ToT conversions / mods in the [http://forums.civfanatics.com/showthread.php?p=10208556#post10208556 Modified Scenarios Workshop thread] at the SL Forum (post#3).
They include: The Italian Wars, Historibus Europae, Hannibal's War, Gold Gulch, Struggle for Empire, Colonialism II, Carolus Invictissimus, The American Civil War and the Thirty Years War.

[[Image:wGreatGameSL.png]] '''11th February 2011''' - Keu releases a modified ToT version of Micheal Daumen's [http://forums.civfanatics.com/showthread.php?p=10206652#post10206652 The Great Game]

[[Image:wAWISL.png]] '''9th February 2011''' - civ2units releases [[American War of Independence]] [http://forums.civfanatics.com/showthread.php?t=411273 SL Thread]

Sci-Fi Units

2023-01-12T17:15:06Z

Prof. Garfield: /* Doctor Who */ Removed section since curtsibling doesn't want his work/art here anymore

[[Category:Units]]
[[Category:curtsibling]]
[[Category:Fairline]]
[[Category:Reno]]
[[Category:Hans99]]
== Dune ==

[[File:Reno_Dune_Units.gif]]

Author: [[Reno]].

[[File:Hans99_Dune2_units.png]]

Author: [[Hans99]].

== Star Wars ==

[[File:Fairline_sw6.png]]

Author: [[Fairline]].

== Star Control ==

[[File:Hans99_StarControl2.png]]

Author: [[Hans99]].

The Age of Reformation

2021-09-16T22:49:27Z

Prof. Garfield: Created Page, copied info

[[Category:Civ2units]]
[[Category:Civilization II: Test of Time]]
[[File:Reformation_Title.jpg]]

"''If you want to change the world, pick up your pen and write.''"
- Martin Luther (1483-1546)

'''JANUARY 1517, EUROPE'''

Since Christopher Columbus journey in 1492, the World is another. Instead of finding a direct seaway to India, he discovered a complete new continent. Indigenous people,
who are thinking the people from the sea are gods welcomes the conquistadors without suspecting that they are not comming in peace. Rumours of large amounts of gold
and other riches allures more and more soldiers from Europe into the New World and leading finally into the conquest of the mighty empires of the Aztecs, Mayas and Incas.

Europe itself awakens from its sleeping beauty after the medieval age and enters into a new era. People starts questioning the old world order, the kings realizing
that there is much more behind the horizen and the catholic church stands in front of a real threat: The Protestant Movement. Initiated by a young theology professor,
this movement will change complete Europe for ever and leading into one of the most devastating wars the continent ever saw.

The Ottomans used them first time during the siege of Constantinople in 1453; giant cannons who damaged the until then undestroyed Theodosian Walls. After the
fall of Constantinople the black powder replaced arrows and bows, swords and shields on the battlefield. The feudal knights where replacde by modern armoured cavalry
and infantry equipped with a pike where accompanied from so called Arquebusiers, men armed with a firearm. Big cannons replaced the catapults and trebuchets and
therefore modernized the whole warfare.

You play as the Spanish-Habsburg Empire and your goal is to establish the Viceroyalty of New Spain. But don't concentrate too much on the New World, dark clouds are
gathering on Europe's horizen as the Reformation Movement finds more and more supporters. The power of the Catholic church is in danger and there is war in the air.
Can you face the threat and re-unite the Holy Roman Empire under one church?

== Required Game Version ==

This scenario requires the latest official Civilization II ToT patch as well as the ToTPP version 0.16

You can find the latest official Civiliazion 2 ToT patch here:

[http://forums.civfanatics.com/resources/test-of-time-v1-1-patch.59/ Official ToT patch 1.1]

You can find the ToTPP version 0.16 here:

[http://forums.civfanatics.com/threads/the-test-of-time-patch-project.517282/ ToTPP from TheNamelessOne]

== Installation ==

Create a new folder called "'''Reformation'''" in your "'''The Test of Time/Original'''" directory.
Copy the following files into the "'''Reformation'''" folder.

Will be filled

== Ingame Graphics ==

Will be filled

== Game Rules ==

This scenario is designed for playing with the Spanish-Habsburg Empire only. Your goal ist to conquer Central and South America and the Holy Roman Empire.

Will be filled

== Victory Points ==

The following cities must be under you control for a complete victory:

'''EUROPE:'''

3x OBJECTIVE points => Munich, Strasbourg, Frankfurt, Nuremberg, Dresden, Berlin, Stettin, Hanover, Hamburg, Cologne, Amsterdam, Antwerp

1x OBJECTIVE points => Zurich, Dijon, Brussels, Prague, Budapest, Zagreb, Trieste, Szeged, Debrecen, Belgrade

'''NEW WORLD:'''

3x OBJECTIVE points => Tenochtitlan (Mexico City), Zacatecas, Tegucigalpa, Chorotega (San José), Quito, Tomebamba (Guayaquil), Bogota

1x OBJECTIVE points => Santarem, Habana (Havana), Camaguey, Moron (Santiago de Cuba), Santo Domingo, Angostura (Paramaribo), Guayana (Ciudad Guayana), Panama (Panama City), Chortli (La Ceiba), Jamaica (Kingston), Caguas (San Juan), Mayaro (San Fernando), Anguilla, Dominica, Tuxpan (Tampico), Xalapa (Veracruz), Tehuacan, Cihuatlan (Acapulco), Xicallancas (Villahermosa)

'''AFRICA:'''

1x OBJECTIVE points => Tunis, Tripolis, Alexandria, Cairo, Ondo, Abidjan, Accra

The victory conditions are as followed:

Decisive victory: >= 90 points

Marginal Victory: >= 80 points

Marginal Defeat: <= 50 points

Decisive Defeat: <= 30 points

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2020-07-05T17:06:56Z

Prof. Garfield: /* Barracks and Veteran Status */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the key "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [https://forums.civfanatics.com/threads/totpp-flags-and-counters-library.648757/ flags]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of the state table passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) </code> to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

NOTE: It was discovered that you can simply create a new unit and delete the produced unit in order to avoid bestowing veteran status from a barracks. This will be much easier than saving stuff in tables. However, this example is still useful.

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you will gain confidence with practice and experience. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2020-07-05T17:06:36Z

Prof. Garfield: /* Barracks and Veteran Status */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the key "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [https://forums.civfanatics.com/threads/totpp-flags-and-counters-library.648757/ flags]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of the state table passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) </code> to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

NOTE: It was discovered that you can simply create a new unit and delete the produced unit in order to avoid bestowing veteran status from a barracks. This will be much easier than saving stuff in tables.

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you will gain confidence with practice and experience. Ask for help if and when you need it.

Main Page

2020-02-09T17:39:45Z

Prof. Garfield: /* NEWS */

[[File:CIV2TITLE.png|center]]

'''Hi! The Scenario League is alive and well. Be sure to check back regularly as we rebuild the wiki. If you would like to help please let us know in this thread [http://forums.civfanatics.com/showthread.php?t=409484| SL Wiki Upload List]'''

== NEWS ==

[[Image:OTRpreview.png]] '''9th February 2020''' - John Petroski & Prof. Garfield release [https://forums.civfanatics.com/resources/over-the-reich.27172/ Over the Reich 4 ToTPP and Lua]

[[Image:Techumseh_avatar.png ]] '''19th January 2020''' - Techumseh re-releases all his scenarios for Test of Time! [http://sleague.civfanatics.com/index.php?title=User:Techumseh]

[[Image:OTRpreview.png]] '''20th December 2018''' - John Petroski & Prof. Garfield release [https://forums.civfanatics.com/threads/over-the-reich-a-multiplayer-scenario-for-totpp-and-lua-released.639907/#post-15313097 Over the Reich ToTPP and Lua]

[[Image:Napoleon Icon.gif]] '''21st November 2018''' - Tootall_2012 releases [https://forums.civfanatics.com/threads/napol%C3%A9on-i-1805-1815-totpp-and-lua-scenario-released.638700/ Napoléon I 1805 - 1815 ToTPP and Lua]

[[Image:Sealion.png]] '''19th June 2018''' - Techumseh releases [https://forums.civfanatics.com/threads/operation-seelowe-released.633642/ Operation Seelowe ToTPP]

[[Image:Caesar1.png]] '''16th April 2018''' - John Petroski & Grishnach release [https://forums.civfanatics.com/threads/caesars-gallic-wars.628330//Caesar's Gallic Wars ToTPP and Lua]

[[Image:4KOR.gif]] '''12th June 2017''' - Patine & McMonkey release [https://forums.civfanatics.com/threads/korean-war-revisited.452059//The_Korean_War_Redux_ToTPP_v1 The Korean War Redux ToTPP]

[[Image:Nam65_Icon.png]] '''20th June 2017''' - Tootall_2012 releases [https://forums.civfanatics.com/threads/vietnam-war-development-thread.534783/ Vietnam 1965- 1975 ToTPP]

[[Image:Anarchist.png]] '''30th March 2015''' - McMonkey releases [http://sleague.civfanatics.com/index.php/The_Spanish_Civil_War_ToTPP Spanish Civil War ToTPP]

[[Image:Numidian.png]] '''12th November 2013''' - Nicheal releases [http://sleague.civfanatics.com/index.php/Ancient_Steel Ancient Steel]

[[Image:Speeder.png]] '''12th November 2013''' - Nicheal releases [http://sleague.civfanatics.com/index.php/SubWar Sub War Deluxe]

[[Image:RomBr.png]] '''5th November 2013''' - committed hero (aka Michael Daumen) releases [http://forums.civfanatics.com/showthread.php?t=513967 Roman Britain]

[[Image:WWIB.png]] '''1st October 2013''' - Bultro releases [http://forums.civfanatics.com/downloads.php?do=file&id=21851 Worldwar - In the Balance]

[[Image:ToT1.png]] '''March to October 2013''' - Petit's ToT Mods include Menilek II of Ethiopia, Unity of Italy, Fire and Roses, Four Sea Republic, Star Wars: Insurrection (version 1.3), Star Contact: Part 1 The Star Wars, Cold War Crisis, Timur, Spanish Civil War: The Defence of Madrid (version 2.1), Mamluks, Sparta, Hellenis, World War One, American Civil War, Komnenai, The Thirty Years War and Carolus [http://forums.civfanatics.com/showthread.php?t=410838&page=6 Petit's ToT Mods thread]

[[Image:AHD.png]] '''13th July 2013''' - Tootall_2012 releases [http://sleague.civfanatics.com/index.php/A_House_Divided_1861_-1865 A House Divided 1861 - 1865]

[[Image:STM.png]] '''24th June 2013''' - Metro Polis releases [http://forums.civfanatics.com/showthread.php?t=466004 Star Trek Mod for ToT]

[[Image:Zarklaw2_Icon.gif]] '''30th April 2013''' - Curtsibling releases [http://forums.civfanatics.com/downloads.php?do=file&id=21147 Battle fo Zarklaw II]

[[Image:LDoE.png]] '''19th April 2013''' - Dadais releases [http://forums.civfanatics.com/downloads.php?do=file&id=21113 Last Days Of Empire]

[[Image:ToT1.png]] '''16th March 2013''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #79).
They include: The Peloponnesian War, Struggle for Empire, The Seven Years War, The Spanish-American War: The Carribean, Crises of the New World Order, 2013: A Union Divided, Moria A Journey in the Dark and The Lord of the Rings by Harlan Thompson.

[[Image:ToT1.png]] '''26th September 2012''' - Techumseh releases [http://forums.civfanatics.com/downloads.php?do=file&id=20137 TechMod]

[[Image:Blood.png]] '''7th October 2012''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=477405 Blood and Sieges]

[[Image:TechMod.png]] '''26th September 2012''' - Techumseh releases [http://forums.civfanatics.com/showthread.php?t=476516 TechMod]

[[Image:SpaceMod.png]] '''18th September 2012''' - Skulb releases [http://forums.civfanatics.com/showthread.php?t=475802 Space Mod for ToT]

[[Image:IwoJima.png]] '''8th September 2012''' - Tootall_2012 releases [http://forums.civfanatics.com/showthread.php?t=474972 Battle of Iwo Jima 1945]

[[Image:Curzan.png]] '''18th August 2012''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=459580 The Cruzan Colony (See post #12)]

[[Image:SciFi.png]] '''24th June 2012''' - Metro Polis releases [http://forums.civfanatics.com/showthread.php?t=466004 Star Trek Mod for ToT]

[[Image:BoF44DD.png]] '''12th February 2012''' - Tootall_2012 releases [http://sleague.civfanatics.com/index.php/Battle_of_France_1944 Battle for France 1944]

[[Image:SilmarilSL.png]] '''3rd October 2011''' - Nicheal releases [http://forums.civfanatics.com/downloads.php?do=file&id=17697 The Silmarillion]

[[Image:Sobieski.png]] '''12th September 2011''' - Nikoagonistes (aka Ghost of Disco) releases [http://forums.civfanatics.com/showthread.php?t=428221 Jan III Sobieski v.1.0 (See post #11)]

[[Image:AmericanKingdomsSL.png]] '''14th August 2011''' - Curtsibling releases [http://forums.civfanatics.com/showthread.php?t=435870 American Kingdoms]

[[Image:ToT1.png]] '''24th June 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?t=410838&page=3 Modified Scenarios Workshop thread] at the SL Forum (post #53).
They include:
Age of Crusades, In Nomine, Medium Aevum and Drole de Guerre

[[Image:WSilverSkullSL.png]] '''15th March 2011''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=415363 The Lord of the Silver Skull]

[[Image:ToT1.png]] '''25th February 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #11).
They include:
The Great War: Highway to Hell, How Few Remain, The War of Cuba and The Mongols: From Genghis to Kublai Khan.

[[Image:WBattleOfZarklawSL.png]] '''19th February 2011''' - Curtsibling releases [http://forums.civfanatics.com/showthread.php?p=10233571#post10233571 Battle of Zarklaw]

[[Image:BeachAssault.png]] '''16th February 2011''' - Harry Tuttle re-releases [[Beach Assault]] [http://forums.civfanatics.com/showthread.php?t=412144 SL Thread]

[[Image:wMoscowSL.png]] '''15th February 2011''' - Keu releases a modified ToT version of Micheal Daumen's [http://forums.civfanatics.com/showthread.php?t=410764 Moscow - The Third Rome (post #17)]

[[Image:wGermanicusSL.png]] '''13th February 2011''' - John Petroski releases [[Germanicus on the Rhine]] [http://forums.civfanatics.com/showthread.php?p=10213254#post10213254 SL Thread]

[[Image:ToT1.png]] '''12th February 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #7).
They include: The Age of Crusades, The Anglo-Boer War, Bonaparte II, Congo!, First Strike, The Lord of the Rings IV, The Russian Revolution and Yugoslavia: Suicide of a European Nation.

[[Image:wKoSSL.png]] '''12th February 2011''' - Custsibling re-releases [[Kingdoms of Steel]] [http://forums.civfanatics.com/showthread.php?p=10210185#post10210185 SL Thread]

[[Image:ToT1.png]] '''11th February 2011''' - Petit releases a collection of ToT conversions / mods in the [http://forums.civfanatics.com/showthread.php?p=10208556#post10208556 Modified Scenarios Workshop thread] at the SL Forum (post#3).
They include: The Italian Wars, Historibus Europae, Hannibal's War, Gold Gulch, Struggle for Empire, Colonialism II, Carolus Invictissimus, The American Civil War and the Thirty Years War.

[[Image:wGreatGameSL.png]] '''11th February 2011''' - Keu releases a modified ToT version of Micheal Daumen's [http://forums.civfanatics.com/showthread.php?p=10206652#post10206652 The Great Game]

[[Image:wAWISL.png]] '''9th February 2011''' - civ2units releases [[American War of Independence]] [http://forums.civfanatics.com/showthread.php?t=411273 SL Thread]

[[Image:wSovietSteelSL.png]] '''4th February 2011''' - Curtsibling re-releases [http://forums.civfanatics.com/downloads.php?do=file&id=16511 Soviet Steel for MGE]

[[Image:wBitterMGE.png]] '''3rd February 2011''' - Curtsibling re-releases [http://forums.civfanatics.com/downloads.php?do=file&id=16500 Bitterfrost for MGE]

[[Image:wKaiserSL.png]] '''29th January 2011''' - Curtsibling re-releases [http://forums.civfanatics.com/showthread.php?t=409947 Kaiser]

[[Image:wDalekSL.png]] '''28th January 2011''' - Curtsibling releases [http://forums.civfanatics.com/downloads.php?do=file&id=16446 Dalek Tyranny]

[[Image:wDictator_2011SL.png]] '''27th January 2011''' - Curtsibling releases [[The Eurasian Wars]] [http://forums.civfanatics.com/downloads.php?do=file&id=16437 SL Thread]

[[Image:wExterminateSL.png]] '''27th January 2011''' - Curtsibling releases [[Extermination]] [http://forums.civfanatics.com/downloads.php?do=file&id=16438 SL Thread]

Main Page

2020-02-09T17:37:48Z

Prof. Garfield: /* NEWS */ Over the Reich 4 release announcement

[[File:CIV2TITLE.png|center]]

'''Hi! The Scenario League is alive and well. Be sure to check back regularly as we rebuild the wiki. If you would like to help please let us know in this thread [http://forums.civfanatics.com/showthread.php?t=409484| SL Wiki Upload List]'''

== NEWS ==

[[Image:OTRpreview.png]] '''9th December 2020''' - John Petroski & Prof. Garfield release [https://forums.civfanatics.com/resources/over-the-reich.27172/ Over the Reich 4 ToTPP and Lua]

[[Image:Techumseh_avatar.png ]] '''19th January 2020''' - Techumseh re-releases all his scenarios for Test of Time! [http://sleague.civfanatics.com/index.php?title=User:Techumseh]

[[Image:OTRpreview.png]] '''20th December 2018''' - John Petroski & Prof. Garfield release [https://forums.civfanatics.com/threads/over-the-reich-a-multiplayer-scenario-for-totpp-and-lua-released.639907/#post-15313097 Over the Reich ToTPP and Lua]

[[Image:Napoleon Icon.gif]] '''21st November 2018''' - Tootall_2012 releases [https://forums.civfanatics.com/threads/napol%C3%A9on-i-1805-1815-totpp-and-lua-scenario-released.638700/ Napoléon I 1805 - 1815 ToTPP and Lua]

[[Image:Sealion.png]] '''19th June 2018''' - Techumseh releases [https://forums.civfanatics.com/threads/operation-seelowe-released.633642/ Operation Seelowe ToTPP]

[[Image:Caesar1.png]] '''16th April 2018''' - John Petroski & Grishnach release [https://forums.civfanatics.com/threads/caesars-gallic-wars.628330//Caesar's Gallic Wars ToTPP and Lua]

[[Image:4KOR.gif]] '''12th June 2017''' - Patine & McMonkey release [https://forums.civfanatics.com/threads/korean-war-revisited.452059//The_Korean_War_Redux_ToTPP_v1 The Korean War Redux ToTPP]

[[Image:Nam65_Icon.png]] '''20th June 2017''' - Tootall_2012 releases [https://forums.civfanatics.com/threads/vietnam-war-development-thread.534783/ Vietnam 1965- 1975 ToTPP]

[[Image:Anarchist.png]] '''30th March 2015''' - McMonkey releases [http://sleague.civfanatics.com/index.php/The_Spanish_Civil_War_ToTPP Spanish Civil War ToTPP]

[[Image:Numidian.png]] '''12th November 2013''' - Nicheal releases [http://sleague.civfanatics.com/index.php/Ancient_Steel Ancient Steel]

[[Image:Speeder.png]] '''12th November 2013''' - Nicheal releases [http://sleague.civfanatics.com/index.php/SubWar Sub War Deluxe]

[[Image:RomBr.png]] '''5th November 2013''' - committed hero (aka Michael Daumen) releases [http://forums.civfanatics.com/showthread.php?t=513967 Roman Britain]

[[Image:WWIB.png]] '''1st October 2013''' - Bultro releases [http://forums.civfanatics.com/downloads.php?do=file&id=21851 Worldwar - In the Balance]

[[Image:ToT1.png]] '''March to October 2013''' - Petit's ToT Mods include Menilek II of Ethiopia, Unity of Italy, Fire and Roses, Four Sea Republic, Star Wars: Insurrection (version 1.3), Star Contact: Part 1 The Star Wars, Cold War Crisis, Timur, Spanish Civil War: The Defence of Madrid (version 2.1), Mamluks, Sparta, Hellenis, World War One, American Civil War, Komnenai, The Thirty Years War and Carolus [http://forums.civfanatics.com/showthread.php?t=410838&page=6 Petit's ToT Mods thread]

[[Image:AHD.png]] '''13th July 2013''' - Tootall_2012 releases [http://sleague.civfanatics.com/index.php/A_House_Divided_1861_-1865 A House Divided 1861 - 1865]

[[Image:STM.png]] '''24th June 2013''' - Metro Polis releases [http://forums.civfanatics.com/showthread.php?t=466004 Star Trek Mod for ToT]

[[Image:Zarklaw2_Icon.gif]] '''30th April 2013''' - Curtsibling releases [http://forums.civfanatics.com/downloads.php?do=file&id=21147 Battle fo Zarklaw II]

[[Image:LDoE.png]] '''19th April 2013''' - Dadais releases [http://forums.civfanatics.com/downloads.php?do=file&id=21113 Last Days Of Empire]

[[Image:ToT1.png]] '''16th March 2013''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #79).
They include: The Peloponnesian War, Struggle for Empire, The Seven Years War, The Spanish-American War: The Carribean, Crises of the New World Order, 2013: A Union Divided, Moria A Journey in the Dark and The Lord of the Rings by Harlan Thompson.

[[Image:ToT1.png]] '''26th September 2012''' - Techumseh releases [http://forums.civfanatics.com/downloads.php?do=file&id=20137 TechMod]

[[Image:Blood.png]] '''7th October 2012''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=477405 Blood and Sieges]

[[Image:TechMod.png]] '''26th September 2012''' - Techumseh releases [http://forums.civfanatics.com/showthread.php?t=476516 TechMod]

[[Image:SpaceMod.png]] '''18th September 2012''' - Skulb releases [http://forums.civfanatics.com/showthread.php?t=475802 Space Mod for ToT]

[[Image:IwoJima.png]] '''8th September 2012''' - Tootall_2012 releases [http://forums.civfanatics.com/showthread.php?t=474972 Battle of Iwo Jima 1945]

[[Image:Curzan.png]] '''18th August 2012''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=459580 The Cruzan Colony (See post #12)]

[[Image:SciFi.png]] '''24th June 2012''' - Metro Polis releases [http://forums.civfanatics.com/showthread.php?t=466004 Star Trek Mod for ToT]

[[Image:BoF44DD.png]] '''12th February 2012''' - Tootall_2012 releases [http://sleague.civfanatics.com/index.php/Battle_of_France_1944 Battle for France 1944]

[[Image:SilmarilSL.png]] '''3rd October 2011''' - Nicheal releases [http://forums.civfanatics.com/downloads.php?do=file&id=17697 The Silmarillion]

[[Image:Sobieski.png]] '''12th September 2011''' - Nikoagonistes (aka Ghost of Disco) releases [http://forums.civfanatics.com/showthread.php?t=428221 Jan III Sobieski v.1.0 (See post #11)]

[[Image:AmericanKingdomsSL.png]] '''14th August 2011''' - Curtsibling releases [http://forums.civfanatics.com/showthread.php?t=435870 American Kingdoms]

[[Image:ToT1.png]] '''24th June 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?t=410838&page=3 Modified Scenarios Workshop thread] at the SL Forum (post #53).
They include:
Age of Crusades, In Nomine, Medium Aevum and Drole de Guerre

[[Image:WSilverSkullSL.png]] '''15th March 2011''' - Nicheal releases [http://forums.civfanatics.com/showthread.php?t=415363 The Lord of the Silver Skull]

[[Image:ToT1.png]] '''25th February 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #11).
They include:
The Great War: Highway to Hell, How Few Remain, The War of Cuba and The Mongols: From Genghis to Kublai Khan.

[[Image:WBattleOfZarklawSL.png]] '''19th February 2011''' - Curtsibling releases [http://forums.civfanatics.com/showthread.php?p=10233571#post10233571 Battle of Zarklaw]

[[Image:BeachAssault.png]] '''16th February 2011''' - Harry Tuttle re-releases [[Beach Assault]] [http://forums.civfanatics.com/showthread.php?t=412144 SL Thread]

[[Image:wMoscowSL.png]] '''15th February 2011''' - Keu releases a modified ToT version of Micheal Daumen's [http://forums.civfanatics.com/showthread.php?t=410764 Moscow - The Third Rome (post #17)]

[[Image:wGermanicusSL.png]] '''13th February 2011''' - John Petroski releases [[Germanicus on the Rhine]] [http://forums.civfanatics.com/showthread.php?p=10213254#post10213254 SL Thread]

[[Image:ToT1.png]] '''12th February 2011''' - Petit releases a collection of ToT conversuons / mods in the [http://forums.civfanatics.com/showthread.php?p=10210259#post10210259 Modified Scenarios Workshop thread] at the SL Forum (post #7).
They include: The Age of Crusades, The Anglo-Boer War, Bonaparte II, Congo!, First Strike, The Lord of the Rings IV, The Russian Revolution and Yugoslavia: Suicide of a European Nation.

[[Image:wKoSSL.png]] '''12th February 2011''' - Custsibling re-releases [[Kingdoms of Steel]] [http://forums.civfanatics.com/showthread.php?p=10210185#post10210185 SL Thread]

[[Image:ToT1.png]] '''11th February 2011''' - Petit releases a collection of ToT conversions / mods in the [http://forums.civfanatics.com/showthread.php?p=10208556#post10208556 Modified Scenarios Workshop thread] at the SL Forum (post#3).
They include: The Italian Wars, Historibus Europae, Hannibal's War, Gold Gulch, Struggle for Empire, Colonialism II, Carolus Invictissimus, The American Civil War and the Thirty Years War.

[[Image:wGreatGameSL.png]] '''11th February 2011''' - Keu releases a modified ToT version of Micheal Daumen's [http://forums.civfanatics.com/showthread.php?p=10206652#post10206652 The Great Game]

[[Image:wAWISL.png]] '''9th February 2011''' - civ2units releases [[American War of Independence]] [http://forums.civfanatics.com/showthread.php?t=411273 SL Thread]

[[Image:wSovietSteelSL.png]] '''4th February 2011''' - Curtsibling re-releases [http://forums.civfanatics.com/downloads.php?do=file&id=16511 Soviet Steel for MGE]

[[Image:wBitterMGE.png]] '''3rd February 2011''' - Curtsibling re-releases [http://forums.civfanatics.com/downloads.php?do=file&id=16500 Bitterfrost for MGE]

[[Image:wKaiserSL.png]] '''29th January 2011''' - Curtsibling re-releases [http://forums.civfanatics.com/showthread.php?t=409947 Kaiser]

[[Image:wDalekSL.png]] '''28th January 2011''' - Curtsibling releases [http://forums.civfanatics.com/downloads.php?do=file&id=16446 Dalek Tyranny]

[[Image:wDictator_2011SL.png]] '''27th January 2011''' - Curtsibling releases [[The Eurasian Wars]] [http://forums.civfanatics.com/downloads.php?do=file&id=16437 SL Thread]

[[Image:wExterminateSL.png]] '''27th January 2011''' - Curtsibling releases [[Extermination]] [http://forums.civfanatics.com/downloads.php?do=file&id=16438 SL Thread]

User:Techumseh

2020-01-05T22:43:21Z

Prof. Garfield: Trying to get same message as Techumseh.

Just trying to create this page to see if I get the same message as Techumseh.

Get Started With Lua Events Lesson 1: "Hello World"

2020-01-05T17:10:08Z

Prof. Garfield:

[[Category:Lua Resources]]
Back To [[Get Started With Lua Events by Prof. Garfield | Get Started With Lua Events]]

This lesson is currently in the thread [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/ Get Started With Lua Events]. If someone were to copy it here, it would be much appreciated.

The spaceship object

2019-08-18T03:38:23Z

Prof. Garfield:

[[Category:Lua Resources]]
Back To [[TOTPP Functions]]

As of ToTPP v0.15.1 there is nothing in the spaceship object. (Or, there is something, but it is not documented in the Lua Function Reference.)

Try these:

spaceship.owner

spaceship.structural

spaceship.propulsion

spaceship.fuel

spaceship.habitation

spaceship.lifesupport

spaceship.solar

spaceship.launched

The spaceship object

2019-08-18T03:38:04Z

Prof. Garfield:

[[Category:Lua Resources]]
Back To [[TOTPP Functions]]

As of ToTPP v0.15.1 there is nothing in the spaceship object. (Or, there is something, but it is not documented in the Lua Function Reference.)

Try these:

spaceship.owner
spaceship.structural
spaceship.propulsion
spaceship.fuel
spaceship.habitation
spaceship.lifesupport
spaceship.solar
spaceship.launched

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-16T02:19:53Z

Prof. Garfield:

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the key "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [https://forums.civfanatics.com/threads/totpp-flags-and-counters-library.648757/ flags]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of the state table passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) </code> to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you will gain confidence with practice and experience. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-16T02:15:57Z

Prof. Garfield: /* Conclusion */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the key "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [https://forums.civfanatics.com/threads/totpp-flags-and-counters-library.648757/ flags]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of the state table passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) </code> to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you will gain confidence with practice and experience. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-16T02:10:36Z

Prof. Garfield: /* Flags and Accessing State from Modules */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the key "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [https://forums.civfanatics.com/threads/totpp-flags-and-counters-library.648757/ flags]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of the state table passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) </code> to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you may be writing mediocre code before you write good code, and accept that. You will improve with practice. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-16T02:09:45Z

Prof. Garfield: /* Flags and Accessing State from Modules */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the key "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [https://forums.civfanatics.com/threads/totpp-flags-and-counters-library.648757/ flags]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of the state table passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you may be writing mediocre code before you write good code, and accept that. You will improve with practice. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-16T01:49:57Z

Prof. Garfield: /* Counting Unit Kills */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the key "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [[flags.lua]]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of it passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you may be writing mediocre code before you write good code, and accept that. You will improve with practice. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-16T01:44:56Z

Prof. Garfield: /* Introduction */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here]. (I provided them at the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the value "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [[flags.lua]]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of it passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you may be writing mediocre code before you write good code, and accept that. You will improve with practice. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-15T23:57:40Z

Prof. Garfield: /* civ.scen.onLoad vs. civ.scen.onScenarioLoaded */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [[here]]. (These are the same as I provided for the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the value "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [[flags.lua]]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of it passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Civ.scen.onLoad and civ.scen.onScenarioLoaded appear at first glance to do the same thing. When a game is loaded, they execute their code. So what's the difference? Well, the first difference is that the "buffer" that is attached to the end of a save game file (and which is used to re-create the state), is available to civ.scen.onLoad. The other difference is timing. civ.scen.onScenarioLoaded happens ''after'' the rules.txt information is accessed by the game, while onLoad happens before that. That means, if you are interested in changing some feature of the game based on the season (such as the road multiplier), you will want to do that in civ.scen.onScenarioLoaded. The code in events.lua (which is not part of a function definition) is executed before civ.scen.onLoad. This is how the various tables and other data are built for the scenario.

I mentioned the road multiplier in the last paragraph. When you did testing in the Classic Rome scenario, you may have noticed that roads granted unlimited movement. This is because when I converted the Rome scenario to Test of Time, I failed to include an @COSMIC2 line in the rules.txt, and due to a bug, TOTPP doesn't look at the @COSMIC value instead. During my live creation of the munition library, I inserted a line <code>totpp.movementMultipliers.road=2</code>, which counteracts the bug. As I mentioned last paragraph, if I wanted to override rules.txt (rather than replace an omission), I would have had to put the line in the function supplied to civ.scen.onScenarioLoaded.

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you may be writing mediocre code before you write good code, and accept that. You will improve with practice. Ask for help if and when you need it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-15T23:57:15Z

Prof. Garfield: /* Conclusion */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [[here]]. (These are the same as I provided for the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the value "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [[flags.lua]]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of it passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

=== Conclusion ===

This concludes the last fundamental lesson for writing Civilization II Scenario Events with Lua. I may, at some point, add some more material, but that will be to either re-visit stuff I mentioned in earlier lessons but then forgot about, or to add tips on how to do certain things or use certain functionality. For the latter case, I may simply decide to write an independent document instead.

Thank you for following these lessons and getting to the end. If there are any improvements you think could be made to these lessons, please either let me know or just make them yourself. My goal is to make it easy for others to use the tools lua provides for Civ II, and if a change would improve this product, then I'd like to make it. Feel free to redistribute and modify these lessons. I would appreciate credit (and a notice that changes were made to the text if applicable), and maybe a PM in the civfanatics forums of what you did, but these aren't really essential. After all, these lessons are only good for teaching Lua with Civilization II, so just about any use of them is likely to further that goal.

Good luck with your projects. Remember that you may be writing mediocre code before you write good code, and accept that. You will improve with practice. Ask for help if and when you need it.

Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files

2019-08-15T23:49:55Z

Prof. Garfield: /* A Munition Generation Module */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

===Introduction===

In this lesson, we will take a look at how to split the code for a scenario's events into multiple files. There are several reasons to consider doing this.

The first reason is simply to organize your work. If you have a series of complicated events, the events.lua file can become very large very quickly. Once your events.lua file has thousands of lines of code in it, it may not be very obvious where the best place is to put that next helper function, or where to implement the function that runs a complicated event. Sometimes even finding the piece of code that has to be changed can be a bit of a hassle. In Over the Reich, I sometimes search for the associated civ.scen line, and then search for the exact name of the function I need. Occasionally, there may even be more searching to find what I actually have to change. With multiple files, it becomes easier to find things.

Another aspect of using multiple files is that you can make certain changes without worrying about breaking things elsewhere. If myBigComplicatedFunction relies on aModestHelperFunction for a certain part of its functionality, and a change to myBigComplicatedFunction also requires a change to aModestHelperFunction, you have to make sure that nothing else in your code also uses aModestHelperFunction, or, if something else does depend on it, that aModestHelperFunction either still provides the original functionality, or that all other functions that use aModestHelperFunction are suitably modified. If myBigComplicatedFunction is defined in its own lua module, then you don't have to worry about forgetting that aModestHelperFunction was used elsewhere, since it can't be accessed outside the module unless you specifically allow it to be.

A second reason to split events code into multiple files is to facilitate collaboration. If all of the events are in a single file, then only one person can make changes to the file at a time. If one partner starts changing an event, but has to do something else before finishing, everyone waits on one person's delay. However, if most aspects of the scenario are separated into individual files, everyone can work on his or her own piece of the puzzle without depriving others of the opportunity to work at that time.

A third reason to split events into multiple modules is to facilitate reusing code. If everything required to implement an event is in its own file (or files), it becomes much easier for other creators to use your functionality in their scenario. Since everything they need is already in one place, they don't have to find every last helper function, or concern themselves with naming conflicts.

===Two Simple Examples===

Let us look at the top of the events.lua file. You can get the version that I started lesson 6 with [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here].

[[File:GetStartedWithLuaLesson6-01-DefaultRequire.jpg]]

We get code from other files by using the command <code>require</code> along with a string specifying the file name (except for the .lua extension). At the moment, we can only get code stored in the lua folder in the Test of Time directory. This is inconvenient if we're trying to distribute a scenario, since installing a scenario would require moving certain files to the lua directory, and those file names might conflict. Instead, we need to tell the Lua interpreter to search in the same folder that the events.lua folder is in.

To do this, we need the following code:
<code>
local eventsPath = string.gsub(debug.getinfo(1).source, "@", "")
local scenarioFolderPath = string.gsub(eventsPath, "events.lua", "?.lua")
if string.find(package.path, scenarioFolderPath, 1, true) == nil then
package.path = package.path .. ";" .. scenarioFolderPath
end
</code>

You can probably cut and paste this code before the require lines in your events.lua file and not worry about how it works. However, I'll provide a brief explanation for reference.

The first line stores the location of the of the current file as a string in eventsPath.

The second line replaces events.lua in the eventsPath with ?.lua, which will tell the Lua interpreter to look for .lua files in the current directory (that is to say, the directory with the events.lua file).

The if statement adds scenarioFolderPath to the places for the Lua interpreter to search for code, if that directory is not already in the search path. Since the search path is kept active by the Lua interpreter, it will not be necessary to repeat these lines of code in every file that performs a require action as long as you are running the file as part of events. If you are writing some other kind of code, you will need to substitute "events.lua" with the name of the file with the code you are running. Note that for some reason, events.lua is always provided in lower case. However, for use in other situations, debug.getinfo(1).source uses the correct case for event files. I have only briefly tested this, so you may have to do some testing yourself if this situation comes up (or ask for help in the forums).

Now that we've told Lua where to look for our extra code, we can begin moving code to other files. Think of require as telling Lua to run the entire contents of another file as a function. We can then assign a value to whatever that file returns, which will usually be a table. A couple of examples will clarify.

For our first example, we will move our scenario's parameters to a separate file, and access it via require. This may not seem worthwhile in this example, but tables like this can get large in a hurry. At the time of writing, Over the Reich has over 100 lines of parameters ("specialNumbers"), and parameters are something that a designer might like to play with while collaborators make other implementations. Also, parameters will have to be referenced by other parts of the code, and a file that is required by events.lua cannot, in turn, require events.lua in order to get information. That means that we'll have to keep our parameters in a separate file anyway.

Cut the parameters table definition and paste it into a new file, classicRomeParameters.lua. For the last line, write
<code>
return parameters
</code>

Now, Near the top of events.lua, where the existing require lines are, add the eventsPath code from above and also the line
<code>
local parameters = require("classicRomeParameters")
</code>

[[File:GetStartedWithLuaLesson6-02-RequireParameters.jpg]]

Open the classicRome scenario and test out a couple of events to make sure everything is the same.

We might find it convenient to put a few tables into the same file. For this, we will simply return a table containing these tables, and give each table a name in the events.lua file.

Create a file classicRomeAliases.lua and move all the "aliases" tables to that file. Also move the getCityAt function.

At the bottom of the file, put the following lines:
<code>
return {
unitAliases=unitAliases,
tribeAliases=tribeAliases,
tileAliases=tileAliases,
cityAliases=cityAliases,
textAliases=textAliases,
terrainAliases=terrainAliases,
improvementAliases=improvementAliases,
}
</code>

Then, add the following lines to events.lua (in the require section)
<code>
local aliases = require("classicRomeAliases")
local unitAliases,tribeAliases,tileAliases,cityAliases,textAliases,
terrainAliases,improvementAliases=aliases.unitAliases,aliases.tribeAliases,
aliases.tileAliases,aliases.cityAliases, aliases.textAliases,aliases.terrainAliases,
aliases.improvementAliases
</code>

Here, our classicRomeAliases module is returning a table with our "alias" tables. We then assign the entries in this returned table to local variables with the desired names. Here, I use multiple variable assignment, which I don't believe I've used before (even though Lua allows it), but these could just as simply have been assigned line by line.

[[File:GetStartedWithLuaLesson6-03-RequireAliases.jpg]]

Now, let us move the legion plundering code into its own file, which we'll call plunder.lua. First, copy over the legionPlunder function, and paste it near the bottom of the new file.

Now, let us go through the code of this function, and figure out what else we need in our plunder.lua module.

The very first part of the function is a check against unitAliases.legion. This means we need the unitAliases table, and so we copy the aliases require code to the top of plunder.lua. We don't need the path information, since that will be added in events.lua.

A few more lines down, we find that the function cityRadius is also used in legionPlunder. Therefore, we move that over as well. We also need the plunderValue function, so copy that over as well.

Next, we check if cityRadius relies on anything, but it doesn't.

Proceeding to plunderValue, we find that it relies on the parameters table, so require that as well. The function plunderValue does not appear to depend on anything else, so we're done moving functionality. If we missed something, the Lua interpreter will complain at some point anyway.

Next, we require the plunder module in events.lua, with the following line:

<code>
local plunder = require("plunder")
</code>

Next, for each of the functions in plunder.lua, we check if it is used somewhere in events.lua. We can do this by searching. plunderValue isn't used anywhere, so we're done with that. City radius is used. At the bottom of plunder.lua, we begin our return table, and have
<code>
return {
cityRadius=cityRadius,
}
</code>

Then, in events.lua, we replace the ocurance of cityRadius with plunder.cityRadius. Alternatively, we could have put
<code>
local cityRadius=plunder.cityRadius
</code>
after the line requiring plunder.

Similarly, for legionPlunder, we add <code>legionPlunder=legionPlunder</code> to the table that plunder.lua returns, and pre-append plunder. to legionPlunder in the one location where it occurs.

Now, we test the legion plunder function and the press 4 generate archers function to make sure everything works.

[[File:GetStartedWithLuaLesson6-04-RequirePlunder.jpg]]

===Working With a Library===

In programming terms, a "library" is a collection of code that can provide some specified functionality to a programmer without that programmer having to modify the code in the library. Thus far, you have been using the "civ" library to interact with the game, and there has been no need modify it in order to use it in our own events. (Unfortunately, in the case of the civ library, we don't actually know how to modify it.) This is in contrast to much of the code we have written thus far. For example, the code we wrote last lesson to make Selucid elephants attack Egypt is highly specific. You couldn't just cut and paste that code, change the argument of a single function, and get your own goto event. It is still a good example for how to write a goto event, but a user would still have to actually write the event.

If you plan to write some functionality for your scenario that others might find useful, it is worth spending a little extra effort to see if you can write that functionality in a form that will allow others to use it with minimal effort. If you can, then a little extra work on your part might save someone else the trouble of re-inventing the wheel, and allow them to complete their project sooner, or to work on some new feature for you to enjoy. Unfortunately, the Lua scenarios that have been completed at the time of writing haven't been that good at creating re-usable code, at least in part since we were all getting used to Lua. This will hopefully be improved in the future.

For now, we're going to look at a library which is called the General Library (unless someone comes up with a better name) and which can be found [https://forums.civfanatics.com/threads/totpp-the-general-library.647583/ here]. The purpose of this module is to provide relatively simple functionality that probably shouldn't be implemented every time it is needed. This is useful for our purposes, since we can look at relatively self contained and simple functions for our first examples. We'll create a library for generating munitions later.

This library would be used by invoking the line

<code>
local gen = require("generalLibrary")
</code>

If you wanted to make these functions available to the console for testing purposes, you would simply omit the local, thereby making gen a global variable.

Let us now take a look at a function provided by the General Library <code> gen.hasIrrigation(tile)-->boolean</code>. The very first line references the helper function <code> toTile(tile or table)-->tile</code>, so let us include that code, and look at it first.

<code>
-- toTile(tile or table)-->tile
-- gen.toTile(tile or table)-->tile
-- If given a tile object, returns the tile
-- If given coordinates for a tile, returns the tile
-- Causes error otherwise
-- Helper Function (provided to this library as toTile and gen.toTile)
local function toTile(input)
if civ.isTile(input) then
return input
elseif type(input) == "table" then
local xVal = input[1] or input["x"]
local yVal = input[2] or input["y"]
local zVal = input[3] or input["z"] or 0
if type(xVal)=="number" and type(yVal)=="number" and type(zVal)=="number" then
if civ.getTile(xVal,yVal,zVal) then
return civ.getTile(xVal,yVal,zVal)
else
error("Table with values {"..tostring(xVal)..","..tostring(yVal)..
","..tostring(zVal).."} does not correspond to a valid tile.")
end
else
error("Table did not correspond to tile coordinates")
end
else
error("Did not receive a tile object or table of coordinates.")
end
end
gen.toTile = toTile

-- gen.hasIrrigation(tile)-->boolean
-- returns true if tile has irrigation but no farm
-- returns false otherwise
function gen.hasIrrigation(tile)
tile = toTile(tile)
local improvements = tile.improvements
-- irrigation, but no mining, so not farmland
if improvements & 0x04 == 0x04 and improvements & 0x08 == 0 then
return true
else
return false
end
end
</code>

[[File:GetStartedWithLuaLesson6-05-HasIrrigation.jpg]]

Let us begin by looking at the function <code>toTile</code>. The purpose of this function is to allow other functions to accept tile coordinates in a table instead of an actual tile object. The function tries to be reasonably permissive in the coordinates it will accept, allowing both integer indices and lowercase string indices, and by assuming that a missing z value corresponds to map 0. The function also tries to give reasonably helpful errors.

This brings up something that should be considered when making reusable code: what to do if you don't get values you were expecting. One option is to throw an error and bring up the Lua console. This is good for scenario creators, so they know something is wrong, but not so great for end users because the error stops the rest of the event from happening, should the mistake slip through playtesting.

The other option is for the code to fail silently, and try to do what it can. This is the way the old Test of Time macro system often fails. If Civ II doesn't "understand" the event, it just doesn't happen, and doesn't bother the player with the error. This means that the scenario will still mostly work, but it is harder to catch issues during playtesting. Sometimes, this means doing something "sensible" if the input isn't of the expected type, and might make the code easier to write, since you don't have to handle inputs differently.

A third option is to write your code such that both things can be done. At the top of your code, you put in a variable named "debugMode" or something, and make all the functions throw errors when true, and fail silently when false. Then you playtest with debugMode set to true, and release with debug mode set to false. However, this means extra work in writing your code and you also have to test everything with debug mode off.

For toTile, I went with the fail with error option, since that will allow every function that uses toTile to assume it is receiving proper data. It also seems unlikely that people will be regularly trying to check tiles that don't exist or have tables with tiles and units and improvement objects all in one. And if they do, "guarding" is fairly straightforward anyway (as we've done in previous lessons).

Although toTile is mainly meant to be a helper function for the General Library, it is also put into the gen table to be made available to end users, since it offers useful functionality. Hence, <code> gen.toTile=toTile</code>. Note that we could have given toTile a different name in the gen table that this module will return, such as gen.tableToTile=toTile. In fact, we could refer to the same function with multiple keys in the gen table, if we want to.

Next, we will look at gen.hasIrrigation.

The first thing to notice is that local is not being used to define this function. That is because we're putting the function for gen.hasIrrigation directly into the gen table that this module will return. We could define hasIrrigation as a local variable and then copy it into the gen table. However, there is a decent chance that the General Library will have more than 200 functions by the time everything is complete, since it is meant to provide a lot of building block functionality and keep it in one place, and we will run into trouble if we assign 200 local variables in a single function (which a required lua file acts as).

Perhaps the most striking thing is that we begin by changing the value of tile, the argument of the function. It looks like we're making a global variable named tile, but we're not. When you specify the names of the arguments for a function (in this case tile), you create local variables for that function, which can be given new values just as if you had explicitly used the local keyword.

Beyond that, we extract the integer representing the tile improvements into a local variable (which upon later reflection isn't really necessary), and check that the irrigation bit is set to 1 and the mining bit is set to 0. Refer to lesson 5 for why this works. In fact, we could have simply returned the value of the if statement, rather than specifying return true and return false, although it is very slightly clearer what is going on in the expanded version of the code.

Now, let us write a function to place irrigation on a square. It seems pretty clear that we should do nothing if the tile has a city, but we also have to decide what to do if there is mining or farmland on the tile, since those interfere with placing irrigation. We'll just remove them, on the basis that if we're trying to "place irrigation," then we want irrigation to be there when we are finished.

<code>
function gen.placeIrrigation(tile)
tile = toTile(tile)
</code>

These lines open the function and convert a table of coordinates to a tile if necessary.

<code>
if tile.city then
return
end
</code>

If the tile has a city, return so nothing else is done in the function.

<code>
-- Set irrigation bit to 1
tile.improvements = tile.improvements | 0x04
-- Set mining bit to 0
tile.improvements = tile.improvements & ~0x08
end
</code>

Set the irrigation bit to 1 and the mining bit to 0.

The functions in this library don't have to be complex, and in fact, most probably shouldn't be. They just have to make life easier for the end user. If you reach this lesson before the General Library is considered "complete," your assignment now is to submit some work for it. If you don't feel comfortable doing bitwise operations, you can test the work of others or submit functions that simplify other tasks. However, there are also some helper functions in the library to facilitate changing bits, so you might also consider working on the unit type flags functions. Remember, if you want to make functions available to the console for testing purposes, they must be global variables.

=== The Threshold Table and First Look at Metatables===

Consider a scenario design situation that occurred in Over the Reich: a bomber is generating some bombs via a key press, and the number of bombs it should generate is dependant on its current remaining hitpoints. The more hitpoints the bomber has, the more bombs it should generate. What we want is to specify that if a bomber has between x and y hitpoints, it should produce 2 bombs. That is, for a given type of bomber, we want to have, for example,

hp >= 16 --> 4 bombs
16 > hp >= 12 --> 3 bombs
12 > hp >= 9 --> 2 bombs
9 > hp >= 4 --> 1 bomb
4 > hp >= 0 --> 0 bombs

Unfortunately, Lua tables do not naturally encode this kind of association by default. However, Lua does have a feature called metatables, which allows us to change the behaviour of tables. (This will be a much better way to make the specification than I ended up writing in Over the Reich.)

A metatable is a table that we can "attach" to another table, and then the metatable changes the behaviour of that table. We'll only look at metatables briefly here, but more information can be found [https://www.tutorialspoint.com/lua/lua_metatables.htm here].

What we want is a data structure that can accept numerical "key values" that are between the key values explicitly specified, and return the appropriate value for those keys. We will call this data structure a threshold table, since we are specifying threshold values as keys. We can do this by assigning the following metatable:

<code>
local mt = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
</code>

If we run <code> setmetatable(myTable,mt)</code>, then whenever we ask for an index from myTable and that index doesn't currently exist in myTable, the function assigned to __index will run. Now let us examine the function.

If the type of the key is not a number, then we return whatever the table value is for that key. We use the function rawget, because the standard <code>thresholdTable[key]</code> will invoke this function again if the key doesn't exist, and so never return an answer (when we want it to return nil).

If the key type is a number, then we look for the largest numerical index that is also less than or equal to the key value. We return a default value of false if the key submitted is smaller than all numerical values. False is chosen over nil, so that a maximum value can be set by setting the value of a numerical index to false. Using the key [-math.huge] allows a return value to be set for all numbers (since all numbers are greater than -math.huge).

Since we don't want scenario creators to have to re-create threshold tables every time they need them, we'll add this functionality to the General Library

<code>
local thresholdTableMetatable = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
-- gen.makeThresholdTable(table or nil)-->thresholdTable
function gen.makeThresholdTable(inputTable)
inputTable = inputTable or {}
return setmetatable(inputTable,thresholdTableMetatable)
end
</code>

[[File:GetStartedWithLuaLesson6-06-ThresholdTable.jpg]]

===A Munition Generation Module===

Now, let us write some re-usable code for a human player to generate units by pressing a key while an appropriate unit is active. This sort of code could be used for ranged attacks (generating a "munition") and also for recruiting mercenaries by paying gold.

The first thing we will want to do is to decide how our code will be used by the end user. This will, perhaps, change by the time we finish writing the code, but it will at least give us a starting point.

spawnUnit(generatingUnit, specificationTable)--> table of unitCreated

Our goal is that when a player attempts to generate a unit using another unit, they will provide the unit spawning the new unit, and a table of information specifying if a unit (or units) can be spawned and anything else that must happen while spawning (like paying money, expending movement points, etc.).

We have an option here. We could have the scenario creator provide the specification table as a required file for our module, or the creator can provide it at the time spawnUnit is called. I choose the latter for a couple of reasons. The first is that it allows the player to have more than one specification table, either because more than one key can spawn a unit, or because the specification can change over time. The other is reason is so that the creator can make the table in the events.lua file if desired (since our module can't require information from events.lua).

Having decided that our generateUnit events are going to be specified by a table, we have to decide what the contents of that table should be. It seems pretty reasonable to index the specificationTable with the index of the unit type of each unit that can generate using the information in the table. If a unit type id number is missing, that unit doesn't generate a munition (or recruit a unit).

The value for each unit type id in the specification table will be a table that specifies how and if that unit generates other units.

--specificationTable[unitType.id]={
--
-- goldCost = integer or nil
-- amount of gold it costs to generate a unit
-- absent means 0
-- minTreasury = integer or nil
-- minimum amount of gold in treasury to generate a unit
-- absent means refer to gold cost
-- (tribe will generate and be set to 0 if treasury is less than goldCost)
-- treasuryFailMessage = string or nil
-- A message to be displayed if the unit fails to spawn a unit due to an
-- insufficient treasury
-- nil means no message

-- There are three ways to specify move costs, in full movement points,
-- in "atomic" movement points, and as a fraction of total movement points for the
-- unit type. Use only one kind per unit type

-- moveCost = integer or nil
-- movement points to be expended generating the unit
-- "full" movement points
-- absent means 0
-- minMove = integer or nil
-- minimum remaining movement points to be allowed to generate a unit
-- "full" movement points
-- absent means any movement points for land/sea, 2 "atomic" for air units
-- postGenMinMove = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostAtomic = integer or nil
-- movement points to be expended generating the unit
-- refers to the unit.moveSpent movement points
-- absent means 0
-- minMoveAtomic = integer or nil
-- minumum remaining movement points to be allowed to generate a unit
-- referes to the unit.moveSpent movement points
-- absent means any movement points for land, 2 "atomic" for air units
-- postGenMinMoveAtomic = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostFraction = number in [0,1] or nil
-- fraction of unit's total movement points expended generating the unit
-- round up to nearest "atomic" movement point
-- absent means 0
-- minMoveFraction = number in [0,1] or nil
-- fraction of unit's total movement points that must remain to be allowed
-- to generate a unit
-- absent means any movement points for land, 2 "atomic" for air units
-- round up to nearest "atomic" movement point
-- postGenMinMoveFraction = number in [0,1] or nil
-- a unit will be left with at least this many movement points after
-- the generation function, round up to nearest "atomic" move point
-- absent means 0 for land/sea, 1 "atomic" for air units
-- roundFractionFull = bool or nil
-- fractional movement cost and minimum are rounded up to full movement point
-- instead of atomic movement point
-- nil/false means don't
-- roundFractionFullDown = bool or nil
-- fractional cost and minimum are rounded down to full move point
-- nil/false means don't
-- minMoveFailMessage = string or nil
-- a message to be displayed if a unit is not generated due to insufficient
-- movement points.
-- nil means no message

-- allowedTerrainTypes = table of integers or nil
-- a unit may only be generated if the tile it is standing on
-- corresponds to one of numbers in the table
-- nil means the unit can be generated on any terrain type
-- terrainTypeFailMessage = string or nil
-- message to be displayed if a unit is not generated due to standing
-- on the incorrect terrain

-- requiredTech = tech object or nil
-- the generating civ must have this technology in order to generate
-- the unit
-- nil means no requirement
-- techFailMessage = string or nil
-- message to be displayed if a unit is not generated due to not having
-- the correct technology

-- payload = boolean or string
-- if true, unit must have a home city in order to generate munitions
-- and generating munitions sets the home city to NONE
-- payloadFailMessage = string or nil
-- message to be displayed if a unit is not generated due to the
-- payload restriction
-- payloadRestrictionCheck = nil or function(unit)-->boolean
-- If function returns false, the home city is not valid for giving the
-- unit a payload. This will be checked when the unit is activated, when
-- the unit is given a new home city with the 'h' key and when the unit
-- tries to generate a munition
-- nil means no restriction
-- payloadRestrictionMessage = nil or string
-- message to show if a unit fails the payloadRestrictionCheck

-- canGenerateFunction = nil or function(unit)-->boolean
-- This function applied to the generating unit must return true in order
-- for a unit to be spawned. All other conditions still apply.
-- any failure message should be part of canGenerateFunction
-- absent means no extra conditions

-- generateUnitFunction = nil or function(unit)-->table of unit
-- This function creates the unit or units to be generated
-- and returns a table containing those units
-- Ignore any specifications prefixed with * if this is used
-- nil means use other specifications

--*generatedUnitType = unitType
-- The type of unit to be generated
-- can't be nil unless generateUnitFunction is used instead

--*giveVeteran = bool or nil
-- generated unit(s) given veteran status if true
-- nil or false means don't give vet status
-- if true, overrides copyVeteranStatus

--*copyVeteranStatus = bool or nil
-- generated unit(s) copy veteran status of generating unit if true
-- nil or false means don't give vet status

--*setHomeCityFunction = nil or function(generatingUnit)-->cityObject
-- determines what home city the spawned unit should have
-- nil means a home city of NONE

--*numberToGenerate = nil or number or thresholdTable or function(generatingUnit)-->number
-- if nil, generate 1 unit in all circumstances
-- if integer, generate that many units (generate 0 if number less than 0)
-- if number not integer, generate floor(number), and 1 more with
-- probability number-floor(number)
-- if thresholdTable, use remaining hp as the key, to get the number to create
-- if function, get the number as the returned value of the function

-- activate = bool or nil
-- Activates one of the generated units if true. If generateUnitFunction was used,
-- the unit at index 1 is activated, if index 1 has a value. (if not, any unit in
-- the list might be chosen)

The very last entry brings forward a change that must be made to our unit generation specification. Lua's activate unit command doesn't run the unit activation trigger, even though the active unit is changed. Therefore, we must do that manually. Hence,

<code>spawnUnit(generatingUnit, specificationTable)--> table of unitCreated</code>

becomes

<code>spawnUnit(generatingUnit,specificationTable,unitActivationCode)-->table of unitCreated</code>

Perhaps we will change it again later.

I've decided to try a different instructional technique for this section. Instead of writing the code and then going through it section by section, I've recorded a video of my coding and testing this module, and I attempt to explain some of the stuff that I do along the way.

I'm not sure of the value of the video. If you find that there seems to be little useful content relative to the time it takes to watch, then feel free to skip it and continue the lesson. I don't teach anything "new" in it, so you won't miss anything crucial, although I do add a line <code>totpp.movementMultipliers.road = 2</code>, which fixes a bug when @COSMIC2 is not defined in the rules.txt. However, the video should be pretty close to how programming Lua can actually happen in the "real world." While I did give some thought to how to write the module before I started, I do attempt to solve problems in real time, and make mistakes that are not discovered for a while (including one where I try to explain how I solve a problem and then not actually do a crucial part).

You can find the code [https://forums.civfanatics.com/threads/totpp-the-munitions-library.647910/ here]. Even if you decide not to watch the video, download the code and try testing some of the features based on the specification above. If you find any bugs, submit a fix (or at least report the issue).

The video can be found [https://youtu.be/XxPyNknGlAo here].

===A Unit Attack Bonus for Complementary Units in Square===

Something we might like to do is to give units an attack bonus if they attack from a square with some special unit, for example a "leader" unit. The [[Napoléon I]] scenario, for example, gives an attack bonus to units if a commander unit, such as Napoleon, is in the square when the unit is activated (the unit can subsequently move and still retain the bonus as long as no other unit is selected). We will now make a module providing the same functionality.

We first have to have a basic idea of how this functionality should work. When a unit is activated, the onActivateUnit event checks if the newly activated unit should get an attack bonus, based on the other units in the square. If the unit deserves an attack bonus, the corresponding unitType.attack entry is changed, and all the attack value of all other units is reset to the default value. If the activated unit also does not deserve an attack bonus, that value is also set to the default value.

This now leads us to some more possibilities. Should multiple bonus units lead to multiple bonuses or only apply the best one? For example, suppose a legion gets a bonus if an archer is also in the same square. Should two archers provide twice the bonus? Perhaps two archers should provide a larger bonus than one, but not twice as much. Perhaps a legion should also get a bonus if there is a catapult in the square, but that bonus should apply even if the maximum archer bonus is already achieved. It seems like perhaps there should be a "ranged unit" bonus, an "artillery unit" bonus and maybe a "cavalry" bonus which should all impact the legion's attack value. It's looking like we might end up demanding that a scenario creator make a big complicated table in order to use this functionality, even if they only have simple needs.

What we can do to alleviate this is to write a "simple" version of the event that is easy to use (and program), and also write a more complicated version that gives the expanded capability.

Specification Table for simpleAttackBonus

--simpleAttackBonusTable[activeUnit.type.id] ={[bonusUnitType.id]=bonusNumber}
--simpleAttackBonusTable.type = string
--if simpleAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if simpleAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
--if simpleAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- if simpleAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- if simpleAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
--simpleAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

The relevant first draft of the code is as follows:

<code>
local function simpleAttackBonus(activeUnit,simpleAttackBonusTable,defaultAttackTable)
-- reset all unit attack values
for unitTypeID,attackValue in pairs(defaultAttackTable) do
civ.getUnitType(unitTypeID).attack = attackValue
end
local unitBonusTable = simpleAttackBonusTable[activeUnit.type.id]
if not unitBonusTable then
-- unitBonusTable is nil (or false), so the active unit can't
-- get a bonus
return
end
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
local bestBonusSoFar = 0
for unit in activeUnit.location.units do
if unitBonusTable[unit.type.id] and unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
if bestBonusSoFar == 0 then
-- If no bonus unit is found, this will be true, so do nothing else
return
end
-- set the new attack and return
if string.lower(simpleAttackBonusTable.type) == "addBonus" then
activeUnit.type.attack = activeUnit.type.attack+bestBonusSoFar
return
end
local attackMultiplier = 1
if type(simpleAttackBonusTable.type) ~= "string" then
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
elseif string.lower(simpleAttackBonusTable.type) == "addpercent" then
attackMultiplier = (100+bestBonusSoFar)/100
elseif string.lower(simpleAttackBonusTable.type) == "addfraction" then
attackMultiplier = 1+bestBonusSoFar
elseif string.lower(simpleAttackBonusTable.type) == "multiplypercent" then
attackMultiplier = bestBonusSoFar/100
elseif string.lower(simpleAttackBonusTable.type) == "multiply" then
attackMultiplier = bestBonusSoFar
else
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
end
-- apply the bonus and round as appropriate
if type(simpleAttackBonusTable.round) ~= "string" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
elseif string.lower(simpleAttackBonusTable.round) == "up" then
activeUnit.type.attack = math.ceil(activeUnit.type.attack*attackMultiplier)
return
elseif string.lower(simpleAttackBonusTable.round) == "down" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier)
return
else
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
end
end
</code>

Now let us go over this section by section.

[[File:GetStartedWithLuaLesson6-07-AttackBonus1.jpg]]

The first thing we do is to reset all the attack values of all the unit types. That way, if a bonus existed for the last unit activated, that bonus no longer applies. If a unit type is not in the defaultAttackTable, then we don't have the information to reset the attack value anyway, so we can safely ignore it by using the pairs function to iterate over the table.

Now, we must find out if the newly activated unit deserves a bonus. For that, we get the table associated with the active unit's type. If the value is nil instead of a table, then the unit's type is not in the simpleAttackBonusTable, so there is no bonus to apply and the function returns.

If the unit is eligible for bonuses, we then check the units in the square to see if any bonuses actually apply. We've seen this kind of code before. If the unit in the stack can provide a bonus, and that bonus is better than the best bonus already found, the unit now provides the best bonus. All bonus types that we can have are better if they are larger, and we are not comparing between bonus types, so a simple numerical comparison will do. All bonuses are larger than 0 in our formulation, so 0 is a good starting value in the search.

If the best bonus so far is still 0, there is no bonus, so the function can return.

At this point, it occurs to me that when searching for the best bonus, we should exclude the active unit from the search. That way, you can have a "strength in numbers" bonus, for example. The relevant change to the code is:

<code>
for unit in activeUnit.location.units do
if unit ~= activeUnit and unitBonusTable[unit.type.id] and
unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
</code>

Next, consider

[[File:GetStartedWithLuaLesson6-08-AttackBonus2.jpg]]

Here, we apply the bonus that we've found. We use string.lower on simpleAttackBonusTable.type so that we don't have to worry about capitalization. That does, however, require a correction to "addBonus", since a lower case string will never be equal to that.

"addbonus" is the only type of bonus that is directly added to the existing attack value. All other bonus types are a form of multiplication. Since the addition is straightforward and doesn't require any rounding, the activeUnit's type attack value can be changed immediately, and the function execution ended with return.

When there is only one bonus being applied, all other types of bonus are different ways of expressing how to multiply the existing attack value to get a new one, so we simply convert to the appropriate multiplier, and provide an error message if the type of bonus is not one of the valid possibilities.

Finally, we round the attack value to an appropriate integer (since unit attack values must be integers), change the attack value of the active unit's type, and return to end the function execution.

Now, we integrate into events.lua by using

<code>
attackBonus = require("attackBonus")
</code>

The relevant integration code for events.lua is
<code>
local defaultAttackValueTable = {[unitAliases.legion.id]=4}
local simpleAttackBonusTable ={}
simpleAttackBonusTable.type = "addbonus"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=3,[unitAliases.musketeer.id]=4}

local function doOnActivation(unit,source)
munitions.payloadRestrictionCheck(unit,munitionSpecificationTable)
attackBonus.simpleAttackBonus(unit,simpleAttackBonusTable,defaultAttackValueTable)
end
</code>

We can check that the bonus is being applied correctly by checking the Civlopedia entry for legion and looking at the attack value. The following cases must be tested (remember that activating a unit from the city screen doesn't run the onActivation event, so activate from the map).

Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (7 attack)
Legion activated with musketeer, but no archer (8 attack)
Legion activated with archer and musketeer (8 attack)
Legion activated with 2 archer, no musketeer (7 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

I recommend making a stack for each of these cases and activating them one by one.
To facilitate the test, add the following line to doOnActivation

<code>
civ.ui.text(tostring(unit.type.attack))
</code>
You will want to comment out this line after testing.

Next, change simpleAttackBonusTable to do "addpercent"
<code>
simpleAttackBonusTable.type = "addpercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=30,[unitAliases.musketeer.id]=70}
</code>

With no rounding set, standard rounding is used
Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)
Legion activated with archer and musketeer (7 attack)
Legion activated with 2 archer, no musketeer (5 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

These numbers test both rounding up and rounding down.

Now, use
simpleAttackBonusTable.round="up"
Legion activated with archer, but no musketeer (6 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next,
simpleAttackBonusTable.round="down"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (6 (6.8) attack)

simpleAttackBonusTable.round="standard"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next, we test "addfraction". Since we've tested all the rounding options, we don't have to do that again.

<code>
simpleAttackBonusTable.type = "addfraction"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=0.3,[unitAliases.musketeer.id]=0.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiplypercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=130,[unitAliases.musketeer.id]=170}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiply"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Before we finish, we should test a legion bonus for the legion.
<code>
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.legion.id]=2,[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>

Legion alone should have 4 attack.
A second legion on the square should provide 8 attack instead.

Now, let us try to formulate a more complicated bonus system. One thing we mentioned is that we'd like the ability to get bonuses from multiple units, and to be able to get bonuses from different "classes" of units (like "artillery," "cavalry," and "ranged attackers." Something else we might want to do is to allow different kinds of bonuses. That is, maybe some units should provide a fixed +2 to any unit receiving the bonus, so that it is better at improving units with a low attack value, while other units should provide a percentage bonus (making them better at supporting units with an already high attack value). It turns out that both of these ideas are not too difficult to implement individually, but that trying to implement them together makes it problematic to find the best bonus.

Let us implement a bonus system with multiple categories but only one bonus type. In our specification, we will first specify a data type called "bonusCategory." It is still just a table (though we could add a metatable if we wanted), but it will help us make our specification clearer.

<code>
-- A "bonusCategory" is a table
-- bonusCategory = {[bonusUnitType.id]=bonusNumber, maxBonusUnits=integer or nil, nextBonusValue = fraction or nil}
-- In a bonusCategory, the value for bonusUnitType.id tells what the base bonus for that unit type is,
-- maxBonusUnits is the maximum number of units that can provide a bonus in this category,
-- nextBonusValue tells how much to reduce the bonus for each subsequent unit,
-- e.g. nextBonusValue = 0.7, and 5 units, which each have a bonusNumber=1
-- The total bonus is 1(0.7)^0+.7+(.7)(.7)+(.7)^3+(.7)^4 = 1+.7+.49+.343+.2401=2.7731
-- (which would be rounded as specified)
-- nil means nextBonusValue=1
--
-- If a unit type is in two bonus categories for the same unit, there is no guarantee that the
-- best bonus will be achieved
</code>

So, the bonus category is indexed by unitType id numbers for units that can give a bonus, and the corresponding bonus. It also specifies the maximum number of units that can give a bonus, and a number that governs how to reduce a bonus for extra units. That way, there can be diminishing returns for bonuses.

Next, we look at the specification for the categoryAttackBonusTable

<code>
--categoryAttackBonusTable[activeUnit.type.id] =table of bonusCategory
--categoryAttackBonusTable.type = string
--if categoryAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if categoryAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
-- for multiple unit bonuses, add up all the percents, then compute the bonus
-- i.e. 50% bonus and 50% bonus is 100% bonus, not 125%
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 50% bonus units become 50% + 25%
-- so attack 6 --> 10.5
--if categoryAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- for multiple unit bonuses, add up the fractions, then compute the bonus
-- i.e. .5 bonus and .5 bonus is 1+.5+.5= 2x bonus, not 2.25x
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 .5 bonus units become .5+.25
-- so attack 6 --> 10.5
-- if categoryAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- bonuses are multiplied together, i.e. 150% and 150% yields 225% of original value
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 100, i.e. nextBonusValue=.5 2 150% bonuses become 150% and 125%
-- so attack 6 --> 11.25
-- if categoryAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
-- bonuses are multiplied together, i.e. 1.5 and 1.5 yields 2.25x
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 1, i.e. nextBonusValue=.5 and two 1.5 bonuses become 1.5 and 1.25
-- so attack 6 --> 11.25
--categoryAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

-- If the active unit can get a bonus, go through each category and compute the bonus for that category.
-- Then, combine the bonuses for all categories to get the overall bonus, and round the result
</code>

With the bonusCategory defined, the value of the unit indices of categoryAttackBonusTable become easy to define. Most of the specification is showing what exactly the different bonus categories mean, so the end user can use them properly. It's not strictly necessary to offer so many choices to the end user on how to specify data, but it can be more convenient.

Here is the actual code (before testing) to implement this more general version of attack bonuses.

<code>
-- HELPER FUNCTION
-- findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable) --> number or false
-- usedUnitTable is indexed by the i.d. number of units, and if the value for a unit is true,
-- then it has already been used for a bonus (and, so, is not eligible)
-- The function returns the bonus (before nextBonusValue is applied) if there is one, and marks the
-- unit as used in the usedUnitTable
-- returns false if no unit qualifies
local function findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable)
local bestBonusSoFar = 0
local bestUnitSoFar = nil
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
for unit in tile.units do
if not usedUnitTable[unit.id] and bonusCategory[unit.type.id]
and bonusCategory[unit.type.id] > bestBonusSoFar then
bestUnitSoFar = unit
bestBonusSoFar = bonusCategory[unit.type.id]
end
end
if bestUnitSoFar then
usedUnitTable[bestUnitSoFar.id] = true
return bestBonusSoFar
else
return false
end
end

-- HELPER FUNCTION
-- computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
-- Computes the bonus that the active unit will receive from this category, taking into
-- account the type of bonus for the table
local function computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
local bonusThusFar = nil
if bonusType == "multiply" then
bonusThusFar = 1
elseif bonusType == "multiplypercent" then
bonusThusFar = 100
else
bonusThusFar = 0
end
local bonusDiscount = 1
for i=1,(bonusCategory.maxBonusUnits or 10000) do
local currentBonus =findBestBonusInUnitStack(activeUnit.location,bonusCategory,usedUnitTable)
if not currentBonus then
-- no more valid bonuses for this category
break
end
if bonusType == "multiply" then
bonusThusFar = bonusThusFar*((currentBonus-1)*bonusDiscount+1)
elseif bonusType =="multiplypercent" then
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
else
bonusThusFar = bonusThusFar+currentBonus*bonusDiscount
end
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
end
return bonusThusFar
end

local function categoryAttackBonus(activeUnit,categoryAttackBonusTable,defaultAttackTable)
local bonusInfoTable = categoryAttackBonusTable[activeUnit.type.id]
if not bonusInfoTable then
-- unit doesn't get a bonus
return
end
-- keep track of bonuses already computed
local bonusResultsTable = {}
-- keep track of units that have already been "used" for a bonus
local usedUnitTable = {[activeUnit.id]=true}
for index,bonusCategory in pairs(bonusInfoTable) do
bonusResultsTable[index]=computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
end
-- compute the bonus
local bonusType = string.lower(categoryAttackBonusTable.type)
local resultAttackBeforeRounding = nil
if bonusType == "multiply" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "multiplypercent" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult/100
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "addbonus" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack+bonus
elseif bonusType == "addfraction" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
elseif bonusType == "addpercent" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+(bonusResult/100)
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
else
error("categoryAttackBonus: categoryAttackBonusTable.type is not a valid value.")
end
-- apply the bonus and round as appropriate
local roundType = categoryAttackBonusTable.round
if type(roundType) ~= "string" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
elseif roundType == "up" then
activeUnit.type.attack = math.ceil(resultAttackBeforeRounding)
return
elseif roundType == "down" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding)
return
else
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
end
end
</code>

The two helper functions for computeCategoryBonus are only used once each in the code, so making them helper functions does not help us re-use code. However, what it does do is to break down the function design process into smaller tasks, which are each more manageable to complete. If you're trying to keep track of too many things in your program, try writing a few helper functions to handle individual tasks. We'll look at the helper functions when we actually arrive at them in the code.

[[File:GetStartedWithLuaLesson6-09-CategoryAtkBonus1.jpg]]

If there is no entry in the categoryAttackBonusTable or the active unit's type, then the function returns without doing anything further.

The bonusResultsTable keeps track of the total bonus from each category, so they can be added or multiplied together after all the category bonuses are applied. The usedUnitsTable keeps track of units that are no longer eligible to contribute to a bonus (such as if they have already contributed), and we initialize it with the active unit, so that it doesn't provide a bonus to itself.

The for loop computes the bonus for every category, and stores the value in the bonusResultsTable, for use later.Now, let us look at the helper functions.

First up is findBestBonusInUnitStack

[[File:GetStartedWithLuaLesson6-10-CategoryAtkBonus2.jpg]]

This basically does what it says in the name. For a bonusCategory, it finds the unit in the tile that provides the best bonus, and has not already provided a bonus elsewhere. If there is no qualifying unit, false is returned. If there is, that unit's bonus is returned, and the unit's id is entered into the usedUnitTable, so that unit can't provide another bonus for the active unit. We've searched for the best of something before, so there is little need to go over it again.

Next is computeCategoryBonus

[[File:GetStartedWithLuaLesson6-11-CategoryAtkBonus3.jpg]]

Here, we're computing the bonus for the entire bonusCategory. We need the bonus type in order to know what kind of math to do. The math itself is not very interesting. We also initialize the bonusDiscount, which keeps track of the fraction of the next unit's bonus that will actually be applied.

Next, we enter a for loop that will run one time for each possible bonus that there can be in a bonus category. If bonusCategory.maxBonusUnits is nil, then we set an arbitrary limit of 10000 units, which is very unlikely to happen in practice.

At each iteration of the loop, the best available bonus in the stack is found. If no unit was eligible to provide a bonus, then the current bonus is false, and the "break" command is issued. Break immediately exits the current loop. So, our program doesn't run 10000 loops if there is no maximum number of bonus units, it just breaks at an appropriate time.

After the bonus is found, it is added to or multiplied with the bonus already found. The bonus computed in this way will be the largest possible, since the bonus provided does not depend on the other units chosen (so we don't have a situation where "catapult" and "rock" are both useless, but "catapult" and "rock" chosen together are best). Also, since the best bonus is chosen first, the smallest bonus discount applies to it, so the cost imposed by the discounting is smallest.

Finally, we update the bonusDisount. Here, I notice a problem in the code as written, since bonusCategory.nextBonusValue is allowed to be nil. Replace
<code>
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
</code>
with
<code>
bonusDiscount = bonusDiscount*(bonusCategory.nextBonusValue or 1)
</code>
so that if there is no nextBonusValue, a default of 1 is used, and the bonusDiscount stays at 1 (i.e. no discount is applied).

We return to categoryAttackBonus to see

[[File:GetStartedWithLuaLesson6-12-CategoryAtkBonus4.jpg]]

From here, we combine the bonuses stored in bonusResultsTable, the exact way of doing so being dependant on the type of bonus involved. The math itself isn't very interesting, and doesn't seem all that likely to come up in this exact form elsewhere. If you need help with the mathematical details of some event you want to write, ask in the forums. There's a good chance someone has the skills to help you solve your specific problem.

For every type of bonus, the result is stored in resultAttackBeforeRounding, so that variable can be rounded up or down as specified by the rounding type.

Here, I notice another error. We should restrict the attack value for a unit to not exceed 98. We can do that with a math.min(value, 98).

Now, we need to test the various aspects of the attack bonus program, so we need an appropriate table
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addbonus"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=2,[unitAliases.chariot.id]=4,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=2,[unitAliases.musketeer.id]=4,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Also, comment out the old attack bonus line, and put in a new one
<code>
attackBonus.categoryAttackBonus(unit,categoryAttackBonusTable,defaultAttackValueTable)
</code>

Expected Test Results when type is "addbonus"
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

Already, we find a problem. Although there were no syntax errors to fix, I forgot to reset unit attack values. So, very quickly, the legions keep gathering extra attack values when they are activated (since the base attack is not reset to 4). Since this is happening anyway, I'll test the 98 attack value maximum. That appears to work, at least in the case of no specified rounding.

Cut and paste the appropriate lines from the simpleAttackBonus to the categoryAttackBonus, and save.

With that bug fixed, everything works as expected.

Next, we change the categoryAttackBonusTable to

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addpercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=50,[unitAliases.chariot.id]=100,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=50,[unitAliases.musketeer.id]=100,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>

Expected Test Results when type is "addpercent". These are the same, since adding we're adding percentages of the same base value of 4. So a value of 2 is the same as adding 50% of 4.
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

The results are the same.

Similarly,

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addfraction"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=.50,[unitAliases.chariot.id]=1.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=.50,[unitAliases.musketeer.id]=1.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

We'll have to do some new calculations, now, since multiply and multiplyfraction give different results than the various adding formulations.

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiply"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=1.50,[unitAliases.chariot.id]=2.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=1.50,[unitAliases.musketeer.id]=2.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Finally, we use multiplyPercent, and check for the same results
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=150,[unitAliases.musketeer.id]=200,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Quickly, I find that if a bonus applies, that bonus makes the attack value of a legion 98. I failed to multiply percents correctly in computeCategoryBonus. The Line
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
</code>
Is changed to
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+100)/100
</code>

Finally, Change archer bonus to 110 and musketeer bonus to 120 (so a unit will make a legion have 4.4 and 4.8 value before rounding), and test the rounding options. You will find they all work.

At the moment, we don't have a way to mix different types of bonuses. As said earlier, we might want this so that some units can be better at giving bonuses to low attack units than to high attack units, while others give a percentage bonus to everything. We could now write a bonus system that allows for multiple types of bonuses. However, the current bonus system allows for the bonus to change per unit. This means that we can, for example, convert a +2 attack bonus to a plus 100% bonus for a unit with 2 attack, and a plus 50% bonus for a unit with 4 attack. In the case of the multiplied bonuses, this will make the bonus more powerful if there is more than one. That is, 2 attack, +2 twice is 6, but if +2 is changed to x2, then the multiplied bonus brings the attack up to 8. However, this seems like it would be a relatively unlikely problem, and there are other things this code can't handle, so we'll let someone else make the code if they actually need it.

So, what we'll do is write a function that will change all appropriate entries in the categoryAttackBonusTable to reflect a different value. Hence,

<code>
-- plusFixed(unitType,number,categoryAttackBonusTable) --> void
-- changes the bonus given by unit type to any unit to be equivalent
-- to adding number to that unit's attack power
</code>

Here, an issue with tables arises. It is very likely that when someone defines their cateogryAttackBonusTable, they'll define it something like this
<code>
local rangeBonusCategory = {[unitAliases.archer.id]=.25,[unitAliases.musketeer.id]=.5}
local bonusTableForInfantry = {rangeBonusCategory}
local cABT = {type="addfraction"}
cABT[unitAliases.phalanx.id]=bonusTableForInfantry
cABT[unitAliases.legion.id] = bonusTableForInfantry
</code>
However, this means that both <code> cABT[unitAliases.legion.id] </code> and <code> cABT[unitAliases.phalanx.id] </code> actually refer to the same piece of memory, and changing cABT[unitAliases.legion.id][1][unitAliases.archer.id] will also change the value at cABT[unitAliases.phalanx.id][1][unitAliases.archer.id]. This is because of the way lua tables are designed. This design can be useful, for example it allowed us to make changes to usedUnitsTable in the last function without having to copy the table, make changes to the copy of the table, and then replace the original table with that copy as a return value. However, it also requires us to be careful when we make changes to entries in tables. In this case, we'll simply copy the table and all its sub values into a new table.

The code to do this is given by
<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

We will explain this code in the next section, since it involves a programming technique which we haven't discussed before.

For now, we analyze plusFixed:

<code>
-- plusFixed({[unitType1.id]=fixedBonus,[unitType2.id]=fixedBonus},categoryAttackBonusTable) --> void
-- changes the bonus given by unitTypeI.id to a unit to be equivalent to
-- to adding number to that unit's attack power. If the unit doesn't receive a bonus
-- from the unitType, then it won't after applying plusFixed.
-- The value of the existing bonus is ignored.

local function plusFixed(fixedUnitBonusTable,categoryAttackBonusTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
for bonusReceivingUnitTypeID,bonusTable in pairs(categoryAttackBonusTable) do
-- replace bonusTable with an equivalent table that is not referened
-- anywhere else, so that changes to it can be made without impacting
-- data elsewhere
categoryAttackBonusTable[bonusReceivingUnitTypeID] = duplicateTable(bonusTable)
-- make bonusTable refer to the "current" bonus table for the unit type
bonusTable =categoryAttackBonusTable[bonusReceivingUnitTypeID]
-- For each unit type in the fixedUnitBonusTable, check if any bonus category
-- in the bonusTable corresponds to it. If so, make the change
for bonusGivingUnitTypeID,fixedBonusValue in pairs(fixedUnitBonusTable) do
-- get the attack of the unit type
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
-- in each bonus category, check if the giver's unit type id is there,
-- if so, change to the correct attack
for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
if bonusCategory[bonusGivingUnitTypeID] then
-- change the bonus appropriately
if bonusType == "addbonus" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue
elseif bonusType == "addpercent" then
bonusCategory[bonusGivingUnitTypeID]=100*fixedBonusValue/baseAttack
elseif bonusType == "addfraction" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue/baseAttack
elseif bonusType == "multiplypercent" then
bonusCategory[bonusGivingUnitTypeID]=100*(fixedBonusValue+baseAttack)/baseAttack
elseif bonusType == "multiply" then
bonusCategory[bonusGivingUnitTypeID]=(fixedBonusValue+baseAttack)/baseAttach
else
error("pluxFixed: categoryAttackBonusTable.type does not have an acceptable value.")
end
end
end
end
end
end
</code>

[[File:GetStartedWithLuaLesson6-13-plusFixed1.jpg]]

As before, we save the bonusType in lower case, since we'll be using it a lot later. Next, we open a for loop, where the index is the id of the unit type receiving the bonus, and the value is the bonus table for that unit type. Next, we duplicate the bonus table, so that we have a table we can change without impacting anything elsewhere, and we store the duplicated table in categoryAttackBonusTable in place of the original bonusTable for the current bonus receiving unit id. Next, we assign this duplicated table to the variable bonusTable, so we can refer to it later in the code.

[[File:GetStartedWithLuaLesson6-14-plusFixed2.jpg]]

We now perform the following actions for each unitType.id and corresponding fixedBonusValue submitted in the fixedUnitBonusTable.

First, get the attack of the bonus receiving unit, since we'll need that in order to customize the bonus. Next, check each bonus category in the bonus table. If the bonus category has the current unitTypeID as a key, then replace the existing value with a bonus equivalent to adding a fixed value to the receiving unit's attack.

That's all that must be done, so end all the loops.

Now we test the function.

Add unitAliases.phalanx = civ.getUnitType(3) to the appropriate file.

<code>
defaultAttackValueTable[unitAliases.phalanx.id]=1
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,
nextBonusValue=0.5,maxBonusUnits=1}
local rangeBonusCategory = {[unitAliases.archer.id]=125,[unitAliases.musketeer.id]=150,
nextBonusValue=0.75,maxBonusUnits=1}
local standardBonus = {cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable[unitAliases.legion.id]=standardBonus
categoryAttackBonusTable[unitAliases.phalanx.id]=standardBonus
categoryAttackBonusTable.round="up"
attackBonus.plusFixed({[unitAliases.chariot.id]=2,[unitAliases.musketeer.id]=2},
categoryAttackBonusTable)
</code>
The chariot and the musketeer individually should each add 2 to both a phalanx and a legion,
so the phalanx should have an attack of 3, and the legion should have an attack of 6, if one bonus
is applied.

Since the bonus type is multiplypercent, together the phalanx would have an attack of 9, and the legion will also have an attack of 9.

In testing, we quickly get this error
<code>
You should see this in lua console if this worked
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: bad argument #1 to 'getUnitType' (number expected, got string)
stack traceback:
[C]: in function 'civ.getUnitType'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>

At line 356, which is

<code>
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
</code>

This must mean that bonusReceivingUnitTypeID is not a number. This is because we're looping over categoryAttackBonusTable, and that table has a couple of entries that are not integers ("type" and "round"). Therefore, we have to insert code to deal with this eventuality.

The simplest way is to put everything in the loop body into an if statement, so that it only runs when bonusGivingUnitTypeID is actually a number. You should be able to do this without detailed instructions, so do so (hint: use type function).

The next error is
<code>
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: bad argument #1 to 'pairs' (table expected, got nil)
stack traceback:
[C]: in function 'pairs'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>
<code>
360 for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
</code>

Here, we have a nil value for bonusTable. This turns out to be an error in duplicateTable. When I duplicated the table, I forgot to return that table. That is, both the if and else statement in that function need a return command, and I forgot to add <code> return duplicatedTable </code> in the if portion. Add this to the duplicate table function.

After this, our predictions are true. Testing the other types of bonus is left as an assignment. You can find the completed code [https://forums.civfanatics.com/threads/totpp-attack-bonus-library.648093/ here].

===Recursive Functions===

Let us return to the duplicateTable function. Recall that in the last section we added a line to it, so we'll restate it here:

<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
return duplicatedTable
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

[[File:GetStartedWithLuaLesson6-16-duplicateTable.jpg]]

The interesting thing about duplicateTable is that it invokes duplicateTable within its code. When we copy the key-value pairs into the new table, we run duplicateTable on the value. If the value is not a table, then we are in the else case, and the value is immediately returned to be inserted into the duplicated table. If the value is a table, that table is duplicated before anything else is done.

Let us look at a simple example of a recursive function, the factorial function N!. In lesson 3, we discussed the factorial function in the context of loops. Since N!=N*(N-1)*(N-2)*...*3*2*1, we can give another definition of N!:
N!=1 if N = 1
N!=N*(N-1)! if N > 1
Or, using the convention that 0!=1, we can state
N!=1 if N = 0
N!=N*(N-1)! if N > 0

The case where N =1 or N=0 is called the "base case." If we keep substituting N! as N*(N-1)!, then we won't go on forever, because we will eventually reach a point where N=0, and N! can be substituted as 1 instead of N*(N-1)!. As long as there is a base case, our program will eventually reach the base case(s), and begin "completing" evaluation.

<code>
function factorial(N)
if N>0 then
return N*factorial(N-1)
else
return 1
end
end
print(factorial(5))
print(factorial(6))
</code>

Run this in code in the lua demo website, or using the TOTPP lua interpreter.

Returning to our duplicateTable function, the base case is any time a table value is not itself a table. When that happens, the recursion "chain" ends, and everything can evaluated.

Although is shouldn't be a problem in this particular case, it should be noted that it is possible for there to not be a "base case" in the recursion style: if table, recur, if not return a value. Consider the following table system

<code>
a={}
b={[1]=a}
a[1]=b
</code>
In this case, the code would never end.

It is possible that even if the code could "theoretically" execute to completion, you run out of memory before that. This is called a "stack overflow," and if it occurs, you will have to think of an alternate way to solve your problem. It will probably be best to ask for help in that case (and it might be useful to provide others with an example of a problem that results in a stack overflow), but you might also look into "tail recursion", including http://www.lua.org/pil/6.3.html .

===Conclusion===

With the skills covered in this chapter, you now have the tools to split a large events file into multiple files that are more manageable. You also have the basics for how to write re-useable modules for your events, so that your work can be used by others. Remember that if someone else uses your implementation of a feature, they will spend much less time coding and testing it, allowing them to either finish the scenario sooner, or to introduce some other feature. So, it might very well pay to spend at least a little effort making your code into a reusable module. Perhaps you have an idea for a cool scenario mechanic, but don't have a scenario for it (or don't want to take the time to make it). If that's the case, just make the module and test it in a "toy" scenario (like Classic Rome) so that it can be used more or less "off the shelf" when someone needs it.

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-15T21:05:33Z

Prof. Garfield:

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [[here]]. (These are the same as I provided for the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the value "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [[flags.lua]]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of it passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

=== Conclusion ===

Get Started With Lua Events by Prof. Garfield

2019-08-15T21:04:32Z

Prof. Garfield:

[[Category:Lua Resources]]

Back To [[:Category:Lua Resources|Lua Resources]]

[https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/ Get Started With Lua Events] thread at the Civfanatics Forums.

[[Get Started With Lua Events Lesson 1: "Hello World"|Lesson 1: "Hello World"]]

[[Get Started With Lua Events Lesson 2: Giving Instructions to Your Computer|Lesson 2: Giving Instructions to Your Computer]]

[[Get Started With Lua Events Lesson 3: Tables, Loops, Logic, and Debugging|Lesson 3: Tables, Loops, Logic, and Debugging]]

[[Get Started With Lua Events Lesson 4: Examples and More Examples| Lesson 4: Examples and More Examples]]

[[Get Started With Lua Events Lesson 5: Even More Examples| Lesson 5: Even More Examples]]

[[Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files| Lesson 6: Splitting Code into Multiple Files]]

[[Get Started With Lua Events Lesson 7: Saving Data in the State Table| Lesson 7: Saving Data in the State Table]]

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-15T20:25:03Z

Prof. Garfield: /* Just Once */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [[here]]. (These are the same as I provided for the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the value "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)</code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [[flags.lua]]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of it passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg

2019-08-15T20:17:07Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg

2019-08-15T20:16:53Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg

2019-08-15T20:16:43Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-13-FlagTest3.jpg

2019-08-15T20:16:32Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-12-FlagTest2.jpg

2019-08-15T20:16:21Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-11-FlagTest1.jpg

2019-08-15T20:16:10Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-10-Flags5.jpg

2019-08-15T20:15:55Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-09-Flags4.jpg

2019-08-15T20:15:42Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-08-Flags3.jpg

2019-08-15T20:15:28Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-07-Flags2.jpg

2019-08-15T20:15:18Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-06-Flags1.jpg

2019-08-15T20:15:06Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-05-JustOnce.jpg

2019-08-15T20:14:53Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg

2019-08-15T20:14:40Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg

2019-08-15T20:13:23Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg

2019-08-15T20:12:01Z

Prof. Garfield:

File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg

2019-08-15T20:11:18Z

Prof. Garfield:

Get Started With Lua Events Lesson 7: Saving Data in the State Table

2019-08-15T20:10:15Z

Prof. Garfield: Put in much of lesson

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This lesson is still under construction.

===Introduction===

Thus far in these lessons we have used Lua to alter the state of the active civilization game. That is, we can create or delete units via events, grant or remove technologies, make adjustments to cities and so forth. However, what we have not done is to keep a record of previous events in order to change how events execute. In this respect, the old macro events system can still do things that we can't, by using functionality such as flags and the justonce modifier. This lesson will remedy the deficiency.

You can get the events for the start of lesson 7 [[here]]. (These are the same as I provided for the end of lesson 6.)

===The 'state' Table===

The Lua Events system allows us to store extra information in a saved game and retrieve it later. The information that we intend to store and retrieve is kept in a table, which is, by convention, named <code>state</code>, and usually referred to as the "state table." The state table got its name from an example events.lua file provided by The Nameless One, but you can change the name if you really want to. It is probably best to follow convention, however, especially if you are using code written by others.

The code to save the state table information to a file is given by:

<code>
civ.scen.onSave(function () return civlua.serialize(state) end)
</code>

<code>civlua.serialize(state)</code> turns the state table into a string, and the event trigger <code>civ.scen.onSave</code> appends that string to the end of the saved game file. To get that information back,

<code>
civ.scen.onLoad(function (buffer) state = civlua.unserialize(buffer) end)
</code>

[[File:GetStartedWithLuaLesson7-01-SaveAndLoad.jpg]]

is used to turn the "buffer" back into a table, named <code>state</code>, when a game is loaded.

===Counting Unit Kills===

In the old macro system, counting things is rather laborious. The following is macro code from an American Civil War scenario that requires 5 Confederate CSA Infantry units to be killed in order to issue the Emancipation Proclamation.

<code>
@IF
TURN
turn=12
@THEN
Flag
Continuous
Who=Union
State=On
Flag=12 ; Activates Antietam Unit KIA Counter
JUSTONCE
TEXT
LINCOLN REQUIRES MILTIARY SUCCESS ON THE BATTLEFIELD TO AVERT EUROPEAN INTERVENTION!
^
As the Commander-in-chief, you need to demonstrate to the European powers that you are
fighting for more then the preservation of the Union but for a higher moral cause, i.e. the
abolition of slavery on the continent through the Emancipation Proclamation.
^
But you cannot emit the Proclamation without gaining a victory on the battlefield and
thereby demonstrating that your ability to emancipate the slaves is backed by more than
words...
ENDTEXT
@ENDIF

@IF
TURN
turn=12
@THEN
TEXT
... As such you have till the end of September 1862 to defeat 5 CSA Infantry units. Failure to
do so will prevent you from emitting the Proclamation in a timely manner and bring France and
England on the side of the Confederacy.
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=12 ;
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=13 ;
JUSTONCE
TEXT
1st CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=13 ; 1st CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=14 ;
JUSTONCE
TEXT
2nd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=14 ; 2nd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=15 ;
JUSTONCE
TEXT
3rd CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=15 ; 3rd CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=16 ;
JUSTONCE
TEXT
4th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
UNITKILLED
unit=CSA Infantry
attacker=Union
defender=Confederates
@AND
CheckFlag
Who=Union
Flag=16 ; 4th CSA Infantry Killed
State=On
@THEN
Flag
Continuous
Who=Union
State=On
Flag=17 ; Emancipation Proclamation Given
JUSTONCE
TEXT
5th CSA Infantry killed!
ENDTEXT
@ENDIF

@IF
CheckFlag
Who=Union
Flag=17 ; Union kills 5th CSA Infantry starting January 1862
State=On
@THEN
GIVETECHNOLOGY
technology=82
receiver=Union
JUSTONCE
TEXT
EMANCIPATION PROCLAMATION ISSUED!
^
President Abraham Lincoln issues the Emancipation Proclamation, which declares the
freedom of all slaves in any state of the Confederate States of America.
ENDTEXT
@ENDIF
</code>

With Lua, we can do much better. Let us write an event that requires the Romans to kill some Celtic chariots, will display a message with the current tally when one is killed, and will display a message when an adequate number are killed, after which no more messages will be displayed.

A state table has already been in our events.lua file since the beginning of these lessons, along with a justOnce function (which we'll discuss later).

[[File:GetStartedWithLuaLesson7-02-StateJustOnce.jpg]]

We'll store the count of Celtic chariots killed in the value "celticChariotsKilledByRomans". We should initialize this value to 0 by using

<code>
state.celticChariotsKilledByRomans = state.celticChariotsKilledByRomans or 0
</code>

This means that if there is no value associated with the key "celticChariotsKilledByRomans" then the key is created and the value set to 0. If there already is a value, then that value is preserved.

We need to make this initialization in 2 places. The first is in the main body of our events.lua script, which is to say not in any particular function or table in the script. Just after the state table is created is a good idea.

The second place is in the function run by <code>civ.scen.onLoad</code>, after the state table is created from the buffer.

[[File:GetStartedWithLuaLesson7-03-initializeChariotCounter.jpg]]

It is important to make the initialization at both places. If the game has never been saved (or not saved with the state table), then the only way to have a state table is to initialize it in the main body of the events.lua. If, however, the game has been saved, onLoad (which will run after the code in events.lua is run) will replace the state table created by events.lua, and so render invalid any initializations done in the body of the events. This means that if you change the state initialization after having saved the game (such as if you add a new state entry during construction of your scenario), that entry will be erased when the state table is unserialized from the data stored in the saved game, so you will have to re-initialize it at least once. Just make the initialization in both places, and you won't have to worry about the meaning of this paragraph.

Let us make a parameter "chariotsToKill" and set it to 5. That means, we'll do something after the fifth chariot is killed.

In doWhenUnitKilled, when a Celtic chariot is killed by a Roman unit, we'll show a message with the number of chariots killed, and a different message when the threshold is reached.

<code>
local function doWhenUnitKilled(loser,winner)
--[[loser.owner.money = math.max(loser.owner.money -campaignCost,0)
winner.owner.money = math.max(winner.owner.money-campaignCost,0)]]
if loser.type == unitAliases.chariot and loser.owner == tribeAliases.celts
and winner.owner == tribeAliases.romans
and state.celticChariotsKilledByRomans < parameters.chariotsToKill then
state.celticChariotsKilledByRomans = 1 + state.celticChariotsKilledByRomans
if state.celticChariotsKilledByRomans < parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(state.celticChariotsKilledByRomans).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s.")
elseif state.celticChariotsKilledByRomans == parameters.chariotsToKill then
civ.ui.text("The "..tribeAliases.romans.name.." have now defeated "..
tostring(parameters.chariotsToKill).." "..tribeAliases.celts.adjective
.." "..unitAliases.chariot.name.."s. Something good happens.")
end
end
-- more code
end
</code>

[[File:GetStartedWithLuaLesson7-04-ChariotCounterCode.jpg]]

There isn't much to say about this code. The "outer" if statement checks if the unit that was killed was a chariot, if the unit was owned by the Celts, if the winning unit was owned by the Romans, and if the number of chariots killed is less than 5 (or whatever the parameter is set to).

If so, then we add 1 to the total of chariots killed. If the total is still less than 5, we display a message with the current number of chariots killed. If the last chariot killed brought the total to 5, a different message is displayed. We could get fancier and have a separate message for the first chariot killed, or whatever.

Note that by using the name and adjective of the tribes and unit types, we can make changes to the names of things without having to go back to our events and rewrite all the text.

Test this code, and make sure it works, even after saving and loading.

===Just Once===

Now let us take a look at <code>justOnce(key,f)</code>.

Fundamentally, <code>justOnce</code> works by checking if <code>key</code> is already in the state table. If it is not, then the function <code>f</code> is executed (with no arguments), and <code>key</code> is added to the state table with the value true. If <code>key</code> is already in the state table, then <code>f</code> is not executed.

What this means is that you have to choose your keys so that they don't conflict with any other key in the state table (either for other justOnce instances or for other things in the state table, such as counter values), unless you specifically want them to. For example, you might have event A and event B, and you want only one of them to happen, and to happen only once. By giving them the same key for justOnce, you will ensure that only one of them happens.

Let us now take a look at how justOnce is implemented. In the civlua module, we have this code

<code>
-- Wraps getting and setting of key `n` in table `t`.
local function property(t, n)
return {get = function () return t[n] end,
set = function (v) t[n] = v end}
end

-- When property `guard` is false, runs `f` and sets `guard` to true, otherwise does nothing.
local function justOnce(guard, f)
if not guard.get() then
f()
guard.set(true)
end
end
</code>

And in events.lua we have:

<code>
local justOnce = function (key, f) civlua.justOnce(civlua.property(state, key), f)
end
</code>

[[File:GetStartedWithLuaLesson7-05-JustOnce.jpg]]

The function <code>civlua.property(t,n)</code> returns two functions, one that gets the value of <code>t[n]</code> and the other that sets <code>t[n]=v</code> for a value v given as an argument to the function.

The function <code>civlua.justOnce(guard,f)<code> takes a table {get=function,set=function(v)} and a function f. If guard.get is nil or false, then the function f is executed and guard.set(true) is run. Basically, the property function returns an appropriate table for civlua.justOnce to use as the guard entry.

Finally, the justOnce function defined in events.lua "wraps" civlua.justOnce. At every instance of justOnce, we need to specify the key and function f, but we always want to use the same table, the state table. So, civlua.property(state,key) returns an appropriate guard value for civlua.justOnce every time, and then civlua.justOnce can be run with the correct guard and function.

I will not provide an example of the usage of justOnce. There should be enough information here for you to figure out how to use it, and you won't always find documentation with examples on how to use code. If you have trouble, ask in the forums.

===Flags and Accessing State from Modules===

When we counted chariot kills, we saw how to define and use our own counter in the state table. We could have made a "flag" by setting true or false values instead. While we certainly can write our events by directly manipulating and accessing the state table to use flags and counters, it will be more convenient to define some functions to do this for us. The scenario Over The Reich has the functions for flags and counters defined directly in the events.lua file, if you want to have a look. For this lesson, however, we're going to define a flags module that can be used from any file.

This raises a question: how can a function in our flag module make changes to the state table, which is local to events.lua? One solution is to make state global (by removing the 'local' when it is defined). That way, any module can access the state table by simply writing <code>state</code>. This has a couple downsides. One is that this forces "state" to be the only name for the state table. This is probably not a huge problem. The other reason is that by giving every module direct access to the state table, you run into the problem that multiple modules might try to use the same key values without realizing it. Of course, it might be useful to make state global if you've split your code into multiple files anyway, setting aside modules written by others.

So, what can we do? The first thing to realize is that tables are fundamentally global. Any part of the program can access a table as long as it has the "name" of the table. If I write <code>local myTable={}</code>, what is stored in the variable myTable is the "name" of the table, not all the key-value pairs of the table. The variable myTable just tells the program where to find the table in memory. If we can provide the value in myTable to another part of the program, then that part of the program can access myTable, even though it was defined locally.

Of course, if we simply write

<code>
local state= state or {}
globalState=state
</code>

then all we have done is to allow the writer of events.lua to use a different name for the state table, without any other benefit. However, we can do something else:

<code>
local state= state or {}
state.moduleOneState = state.moduleOneState or {}
globalModuleOneState = state.moduleOneState
</code>

What this does is create a new table in the state table at the key "moduleOneState", unless something already exists at that key, and ''that'' table is provided to moduleOne via the global variable globalModuleOneState. Then, to prevent conflicts, the scenario designer only has to make sure that the key "moduleOneState" is not used for any other purpose in the state table, and that globalModuleOneState is not used anywhere other than in ModuleOne.

However, if we like, we can be even cleverer. Consider this module, [[flags.lua]]:

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}

local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState

-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define

-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags

-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle

return flag
</code>

Let's first look at this part

<code>
local flagState = "flagState not linked"
-- the module name for flags if moduleName is not specified
-- moduleName allows the use of flags in other modules or libraries
-- without worrying about name conflicts
local defaultModuleName = "events.lua"

-- a table of flag keys and their initialized values
local initializeFlagList = {}

-- table of flag functions to be returned with the module
local flag = {}
</code>

[[File:GetStartedWithLuaLesson7-06-Flags1.jpg]]

The variables flag is a table to hold the functions this module will provide, and is not very interesting. Default module name is just a substitute for the string "events.lua", so that it is only defined in one place (on the off chance that we might want to change it).

The variables flagState and initializeFlagList are more interesting to us. Although they are local variables within this module, the functions ''within'' flags.lua will treat them as global variables. And these are not just constants that we've defined in one place for consistency and ease of making changes; we're actually going to change them as the program runs.

Recall the following code in lesson 2

<code>
function buggy(input)
j = 3
print(input)
end
print(j)
j = 7
buggy(8)
print(j)
</code>

This code prints
<code>
nil
8
3
</code>
Since the variable j is changed to 3 whenever buggy is run. We are going to do that on purpose to the variable flagState.

When the module is first loaded, flagState is set to the string "flagState not linked". This is simply so that we have an easy error check.

Now, consider the next function that was written

<code>
local function linkState(tableInStateTable)
if type(tableInStateTable) == "table" then
flagState = tableInStateTable
else
error("linkState: linkState takes a table as an argument.")
end
end

flag.linkState = linkState
</code>

[[File:GetStartedWithLuaLesson7-07-Flags2.jpg]]

This function takes the "name" of a table as input, and stores that name in the flagState variable, so that the table can be accessed by other functions in this module. If the state table is passed to this function, or, preferably, a table stored as a value in the state table, then all the functions in this module can write to the state table, or at least the part of it passed as an argument to linkState. Hence, we have achieved access to the state table without defining a global variable or by requiring that the state table be passed as an argument for every single function provided.

Now, look at

<code>
-- Specifies a key for a flag, and that flag's initial value.
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function define(key,initialValue,moduleName)
if type(initialValue) ~= "boolean" then
error("A flag in the flag module must have an initial value of true or false.")
end
if type(key) ~= "string" then
error("The flag module only allows strings for flag names. Consider using the function tostring to make the conversion if necessary.")
end
-- the moduleName is prefixed to prevent conflicts in different modules
-- define is only meant to be used in actual scenarios, not in library modules
moduleName = moduleName or defaultModuleName
-- if this key hasn't been used for a flag yet, then
if initializeFlagList[moduleName..key] == nil then
initializeFlagList[moduleName..key] = initialValue
else
error("The key "..tostring(key).." has already been used for a flag.")
end
end
flag.define = define
</code>

[[File:GetStartedWithLuaLesson7-08-Flags3.jpg]]

Much of this function is error checking, to make sure that appropriate values are given. The name of the flag (or the key) must be a string, and the initial value for the flag must be a boolean.

The moduleName variable is optional. If it is nil (which is the same as not being provided at all), then defaultModuleName is used. Basically, this allows a someone writing a module to use the flag library without worrying about writing flag names that will conflict with the flag names written by some scenario designer. Since the "true" key is the moduleName prefixed to the actual key, as long as moduleName is different in each module (and none are "events.lua"), there will be no conflict. This way, the scenario designer doesn't have to worry about the name at all, and module writers just have to add an extra argument to their function calls, and everything will work well "under the hood".

The line
<code>
if initializeFlagList[moduleName..key] == nil then
</code>
checks to make sure that the flag key in question has not already been used elsewhere. If it has, then its value will not be nil, and so an error can be given. Note that since false is a valid initialization, we must specify whether the value is nil or not.

If the key is not already in the table, it is added, with the initial value specified as the value. Each use of define permanently changes initializeFlagList, by adding a value to the table.

<code>
-- makes sure all flags are in the state table
-- if a flag is not in the state table, it is inserted
-- and initialized to the correct value
local function initializeFlags()
if type(flagState) == "string" and flagState == "flagState not linked" then
error("Use the function linkState before trying to initialize flags")
end
for key,initialValue in pairs(initializeFlagList) do
if flagState[key] == nil then
flagState[key] = initialValue
end
end
end
flag.initializeFlags = initializeFlags
</code>

[[File:GetStartedWithLuaLesson7-09-Flags4.jpg]]

Here, we first check that flagState has actually been replaced with a table. Next, we go through all the key-value pairs in initializeFlagList. If the key is not already in flagState, the key is added along with the initial value.

<code>
-- returns the current state (i.e. true or false) of the flag with the key
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function value(key,moduleName)
moduleName = moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
end
return flagState[moduleName..key]
end
flag.value = value

-- sets the flag's value to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setTrue(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = true
end
end
flag.setTrue = setTrue

-- sets the flag's value to false
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function setFalse(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = false
end
end
flag.setFalse = setFalse

-- changes the flag's value from true to false or false to true
-- optional parameter moduleName prevents name conflicts if
-- flags are used in a module or library
local function toggle(key,moduleName)
moduleName=moduleName or defaultModuleName
if flagState[moduleName..key] == nil then
error("The key "..key.." has not been initialized. Check your flag definitions and "..
"that the initializeFlags function has been executed.")
else
flagState[moduleName..key] = not(flagState[moduleName..key])
end
end
flag.toggle = toggle
</code>

[[File:GetStartedWithLuaLesson7-10-Flags5.jpg]]

All of these functions simply provide access to the flagState table, adding the moduleName and producing an error if the flag doesn't exist.

Now, let us do some tests.

<code>
local flag = require("flags")
flag.define("warriorKilled",false)
flag.define("phalanxKilled",false)
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

And in onLoad
<code>
state.flagState=state.flagState or {}
flag.linkState(state.flagState)
flag.initializeFlags()
</code>

[[File:GetStartedWithLuaLesson7-11-FlagTest1.jpg]]

Add a warrior alias to classicRomeAliases, and the following code to doWhenUnitKilled
<code>
if loser.type == unitAliases.warrior and not flag.value("warriorKilled") then
civ.ui.text("First Warrior Killed")
flag.setTrue("warriorKilled")
end
if loser.type == unitAliases.phalanx and not flag.value("phalanxKilled") then
civ.ui.text("First Phalanx Killed")
flag.setTrue("phalanxKilled")
end
</code>

[[File:GetStartedWithLuaLesson7-12-FlagTest2.jpg]]

Test this by killing warriors and phalanxes (suicide attacks are effective here). Only the first one killed should show a message.

We'll make a little addendum to the plunder module, to test flags in separate modules.

<code>
flag = require("flags")
flag.define("warriorKilled",false,"plunder.lua")
local function firstLegion(loser)
if loser.type == unitAliases.legion and
not flag.value("warriorKilled","plunder.lua") then
civ.ui.text("First Legion Killed.")
flag.setTrue("warriorKilled","plunder.lua")
end
end

return {
firstLegion=firstLegion,
</code>
[[File:GetStartedWithLuaLesson7-13-FlagTest3.jpg]]

Add <code> plunder.firstLegion(loser) to the doWhenUnitKilled function.

It should have the same effect as the warrior and phalanx events, but for legions. This is true even though we reused the "warriorKilled" string for a flag name. Note that to use flags in a module, the flag module must also be set up in events.lua.

=== After Production Events ===

With flag functionality, we can now introduce a new event trigger, the "afterProduction" trigger. This event trigger takes place after city production is complete for the turn, but before unit movement begins. This is not a built in event trigger from the civ.scen library, however. Instead, what we're going to do is use the civ.scen.onActivateUnit trigger to achieve it.

We'll make this trigger by running our "doAfterProduction" function the first time a unit is activated for a player during a turn. So that doAfterProduction is only run once per tribe per turn, we'll have flags that tell if the afterProduction event has been run. If it has, the onActivateUnit code will ignore it. Then, the flags are reset each turn.

We'll make a simple after production event
<code>
local function doAfterProduction(turn,tribe)
civ.ui.text(tribe.name.." is the active tribe.")
if tribe.isHuman then
civ.ui.text(tribe.leader.name.." is a human.")
end
end
</code>

In our flag definitions, we add the following lines:
<code>
for i=0,7 do
flag.define("afterProductionForTribe"..tostring(i).."NotDone",true)
end
</code>

In our doOnActivation function, we add the lines
<code>
if flag.value("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone") then
doAfterProduction(civ.getTurn(),civ.getCurrentTribe())
flag.setFalse("afterProductionForTribe"..tostring(civ.getCurrentTribe().id).."NotDone")
end
</code>

Finally, in doThisOnTurn, we add the loop
<code>
for i=0,7 do
flag.setTrue("afterProductionForTribe"..tostring(i).."NotDone")
end
</code>

This loop will reset the flags to true each turn, so that after production will run every turn.

[[File:GetStartedWithLuaLesson7-14-AfterProduction1.jpg]]
[[File:GetStartedWithLuaLesson7-15-AfterProduction2.jpg]]

Now we try it out. One message should appear for each tribe every turn, but the other message should appear only for the human owned tribe.

Note that the after production event won't run if a player has no active units after city production. If this is a likely possibility for your scenario, you will have to account for that. For example, during the after production event, you could create a unit for the next tribe in a remote corner of the map, and delete the guaranteeing unit for the current tribe.

===Barracks and Veteran Status===

Back in Lesson 4, I mentioned that we couldn't remove veteran status from newly created units (bestowed by a barracks) because the veteran status was not applied until ''after'' the on production event was completed. However, now that we have the afterProduction functionality, we can make the change.

What we'll do is keep a list of all (ground) units produced in cities with barracks, and remove veteran status for those units after production. We won't bother checking if Sun Tzu is built or anything else.

The code in doOnCityProduciton is
<code>
if civ.isUnit(prod) then
if civ.hasImprovement(city,improvementAliases.barracks) and prod.type.domain == 0 then
state.vetStatusToRemove = state.vetStatusToRemove or {}
state.vetStatusToRemove[#state.vetStatusToRemove+1] = prod
end
</code>

The code in doAfterProduction is
<code>
state.vetStatusToRemove=state.vetStatusToRemove or {}
for index,unit in pairs(state.vetStatusToRemove) do
unit.veteran = false
state.vetStatusToRemove[index] = nil
end
</code>

[[File:GetStartedWithLuaLesson7-16-NoBarracksVet.jpg]]

Something to note is that before referring to state.vetStatusToRemove, we make sure that it exists, and create it if it doesn't. This ensures that there will not be any errors trying to index a nil value. We might want to make functions to add, check, and remove things from the state table (and, more particularly, any subtables in state) so that we don't have to write the checks that all the tables exist manually each time.

Try this code. It should work perfectly fine (except that it will remove the effect of Sun Tzu's from cities with barracks). Be sure to test that units produced in previous turns that have subsequently gained veteran status keep it, and test that sea units produced in a city with a port facility and barracks still retain the port facility advantage.

=== civ.scen.onLoad vs. civ.scen.onScenarioLoaded ===

Get Started With Lua Events by Prof. Garfield

2019-08-15T20:08:00Z

Prof. Garfield:

The scenario library

2019-08-15T20:05:08Z

Prof. Garfield: Added onLoad and OnSave events

[[Category:Lua Resources]]
Back To [[TOTPP Functions]]

[[civ.scen.onTurn|onTurn]]

<code>civ.scen.onTurn(function (turn) -> void)</code>

[[civ.scen.onUnitKilled|onUnitKilled]]

<code>civ.scen.onUnitKilled(function (loser, winner) -> void)</code>

[[civ.scen.onLoad|onLoad]]

<code>civ.scen.onLoad(function (buffer) -> void)</code>

Buffer is a string attached to the end of a saved game file. It can be unserialized back into a state table.

[[civ.scen.onSave|onSave]]

<civ.scen.onSave( function () --> string)</code>

The string returned is attached to the end of the saved game file.

[[civ.scen.onScenarioLoaded|onScenarioLoaded]]

<code>civ.scen.onScenarioLoaded(function () -> void)</code>

[[civ.scen.onNegotiation|onNegotiation]]

<code>civ.scen.onNegotiation(function (talker, listener) -> boolean)</code>

[[civ.scen.onSchism|onSchism]]

<code>civ.scen.onSchism(function (tribe) -> boolean)</code>

[[civ.scen.onCityTaken|onCityTaken]]

<code>civ.scen.onCityTaken(function (city, defender) -> void)</code>

[[civ.scen.onCityProduction|onCityProduction]]

<code>civ.scen.onCityProduction(function (city, prod) -> void)</code>

[[civ.scen.onCentauriArrival|onCentauriArrival]]

<code>civ.scen.onCentauriArrival(function (tribe) -> void)</code>

[[civ.scen.onCityDestroyed|onCityDestroyed]]

<code>civ.scen.onCityDestroyed(function (city) -> void)</code>

[[civ.scen.onBribeUnit|onBribeUnit]]

<code>civ.scen.onBribeUnit(function (unit, previousOwner) -> void)</code>

[[civ.scen.onGameEnds|onGameEnds]]

<code>civ.scen.onGameEnds(function (reason) -> boolean)</code>

[[civ.scen.onKeyPress|onKeyPress]]

<code>civ.scen.onKeyPress(function (keyCode) -> void)</code>

Registers a function to be called every time a key is pressed.

[[civ.scen.onActivateUnit|onActivateUnit]]

<code>civ.scen.onActivateUnit(function (unit, source) -> void)</code>

Registers a function to be called every time a unit is activated. The callback takes the unit activated as a parameter, and the source of unit activation. Source is `true` if activated by keyboard or mouse click, `false` if activated by the game itself.

[[civ.scen.onCityFounded|onCityFounded]]

<code>civ.scen.onCityFounded(function (city) -> void)</code>

Registers a function to be called every time a city is founded. The callback takes the city as a parameter.

[[civ.scen.onResolveCombat|onResolveCombat]]

<code>civ.scen.onResolveCombat(function (defaultResolutionFunction, defender, attacker) -> boolean)</code>

Registers a function to be called during every combat turn. The first parameter of the callback is the default resolution function, as implemented by the game. It takes the attacker and defender as parameters. You can call this to produce a result for cases you don't need to handle yourself.
Return `true` to continue combat, `false` to stop.

[[civ.scen.onCanBuild|onCanBuild]]

<code>civ.scen.onCanBuild(function (defaultBuildFunction, city, item) -> boolean)</code>

Registers a function to be called every time a check is done whether a city can build something or not. It is called for all unit types, improvements and wonders. The first parameter of the callback is the default build function, as implemented by the game. It takes the city and item as parameters. You can call this to produce a result for cases you don't need to handle yourself. `item` can be a unittype, improvement or wonder.
Return `true` if `city` is allowed to produce `item`, `false` if not.

Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files

2019-07-26T16:19:51Z

Prof. Garfield:

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

===Introduction===

In this lesson, we will take a look at how to split the code for a scenario's events into multiple files. There are several reasons to consider doing this.

The first reason is simply to organize your work. If you have a series of complicated events, the events.lua file can become very large very quickly. Once your events.lua file has thousands of lines of code in it, it may not be very obvious where the best place is to put that next helper function, or where to implement the function that runs a complicated event. Sometimes even finding the piece of code that has to be changed can be a bit of a hassle. In Over the Reich, I sometimes search for the associated civ.scen line, and then search for the exact name of the function I need. Occasionally, there may even be more searching to find what I actually have to change. With multiple files, it becomes easier to find things.

Another aspect of using multiple files is that you can make certain changes without worrying about breaking things elsewhere. If myBigComplicatedFunction relies on aModestHelperFunction for a certain part of its functionality, and a change to myBigComplicatedFunction also requires a change to aModestHelperFunction, you have to make sure that nothing else in your code also uses aModestHelperFunction, or, if something else does depend on it, that aModestHelperFunction either still provides the original functionality, or that all other functions that use aModestHelperFunction are suitably modified. If myBigComplicatedFunction is defined in its own lua module, then you don't have to worry about forgetting that aModestHelperFunction was used elsewhere, since it can't be accessed outside the module unless you specifically allow it to be.

A second reason to split events code into multiple files is to facilitate collaboration. If all of the events are in a single file, then only one person can make changes to the file at a time. If one partner starts changing an event, but has to do something else before finishing, everyone waits on one person's delay. However, if most aspects of the scenario are separated into individual files, everyone can work on his or her own piece of the puzzle without depriving others of the opportunity to work at that time.

A third reason to split events into multiple modules is to facilitate reusing code. If everything required to implement an event is in its own file (or files), it becomes much easier for other creators to use your functionality in their scenario. Since everything they need is already in one place, they don't have to find every last helper function, or concern themselves with naming conflicts.

===Two Simple Examples===

Let us look at the top of the events.lua file. You can get the version that I started lesson 6 with [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here].

[[File:GetStartedWithLuaLesson6-01-DefaultRequire.jpg]]

We get code from other files by using the command <code>require</code> along with a string specifying the file name (except for the .lua extension). At the moment, we can only get code stored in the lua folder in the Test of Time directory. This is inconvenient if we're trying to distribute a scenario, since installing a scenario would require moving certain files to the lua directory, and those file names might conflict. Instead, we need to tell the Lua interpreter to search in the same folder that the events.lua folder is in.

To do this, we need the following code:
<code>
local eventsPath = string.gsub(debug.getinfo(1).source, "@", "")
local scenarioFolderPath = string.gsub(eventsPath, "events.lua", "?.lua")
if string.find(package.path, scenarioFolderPath, 1, true) == nil then
package.path = package.path .. ";" .. scenarioFolderPath
end
</code>

You can probably cut and paste this code before the require lines in your events.lua file and not worry about how it works. However, I'll provide a brief explanation for reference.

The first line stores the location of the of the current file as a string in eventsPath.

The second line replaces events.lua in the eventsPath with ?.lua, which will tell the Lua interpreter to look for .lua files in the current directory (that is to say, the directory with the events.lua file).

The if statement adds scenarioFolderPath to the places for the Lua interpreter to search for code, if that directory is not already in the search path. Since the search path is kept active by the Lua interpreter, it will not be necessary to repeat these lines of code in every file that performs a require action as long as you are running the file as part of events. If you are writing some other kind of code, you will need to substitute "events.lua" with the name of the file with the code you are running. Note that for some reason, events.lua is always provided in lower case. However, for use in other situations, debug.getinfo(1).source uses the correct case for event files. I have only briefly tested this, so you may have to do some testing yourself if this situation comes up (or ask for help in the forums).

Now that we've told Lua where to look for our extra code, we can begin moving code to other files. Think of require as telling Lua to run the entire contents of another file as a function. We can then assign a value to whatever that file returns, which will usually be a table. A couple of examples will clarify.

For our first example, we will move our scenario's parameters to a separate file, and access it via require. This may not seem worthwhile in this example, but tables like this can get large in a hurry. At the time of writing, Over the Reich has over 100 lines of parameters ("specialNumbers"), and parameters are something that a designer might like to play with while collaborators make other implementations. Also, parameters will have to be referenced by other parts of the code, and a file that is required by events.lua cannot, in turn, require events.lua in order to get information. That means that we'll have to keep our parameters in a separate file anyway.

Cut the parameters table definition and paste it into a new file, classicRomeParameters.lua. For the last line, write
<code>
return parameters
</code>

Now, Near the top of events.lua, where the existing require lines are, add the eventsPath code from above and also the line
<code>
local parameters = require("classicRomeParameters")
</code>

[[File:GetStartedWithLuaLesson6-02-RequireParameters.jpg]]

Open the classicRome scenario and test out a couple of events to make sure everything is the same.

We might find it convenient to put a few tables into the same file. For this, we will simply return a table containing these tables, and give each table a name in the events.lua file.

Create a file classicRomeAliases.lua and move all the "aliases" tables to that file. Also move the getCityAt function.

At the bottom of the file, put the following lines:
<code>
return {
unitAliases=unitAliases,
tribeAliases=tribeAliases,
tileAliases=tileAliases,
cityAliases=cityAliases,
textAliases=textAliases,
terrainAliases=terrainAliases,
improvementAliases=improvementAliases,
}
</code>

Then, add the following lines to events.lua (in the require section)
<code>
local aliases = require("classicRomeAliases")
local unitAliases,tribeAliases,tileAliases,cityAliases,textAliases,
terrainAliases,improvementAliases=aliases.unitAliases,aliases.tribeAliases,
aliases.tileAliases,aliases.cityAliases, aliases.textAliases,aliases.terrainAliases,
aliases.improvementAliases
</code>

Here, our classicRomeAliases module is returning a table with our "alias" tables. We then assign the entries in this returned table to local variables with the desired names. Here, I use multiple variable assignment, which I don't believe I've used before (even though Lua allows it), but these could just as simply have been assigned line by line.

[[File:GetStartedWithLuaLesson6-03-RequireAliases.jpg]]

Now, let us move the legion plundering code into its own file, which we'll call plunder.lua. First, copy over the legionPlunder function, and paste it near the bottom of the new file.

Now, let us go through the code of this function, and figure out what else we need in our plunder.lua module.

The very first part of the function is a check against unitAliases.legion. This means we need the unitAliases table, and so we copy the aliases require code to the top of plunder.lua. We don't need the path information, since that will be added in events.lua.

A few more lines down, we find that the function cityRadius is also used in legionPlunder. Therefore, we move that over as well. We also need the plunderValue function, so copy that over as well.

Next, we check if cityRadius relies on anything, but it doesn't.

Proceeding to plunderValue, we find that it relies on the parameters table, so require that as well. The function plunderValue does not appear to depend on anything else, so we're done moving functionality. If we missed something, the Lua interpreter will complain at some point anyway.

Next, we require the plunder module in events.lua, with the following line:

<code>
local plunder = require("plunder")
</code>

Next, for each of the functions in plunder.lua, we check if it is used somewhere in events.lua. We can do this by searching. plunderValue isn't used anywhere, so we're done with that. City radius is used. At the bottom of plunder.lua, we begin our return table, and have
<code>
return {
cityRadius=cityRadius,
}
</code>

Then, in events.lua, we replace the ocurance of cityRadius with plunder.cityRadius. Alternatively, we could have put
<code>
local cityRadius=plunder.cityRadius
</code>
after the line requiring plunder.

Similarly, for legionPlunder, we add <code>legionPlunder=legionPlunder</code> to the table that plunder.lua returns, and pre-append plunder. to legionPlunder in the one location where it occurs.

Now, we test the legion plunder function and the press 4 generate archers function to make sure everything works.

[[File:GetStartedWithLuaLesson6-04-RequirePlunder.jpg]]

===Working With a Library===

In programming terms, a "library" is a collection of code that can provide some specified functionality to a programmer without that programmer having to modify the code in the library. Thus far, you have been using the "civ" library to interact with the game, and there has been no need modify it in order to use it in our own events. (Unfortunately, in the case of the civ library, we don't actually know how to modify it.) This is in contrast to much of the code we have written thus far. For example, the code we wrote last lesson to make Selucid elephants attack Egypt is highly specific. You couldn't just cut and paste that code, change the argument of a single function, and get your own goto event. It is still a good example for how to write a goto event, but a user would still have to actually write the event.

If you plan to write some functionality for your scenario that others might find useful, it is worth spending a little extra effort to see if you can write that functionality in a form that will allow others to use it with minimal effort. If you can, then a little extra work on your part might save someone else the trouble of re-inventing the wheel, and allow them to complete their project sooner, or to work on some new feature for you to enjoy. Unfortunately, the Lua scenarios that have been completed at the time of writing haven't been that good at creating re-usable code, at least in part since we were all getting used to Lua. This will hopefully be improved in the future.

For now, we're going to look at a library which is called the General Library (unless someone comes up with a better name) and which can be found [https://forums.civfanatics.com/threads/totpp-the-general-library.647583/ here]. The purpose of this module is to provide relatively simple functionality that probably shouldn't be implemented every time it is needed. This is useful for our purposes, since we can look at relatively self contained and simple functions for our first examples. We'll create a library for generating munitions later.

This library would be used by invoking the line

<code>
local gen = require("generalLibrary")
</code>

If you wanted to make these functions available to the console for testing purposes, you would simply omit the local, thereby making gen a global variable.

Let us now take a look at a function provided by the General Library <code> gen.hasIrrigation(tile)-->boolean</code>. The very first line references the helper function <code> toTile(tile or table)-->tile</code>, so let us include that code, and look at it first.

<code>
-- toTile(tile or table)-->tile
-- gen.toTile(tile or table)-->tile
-- If given a tile object, returns the tile
-- If given coordinates for a tile, returns the tile
-- Causes error otherwise
-- Helper Function (provided to this library as toTile and gen.toTile)
local function toTile(input)
if civ.isTile(input) then
return input
elseif type(input) == "table" then
local xVal = input[1] or input["x"]
local yVal = input[2] or input["y"]
local zVal = input[3] or input["z"] or 0
if type(xVal)=="number" and type(yVal)=="number" and type(zVal)=="number" then
if civ.getTile(xVal,yVal,zVal) then
return civ.getTile(xVal,yVal,zVal)
else
error("Table with values {"..tostring(xVal)..","..tostring(yVal)..
","..tostring(zVal).."} does not correspond to a valid tile.")
end
else
error("Table did not correspond to tile coordinates")
end
else
error("Did not receive a tile object or table of coordinates.")
end
end
gen.toTile = toTile

-- gen.hasIrrigation(tile)-->boolean
-- returns true if tile has irrigation but no farm
-- returns false otherwise
function gen.hasIrrigation(tile)
tile = toTile(tile)
local improvements = tile.improvements
-- irrigation, but no mining, so not farmland
if improvements & 0x04 == 0x04 and improvements & 0x08 == 0 then
return true
else
return false
end
end
</code>

[[File:GetStartedWithLuaLesson6-05-HasIrrigation.jpg]]

Let us begin by looking at the function <code>toTile</code>. The purpose of this function is to allow other functions to accept tile coordinates in a table instead of an actual tile object. The function tries to be reasonably permissive in the coordinates it will accept, allowing both integer indices and lowercase string indices, and by assuming that a missing z value corresponds to map 0. The function also tries to give reasonably helpful errors.

This brings up something that should be considered when making reusable code: what to do if you don't get values you were expecting. One option is to throw an error and bring up the Lua console. This is good for scenario creators, so they know something is wrong, but not so great for end users because the error stops the rest of the event from happening, should the mistake slip through playtesting.

The other option is for the code to fail silently, and try to do what it can. This is the way the old Test of Time macro system often fails. If Civ II doesn't "understand" the event, it just doesn't happen, and doesn't bother the player with the error. This means that the scenario will still mostly work, but it is harder to catch issues during playtesting. Sometimes, this means doing something "sensible" if the input isn't of the expected type, and might make the code easier to write, since you don't have to handle inputs differently.

A third option is to write your code such that both things can be done. At the top of your code, you put in a variable named "debugMode" or something, and make all the functions throw errors when true, and fail silently when false. Then you playtest with debugMode set to true, and release with debug mode set to false. However, this means extra work in writing your code and you also have to test everything with debug mode off.

For toTile, I went with the fail with error option, since that will allow every function that uses toTile to assume it is receiving proper data. It also seems unlikely that people will be regularly trying to check tiles that don't exist or have tables with tiles and units and improvement objects all in one. And if they do, "guarding" is fairly straightforward anyway (as we've done in previous lessons).

Although toTile is mainly meant to be a helper function for the General Library, it is also put into the gen table to be made available to end users, since it offers useful functionality. Hence, <code> gen.toTile=toTile</code>. Note that we could have given toTile a different name in the gen table that this module will return, such as gen.tableToTile=toTile. In fact, we could refer to the same function with multiple keys in the gen table, if we want to.

Next, we will look at gen.hasIrrigation.

The first thing to notice is that local is not being used to define this function. That is because we're putting the function for gen.hasIrrigation directly into the gen table that this module will return. We could define hasIrrigation as a local variable and then copy it into the gen table. However, there is a decent chance that the General Library will have more than 200 functions by the time everything is complete, since it is meant to provide a lot of building block functionality and keep it in one place, and we will run into trouble if we assign 200 local variables in a single function (which a required lua file acts as).

Perhaps the most striking thing is that we begin by changing the value of tile, the argument of the function. It looks like we're making a global variable named tile, but we're not. When you specify the names of the arguments for a function (in this case tile), you create local variables for that function, which can be given new values just as if you had explicitly used the local keyword.

Beyond that, we extract the integer representing the tile improvements into a local variable (which upon later reflection isn't really necessary), and check that the irrigation bit is set to 1 and the mining bit is set to 0. Refer to lesson 5 for why this works. In fact, we could have simply returned the value of the if statement, rather than specifying return true and return false, although it is very slightly clearer what is going on in the expanded version of the code.

Now, let us write a function to place irrigation on a square. It seems pretty clear that we should do nothing if the tile has a city, but we also have to decide what to do if there is mining or farmland on the tile, since those interfere with placing irrigation. We'll just remove them, on the basis that if we're trying to "place irrigation," then we want irrigation to be there when we are finished.

<code>
function gen.placeIrrigation(tile)
tile = toTile(tile)
</code>

These lines open the function and convert a table of coordinates to a tile if necessary.

<code>
if tile.city then
return
end
</code>

If the tile has a city, return so nothing else is done in the function.

<code>
-- Set irrigation bit to 1
tile.improvements = tile.improvements | 0x04
-- Set mining bit to 0
tile.improvements = tile.improvements & ~0x08
end
</code>

Set the irrigation bit to 1 and the mining bit to 0.

The functions in this library don't have to be complex, and in fact, most probably shouldn't be. They just have to make life easier for the end user. If you reach this lesson before the General Library is considered "complete," your assignment now is to submit some work for it. If you don't feel comfortable doing bitwise operations, you can test the work of others or submit functions that simplify other tasks. However, there are also some helper functions in the library to facilitate changing bits, so you might also consider working on the unit type flags functions. Remember, if you want to make functions available to the console for testing purposes, they must be global variables.

=== The Threshold Table and First Look at Metatables===

Consider a scenario design situation that occurred in Over the Reich: a bomber is generating some bombs via a key press, and the number of bombs it should generate is dependant on its current remaining hitpoints. The more hitpoints the bomber has, the more bombs it should generate. What we want is to specify that if a bomber has between x and y hitpoints, it should produce 2 bombs. That is, for a given type of bomber, we want to have, for example,

hp >= 16 --> 4 bombs
16 > hp >= 12 --> 3 bombs
12 > hp >= 9 --> 2 bombs
9 > hp >= 4 --> 1 bomb
4 > hp >= 0 --> 0 bombs

Unfortunately, Lua tables do not naturally encode this kind of association by default. However, Lua does have a feature called metatables, which allows us to change the behaviour of tables. (This will be a much better way to make the specification than I ended up writing in Over the Reich.)

A metatable is a table that we can "attach" to another table, and then the metatable changes the behaviour of that table. We'll only look at metatables briefly here, but more information can be found [https://www.tutorialspoint.com/lua/lua_metatables.htm here].

What we want is a data structure that can accept numerical "key values" that are between the key values explicitly specified, and return the appropriate value for those keys. We will call this data structure a threshold table, since we are specifying threshold values as keys. We can do this by assigning the following metatable:

<code>
local mt = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
</code>

If we run <code> setmetatable(myTable,mt)</code>, then whenever we ask for an index from myTable and that index doesn't currently exist in myTable, the function assigned to __index will run. Now let us examine the function.

If the type of the key is not a number, then we return whatever the table value is for that key. We use the function rawget, because the standard <code>thresholdTable[key]</code> will invoke this function again if the key doesn't exist, and so never return an answer (when we want it to return nil).

If the key type is a number, then we look for the largest numerical index that is also less than or equal to the key value. We return a default value of false if the key submitted is smaller than all numerical values. False is chosen over nil, so that a maximum value can be set by setting the value of a numerical index to false. Using the key [-math.huge] allows a return value to be set for all numbers (since all numbers are greater than -math.huge).

Since we don't want scenario creators to have to re-create threshold tables every time they need them, we'll add this functionality to the General Library

<code>
local thresholdTableMetatable = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
-- gen.makeThresholdTable(table or nil)-->thresholdTable
function gen.makeThresholdTable(inputTable)
inputTable = inputTable or {}
return setmetatable(inputTable,thresholdTableMetatable)
end
</code>

[[File:GetStartedWithLuaLesson6-06-ThresholdTable.jpg]]

===A Munition Generation Module===

Now, let us write some re-usable code for a human player to generate units by pressing a key while an appropriate unit is active. This sort of code could be used for ranged attacks (generating a "munition") and also for recruiting mercenaries by paying gold.

The first thing we will want to do is to decide how our code will be used by the end user. This will, perhaps, change by the time we finish writing the code, but it will at least give us a starting point.

spawnUnit(generatingUnit, specificationTable)--> table of unitCreated

Our goal is that when a player attempts to generate a unit using another unit, they will provide the unit spawning the new unit, and a table of information specifying if a unit (or units) can be spawned and anything else that must happen while spawning (like paying money, expending movement points, etc.).

We have an option here. We could have the scenario creator provide the specification table as a required file for our module, or the creator can provide it at the time spawnUnit is called. I choose the latter for a couple of reasons. The first is that it allows the player to have more than one specification table, either because more than one key can spawn a unit, or because the specification can change over time. The other is reason is so that the creator can make the table in the events.lua file if desired (since our module can't require information from events.lua).

Having decided that our generateUnit events are going to be specified by a table, we have to decide what the contents of that table should be. It seems pretty reasonable to index the specificationTable with the index of the unit type of each unit that can generate using the information in the table. If a unit type id number is missing, that unit doesn't generate a munition (or recruit a unit).

The value for each unit type id in the specification table will be a table that specifies how and if that unit generates other units.

--specificationTable[unitType.id]={
--
-- goldCost = integer or nil
-- amount of gold it costs to generate a unit
-- absent means 0
-- minTreasury = integer or nil
-- minimum amount of gold in treasury to generate a unit
-- absent means refer to gold cost
-- (tribe will generate and be set to 0 if treasury is less than goldCost)
-- treasuryFailMessage = string or nil
-- A message to be displayed if the unit fails to spawn a unit due to an
-- insufficient treasury
-- nil means no message

-- There are three ways to specify move costs, in full movement points,
-- in "atomic" movement points, and as a fraction of total movement points for the
-- unit type. Use only one kind per unit type

-- moveCost = integer or nil
-- movement points to be expended generating the unit
-- "full" movement points
-- absent means 0
-- minMove = integer or nil
-- minimum remaining movement points to be allowed to generate a unit
-- "full" movement points
-- absent means any movement points for land/sea, 2 "atomic" for air units
-- postGenMinMove = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostAtomic = integer or nil
-- movement points to be expended generating the unit
-- refers to the unit.moveSpent movement points
-- absent means 0
-- minMoveAtomic = integer or nil
-- minumum remaining movement points to be allowed to generate a unit
-- referes to the unit.moveSpent movement points
-- absent means any movement points for land, 2 "atomic" for air units
-- postGenMinMoveAtomic = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostFraction = number in [0,1] or nil
-- fraction of unit's total movement points expended generating the unit
-- round up to nearest "atomic" movement point
-- absent means 0
-- minMoveFraction = number in [0,1] or nil
-- fraction of unit's total movement points that must remain to be allowed
-- to generate a unit
-- absent means any movement points for land, 2 "atomic" for air units
-- round up to nearest "atomic" movement point
-- postGenMinMoveFraction = number in [0,1] or nil
-- a unit will be left with at least this many movement points after
-- the generation function, round up to nearest "atomic" move point
-- absent means 0 for land/sea, 1 "atomic" for air units
-- roundFractionFull = bool or nil
-- fractional movement cost and minimum are rounded up to full movement point
-- instead of atomic movement point
-- nil/false means don't
-- roundFractionFullDown = bool or nil
-- fractional cost and minimum are rounded down to full move point
-- nil/false means don't
-- minMoveFailMessage = string or nil
-- a message to be displayed if a unit is not generated due to insufficient
-- movement points.
-- nil means no message

-- allowedTerrainTypes = table of integers or nil
-- a unit may only be generated if the tile it is standing on
-- corresponds to one of numbers in the table
-- nil means the unit can be generated on any terrain type
-- terrainTypeFailMessage = string or nil
-- message to be displayed if a unit is not generated due to standing
-- on the incorrect terrain

-- requiredTech = tech object or nil
-- the generating civ must have this technology in order to generate
-- the unit
-- nil means no requirement
-- techFailMessage = string or nil
-- message to be displayed if a unit is not generated due to not having
-- the correct technology

-- payload = boolean or string
-- if true, unit must have a home city in order to generate munitions
-- and generating munitions sets the home city to NONE
-- payloadFailMessage = string or nil
-- message to be displayed if a unit is not generated due to the
-- payload restriction
-- payloadRestrictionCheck = nil or function(unit)-->boolean
-- If function returns false, the home city is not valid for giving the
-- unit a payload. This will be checked when the unit is activated, when
-- the unit is given a new home city with the 'h' key and when the unit
-- tries to generate a munition
-- nil means no restriction
-- payloadRestrictionMessage = nil or string
-- message to show if a unit fails the payloadRestrictionCheck

-- canGenerateFunction = nil or function(unit)-->boolean
-- This function applied to the generating unit must return true in order
-- for a unit to be spawned. All other conditions still apply.
-- any failure message should be part of canGenerateFunction
-- absent means no extra conditions

-- generateUnitFunction = nil or function(unit)-->table of unit
-- This function creates the unit or units to be generated
-- and returns a table containing those units
-- Ignore any specifications prefixed with * if this is used
-- nil means use other specifications

--*generatedUnitType = unitType
-- The type of unit to be generated
-- can't be nil unless generateUnitFunction is used instead

--*giveVeteran = bool or nil
-- generated unit(s) given veteran status if true
-- nil or false means don't give vet status
-- if true, overrides copyVeteranStatus

--*copyVeteranStatus = bool or nil
-- generated unit(s) copy veteran status of generating unit if true
-- nil or false means don't give vet status

--*setHomeCityFunction = nil or function(generatingUnit)-->cityObject
-- determines what home city the spawned unit should have
-- nil means a home city of NONE

--*numberToGenerate = nil or number or thresholdTable or function(generatingUnit)-->number
-- if nil, generate 1 unit in all circumstances
-- if integer, generate that many units (generate 0 if number less than 0)
-- if number not integer, generate floor(number), and 1 more with
-- probability number-floor(number)
-- if thresholdTable, use remaining hp as the key, to get the number to create
-- if function, get the number as the returned value of the function

-- activate = bool or nil
-- Activates one of the generated units if true. If generateUnitFunction was used,
-- the unit at index 1 is activated, if index 1 has a value. (if not, any unit in
-- the list might be chosen)

The very last entry brings forward a change that must be made to our unit generation specification. Lua's activate unit command doesn't run the unit activation trigger, even though the active unit is changed. Therefore, we must do that manually. Hence,

<code>spawnUnit(generatingUnit, specificationTable)--> table of unitCreated</code>

becomes

<code>spawnUnit(generatingUnit,specificationTable,unitActivationCode)-->table of unitCreated</code>

Perhaps we will change it again later.

I've decided to try a different instructional technique for this section. Instead of writing the code and then going through it section by section, I've recorded a video of my coding and testing this module, and I attempt to explain some of the stuff that I do along the way.

I'm not sure of the value of the video. If you find that there seems to be little useful content relative to the time it takes to watch, then feel free to skip it and continue the lesson. I don't teach anything "new" in it, so you won't miss anything crucial. However, it should be pretty close to how programming Lua can actually happen in the "real world." While I did give some thought to how to write the module before I started, I do attempt to solve problems in real time, and make mistakes that are not discovered for a while (including one where I try to explain how I solve a problem and then not actually do a crucial part).

You can find the code [https://forums.civfanatics.com/threads/totpp-the-munitions-library.647910/ here]. Even if you decide not to watch the video, download the code and try testing some of the features based on the specification above. If you find any bugs, submit a fix (or at least report the issue).

The video can be found [https://youtu.be/XxPyNknGlAo here].

===A Unit Attack Bonus for Complementary Units in Square===

Something we might like to do is to give units an attack bonus if they attack from a square with some special unit, for example a "leader" unit. The [[Napoléon I]] scenario, for example, gives an attack bonus to units if a commander unit, such as Napoleon, is in the square when the unit is activated (the unit can subsequently move and still retain the bonus as long as no other unit is selected). We will now make a module providing the same functionality.

We first have to have a basic idea of how this functionality should work. When a unit is activated, the onActivateUnit event checks if the newly activated unit should get an attack bonus, based on the other units in the square. If the unit deserves an attack bonus, the corresponding unitType.attack entry is changed, and all the attack value of all other units is reset to the default value. If the activated unit also does not deserve an attack bonus, that value is also set to the default value.

This now leads us to some more possibilities. Should multiple bonus units lead to multiple bonuses or only apply the best one? For example, suppose a legion gets a bonus if an archer is also in the same square. Should two archers provide twice the bonus? Perhaps two archers should provide a larger bonus than one, but not twice as much. Perhaps a legion should also get a bonus if there is a catapult in the square, but that bonus should apply even if the maximum archer bonus is already achieved. It seems like perhaps there should be a "ranged unit" bonus, an "artillery unit" bonus and maybe a "cavalry" bonus which should all impact the legion's attack value. It's looking like we might end up demanding that a scenario creator make a big complicated table in order to use this functionality, even if they only have simple needs.

What we can do to alleviate this is to write a "simple" version of the event that is easy to use (and program), and also write a more complicated version that gives the expanded capability.

Specification Table for simpleAttackBonus

--simpleAttackBonusTable[activeUnit.type.id] ={[bonusUnitType.id]=bonusNumber}
--simpleAttackBonusTable.type = string
--if simpleAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if simpleAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
--if simpleAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- if simpleAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- if simpleAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
--simpleAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

The relevant first draft of the code is as follows:

<code>
local function simpleAttackBonus(activeUnit,simpleAttackBonusTable,defaultAttackTable)
-- reset all unit attack values
for unitTypeID,attackValue in pairs(defaultAttackTable) do
civ.getUnitType(unitTypeID).attack = attackValue
end
local unitBonusTable = simpleAttackBonusTable[activeUnit.type.id]
if not unitBonusTable then
-- unitBonusTable is nil (or false), so the active unit can't
-- get a bonus
return
end
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
local bestBonusSoFar = 0
for unit in activeUnit.location.units do
if unitBonusTable[unit.type.id] and unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
if bestBonusSoFar == 0 then
-- If no bonus unit is found, this will be true, so do nothing else
return
end
-- set the new attack and return
if string.lower(simpleAttackBonusTable.type) == "addBonus" then
activeUnit.type.attack = activeUnit.type.attack+bestBonusSoFar
return
end
local attackMultiplier = 1
if type(simpleAttackBonusTable.type) ~= "string" then
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
elseif string.lower(simpleAttackBonusTable.type) == "addpercent" then
attackMultiplier = (100+bestBonusSoFar)/100
elseif string.lower(simpleAttackBonusTable.type) == "addfraction" then
attackMultiplier = 1+bestBonusSoFar
elseif string.lower(simpleAttackBonusTable.type) == "multiplypercent" then
attackMultiplier = bestBonusSoFar/100
elseif string.lower(simpleAttackBonusTable.type) == "multiply" then
attackMultiplier = bestBonusSoFar
else
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
end
-- apply the bonus and round as appropriate
if type(simpleAttackBonusTable.round) ~= "string" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
elseif string.lower(simpleAttackBonusTable.round) == "up" then
activeUnit.type.attack = math.ceil(activeUnit.type.attack*attackMultiplier)
return
elseif string.lower(simpleAttackBonusTable.round) == "down" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier)
return
else
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
end
end
</code>

Now let us go over this section by section.

[[File:GetStartedWithLuaLesson6-07-AttackBonus1.jpg]]

The first thing we do is to reset all the attack values of all the unit types. That way, if a bonus existed for the last unit activated, that bonus no longer applies. If a unit type is not in the defaultAttackTable, then we don't have the information to reset the attack value anyway, so we can safely ignore it by using the pairs function to iterate over the table.

Now, we must find out if the newly activated unit deserves a bonus. For that, we get the table associated with the active unit's type. If the value is nil instead of a table, then the unit's type is not in the simpleAttackBonusTable, so there is no bonus to apply and the function returns.

If the unit is eligible for bonuses, we then check the units in the square to see if any bonuses actually apply. We've seen this kind of code before. If the unit in the stack can provide a bonus, and that bonus is better than the best bonus already found, the unit now provides the best bonus. All bonus types that we can have are better if they are larger, and we are not comparing between bonus types, so a simple numerical comparison will do. All bonuses are larger than 0 in our formulation, so 0 is a good starting value in the search.

If the best bonus so far is still 0, there is no bonus, so the function can return.

At this point, it occurs to me that when searching for the best bonus, we should exclude the active unit from the search. That way, you can have a "strength in numbers" bonus, for example. The relevant change to the code is:

<code>
for unit in activeUnit.location.units do
if unit ~= activeUnit and unitBonusTable[unit.type.id] and
unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
</code>

Next, consider

[[File:GetStartedWithLuaLesson6-08-AttackBonus2.jpg]]

Here, we apply the bonus that we've found. We use string.lower on simpleAttackBonusTable.type so that we don't have to worry about capitalization. That does, however, require a correction to "addBonus", since a lower case string will never be equal to that.

"addbonus" is the only type of bonus that is directly added to the existing attack value. All other bonus types are a form of multiplication. Since the addition is straightforward and doesn't require any rounding, the activeUnit's type attack value can be changed immediately, and the function execution ended with return.

When there is only one bonus being applied, all other types of bonus are different ways of expressing how to multiply the existing attack value to get a new one, so we simply convert to the appropriate multiplier, and provide an error message if the type of bonus is not one of the valid possibilities.

Finally, we round the attack value to an appropriate integer (since unit attack values must be integers), change the attack value of the active unit's type, and return to end the function execution.

Now, we integrate into events.lua by using

<code>
attackBonus = require("attackBonus")
</code>

The relevant integration code for events.lua is
<code>
local defaultAttackValueTable = {[unitAliases.legion.id]=4}
local simpleAttackBonusTable ={}
simpleAttackBonusTable.type = "addbonus"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=3,[unitAliases.musketeer.id]=4}

local function doOnActivation(unit,source)
munitions.payloadRestrictionCheck(unit,munitionSpecificationTable)
attackBonus.simpleAttackBonus(unit,simpleAttackBonusTable,defaultAttackValueTable)
end
</code>

We can check that the bonus is being applied correctly by checking the Civlopedia entry for legion and looking at the attack value. The following cases must be tested (remember that activating a unit from the city screen doesn't run the onActivation event, so activate from the map).

Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (7 attack)
Legion activated with musketeer, but no archer (8 attack)
Legion activated with archer and musketeer (8 attack)
Legion activated with 2 archer, no musketeer (7 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

I recommend making a stack for each of these cases and activating them one by one.
To facilitate the test, add the following line to doOnActivation

<code>
civ.ui.text(tostring(unit.type.attack))
</code>
You will want to comment out this line after testing.

Next, change simpleAttackBonusTable to do "addpercent"
<code>
simpleAttackBonusTable.type = "addpercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=30,[unitAliases.musketeer.id]=70}
</code>

With no rounding set, standard rounding is used
Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)
Legion activated with archer and musketeer (7 attack)
Legion activated with 2 archer, no musketeer (5 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

These numbers test both rounding up and rounding down.

Now, use
simpleAttackBonusTable.round="up"
Legion activated with archer, but no musketeer (6 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next,
simpleAttackBonusTable.round="down"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (6 (6.8) attack)

simpleAttackBonusTable.round="standard"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next, we test "addfraction". Since we've tested all the rounding options, we don't have to do that again.

<code>
simpleAttackBonusTable.type = "addfraction"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=0.3,[unitAliases.musketeer.id]=0.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiplypercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=130,[unitAliases.musketeer.id]=170}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiply"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Before we finish, we should test a legion bonus for the legion.
<code>
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.legion.id]=2,[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>

Legion alone should have 4 attack.
A second legion on the square should provide 8 attack instead.

Now, let us try to formulate a more complicated bonus system. One thing we mentioned is that we'd like the ability to get bonuses from multiple units, and to be able to get bonuses from different "classes" of units (like "artillery," "cavalry," and "ranged attackers." Something else we might want to do is to allow different kinds of bonuses. That is, maybe some units should provide a fixed +2 to any unit receiving the bonus, so that it is better at improving units with a low attack value, while other units should provide a percentage bonus (making them better at supporting units with an already high attack value). It turns out that both of these ideas are not too difficult to implement individually, but that trying to implement them together makes it problematic to find the best bonus.

Let us implement a bonus system with multiple categories but only one bonus type. In our specification, we will first specify a data type called "bonusCategory." It is still just a table (though we could add a metatable if we wanted), but it will help us make our specification clearer.

<code>
-- A "bonusCategory" is a table
-- bonusCategory = {[bonusUnitType.id]=bonusNumber, maxBonusUnits=integer or nil, nextBonusValue = fraction or nil}
-- In a bonusCategory, the value for bonusUnitType.id tells what the base bonus for that unit type is,
-- maxBonusUnits is the maximum number of units that can provide a bonus in this category,
-- nextBonusValue tells how much to reduce the bonus for each subsequent unit,
-- e.g. nextBonusValue = 0.7, and 5 units, which each have a bonusNumber=1
-- The total bonus is 1(0.7)^0+.7+(.7)(.7)+(.7)^3+(.7)^4 = 1+.7+.49+.343+.2401=2.7731
-- (which would be rounded as specified)
-- nil means nextBonusValue=1
--
-- If a unit type is in two bonus categories for the same unit, there is no guarantee that the
-- best bonus will be achieved
</code>

So, the bonus category is indexed by unitType id numbers for units that can give a bonus, and the corresponding bonus. It also specifies the maximum number of units that can give a bonus, and a number that governs how to reduce a bonus for extra units. That way, there can be diminishing returns for bonuses.

Next, we look at the specification for the categoryAttackBonusTable

<code>
--categoryAttackBonusTable[activeUnit.type.id] =table of bonusCategory
--categoryAttackBonusTable.type = string
--if categoryAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if categoryAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
-- for multiple unit bonuses, add up all the percents, then compute the bonus
-- i.e. 50% bonus and 50% bonus is 100% bonus, not 125%
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 50% bonus units become 50% + 25%
-- so attack 6 --> 10.5
--if categoryAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- for multiple unit bonuses, add up the fractions, then compute the bonus
-- i.e. .5 bonus and .5 bonus is 1+.5+.5= 2x bonus, not 2.25x
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 .5 bonus units become .5+.25
-- so attack 6 --> 10.5
-- if categoryAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- bonuses are multiplied together, i.e. 150% and 150% yields 225% of original value
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 100, i.e. nextBonusValue=.5 2 150% bonuses become 150% and 125%
-- so attack 6 --> 11.25
-- if categoryAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
-- bonuses are multiplied together, i.e. 1.5 and 1.5 yields 2.25x
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 1, i.e. nextBonusValue=.5 and two 1.5 bonuses become 1.5 and 1.25
-- so attack 6 --> 11.25
--categoryAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

-- If the active unit can get a bonus, go through each category and compute the bonus for that category.
-- Then, combine the bonuses for all categories to get the overall bonus, and round the result
</code>

With the bonusCategory defined, the value of the unit indices of categoryAttackBonusTable become easy to define. Most of the specification is showing what exactly the different bonus categories mean, so the end user can use them properly. It's not strictly necessary to offer so many choices to the end user on how to specify data, but it can be more convenient.

Here is the actual code (before testing) to implement this more general version of attack bonuses.

<code>
-- HELPER FUNCTION
-- findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable) --> number or false
-- usedUnitTable is indexed by the i.d. number of units, and if the value for a unit is true,
-- then it has already been used for a bonus (and, so, is not eligible)
-- The function returns the bonus (before nextBonusValue is applied) if there is one, and marks the
-- unit as used in the usedUnitTable
-- returns false if no unit qualifies
local function findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable)
local bestBonusSoFar = 0
local bestUnitSoFar = nil
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
for unit in tile.units do
if not usedUnitTable[unit.id] and bonusCategory[unit.type.id]
and bonusCategory[unit.type.id] > bestBonusSoFar then
bestUnitSoFar = unit
bestBonusSoFar = bonusCategory[unit.type.id]
end
end
if bestUnitSoFar then
usedUnitTable[bestUnitSoFar.id] = true
return bestBonusSoFar
else
return false
end
end

-- HELPER FUNCTION
-- computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
-- Computes the bonus that the active unit will receive from this category, taking into
-- account the type of bonus for the table
local function computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
local bonusThusFar = nil
if bonusType == "multiply" then
bonusThusFar = 1
elseif bonusType == "multiplypercent" then
bonusThusFar = 100
else
bonusThusFar = 0
end
local bonusDiscount = 1
for i=1,(bonusCategory.maxBonusUnits or 10000) do
local currentBonus =findBestBonusInUnitStack(activeUnit.location,bonusCategory,usedUnitTable)
if not currentBonus then
-- no more valid bonuses for this category
break
end
if bonusType == "multiply" then
bonusThusFar = bonusThusFar*((currentBonus-1)*bonusDiscount+1)
elseif bonusType =="multiplypercent" then
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
else
bonusThusFar = bonusThusFar+currentBonus*bonusDiscount
end
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
end
return bonusThusFar
end

local function categoryAttackBonus(activeUnit,categoryAttackBonusTable,defaultAttackTable)
local bonusInfoTable = categoryAttackBonusTable[activeUnit.type.id]
if not bonusInfoTable then
-- unit doesn't get a bonus
return
end
-- keep track of bonuses already computed
local bonusResultsTable = {}
-- keep track of units that have already been "used" for a bonus
local usedUnitTable = {[activeUnit.id]=true}
for index,bonusCategory in pairs(bonusInfoTable) do
bonusResultsTable[index]=computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
end
-- compute the bonus
local bonusType = string.lower(categoryAttackBonusTable.type)
local resultAttackBeforeRounding = nil
if bonusType == "multiply" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "multiplypercent" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult/100
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "addbonus" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack+bonus
elseif bonusType == "addfraction" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
elseif bonusType == "addpercent" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+(bonusResult/100)
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
else
error("categoryAttackBonus: categoryAttackBonusTable.type is not a valid value.")
end
-- apply the bonus and round as appropriate
local roundType = categoryAttackBonusTable.round
if type(roundType) ~= "string" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
elseif roundType == "up" then
activeUnit.type.attack = math.ceil(resultAttackBeforeRounding)
return
elseif roundType == "down" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding)
return
else
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
end
end
</code>

The two helper functions for computeCategoryBonus are only used once each in the code, so making them helper functions does not help us re-use code. However, what it does do is to break down the function design process into smaller tasks, which are each more manageable to complete. If you're trying to keep track of too many things in your program, try writing a few helper functions to handle individual tasks. We'll look at the helper functions when we actually arrive at them in the code.

[[File:GetStartedWithLuaLesson6-09-CategoryAtkBonus1.jpg]]

If there is no entry in the categoryAttackBonusTable or the active unit's type, then the function returns without doing anything further.

The bonusResultsTable keeps track of the total bonus from each category, so they can be added or multiplied together after all the category bonuses are applied. The usedUnitsTable keeps track of units that are no longer eligible to contribute to a bonus (such as if they have already contributed), and we initialize it with the active unit, so that it doesn't provide a bonus to itself.

The for loop computes the bonus for every category, and stores the value in the bonusResultsTable, for use later.Now, let us look at the helper functions.

First up is findBestBonusInUnitStack

[[File:GetStartedWithLuaLesson6-10-CategoryAtkBonus2.jpg]]

This basically does what it says in the name. For a bonusCategory, it finds the unit in the tile that provides the best bonus, and has not already provided a bonus elsewhere. If there is no qualifying unit, false is returned. If there is, that unit's bonus is returned, and the unit's id is entered into the usedUnitTable, so that unit can't provide another bonus for the active unit. We've searched for the best of something before, so there is little need to go over it again.

Next is computeCategoryBonus

[[File:GetStartedWithLuaLesson6-11-CategoryAtkBonus3.jpg]]

Here, we're computing the bonus for the entire bonusCategory. We need the bonus type in order to know what kind of math to do. The math itself is not very interesting. We also initialize the bonusDiscount, which keeps track of the fraction of the next unit's bonus that will actually be applied.

Next, we enter a for loop that will run one time for each possible bonus that there can be in a bonus category. If bonusCategory.maxBonusUnits is nil, then we set an arbitrary limit of 10000 units, which is very unlikely to happen in practice.

At each iteration of the loop, the best available bonus in the stack is found. If no unit was eligible to provide a bonus, then the current bonus is false, and the "break" command is issued. Break immediately exits the current loop. So, our program doesn't run 10000 loops if there is no maximum number of bonus units, it just breaks at an appropriate time.

After the bonus is found, it is added to or multiplied with the bonus already found. The bonus computed in this way will be the largest possible, since the bonus provided does not depend on the other units chosen (so we don't have a situation where "catapult" and "rock" are both useless, but "catapult" and "rock" chosen together are best). Also, since the best bonus is chosen first, the smallest bonus discount applies to it, so the cost imposed by the discounting is smallest.

Finally, we update the bonusDisount. Here, I notice a problem in the code as written, since bonusCategory.nextBonusValue is allowed to be nil. Replace
<code>
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
</code>
with
<code>
bonusDiscount = bonusDiscount*(bonusCategory.nextBonusValue or 1)
</code>
so that if there is no nextBonusValue, a default of 1 is used, and the bonusDiscount stays at 1 (i.e. no discount is applied).

We return to categoryAttackBonus to see

[[File:GetStartedWithLuaLesson6-12-CategoryAtkBonus4.jpg]]

From here, we combine the bonuses stored in bonusResultsTable, the exact way of doing so being dependant on the type of bonus involved. The math itself isn't very interesting, and doesn't seem all that likely to come up in this exact form elsewhere. If you need help with the mathematical details of some event you want to write, ask in the forums. There's a good chance someone has the skills to help you solve your specific problem.

For every type of bonus, the result is stored in resultAttackBeforeRounding, so that variable can be rounded up or down as specified by the rounding type.

Here, I notice another error. We should restrict the attack value for a unit to not exceed 98. We can do that with a math.min(value, 98).

Now, we need to test the various aspects of the attack bonus program, so we need an appropriate table
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addbonus"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=2,[unitAliases.chariot.id]=4,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=2,[unitAliases.musketeer.id]=4,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Also, comment out the old attack bonus line, and put in a new one
<code>
attackBonus.categoryAttackBonus(unit,categoryAttackBonusTable,defaultAttackValueTable)
</code>

Expected Test Results when type is "addbonus"
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

Already, we find a problem. Although there were no syntax errors to fix, I forgot to reset unit attack values. So, very quickly, the legions keep gathering extra attack values when they are activated (since the base attack is not reset to 4). Since this is happening anyway, I'll test the 98 attack value maximum. That appears to work, at least in the case of no specified rounding.

Cut and paste the appropriate lines from the simpleAttackBonus to the categoryAttackBonus, and save.

With that bug fixed, everything works as expected.

Next, we change the categoryAttackBonusTable to

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addpercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=50,[unitAliases.chariot.id]=100,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=50,[unitAliases.musketeer.id]=100,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>

Expected Test Results when type is "addpercent". These are the same, since adding we're adding percentages of the same base value of 4. So a value of 2 is the same as adding 50% of 4.
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

The results are the same.

Similarly,

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addfraction"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=.50,[unitAliases.chariot.id]=1.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=.50,[unitAliases.musketeer.id]=1.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

We'll have to do some new calculations, now, since multiply and multiplyfraction give different results than the various adding formulations.

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiply"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=1.50,[unitAliases.chariot.id]=2.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=1.50,[unitAliases.musketeer.id]=2.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Finally, we use multiplyPercent, and check for the same results
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=150,[unitAliases.musketeer.id]=200,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Quickly, I find that if a bonus applies, that bonus makes the attack value of a legion 98. I failed to multiply percents correctly in computeCategoryBonus. The Line
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
</code>
Is changed to
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+100)/100
</code>

Finally, Change archer bonus to 110 and musketeer bonus to 120 (so a unit will make a legion have 4.4 and 4.8 value before rounding), and test the rounding options. You will find they all work.

At the moment, we don't have a way to mix different types of bonuses. As said earlier, we might want this so that some units can be better at giving bonuses to low attack units than to high attack units, while others give a percentage bonus to everything. We could now write a bonus system that allows for multiple types of bonuses. However, the current bonus system allows for the bonus to change per unit. This means that we can, for example, convert a +2 attack bonus to a plus 100% bonus for a unit with 2 attack, and a plus 50% bonus for a unit with 4 attack. In the case of the multiplied bonuses, this will make the bonus more powerful if there is more than one. That is, 2 attack, +2 twice is 6, but if +2 is changed to x2, then the multiplied bonus brings the attack up to 8. However, this seems like it would be a relatively unlikely problem, and there are other things this code can't handle, so we'll let someone else make the code if they actually need it.

So, what we'll do is write a function that will change all appropriate entries in the categoryAttackBonusTable to reflect a different value. Hence,

<code>
-- plusFixed(unitType,number,categoryAttackBonusTable) --> void
-- changes the bonus given by unit type to any unit to be equivalent
-- to adding number to that unit's attack power
</code>

Here, an issue with tables arises. It is very likely that when someone defines their cateogryAttackBonusTable, they'll define it something like this
<code>
local rangeBonusCategory = {[unitAliases.archer.id]=.25,[unitAliases.musketeer.id]=.5}
local bonusTableForInfantry = {rangeBonusCategory}
local cABT = {type="addfraction"}
cABT[unitAliases.phalanx.id]=bonusTableForInfantry
cABT[unitAliases.legion.id] = bonusTableForInfantry
</code>
However, this means that both <code> cABT[unitAliases.legion.id] </code> and <code> cABT[unitAliases.phalanx.id] </code> actually refer to the same piece of memory, and changing cABT[unitAliases.legion.id][1][unitAliases.archer.id] will also change the value at cABT[unitAliases.phalanx.id][1][unitAliases.archer.id]. This is because of the way lua tables are designed. This design can be useful, for example it allowed us to make changes to usedUnitsTable in the last function without having to copy the table, make changes to the copy of the table, and then replace the original table with that copy as a return value. However, it also requires us to be careful when we make changes to entries in tables. In this case, we'll simply copy the table and all its sub values into a new table.

The code to do this is given by
<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

We will explain this code in the next section, since it involves a programming technique which we haven't discussed before.

For now, we analyze plusFixed:

<code>
-- plusFixed({[unitType1.id]=fixedBonus,[unitType2.id]=fixedBonus},categoryAttackBonusTable) --> void
-- changes the bonus given by unitTypeI.id to a unit to be equivalent to
-- to adding number to that unit's attack power. If the unit doesn't receive a bonus
-- from the unitType, then it won't after applying plusFixed.
-- The value of the existing bonus is ignored.

local function plusFixed(fixedUnitBonusTable,categoryAttackBonusTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
for bonusReceivingUnitTypeID,bonusTable in pairs(categoryAttackBonusTable) do
-- replace bonusTable with an equivalent table that is not referened
-- anywhere else, so that changes to it can be made without impacting
-- data elsewhere
categoryAttackBonusTable[bonusReceivingUnitTypeID] = duplicateTable(bonusTable)
-- make bonusTable refer to the "current" bonus table for the unit type
bonusTable =categoryAttackBonusTable[bonusReceivingUnitTypeID]
-- For each unit type in the fixedUnitBonusTable, check if any bonus category
-- in the bonusTable corresponds to it. If so, make the change
for bonusGivingUnitTypeID,fixedBonusValue in pairs(fixedUnitBonusTable) do
-- get the attack of the unit type
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
-- in each bonus category, check if the giver's unit type id is there,
-- if so, change to the correct attack
for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
if bonusCategory[bonusGivingUnitTypeID] then
-- change the bonus appropriately
if bonusType == "addbonus" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue
elseif bonusType == "addpercent" then
bonusCategory[bonusGivingUnitTypeID]=100*fixedBonusValue/baseAttack
elseif bonusType == "addfraction" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue/baseAttack
elseif bonusType == "multiplypercent" then
bonusCategory[bonusGivingUnitTypeID]=100*(fixedBonusValue+baseAttack)/baseAttack
elseif bonusType == "multiply" then
bonusCategory[bonusGivingUnitTypeID]=(fixedBonusValue+baseAttack)/baseAttach
else
error("pluxFixed: categoryAttackBonusTable.type does not have an acceptable value.")
end
end
end
end
end
end
</code>

[[File:GetStartedWithLuaLesson6-13-plusFixed1.jpg]]

As before, we save the bonusType in lower case, since we'll be using it a lot later. Next, we open a for loop, where the index is the id of the unit type receiving the bonus, and the value is the bonus table for that unit type. Next, we duplicate the bonus table, so that we have a table we can change without impacting anything elsewhere, and we store the duplicated table in categoryAttackBonusTable in place of the original bonusTable for the current bonus receiving unit id. Next, we assign this duplicated table to the variable bonusTable, so we can refer to it later in the code.

[[File:GetStartedWithLuaLesson6-14-plusFixed2.jpg]]

We now perform the following actions for each unitType.id and corresponding fixedBonusValue submitted in the fixedUnitBonusTable.

First, get the attack of the bonus receiving unit, since we'll need that in order to customize the bonus. Next, check each bonus category in the bonus table. If the bonus category has the current unitTypeID as a key, then replace the existing value with a bonus equivalent to adding a fixed value to the receiving unit's attack.

That's all that must be done, so end all the loops.

Now we test the function.

Add unitAliases.phalanx = civ.getUnitType(3) to the appropriate file.

<code>
defaultAttackValueTable[unitAliases.phalanx.id]=1
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,
nextBonusValue=0.5,maxBonusUnits=1}
local rangeBonusCategory = {[unitAliases.archer.id]=125,[unitAliases.musketeer.id]=150,
nextBonusValue=0.75,maxBonusUnits=1}
local standardBonus = {cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable[unitAliases.legion.id]=standardBonus
categoryAttackBonusTable[unitAliases.phalanx.id]=standardBonus
categoryAttackBonusTable.round="up"
attackBonus.plusFixed({[unitAliases.chariot.id]=2,[unitAliases.musketeer.id]=2},
categoryAttackBonusTable)
</code>
The chariot and the musketeer individually should each add 2 to both a phalanx and a legion,
so the phalanx should have an attack of 3, and the legion should have an attack of 6, if one bonus
is applied.

Since the bonus type is multiplypercent, together the phalanx would have an attack of 9, and the legion will also have an attack of 9.

In testing, we quickly get this error
<code>
You should see this in lua console if this worked
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: bad argument #1 to 'getUnitType' (number expected, got string)
stack traceback:
[C]: in function 'civ.getUnitType'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>

At line 356, which is

<code>
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
</code>

This must mean that bonusReceivingUnitTypeID is not a number. This is because we're looping over categoryAttackBonusTable, and that table has a couple of entries that are not integers ("type" and "round"). Therefore, we have to insert code to deal with this eventuality.

The simplest way is to put everything in the loop body into an if statement, so that it only runs when bonusGivingUnitTypeID is actually a number. You should be able to do this without detailed instructions, so do so (hint: use type function).

The next error is
<code>
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: bad argument #1 to 'pairs' (table expected, got nil)
stack traceback:
[C]: in function 'pairs'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>
<code>
360 for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
</code>

Here, we have a nil value for bonusTable. This turns out to be an error in duplicateTable. When I duplicated the table, I forgot to return that table. That is, both the if and else statement in that function need a return command, and I forgot to add <code> return duplicatedTable </code> in the if portion. Add this to the duplicate table function.

After this, our predictions are true. Testing the other types of bonus is left as an assignment. You can find the completed code [https://forums.civfanatics.com/threads/totpp-attack-bonus-library.648093/ here].

===Recursive Functions===

Let us return to the duplicateTable function. Recall that in the last section we added a line to it, so we'll restate it here:

<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
return duplicatedTable
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

[[File:GetStartedWithLuaLesson6-16-duplicateTable.jpg]]

The interesting thing about duplicateTable is that it invokes duplicateTable within its code. When we copy the key-value pairs into the new table, we run duplicateTable on the value. If the value is not a table, then we are in the else case, and the value is immediately returned to be inserted into the duplicated table. If the value is a table, that table is duplicated before anything else is done.

Let us look at a simple example of a recursive function, the factorial function N!. In lesson 3, we discussed the factorial function in the context of loops. Since N!=N*(N-1)*(N-2)*...*3*2*1, we can give another definition of N!:
N!=1 if N = 1
N!=N*(N-1)! if N > 1
Or, using the convention that 0!=1, we can state
N!=1 if N = 0
N!=N*(N-1)! if N > 0

The case where N =1 or N=0 is called the "base case." If we keep substituting N! as N*(N-1)!, then we won't go on forever, because we will eventually reach a point where N=0, and N! can be substituted as 1 instead of N*(N-1)!. As long as there is a base case, our program will eventually reach the base case(s), and begin "completing" evaluation.

<code>
function factorial(N)
if N>0 then
return N*factorial(N-1)
else
return 1
end
end
print(factorial(5))
print(factorial(6))
</code>

Run this in code in the lua demo website, or using the TOTPP lua interpreter.

Returning to our duplicateTable function, the base case is any time a table value is not itself a table. When that happens, the recursion "chain" ends, and everything can evaluated.

Although is shouldn't be a problem in this particular case, it should be noted that it is possible for there to not be a "base case" in the recursion style: if table, recur, if not return a value. Consider the following table system

<code>
a={}
b={[1]=a}
a[1]=b
</code>
In this case, the code would never end.

It is possible that even if the code could "theoretically" execute to completion, you run out of memory before that. This is called a "stack overflow," and if it occurs, you will have to think of an alternate way to solve your problem. It will probably be best to ask for help in that case (and it might be useful to provide others with an example of a problem that results in a stack overflow), but you might also look into "tail recursion", including http://www.lua.org/pil/6.3.html .

===Conclusion===

With the skills covered in this chapter, you now have the tools to split a large events file into multiple files that are more manageable. You also have the basics for how to write re-useable modules for your events, so that your work can be used by others. Remember that if someone else uses your implementation of a feature, they will spend much less time coding and testing it, allowing them to either finish the scenario sooner, or to introduce some other feature. So, it might very well pay to spend at least a little effort making your code into a reusable module. Perhaps you have an idea for a cool scenario mechanic, but don't have a scenario for it (or don't want to take the time to make it). If that's the case, just make the module and test it in a "toy" scenario (like Classic Rome) so that it can be used more or less "off the shelf" when someone needs it.

Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files

2019-07-26T16:19:03Z

Prof. Garfield: /* Two Simple Examples */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This Lesson is under construction.

===Introduction===

In this lesson, we will take a look at how to split the code for a scenario's events into multiple files. There are several reasons to consider doing this.

The first reason is simply to organize your work. If you have a series of complicated events, the events.lua file can become very large very quickly. Once your events.lua file has thousands of lines of code in it, it may not be very obvious where the best place is to put that next helper function, or where to implement the function that runs a complicated event. Sometimes even finding the piece of code that has to be changed can be a bit of a hassle. In Over the Reich, I sometimes search for the associated civ.scen line, and then search for the exact name of the function I need. Occasionally, there may even be more searching to find what I actually have to change. With multiple files, it becomes easier to find things.

Another aspect of using multiple files is that you can make certain changes without worrying about breaking things elsewhere. If myBigComplicatedFunction relies on aModestHelperFunction for a certain part of its functionality, and a change to myBigComplicatedFunction also requires a change to aModestHelperFunction, you have to make sure that nothing else in your code also uses aModestHelperFunction, or, if something else does depend on it, that aModestHelperFunction either still provides the original functionality, or that all other functions that use aModestHelperFunction are suitably modified. If myBigComplicatedFunction is defined in its own lua module, then you don't have to worry about forgetting that aModestHelperFunction was used elsewhere, since it can't be accessed outside the module unless you specifically allow it to be.

A second reason to split events code into multiple files is to facilitate collaboration. If all of the events are in a single file, then only one person can make changes to the file at a time. If one partner starts changing an event, but has to do something else before finishing, everyone waits on one person's delay. However, if most aspects of the scenario are separated into individual files, everyone can work on his or her own piece of the puzzle without depriving others of the opportunity to work at that time.

A third reason to split events into multiple modules is to facilitate reusing code. If everything required to implement an event is in its own file (or files), it becomes much easier for other creators to use your functionality in their scenario. Since everything they need is already in one place, they don't have to find every last helper function, or concern themselves with naming conflicts.

===Two Simple Examples===

Let us look at the top of the events.lua file. You can get the version that I started lesson 6 with [https://forums.civfanatics.com/threads/totpp-get-started-with-lua-events.636192/#post-15212114 here].

[[File:GetStartedWithLuaLesson6-01-DefaultRequire.jpg]]

We get code from other files by using the command <code>require</code> along with a string specifying the file name (except for the .lua extension). At the moment, we can only get code stored in the lua folder in the Test of Time directory. This is inconvenient if we're trying to distribute a scenario, since installing a scenario would require moving certain files to the lua directory, and those file names might conflict. Instead, we need to tell the Lua interpreter to search in the same folder that the events.lua folder is in.

To do this, we need the following code:
<code>
local eventsPath = string.gsub(debug.getinfo(1).source, "@", "")
local scenarioFolderPath = string.gsub(eventsPath, "events.lua", "?.lua")
if string.find(package.path, scenarioFolderPath, 1, true) == nil then
package.path = package.path .. ";" .. scenarioFolderPath
end
</code>

You can probably cut and paste this code before the require lines in your events.lua file and not worry about how it works. However, I'll provide a brief explanation for reference.

The first line stores the location of the of the current file as a string in eventsPath.

The second line replaces events.lua in the eventsPath with ?.lua, which will tell the Lua interpreter to look for .lua files in the current directory (that is to say, the directory with the events.lua file).

The if statement adds scenarioFolderPath to the places for the Lua interpreter to search for code, if that directory is not already in the search path. Since the search path is kept active by the Lua interpreter, it will not be necessary to repeat these lines of code in every file that performs a require action as long as you are running the file as part of events. If you are writing some other kind of code, you will need to substitute "events.lua" with the name of the file with the code you are running. Note that for some reason, events.lua is always provided in lower case. However, for use in other situations, debug.getinfo(1).source uses the correct case for event files. I have only briefly tested this, so you may have to do some testing yourself if this situation comes up (or ask for help in the forums).

Now that we've told Lua where to look for our extra code, we can begin moving code to other files. Think of require as telling Lua to run the entire contents of another file as a function. We can then assign a value to whatever that file returns, which will usually be a table. A couple of examples will clarify.

For our first example, we will move our scenario's parameters to a separate file, and access it via require. This may not seem worthwhile in this example, but tables like this can get large in a hurry. At the time of writing, Over the Reich has over 100 lines of parameters ("specialNumbers"), and parameters are something that a designer might like to play with while collaborators make other implementations. Also, parameters will have to be referenced by other parts of the code, and a file that is required by events.lua cannot, in turn, require events.lua in order to get information. That means that we'll have to keep our parameters in a separate file anyway.

Cut the parameters table definition and paste it into a new file, classicRomeParameters.lua. For the last line, write
<code>
return parameters
</code>

Now, Near the top of events.lua, where the existing require lines are, add the eventsPath code from above and also the line
<code>
local parameters = require("classicRomeParameters")
</code>

[[File:GetStartedWithLuaLesson6-02-RequireParameters.jpg]]

Open the classicRome scenario and test out a couple of events to make sure everything is the same.

We might find it convenient to put a few tables into the same file. For this, we will simply return a table containing these tables, and give each table a name in the events.lua file.

Create a file classicRomeAliases.lua and move all the "aliases" tables to that file. Also move the getCityAt function.

At the bottom of the file, put the following lines:
<code>
return {
unitAliases=unitAliases,
tribeAliases=tribeAliases,
tileAliases=tileAliases,
cityAliases=cityAliases,
textAliases=textAliases,
terrainAliases=terrainAliases,
improvementAliases=improvementAliases,
}
</code>

Then, add the following lines to events.lua (in the require section)
<code>
local aliases = require("classicRomeAliases")
local unitAliases,tribeAliases,tileAliases,cityAliases,textAliases,
terrainAliases,improvementAliases=aliases.unitAliases,aliases.tribeAliases,
aliases.tileAliases,aliases.cityAliases, aliases.textAliases,aliases.terrainAliases,
aliases.improvementAliases
</code>

Here, our classicRomeAliases module is returning a table with our "alias" tables. We then assign the entries in this returned table to local variables with the desired names. Here, I use multiple variable assignment, which I don't believe I've used before (even though Lua allows it), but these could just as simply have been assigned line by line.

[[File:GetStartedWithLuaLesson6-03-RequireAliases.jpg]]

Now, let us move the legion plundering code into its own file, which we'll call plunder.lua. First, copy over the legionPlunder function, and paste it near the bottom of the new file.

Now, let us go through the code of this function, and figure out what else we need in our plunder.lua module.

The very first part of the function is a check against unitAliases.legion. This means we need the unitAliases table, and so we copy the aliases require code to the top of plunder.lua. We don't need the path information, since that will be added in events.lua.

A few more lines down, we find that the function cityRadius is also used in legionPlunder. Therefore, we move that over as well. We also need the plunderValue function, so copy that over as well.

Next, we check if cityRadius relies on anything, but it doesn't.

Proceeding to plunderValue, we find that it relies on the parameters table, so require that as well. The function plunderValue does not appear to depend on anything else, so we're done moving functionality. If we missed something, the Lua interpreter will complain at some point anyway.

Next, we require the plunder module in events.lua, with the following line:

<code>
local plunder = require("plunder")
</code>

Next, for each of the functions in plunder.lua, we check if it is used somewhere in events.lua. We can do this by searching. plunderValue isn't used anywhere, so we're done with that. City radius is used. At the bottom of plunder.lua, we begin our return table, and have
<code>
return {
cityRadius=cityRadius,
}
</code>

Then, in events.lua, we replace the ocurance of cityRadius with plunder.cityRadius. Alternatively, we could have put
<code>
local cityRadius=plunder.cityRadius
</code>
after the line requiring plunder.

Similarly, for legionPlunder, we add <code>legionPlunder=legionPlunder</code> to the table that plunder.lua returns, and pre-append plunder. to legionPlunder in the one location where it occurs.

Now, we test the legion plunder function and the press 4 generate archers function to make sure everything works.

[[File:GetStartedWithLuaLesson6-04-RequirePlunder.jpg]]

===Working With a Library===

In programming terms, a "library" is a collection of code that can provide some specified functionality to a programmer without that programmer having to modify the code in the library. Thus far, you have been using the "civ" library to interact with the game, and there has been no need modify it in order to use it in our own events. (Unfortunately, in the case of the civ library, we don't actually know how to modify it.) This is in contrast to much of the code we have written thus far. For example, the code we wrote last lesson to make Selucid elephants attack Egypt is highly specific. You couldn't just cut and paste that code, change the argument of a single function, and get your own goto event. It is still a good example for how to write a goto event, but a user would still have to actually write the event.

If you plan to write some functionality for your scenario that others might find useful, it is worth spending a little extra effort to see if you can write that functionality in a form that will allow others to use it with minimal effort. If you can, then a little extra work on your part might save someone else the trouble of re-inventing the wheel, and allow them to complete their project sooner, or to work on some new feature for you to enjoy. Unfortunately, the Lua scenarios that have been completed at the time of writing haven't been that good at creating re-usable code, at least in part since we were all getting used to Lua. This will hopefully be improved in the future.

For now, we're going to look at a library which is called the General Library (unless someone comes up with a better name) and which can be found [https://forums.civfanatics.com/threads/totpp-the-general-library.647583/ here]. The purpose of this module is to provide relatively simple functionality that probably shouldn't be implemented every time it is needed. This is useful for our purposes, since we can look at relatively self contained and simple functions for our first examples. We'll create a library for generating munitions later.

This library would be used by invoking the line

<code>
local gen = require("generalLibrary")
</code>

If you wanted to make these functions available to the console for testing purposes, you would simply omit the local, thereby making gen a global variable.

Let us now take a look at a function provided by the General Library <code> gen.hasIrrigation(tile)-->boolean</code>. The very first line references the helper function <code> toTile(tile or table)-->tile</code>, so let us include that code, and look at it first.

<code>
-- toTile(tile or table)-->tile
-- gen.toTile(tile or table)-->tile
-- If given a tile object, returns the tile
-- If given coordinates for a tile, returns the tile
-- Causes error otherwise
-- Helper Function (provided to this library as toTile and gen.toTile)
local function toTile(input)
if civ.isTile(input) then
return input
elseif type(input) == "table" then
local xVal = input[1] or input["x"]
local yVal = input[2] or input["y"]
local zVal = input[3] or input["z"] or 0
if type(xVal)=="number" and type(yVal)=="number" and type(zVal)=="number" then
if civ.getTile(xVal,yVal,zVal) then
return civ.getTile(xVal,yVal,zVal)
else
error("Table with values {"..tostring(xVal)..","..tostring(yVal)..
","..tostring(zVal).."} does not correspond to a valid tile.")
end
else
error("Table did not correspond to tile coordinates")
end
else
error("Did not receive a tile object or table of coordinates.")
end
end
gen.toTile = toTile

-- gen.hasIrrigation(tile)-->boolean
-- returns true if tile has irrigation but no farm
-- returns false otherwise
function gen.hasIrrigation(tile)
tile = toTile(tile)
local improvements = tile.improvements
-- irrigation, but no mining, so not farmland
if improvements & 0x04 == 0x04 and improvements & 0x08 == 0 then
return true
else
return false
end
end
</code>

[[File:GetStartedWithLuaLesson6-05-HasIrrigation.jpg]]

Let us begin by looking at the function <code>toTile</code>. The purpose of this function is to allow other functions to accept tile coordinates in a table instead of an actual tile object. The function tries to be reasonably permissive in the coordinates it will accept, allowing both integer indices and lowercase string indices, and by assuming that a missing z value corresponds to map 0. The function also tries to give reasonably helpful errors.

This brings up something that should be considered when making reusable code: what to do if you don't get values you were expecting. One option is to throw an error and bring up the Lua console. This is good for scenario creators, so they know something is wrong, but not so great for end users because the error stops the rest of the event from happening, should the mistake slip through playtesting.

The other option is for the code to fail silently, and try to do what it can. This is the way the old Test of Time macro system often fails. If Civ II doesn't "understand" the event, it just doesn't happen, and doesn't bother the player with the error. This means that the scenario will still mostly work, but it is harder to catch issues during playtesting. Sometimes, this means doing something "sensible" if the input isn't of the expected type, and might make the code easier to write, since you don't have to handle inputs differently.

A third option is to write your code such that both things can be done. At the top of your code, you put in a variable named "debugMode" or something, and make all the functions throw errors when true, and fail silently when false. Then you playtest with debugMode set to true, and release with debug mode set to false. However, this means extra work in writing your code and you also have to test everything with debug mode off.

For toTile, I went with the fail with error option, since that will allow every function that uses toTile to assume it is receiving proper data. It also seems unlikely that people will be regularly trying to check tiles that don't exist or have tables with tiles and units and improvement objects all in one. And if they do, "guarding" is fairly straightforward anyway (as we've done in previous lessons).

Although toTile is mainly meant to be a helper function for the General Library, it is also put into the gen table to be made available to end users, since it offers useful functionality. Hence, <code> gen.toTile=toTile</code>. Note that we could have given toTile a different name in the gen table that this module will return, such as gen.tableToTile=toTile. In fact, we could refer to the same function with multiple keys in the gen table, if we want to.

Next, we will look at gen.hasIrrigation.

The first thing to notice is that local is not being used to define this function. That is because we're putting the function for gen.hasIrrigation directly into the gen table that this module will return. We could define hasIrrigation as a local variable and then copy it into the gen table. However, there is a decent chance that the General Library will have more than 200 functions by the time everything is complete, since it is meant to provide a lot of building block functionality and keep it in one place, and we will run into trouble if we assign 200 local variables in a single function (which a required lua file acts as).

Perhaps the most striking thing is that we begin by changing the value of tile, the argument of the function. It looks like we're making a global variable named tile, but we're not. When you specify the names of the arguments for a function (in this case tile), you create local variables for that function, which can be given new values just as if you had explicitly used the local keyword.

Beyond that, we extract the integer representing the tile improvements into a local variable (which upon later reflection isn't really necessary), and check that the irrigation bit is set to 1 and the mining bit is set to 0. Refer to lesson 5 for why this works. In fact, we could have simply returned the value of the if statement, rather than specifying return true and return false, although it is very slightly clearer what is going on in the expanded version of the code.

Now, let us write a function to place irrigation on a square. It seems pretty clear that we should do nothing if the tile has a city, but we also have to decide what to do if there is mining or farmland on the tile, since those interfere with placing irrigation. We'll just remove them, on the basis that if we're trying to "place irrigation," then we want irrigation to be there when we are finished.

<code>
function gen.placeIrrigation(tile)
tile = toTile(tile)
</code>

These lines open the function and convert a table of coordinates to a tile if necessary.

<code>
if tile.city then
return
end
</code>

If the tile has a city, return so nothing else is done in the function.

<code>
-- Set irrigation bit to 1
tile.improvements = tile.improvements | 0x04
-- Set mining bit to 0
tile.improvements = tile.improvements & ~0x08
end
</code>

Set the irrigation bit to 1 and the mining bit to 0.

The functions in this library don't have to be complex, and in fact, most probably shouldn't be. They just have to make life easier for the end user. If you reach this lesson before the General Library is considered "complete," your assignment now is to submit some work for it. If you don't feel comfortable doing bitwise operations, you can test the work of others or submit functions that simplify other tasks. However, there are also some helper functions in the library to facilitate changing bits, so you might also consider working on the unit type flags functions. Remember, if you want to make functions available to the console for testing purposes, they must be global variables.

=== The Threshold Table and First Look at Metatables===

Consider a scenario design situation that occurred in Over the Reich: a bomber is generating some bombs via a key press, and the number of bombs it should generate is dependant on its current remaining hitpoints. The more hitpoints the bomber has, the more bombs it should generate. What we want is to specify that if a bomber has between x and y hitpoints, it should produce 2 bombs. That is, for a given type of bomber, we want to have, for example,

hp >= 16 --> 4 bombs
16 > hp >= 12 --> 3 bombs
12 > hp >= 9 --> 2 bombs
9 > hp >= 4 --> 1 bomb
4 > hp >= 0 --> 0 bombs

Unfortunately, Lua tables do not naturally encode this kind of association by default. However, Lua does have a feature called metatables, which allows us to change the behaviour of tables. (This will be a much better way to make the specification than I ended up writing in Over the Reich.)

A metatable is a table that we can "attach" to another table, and then the metatable changes the behaviour of that table. We'll only look at metatables briefly here, but more information can be found [https://www.tutorialspoint.com/lua/lua_metatables.htm here].

What we want is a data structure that can accept numerical "key values" that are between the key values explicitly specified, and return the appropriate value for those keys. We will call this data structure a threshold table, since we are specifying threshold values as keys. We can do this by assigning the following metatable:

<code>
local mt = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
</code>

If we run <code> setmetatable(myTable,mt)</code>, then whenever we ask for an index from myTable and that index doesn't currently exist in myTable, the function assigned to __index will run. Now let us examine the function.

If the type of the key is not a number, then we return whatever the table value is for that key. We use the function rawget, because the standard <code>thresholdTable[key]</code> will invoke this function again if the key doesn't exist, and so never return an answer (when we want it to return nil).

If the key type is a number, then we look for the largest numerical index that is also less than or equal to the key value. We return a default value of false if the key submitted is smaller than all numerical values. False is chosen over nil, so that a maximum value can be set by setting the value of a numerical index to false. Using the key [-math.huge] allows a return value to be set for all numbers (since all numbers are greater than -math.huge).

Since we don't want scenario creators to have to re-create threshold tables every time they need them, we'll add this functionality to the General Library

<code>
local thresholdTableMetatable = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
-- gen.makeThresholdTable(table or nil)-->thresholdTable
function gen.makeThresholdTable(inputTable)
inputTable = inputTable or {}
return setmetatable(inputTable,thresholdTableMetatable)
end
</code>

[[File:GetStartedWithLuaLesson6-06-ThresholdTable.jpg]]

===A Munition Generation Module===

Now, let us write some re-usable code for a human player to generate units by pressing a key while an appropriate unit is active. This sort of code could be used for ranged attacks (generating a "munition") and also for recruiting mercenaries by paying gold.

The first thing we will want to do is to decide how our code will be used by the end user. This will, perhaps, change by the time we finish writing the code, but it will at least give us a starting point.

spawnUnit(generatingUnit, specificationTable)--> table of unitCreated

Our goal is that when a player attempts to generate a unit using another unit, they will provide the unit spawning the new unit, and a table of information specifying if a unit (or units) can be spawned and anything else that must happen while spawning (like paying money, expending movement points, etc.).

We have an option here. We could have the scenario creator provide the specification table as a required file for our module, or the creator can provide it at the time spawnUnit is called. I choose the latter for a couple of reasons. The first is that it allows the player to have more than one specification table, either because more than one key can spawn a unit, or because the specification can change over time. The other is reason is so that the creator can make the table in the events.lua file if desired (since our module can't require information from events.lua).

Having decided that our generateUnit events are going to be specified by a table, we have to decide what the contents of that table should be. It seems pretty reasonable to index the specificationTable with the index of the unit type of each unit that can generate using the information in the table. If a unit type id number is missing, that unit doesn't generate a munition (or recruit a unit).

The value for each unit type id in the specification table will be a table that specifies how and if that unit generates other units.

--specificationTable[unitType.id]={
--
-- goldCost = integer or nil
-- amount of gold it costs to generate a unit
-- absent means 0
-- minTreasury = integer or nil
-- minimum amount of gold in treasury to generate a unit
-- absent means refer to gold cost
-- (tribe will generate and be set to 0 if treasury is less than goldCost)
-- treasuryFailMessage = string or nil
-- A message to be displayed if the unit fails to spawn a unit due to an
-- insufficient treasury
-- nil means no message

-- There are three ways to specify move costs, in full movement points,
-- in "atomic" movement points, and as a fraction of total movement points for the
-- unit type. Use only one kind per unit type

-- moveCost = integer or nil
-- movement points to be expended generating the unit
-- "full" movement points
-- absent means 0
-- minMove = integer or nil
-- minimum remaining movement points to be allowed to generate a unit
-- "full" movement points
-- absent means any movement points for land/sea, 2 "atomic" for air units
-- postGenMinMove = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostAtomic = integer or nil
-- movement points to be expended generating the unit
-- refers to the unit.moveSpent movement points
-- absent means 0
-- minMoveAtomic = integer or nil
-- minumum remaining movement points to be allowed to generate a unit
-- referes to the unit.moveSpent movement points
-- absent means any movement points for land, 2 "atomic" for air units
-- postGenMinMoveAtomic = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostFraction = number in [0,1] or nil
-- fraction of unit's total movement points expended generating the unit
-- round up to nearest "atomic" movement point
-- absent means 0
-- minMoveFraction = number in [0,1] or nil
-- fraction of unit's total movement points that must remain to be allowed
-- to generate a unit
-- absent means any movement points for land, 2 "atomic" for air units
-- round up to nearest "atomic" movement point
-- postGenMinMoveFraction = number in [0,1] or nil
-- a unit will be left with at least this many movement points after
-- the generation function, round up to nearest "atomic" move point
-- absent means 0 for land/sea, 1 "atomic" for air units
-- roundFractionFull = bool or nil
-- fractional movement cost and minimum are rounded up to full movement point
-- instead of atomic movement point
-- nil/false means don't
-- roundFractionFullDown = bool or nil
-- fractional cost and minimum are rounded down to full move point
-- nil/false means don't
-- minMoveFailMessage = string or nil
-- a message to be displayed if a unit is not generated due to insufficient
-- movement points.
-- nil means no message

-- allowedTerrainTypes = table of integers or nil
-- a unit may only be generated if the tile it is standing on
-- corresponds to one of numbers in the table
-- nil means the unit can be generated on any terrain type
-- terrainTypeFailMessage = string or nil
-- message to be displayed if a unit is not generated due to standing
-- on the incorrect terrain

-- requiredTech = tech object or nil
-- the generating civ must have this technology in order to generate
-- the unit
-- nil means no requirement
-- techFailMessage = string or nil
-- message to be displayed if a unit is not generated due to not having
-- the correct technology

-- payload = boolean or string
-- if true, unit must have a home city in order to generate munitions
-- and generating munitions sets the home city to NONE
-- payloadFailMessage = string or nil
-- message to be displayed if a unit is not generated due to the
-- payload restriction
-- payloadRestrictionCheck = nil or function(unit)-->boolean
-- If function returns false, the home city is not valid for giving the
-- unit a payload. This will be checked when the unit is activated, when
-- the unit is given a new home city with the 'h' key and when the unit
-- tries to generate a munition
-- nil means no restriction
-- payloadRestrictionMessage = nil or string
-- message to show if a unit fails the payloadRestrictionCheck

-- canGenerateFunction = nil or function(unit)-->boolean
-- This function applied to the generating unit must return true in order
-- for a unit to be spawned. All other conditions still apply.
-- any failure message should be part of canGenerateFunction
-- absent means no extra conditions

-- generateUnitFunction = nil or function(unit)-->table of unit
-- This function creates the unit or units to be generated
-- and returns a table containing those units
-- Ignore any specifications prefixed with * if this is used
-- nil means use other specifications

--*generatedUnitType = unitType
-- The type of unit to be generated
-- can't be nil unless generateUnitFunction is used instead

--*giveVeteran = bool or nil
-- generated unit(s) given veteran status if true
-- nil or false means don't give vet status
-- if true, overrides copyVeteranStatus

--*copyVeteranStatus = bool or nil
-- generated unit(s) copy veteran status of generating unit if true
-- nil or false means don't give vet status

--*setHomeCityFunction = nil or function(generatingUnit)-->cityObject
-- determines what home city the spawned unit should have
-- nil means a home city of NONE

--*numberToGenerate = nil or number or thresholdTable or function(generatingUnit)-->number
-- if nil, generate 1 unit in all circumstances
-- if integer, generate that many units (generate 0 if number less than 0)
-- if number not integer, generate floor(number), and 1 more with
-- probability number-floor(number)
-- if thresholdTable, use remaining hp as the key, to get the number to create
-- if function, get the number as the returned value of the function

-- activate = bool or nil
-- Activates one of the generated units if true. If generateUnitFunction was used,
-- the unit at index 1 is activated, if index 1 has a value. (if not, any unit in
-- the list might be chosen)

The very last entry brings forward a change that must be made to our unit generation specification. Lua's activate unit command doesn't run the unit activation trigger, even though the active unit is changed. Therefore, we must do that manually. Hence,

<code>spawnUnit(generatingUnit, specificationTable)--> table of unitCreated</code>

becomes

<code>spawnUnit(generatingUnit,specificationTable,unitActivationCode)-->table of unitCreated</code>

Perhaps we will change it again later.

I've decided to try a different instructional technique for this section. Instead of writing the code and then going through it section by section, I've recorded a video of my coding and testing this module, and I attempt to explain some of the stuff that I do along the way.

I'm not sure of the value of the video. If you find that there seems to be little useful content relative to the time it takes to watch, then feel free to skip it and continue the lesson. I don't teach anything "new" in it, so you won't miss anything crucial. However, it should be pretty close to how programming Lua can actually happen in the "real world." While I did give some thought to how to write the module before I started, I do attempt to solve problems in real time, and make mistakes that are not discovered for a while (including one where I try to explain how I solve a problem and then not actually do a crucial part).

You can find the code [https://forums.civfanatics.com/threads/totpp-the-munitions-library.647910/ here]. Even if you decide not to watch the video, download the code and try testing some of the features based on the specification above. If you find any bugs, submit a fix (or at least report the issue).

The video can be found [https://youtu.be/XxPyNknGlAo here].

===A Unit Attack Bonus for Complementary Units in Square===

Something we might like to do is to give units an attack bonus if they attack from a square with some special unit, for example a "leader" unit. The [[Napoléon I]] scenario, for example, gives an attack bonus to units if a commander unit, such as Napoleon, is in the square when the unit is activated (the unit can subsequently move and still retain the bonus as long as no other unit is selected). We will now make a module providing the same functionality.

We first have to have a basic idea of how this functionality should work. When a unit is activated, the onActivateUnit event checks if the newly activated unit should get an attack bonus, based on the other units in the square. If the unit deserves an attack bonus, the corresponding unitType.attack entry is changed, and all the attack value of all other units is reset to the default value. If the activated unit also does not deserve an attack bonus, that value is also set to the default value.

This now leads us to some more possibilities. Should multiple bonus units lead to multiple bonuses or only apply the best one? For example, suppose a legion gets a bonus if an archer is also in the same square. Should two archers provide twice the bonus? Perhaps two archers should provide a larger bonus than one, but not twice as much. Perhaps a legion should also get a bonus if there is a catapult in the square, but that bonus should apply even if the maximum archer bonus is already achieved. It seems like perhaps there should be a "ranged unit" bonus, an "artillery unit" bonus and maybe a "cavalry" bonus which should all impact the legion's attack value. It's looking like we might end up demanding that a scenario creator make a big complicated table in order to use this functionality, even if they only have simple needs.

What we can do to alleviate this is to write a "simple" version of the event that is easy to use (and program), and also write a more complicated version that gives the expanded capability.

Specification Table for simpleAttackBonus

--simpleAttackBonusTable[activeUnit.type.id] ={[bonusUnitType.id]=bonusNumber}
--simpleAttackBonusTable.type = string
--if simpleAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if simpleAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
--if simpleAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- if simpleAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- if simpleAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
--simpleAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

The relevant first draft of the code is as follows:

<code>
local function simpleAttackBonus(activeUnit,simpleAttackBonusTable,defaultAttackTable)
-- reset all unit attack values
for unitTypeID,attackValue in pairs(defaultAttackTable) do
civ.getUnitType(unitTypeID).attack = attackValue
end
local unitBonusTable = simpleAttackBonusTable[activeUnit.type.id]
if not unitBonusTable then
-- unitBonusTable is nil (or false), so the active unit can't
-- get a bonus
return
end
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
local bestBonusSoFar = 0
for unit in activeUnit.location.units do
if unitBonusTable[unit.type.id] and unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
if bestBonusSoFar == 0 then
-- If no bonus unit is found, this will be true, so do nothing else
return
end
-- set the new attack and return
if string.lower(simpleAttackBonusTable.type) == "addBonus" then
activeUnit.type.attack = activeUnit.type.attack+bestBonusSoFar
return
end
local attackMultiplier = 1
if type(simpleAttackBonusTable.type) ~= "string" then
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
elseif string.lower(simpleAttackBonusTable.type) == "addpercent" then
attackMultiplier = (100+bestBonusSoFar)/100
elseif string.lower(simpleAttackBonusTable.type) == "addfraction" then
attackMultiplier = 1+bestBonusSoFar
elseif string.lower(simpleAttackBonusTable.type) == "multiplypercent" then
attackMultiplier = bestBonusSoFar/100
elseif string.lower(simpleAttackBonusTable.type) == "multiply" then
attackMultiplier = bestBonusSoFar
else
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
end
-- apply the bonus and round as appropriate
if type(simpleAttackBonusTable.round) ~= "string" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
elseif string.lower(simpleAttackBonusTable.round) == "up" then
activeUnit.type.attack = math.ceil(activeUnit.type.attack*attackMultiplier)
return
elseif string.lower(simpleAttackBonusTable.round) == "down" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier)
return
else
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
end
end
</code>

Now let us go over this section by section.

[[File:GetStartedWithLuaLesson6-07-AttackBonus1.jpg]]

The first thing we do is to reset all the attack values of all the unit types. That way, if a bonus existed for the last unit activated, that bonus no longer applies. If a unit type is not in the defaultAttackTable, then we don't have the information to reset the attack value anyway, so we can safely ignore it by using the pairs function to iterate over the table.

Now, we must find out if the newly activated unit deserves a bonus. For that, we get the table associated with the active unit's type. If the value is nil instead of a table, then the unit's type is not in the simpleAttackBonusTable, so there is no bonus to apply and the function returns.

If the unit is eligible for bonuses, we then check the units in the square to see if any bonuses actually apply. We've seen this kind of code before. If the unit in the stack can provide a bonus, and that bonus is better than the best bonus already found, the unit now provides the best bonus. All bonus types that we can have are better if they are larger, and we are not comparing between bonus types, so a simple numerical comparison will do. All bonuses are larger than 0 in our formulation, so 0 is a good starting value in the search.

If the best bonus so far is still 0, there is no bonus, so the function can return.

At this point, it occurs to me that when searching for the best bonus, we should exclude the active unit from the search. That way, you can have a "strength in numbers" bonus, for example. The relevant change to the code is:

<code>
for unit in activeUnit.location.units do
if unit ~= activeUnit and unitBonusTable[unit.type.id] and
unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
</code>

Next, consider

[[File:GetStartedWithLuaLesson6-08-AttackBonus2.jpg]]

Here, we apply the bonus that we've found. We use string.lower on simpleAttackBonusTable.type so that we don't have to worry about capitalization. That does, however, require a correction to "addBonus", since a lower case string will never be equal to that.

"addbonus" is the only type of bonus that is directly added to the existing attack value. All other bonus types are a form of multiplication. Since the addition is straightforward and doesn't require any rounding, the activeUnit's type attack value can be changed immediately, and the function execution ended with return.

When there is only one bonus being applied, all other types of bonus are different ways of expressing how to multiply the existing attack value to get a new one, so we simply convert to the appropriate multiplier, and provide an error message if the type of bonus is not one of the valid possibilities.

Finally, we round the attack value to an appropriate integer (since unit attack values must be integers), change the attack value of the active unit's type, and return to end the function execution.

Now, we integrate into events.lua by using

<code>
attackBonus = require("attackBonus")
</code>

The relevant integration code for events.lua is
<code>
local defaultAttackValueTable = {[unitAliases.legion.id]=4}
local simpleAttackBonusTable ={}
simpleAttackBonusTable.type = "addbonus"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=3,[unitAliases.musketeer.id]=4}

local function doOnActivation(unit,source)
munitions.payloadRestrictionCheck(unit,munitionSpecificationTable)
attackBonus.simpleAttackBonus(unit,simpleAttackBonusTable,defaultAttackValueTable)
end
</code>

We can check that the bonus is being applied correctly by checking the Civlopedia entry for legion and looking at the attack value. The following cases must be tested (remember that activating a unit from the city screen doesn't run the onActivation event, so activate from the map).

Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (7 attack)
Legion activated with musketeer, but no archer (8 attack)
Legion activated with archer and musketeer (8 attack)
Legion activated with 2 archer, no musketeer (7 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

I recommend making a stack for each of these cases and activating them one by one.
To facilitate the test, add the following line to doOnActivation

<code>
civ.ui.text(tostring(unit.type.attack))
</code>
You will want to comment out this line after testing.

Next, change simpleAttackBonusTable to do "addpercent"
<code>
simpleAttackBonusTable.type = "addpercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=30,[unitAliases.musketeer.id]=70}
</code>

With no rounding set, standard rounding is used
Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)
Legion activated with archer and musketeer (7 attack)
Legion activated with 2 archer, no musketeer (5 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

These numbers test both rounding up and rounding down.

Now, use
simpleAttackBonusTable.round="up"
Legion activated with archer, but no musketeer (6 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next,
simpleAttackBonusTable.round="down"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (6 (6.8) attack)

simpleAttackBonusTable.round="standard"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next, we test "addfraction". Since we've tested all the rounding options, we don't have to do that again.

<code>
simpleAttackBonusTable.type = "addfraction"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=0.3,[unitAliases.musketeer.id]=0.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiplypercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=130,[unitAliases.musketeer.id]=170}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiply"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Before we finish, we should test a legion bonus for the legion.
<code>
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.legion.id]=2,[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>

Legion alone should have 4 attack.
A second legion on the square should provide 8 attack instead.

Now, let us try to formulate a more complicated bonus system. One thing we mentioned is that we'd like the ability to get bonuses from multiple units, and to be able to get bonuses from different "classes" of units (like "artillery," "cavalry," and "ranged attackers." Something else we might want to do is to allow different kinds of bonuses. That is, maybe some units should provide a fixed +2 to any unit receiving the bonus, so that it is better at improving units with a low attack value, while other units should provide a percentage bonus (making them better at supporting units with an already high attack value). It turns out that both of these ideas are not too difficult to implement individually, but that trying to implement them together makes it problematic to find the best bonus.

Let us implement a bonus system with multiple categories but only one bonus type. In our specification, we will first specify a data type called "bonusCategory." It is still just a table (though we could add a metatable if we wanted), but it will help us make our specification clearer.

<code>
-- A "bonusCategory" is a table
-- bonusCategory = {[bonusUnitType.id]=bonusNumber, maxBonusUnits=integer or nil, nextBonusValue = fraction or nil}
-- In a bonusCategory, the value for bonusUnitType.id tells what the base bonus for that unit type is,
-- maxBonusUnits is the maximum number of units that can provide a bonus in this category,
-- nextBonusValue tells how much to reduce the bonus for each subsequent unit,
-- e.g. nextBonusValue = 0.7, and 5 units, which each have a bonusNumber=1
-- The total bonus is 1(0.7)^0+.7+(.7)(.7)+(.7)^3+(.7)^4 = 1+.7+.49+.343+.2401=2.7731
-- (which would be rounded as specified)
-- nil means nextBonusValue=1
--
-- If a unit type is in two bonus categories for the same unit, there is no guarantee that the
-- best bonus will be achieved
</code>

So, the bonus category is indexed by unitType id numbers for units that can give a bonus, and the corresponding bonus. It also specifies the maximum number of units that can give a bonus, and a number that governs how to reduce a bonus for extra units. That way, there can be diminishing returns for bonuses.

Next, we look at the specification for the categoryAttackBonusTable

<code>
--categoryAttackBonusTable[activeUnit.type.id] =table of bonusCategory
--categoryAttackBonusTable.type = string
--if categoryAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if categoryAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
-- for multiple unit bonuses, add up all the percents, then compute the bonus
-- i.e. 50% bonus and 50% bonus is 100% bonus, not 125%
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 50% bonus units become 50% + 25%
-- so attack 6 --> 10.5
--if categoryAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- for multiple unit bonuses, add up the fractions, then compute the bonus
-- i.e. .5 bonus and .5 bonus is 1+.5+.5= 2x bonus, not 2.25x
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 .5 bonus units become .5+.25
-- so attack 6 --> 10.5
-- if categoryAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- bonuses are multiplied together, i.e. 150% and 150% yields 225% of original value
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 100, i.e. nextBonusValue=.5 2 150% bonuses become 150% and 125%
-- so attack 6 --> 11.25
-- if categoryAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
-- bonuses are multiplied together, i.e. 1.5 and 1.5 yields 2.25x
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 1, i.e. nextBonusValue=.5 and two 1.5 bonuses become 1.5 and 1.25
-- so attack 6 --> 11.25
--categoryAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

-- If the active unit can get a bonus, go through each category and compute the bonus for that category.
-- Then, combine the bonuses for all categories to get the overall bonus, and round the result
</code>

With the bonusCategory defined, the value of the unit indices of categoryAttackBonusTable become easy to define. Most of the specification is showing what exactly the different bonus categories mean, so the end user can use them properly. It's not strictly necessary to offer so many choices to the end user on how to specify data, but it can be more convenient.

Here is the actual code (before testing) to implement this more general version of attack bonuses.

<code>
-- HELPER FUNCTION
-- findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable) --> number or false
-- usedUnitTable is indexed by the i.d. number of units, and if the value for a unit is true,
-- then it has already been used for a bonus (and, so, is not eligible)
-- The function returns the bonus (before nextBonusValue is applied) if there is one, and marks the
-- unit as used in the usedUnitTable
-- returns false if no unit qualifies
local function findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable)
local bestBonusSoFar = 0
local bestUnitSoFar = nil
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
for unit in tile.units do
if not usedUnitTable[unit.id] and bonusCategory[unit.type.id]
and bonusCategory[unit.type.id] > bestBonusSoFar then
bestUnitSoFar = unit
bestBonusSoFar = bonusCategory[unit.type.id]
end
end
if bestUnitSoFar then
usedUnitTable[bestUnitSoFar.id] = true
return bestBonusSoFar
else
return false
end
end

-- HELPER FUNCTION
-- computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
-- Computes the bonus that the active unit will receive from this category, taking into
-- account the type of bonus for the table
local function computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
local bonusThusFar = nil
if bonusType == "multiply" then
bonusThusFar = 1
elseif bonusType == "multiplypercent" then
bonusThusFar = 100
else
bonusThusFar = 0
end
local bonusDiscount = 1
for i=1,(bonusCategory.maxBonusUnits or 10000) do
local currentBonus =findBestBonusInUnitStack(activeUnit.location,bonusCategory,usedUnitTable)
if not currentBonus then
-- no more valid bonuses for this category
break
end
if bonusType == "multiply" then
bonusThusFar = bonusThusFar*((currentBonus-1)*bonusDiscount+1)
elseif bonusType =="multiplypercent" then
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
else
bonusThusFar = bonusThusFar+currentBonus*bonusDiscount
end
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
end
return bonusThusFar
end

local function categoryAttackBonus(activeUnit,categoryAttackBonusTable,defaultAttackTable)
local bonusInfoTable = categoryAttackBonusTable[activeUnit.type.id]
if not bonusInfoTable then
-- unit doesn't get a bonus
return
end
-- keep track of bonuses already computed
local bonusResultsTable = {}
-- keep track of units that have already been "used" for a bonus
local usedUnitTable = {[activeUnit.id]=true}
for index,bonusCategory in pairs(bonusInfoTable) do
bonusResultsTable[index]=computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
end
-- compute the bonus
local bonusType = string.lower(categoryAttackBonusTable.type)
local resultAttackBeforeRounding = nil
if bonusType == "multiply" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "multiplypercent" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult/100
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "addbonus" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack+bonus
elseif bonusType == "addfraction" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
elseif bonusType == "addpercent" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+(bonusResult/100)
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
else
error("categoryAttackBonus: categoryAttackBonusTable.type is not a valid value.")
end
-- apply the bonus and round as appropriate
local roundType = categoryAttackBonusTable.round
if type(roundType) ~= "string" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
elseif roundType == "up" then
activeUnit.type.attack = math.ceil(resultAttackBeforeRounding)
return
elseif roundType == "down" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding)
return
else
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
end
end
</code>

The two helper functions for computeCategoryBonus are only used once each in the code, so making them helper functions does not help us re-use code. However, what it does do is to break down the function design process into smaller tasks, which are each more manageable to complete. If you're trying to keep track of too many things in your program, try writing a few helper functions to handle individual tasks. We'll look at the helper functions when we actually arrive at them in the code.

[[File:GetStartedWithLuaLesson6-09-CategoryAtkBonus1.jpg]]

If there is no entry in the categoryAttackBonusTable or the active unit's type, then the function returns without doing anything further.

The bonusResultsTable keeps track of the total bonus from each category, so they can be added or multiplied together after all the category bonuses are applied. The usedUnitsTable keeps track of units that are no longer eligible to contribute to a bonus (such as if they have already contributed), and we initialize it with the active unit, so that it doesn't provide a bonus to itself.

The for loop computes the bonus for every category, and stores the value in the bonusResultsTable, for use later.Now, let us look at the helper functions.

First up is findBestBonusInUnitStack

[[File:GetStartedWithLuaLesson6-10-CategoryAtkBonus2.jpg]]

This basically does what it says in the name. For a bonusCategory, it finds the unit in the tile that provides the best bonus, and has not already provided a bonus elsewhere. If there is no qualifying unit, false is returned. If there is, that unit's bonus is returned, and the unit's id is entered into the usedUnitTable, so that unit can't provide another bonus for the active unit. We've searched for the best of something before, so there is little need to go over it again.

Next is computeCategoryBonus

[[File:GetStartedWithLuaLesson6-11-CategoryAtkBonus3.jpg]]

Here, we're computing the bonus for the entire bonusCategory. We need the bonus type in order to know what kind of math to do. The math itself is not very interesting. We also initialize the bonusDiscount, which keeps track of the fraction of the next unit's bonus that will actually be applied.

Next, we enter a for loop that will run one time for each possible bonus that there can be in a bonus category. If bonusCategory.maxBonusUnits is nil, then we set an arbitrary limit of 10000 units, which is very unlikely to happen in practice.

At each iteration of the loop, the best available bonus in the stack is found. If no unit was eligible to provide a bonus, then the current bonus is false, and the "break" command is issued. Break immediately exits the current loop. So, our program doesn't run 10000 loops if there is no maximum number of bonus units, it just breaks at an appropriate time.

After the bonus is found, it is added to or multiplied with the bonus already found. The bonus computed in this way will be the largest possible, since the bonus provided does not depend on the other units chosen (so we don't have a situation where "catapult" and "rock" are both useless, but "catapult" and "rock" chosen together are best). Also, since the best bonus is chosen first, the smallest bonus discount applies to it, so the cost imposed by the discounting is smallest.

Finally, we update the bonusDisount. Here, I notice a problem in the code as written, since bonusCategory.nextBonusValue is allowed to be nil. Replace
<code>
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
</code>
with
<code>
bonusDiscount = bonusDiscount*(bonusCategory.nextBonusValue or 1)
</code>
so that if there is no nextBonusValue, a default of 1 is used, and the bonusDiscount stays at 1 (i.e. no discount is applied).

We return to categoryAttackBonus to see

[[File:GetStartedWithLuaLesson6-12-CategoryAtkBonus4.jpg]]

From here, we combine the bonuses stored in bonusResultsTable, the exact way of doing so being dependant on the type of bonus involved. The math itself isn't very interesting, and doesn't seem all that likely to come up in this exact form elsewhere. If you need help with the mathematical details of some event you want to write, ask in the forums. There's a good chance someone has the skills to help you solve your specific problem.

For every type of bonus, the result is stored in resultAttackBeforeRounding, so that variable can be rounded up or down as specified by the rounding type.

Here, I notice another error. We should restrict the attack value for a unit to not exceed 98. We can do that with a math.min(value, 98).

Now, we need to test the various aspects of the attack bonus program, so we need an appropriate table
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addbonus"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=2,[unitAliases.chariot.id]=4,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=2,[unitAliases.musketeer.id]=4,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Also, comment out the old attack bonus line, and put in a new one
<code>
attackBonus.categoryAttackBonus(unit,categoryAttackBonusTable,defaultAttackValueTable)
</code>

Expected Test Results when type is "addbonus"
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

Already, we find a problem. Although there were no syntax errors to fix, I forgot to reset unit attack values. So, very quickly, the legions keep gathering extra attack values when they are activated (since the base attack is not reset to 4). Since this is happening anyway, I'll test the 98 attack value maximum. That appears to work, at least in the case of no specified rounding.

Cut and paste the appropriate lines from the simpleAttackBonus to the categoryAttackBonus, and save.

With that bug fixed, everything works as expected.

Next, we change the categoryAttackBonusTable to

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addpercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=50,[unitAliases.chariot.id]=100,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=50,[unitAliases.musketeer.id]=100,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>

Expected Test Results when type is "addpercent". These are the same, since adding we're adding percentages of the same base value of 4. So a value of 2 is the same as adding 50% of 4.
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

The results are the same.

Similarly,

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addfraction"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=.50,[unitAliases.chariot.id]=1.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=.50,[unitAliases.musketeer.id]=1.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

We'll have to do some new calculations, now, since multiply and multiplyfraction give different results than the various adding formulations.

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiply"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=1.50,[unitAliases.chariot.id]=2.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=1.50,[unitAliases.musketeer.id]=2.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Finally, we use multiplyPercent, and check for the same results
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=150,[unitAliases.musketeer.id]=200,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Quickly, I find that if a bonus applies, that bonus makes the attack value of a legion 98. I failed to multiply percents correctly in computeCategoryBonus. The Line
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
</code>
Is changed to
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+100)/100
</code>

Finally, Change archer bonus to 110 and musketeer bonus to 120 (so a unit will make a legion have 4.4 and 4.8 value before rounding), and test the rounding options. You will find they all work.

At the moment, we don't have a way to mix different types of bonuses. As said earlier, we might want this so that some units can be better at giving bonuses to low attack units than to high attack units, while others give a percentage bonus to everything. We could now write a bonus system that allows for multiple types of bonuses. However, the current bonus system allows for the bonus to change per unit. This means that we can, for example, convert a +2 attack bonus to a plus 100% bonus for a unit with 2 attack, and a plus 50% bonus for a unit with 4 attack. In the case of the multiplied bonuses, this will make the bonus more powerful if there is more than one. That is, 2 attack, +2 twice is 6, but if +2 is changed to x2, then the multiplied bonus brings the attack up to 8. However, this seems like it would be a relatively unlikely problem, and there are other things this code can't handle, so we'll let someone else make the code if they actually need it.

So, what we'll do is write a function that will change all appropriate entries in the categoryAttackBonusTable to reflect a different value. Hence,

<code>
-- plusFixed(unitType,number,categoryAttackBonusTable) --> void
-- changes the bonus given by unit type to any unit to be equivalent
-- to adding number to that unit's attack power
</code>

Here, an issue with tables arises. It is very likely that when someone defines their cateogryAttackBonusTable, they'll define it something like this
<code>
local rangeBonusCategory = {[unitAliases.archer.id]=.25,[unitAliases.musketeer.id]=.5}
local bonusTableForInfantry = {rangeBonusCategory}
local cABT = {type="addfraction"}
cABT[unitAliases.phalanx.id]=bonusTableForInfantry
cABT[unitAliases.legion.id] = bonusTableForInfantry
</code>
However, this means that both <code> cABT[unitAliases.legion.id] </code> and <code> cABT[unitAliases.phalanx.id] </code> actually refer to the same piece of memory, and changing cABT[unitAliases.legion.id][1][unitAliases.archer.id] will also change the value at cABT[unitAliases.phalanx.id][1][unitAliases.archer.id]. This is because of the way lua tables are designed. This design can be useful, for example it allowed us to make changes to usedUnitsTable in the last function without having to copy the table, make changes to the copy of the table, and then replace the original table with that copy as a return value. However, it also requires us to be careful when we make changes to entries in tables. In this case, we'll simply copy the table and all its sub values into a new table.

The code to do this is given by
<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

We will explain this code in the next section, since it involves a programming technique which we haven't discussed before.

For now, we analyze plusFixed:

<code>
-- plusFixed({[unitType1.id]=fixedBonus,[unitType2.id]=fixedBonus},categoryAttackBonusTable) --> void
-- changes the bonus given by unitTypeI.id to a unit to be equivalent to
-- to adding number to that unit's attack power. If the unit doesn't receive a bonus
-- from the unitType, then it won't after applying plusFixed.
-- The value of the existing bonus is ignored.

local function plusFixed(fixedUnitBonusTable,categoryAttackBonusTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
for bonusReceivingUnitTypeID,bonusTable in pairs(categoryAttackBonusTable) do
-- replace bonusTable with an equivalent table that is not referened
-- anywhere else, so that changes to it can be made without impacting
-- data elsewhere
categoryAttackBonusTable[bonusReceivingUnitTypeID] = duplicateTable(bonusTable)
-- make bonusTable refer to the "current" bonus table for the unit type
bonusTable =categoryAttackBonusTable[bonusReceivingUnitTypeID]
-- For each unit type in the fixedUnitBonusTable, check if any bonus category
-- in the bonusTable corresponds to it. If so, make the change
for bonusGivingUnitTypeID,fixedBonusValue in pairs(fixedUnitBonusTable) do
-- get the attack of the unit type
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
-- in each bonus category, check if the giver's unit type id is there,
-- if so, change to the correct attack
for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
if bonusCategory[bonusGivingUnitTypeID] then
-- change the bonus appropriately
if bonusType == "addbonus" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue
elseif bonusType == "addpercent" then
bonusCategory[bonusGivingUnitTypeID]=100*fixedBonusValue/baseAttack
elseif bonusType == "addfraction" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue/baseAttack
elseif bonusType == "multiplypercent" then
bonusCategory[bonusGivingUnitTypeID]=100*(fixedBonusValue+baseAttack)/baseAttack
elseif bonusType == "multiply" then
bonusCategory[bonusGivingUnitTypeID]=(fixedBonusValue+baseAttack)/baseAttach
else
error("pluxFixed: categoryAttackBonusTable.type does not have an acceptable value.")
end
end
end
end
end
end
</code>

[[File:GetStartedWithLuaLesson6-13-plusFixed1.jpg]]

As before, we save the bonusType in lower case, since we'll be using it a lot later. Next, we open a for loop, where the index is the id of the unit type receiving the bonus, and the value is the bonus table for that unit type. Next, we duplicate the bonus table, so that we have a table we can change without impacting anything elsewhere, and we store the duplicated table in categoryAttackBonusTable in place of the original bonusTable for the current bonus receiving unit id. Next, we assign this duplicated table to the variable bonusTable, so we can refer to it later in the code.

[[File:GetStartedWithLuaLesson6-14-plusFixed2.jpg]]

We now perform the following actions for each unitType.id and corresponding fixedBonusValue submitted in the fixedUnitBonusTable.

First, get the attack of the bonus receiving unit, since we'll need that in order to customize the bonus. Next, check each bonus category in the bonus table. If the bonus category has the current unitTypeID as a key, then replace the existing value with a bonus equivalent to adding a fixed value to the receiving unit's attack.

That's all that must be done, so end all the loops.

Now we test the function.

Add unitAliases.phalanx = civ.getUnitType(3) to the appropriate file.

<code>
defaultAttackValueTable[unitAliases.phalanx.id]=1
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,
nextBonusValue=0.5,maxBonusUnits=1}
local rangeBonusCategory = {[unitAliases.archer.id]=125,[unitAliases.musketeer.id]=150,
nextBonusValue=0.75,maxBonusUnits=1}
local standardBonus = {cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable[unitAliases.legion.id]=standardBonus
categoryAttackBonusTable[unitAliases.phalanx.id]=standardBonus
categoryAttackBonusTable.round="up"
attackBonus.plusFixed({[unitAliases.chariot.id]=2,[unitAliases.musketeer.id]=2},
categoryAttackBonusTable)
</code>
The chariot and the musketeer individually should each add 2 to both a phalanx and a legion,
so the phalanx should have an attack of 3, and the legion should have an attack of 6, if one bonus
is applied.

Since the bonus type is multiplypercent, together the phalanx would have an attack of 9, and the legion will also have an attack of 9.

In testing, we quickly get this error
<code>
You should see this in lua console if this worked
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: bad argument #1 to 'getUnitType' (number expected, got string)
stack traceback:
[C]: in function 'civ.getUnitType'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>

At line 356, which is

<code>
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
</code>

This must mean that bonusReceivingUnitTypeID is not a number. This is because we're looping over categoryAttackBonusTable, and that table has a couple of entries that are not integers ("type" and "round"). Therefore, we have to insert code to deal with this eventuality.

The simplest way is to put everything in the loop body into an if statement, so that it only runs when bonusGivingUnitTypeID is actually a number. You should be able to do this without detailed instructions, so do so (hint: use type function).

The next error is
<code>
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: bad argument #1 to 'pairs' (table expected, got nil)
stack traceback:
[C]: in function 'pairs'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>
<code>
360 for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
</code>

Here, we have a nil value for bonusTable. This turns out to be an error in duplicateTable. When I duplicated the table, I forgot to return that table. That is, both the if and else statement in that function need a return command, and I forgot to add <code> return duplicatedTable </code> in the if portion. Add this to the duplicate table function.

After this, our predictions are true. Testing the other types of bonus is left as an assignment. You can find the completed code [https://forums.civfanatics.com/threads/totpp-attack-bonus-library.648093/ here].

===Recursive Functions===

Let us return to the duplicateTable function. Recall that in the last section we added a line to it, so we'll restate it here:

<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
return duplicatedTable
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

[[File:GetStartedWithLuaLesson6-16-duplicateTable.jpg]]

The interesting thing about duplicateTable is that it invokes duplicateTable within its code. When we copy the key-value pairs into the new table, we run duplicateTable on the value. If the value is not a table, then we are in the else case, and the value is immediately returned to be inserted into the duplicated table. If the value is a table, that table is duplicated before anything else is done.

Let us look at a simple example of a recursive function, the factorial function N!. In lesson 3, we discussed the factorial function in the context of loops. Since N!=N*(N-1)*(N-2)*...*3*2*1, we can give another definition of N!:
N!=1 if N = 1
N!=N*(N-1)! if N > 1
Or, using the convention that 0!=1, we can state
N!=1 if N = 0
N!=N*(N-1)! if N > 0

The case where N =1 or N=0 is called the "base case." If we keep substituting N! as N*(N-1)!, then we won't go on forever, because we will eventually reach a point where N=0, and N! can be substituted as 1 instead of N*(N-1)!. As long as there is a base case, our program will eventually reach the base case(s), and begin "completing" evaluation.

<code>
function factorial(N)
if N>0 then
return N*factorial(N-1)
else
return 1
end
end
print(factorial(5))
print(factorial(6))
</code>

Run this in code in the lua demo website, or using the TOTPP lua interpreter.

Returning to our duplicateTable function, the base case is any time a table value is not itself a table. When that happens, the recursion "chain" ends, and everything can evaluated.

Although is shouldn't be a problem in this particular case, it should be noted that it is possible for there to not be a "base case" in the recursion style: if table, recur, if not return a value. Consider the following table system

<code>
a={}
b={[1]=a}
a[1]=b
</code>
In this case, the code would never end.

It is possible that even if the code could "theoretically" execute to completion, you run out of memory before that. This is called a "stack overflow," and if it occurs, you will have to think of an alternate way to solve your problem. It will probably be best to ask for help in that case (and it might be useful to provide others with an example of a problem that results in a stack overflow), but you might also look into "tail recursion", including http://www.lua.org/pil/6.3.html .

===Conclusion===

With the skills covered in this chapter, you now have the tools to split a large events file into multiple files that are more manageable. You also have the basics for how to write re-useable modules for your events, so that your work can be used by others. Remember that if someone else uses your implementation of a feature, they will spend much less time coding and testing it, allowing them to either finish the scenario sooner, or to introduce some other feature. So, it might very well pay to spend at least a little effort making your code into a reusable module. Perhaps you have an idea for a cool scenario mechanic, but don't have a scenario for it (or don't want to take the time to make it). If that's the case, just make the module and test it in a "toy" scenario (like Classic Rome) so that it can be used more or less "off the shelf" when someone needs it.

Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files

2019-07-26T15:16:05Z

Prof. Garfield: /* Recursive Functions */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This Lesson is under construction.

===Introduction===

In this lesson, we will take a look at how to split the code for a scenario's events into multiple files. There are several reasons to consider doing this.

The first reason is simply to organize your work. If you have a series of complicated events, the events.lua file can become very large very quickly. Once your events.lua file has thousands of lines of code in it, it may not be very obvious where the best place is to put that next helper function, or where to implement the function that runs a complicated event. Sometimes even finding the piece of code that has to be changed can be a bit of a hassle. In Over the Reich, I sometimes search for the associated civ.scen line, and then search for the exact name of the function I need. Occasionally, there may even be more searching to find what I actually have to change. With multiple files, it becomes easier to find things.

Another aspect of using multiple files is that you can make certain changes without worrying about breaking things elsewhere. If myBigComplicatedFunction relies on aModestHelperFunction for a certain part of its functionality, and a change to myBigComplicatedFunction also requires a change to aModestHelperFunction, you have to make sure that nothing else in your code also uses aModestHelperFunction, or, if something else does depend on it, that aModestHelperFunction either still provides the original functionality, or that all other functions that use aModestHelperFunction are suitably modified. If myBigComplicatedFunction is defined in its own lua module, then you don't have to worry about forgetting that aModestHelperFunction was used elsewhere, since it can't be accessed outside the module unless you specifically allow it to be.

A second reason to split events code into multiple files is to facilitate collaboration. If all of the events are in a single file, then only one person can make changes to the file at a time. If one partner starts changing an event, but has to do something else before finishing, everyone waits on one person's delay. However, if most aspects of the scenario are separated into individual files, everyone can work on his or her own piece of the puzzle without depriving others of the opportunity to work at that time.

A third reason to split events into multiple modules is to facilitate reusing code. If everything required to implement an event is in its own file (or files), it becomes much easier for other creators to use your functionality in their scenario. Since everything they need is already in one place, they don't have to find every last helper function, or concern themselves with naming conflicts.

===Two Simple Examples===

Let us look at the top of the events.lua file. You can get the version that I started lesson 6 with [[here]].

[[File:GetStartedWithLuaLesson6-01-DefaultRequire.jpg]]

We get code from other files by using the command <code>require</code> along with a string specifying the file name (except for the .lua extension). At the moment, we can only get code stored in the lua folder in the Test of Time directory. This is inconvenient if we're trying to distribute a scenario, since installing a scenario would require moving certain files to the lua directory, and those file names might conflict. Instead, we need to tell the Lua interpreter to search in the same folder that the events.lua folder is in.

To do this, we need the following code:
<code>
local eventsPath = string.gsub(debug.getinfo(1).source, "@", "")
local scenarioFolderPath = string.gsub(eventsPath, "events.lua", "?.lua")
if string.find(package.path, scenarioFolderPath, 1, true) == nil then
package.path = package.path .. ";" .. scenarioFolderPath
end
</code>

You can probably cut and paste this code before the require lines in your events.lua file and not worry about how it works. However, I'll provide a brief explanation for reference.

The first line stores the location of the of the current file as a string in eventsPath.

The second line replaces events.lua in the eventsPath with ?.lua, which will tell the Lua interpreter to look for .lua files in the current directory (that is to say, the directory with the events.lua file).

The if statement adds scenarioFolderPath to the places for the Lua interpreter to search for code, if that directory is not already in the search path. Since the search path is kept active by the Lua interpreter, it will not be necessary to repeat these lines of code in every file that performs a require action as long as you are running the file as part of events. If you are writing some other kind of code, you will need to substitute "events.lua" with the name of the file with the code you are running. Note that for some reason, events.lua is always provided in lower case. However, for use in other situations, debug.getinfo(1).source uses the correct case for event files. I have only briefly tested this, so you may have to do some testing yourself if this situation comes up (or ask for help in the forums).

Now that we've told Lua where to look for our extra code, we can begin moving code to other files. Think of require as telling Lua to run the entire contents of another file as a function. We can then assign a value to whatever that file returns, which will usually be a table. A couple of examples will clarify.

For our first example, we will move our scenario's parameters to a separate file, and access it via require. This may not seem worthwhile in this example, but tables like this can get large in a hurry. At the time of writing, Over the Reich has over 100 lines of parameters ("specialNumbers"), and parameters are something that a designer might like to play with while collaborators make other implementations. Also, parameters will have to be referenced by other parts of the code, and a file that is required by events.lua cannot, in turn, require events.lua in order to get information. That means that we'll have to keep our parameters in a separate file anyway.

Cut the parameters table definition and paste it into a new file, classicRomeParameters.lua. For the last line, write
<code>
return parameters
</code>

Now, Near the top of events.lua, where the existing require lines are, add the eventsPath code from above and also the line
<code>
local parameters = require("classicRomeParameters")
</code>

[[File:GetStartedWithLuaLesson6-02-RequireParameters.jpg]]

Open the classicRome scenario and test out a couple of events to make sure everything is the same.

We might find it convenient to put a few tables into the same file. For this, we will simply return a table containing these tables, and give each table a name in the events.lua file.

Create a file classicRomeAliases.lua and move all the "aliases" tables to that file. Also move the getCityAt function.

At the bottom of the file, put the following lines:
<code>
return {
unitAliases=unitAliases,
tribeAliases=tribeAliases,
tileAliases=tileAliases,
cityAliases=cityAliases,
textAliases=textAliases,
terrainAliases=terrainAliases,
improvementAliases=improvementAliases,
}
</code>

Then, add the following lines to events.lua (in the require section)
<code>
local aliases = require("classicRomeAliases")
local unitAliases,tribeAliases,tileAliases,cityAliases,textAliases,
terrainAliases,improvementAliases=aliases.unitAliases,aliases.tribeAliases,
aliases.tileAliases,aliases.cityAliases, aliases.textAliases,aliases.terrainAliases,
aliases.improvementAliases
</code>

Here, our classicRomeAliases module is returning a table with our "alias" tables. We then assign the entries in this returned table to local variables with the desired names. Here, I use multiple variable assignment, which I don't believe I've used before (even though Lua allows it), but these could just as simply have been assigned line by line.

[[File:GetStartedWithLuaLesson6-03-RequireAliases.jpg]]

Now, let us move the legion plundering code into its own file, which we'll call plunder.lua. First, copy over the legionPlunder function, and paste it near the bottom of the new file.

Now, let us go through the code of this function, and figure out what else we need in our plunder.lua module.

The very first part of the function is a check against unitAliases.legion. This means we need the unitAliases table, and so we copy the aliases require code to the top of plunder.lua. We don't need the path information, since that will be added in events.lua.

A few more lines down, we find that the function cityRadius is also used in legionPlunder. Therefore, we move that over as well. We also need the plunderValue function, so copy that over as well.

Next, we check if cityRadius relies on anything, but it doesn't.

Proceeding to plunderValue, we find that it relies on the parameters table, so require that as well. The function plunderValue does not appear to depend on anything else, so we're done moving functionality. If we missed something, the Lua interpreter will complain at some point anyway.

Next, we require the plunder module in events.lua, with the following line:

<code>
local plunder = require("plunder")
</code>

Next, for each of the functions in plunder.lua, we check if it is used somewhere in events.lua. We can do this by searching. plunderValue isn't used anywhere, so we're done with that. City radius is used. At the bottom of plunder.lua, we begin our return table, and have
<code>
return {
cityRadius=cityRadius,
}
</code>

Then, in events.lua, we replace the ocurance of cityRadius with plunder.cityRadius. Alternatively, we could have put
<code>
local cityRadius=plunder.cityRadius
</code>
after the line requiring plunder.

Similarly, for legionPlunder, we add <code>legionPlunder=legionPlunder</code> to the table that plunder.lua returns, and pre-append plunder. to legionPlunder in the one location where it occurs.

Now, we test the legion plunder function and the press 4 generate archers function to make sure everything works.

[[File:GetStartedWithLuaLesson6-04-RequirePlunder.jpg]]

===Working With a Library===

In programming terms, a "library" is a collection of code that can provide some specified functionality to a programmer without that programmer having to modify the code in the library. Thus far, you have been using the "civ" library to interact with the game, and there has been no need modify it in order to use it in our own events. (Unfortunately, in the case of the civ library, we don't actually know how to modify it.) This is in contrast to much of the code we have written thus far. For example, the code we wrote last lesson to make Selucid elephants attack Egypt is highly specific. You couldn't just cut and paste that code, change the argument of a single function, and get your own goto event. It is still a good example for how to write a goto event, but a user would still have to actually write the event.

If you plan to write some functionality for your scenario that others might find useful, it is worth spending a little extra effort to see if you can write that functionality in a form that will allow others to use it with minimal effort. If you can, then a little extra work on your part might save someone else the trouble of re-inventing the wheel, and allow them to complete their project sooner, or to work on some new feature for you to enjoy. Unfortunately, the Lua scenarios that have been completed at the time of writing haven't been that good at creating re-usable code, at least in part since we were all getting used to Lua. This will hopefully be improved in the future.

For now, we're going to look at a library which is called the General Library (unless someone comes up with a better name) and which can be found [https://forums.civfanatics.com/threads/totpp-the-general-library.647583/ here]. The purpose of this module is to provide relatively simple functionality that probably shouldn't be implemented every time it is needed. This is useful for our purposes, since we can look at relatively self contained and simple functions for our first examples. We'll create a library for generating munitions later.

This library would be used by invoking the line

<code>
local gen = require("generalLibrary")
</code>

If you wanted to make these functions available to the console for testing purposes, you would simply omit the local, thereby making gen a global variable.

Let us now take a look at a function provided by the General Library <code> gen.hasIrrigation(tile)-->boolean</code>. The very first line references the helper function <code> toTile(tile or table)-->tile</code>, so let us include that code, and look at it first.

<code>
-- toTile(tile or table)-->tile
-- gen.toTile(tile or table)-->tile
-- If given a tile object, returns the tile
-- If given coordinates for a tile, returns the tile
-- Causes error otherwise
-- Helper Function (provided to this library as toTile and gen.toTile)
local function toTile(input)
if civ.isTile(input) then
return input
elseif type(input) == "table" then
local xVal = input[1] or input["x"]
local yVal = input[2] or input["y"]
local zVal = input[3] or input["z"] or 0
if type(xVal)=="number" and type(yVal)=="number" and type(zVal)=="number" then
if civ.getTile(xVal,yVal,zVal) then
return civ.getTile(xVal,yVal,zVal)
else
error("Table with values {"..tostring(xVal)..","..tostring(yVal)..
","..tostring(zVal).."} does not correspond to a valid tile.")
end
else
error("Table did not correspond to tile coordinates")
end
else
error("Did not receive a tile object or table of coordinates.")
end
end
gen.toTile = toTile

-- gen.hasIrrigation(tile)-->boolean
-- returns true if tile has irrigation but no farm
-- returns false otherwise
function gen.hasIrrigation(tile)
tile = toTile(tile)
local improvements = tile.improvements
-- irrigation, but no mining, so not farmland
if improvements & 0x04 == 0x04 and improvements & 0x08 == 0 then
return true
else
return false
end
end
</code>

[[File:GetStartedWithLuaLesson6-05-HasIrrigation.jpg]]

Let us begin by looking at the function <code>toTile</code>. The purpose of this function is to allow other functions to accept tile coordinates in a table instead of an actual tile object. The function tries to be reasonably permissive in the coordinates it will accept, allowing both integer indices and lowercase string indices, and by assuming that a missing z value corresponds to map 0. The function also tries to give reasonably helpful errors.

This brings up something that should be considered when making reusable code: what to do if you don't get values you were expecting. One option is to throw an error and bring up the Lua console. This is good for scenario creators, so they know something is wrong, but not so great for end users because the error stops the rest of the event from happening, should the mistake slip through playtesting.

The other option is for the code to fail silently, and try to do what it can. This is the way the old Test of Time macro system often fails. If Civ II doesn't "understand" the event, it just doesn't happen, and doesn't bother the player with the error. This means that the scenario will still mostly work, but it is harder to catch issues during playtesting. Sometimes, this means doing something "sensible" if the input isn't of the expected type, and might make the code easier to write, since you don't have to handle inputs differently.

A third option is to write your code such that both things can be done. At the top of your code, you put in a variable named "debugMode" or something, and make all the functions throw errors when true, and fail silently when false. Then you playtest with debugMode set to true, and release with debug mode set to false. However, this means extra work in writing your code and you also have to test everything with debug mode off.

For toTile, I went with the fail with error option, since that will allow every function that uses toTile to assume it is receiving proper data. It also seems unlikely that people will be regularly trying to check tiles that don't exist or have tables with tiles and units and improvement objects all in one. And if they do, "guarding" is fairly straightforward anyway (as we've done in previous lessons).

Although toTile is mainly meant to be a helper function for the General Library, it is also put into the gen table to be made available to end users, since it offers useful functionality. Hence, <code> gen.toTile=toTile</code>. Note that we could have given toTile a different name in the gen table that this module will return, such as gen.tableToTile=toTile. In fact, we could refer to the same function with multiple keys in the gen table, if we want to.

Next, we will look at gen.hasIrrigation.

The first thing to notice is that local is not being used to define this function. That is because we're putting the function for gen.hasIrrigation directly into the gen table that this module will return. We could define hasIrrigation as a local variable and then copy it into the gen table. However, there is a decent chance that the General Library will have more than 200 functions by the time everything is complete, since it is meant to provide a lot of building block functionality and keep it in one place, and we will run into trouble if we assign 200 local variables in a single function (which a required lua file acts as).

Perhaps the most striking thing is that we begin by changing the value of tile, the argument of the function. It looks like we're making a global variable named tile, but we're not. When you specify the names of the arguments for a function (in this case tile), you create local variables for that function, which can be given new values just as if you had explicitly used the local keyword.

Beyond that, we extract the integer representing the tile improvements into a local variable (which upon later reflection isn't really necessary), and check that the irrigation bit is set to 1 and the mining bit is set to 0. Refer to lesson 5 for why this works. In fact, we could have simply returned the value of the if statement, rather than specifying return true and return false, although it is very slightly clearer what is going on in the expanded version of the code.

Now, let us write a function to place irrigation on a square. It seems pretty clear that we should do nothing if the tile has a city, but we also have to decide what to do if there is mining or farmland on the tile, since those interfere with placing irrigation. We'll just remove them, on the basis that if we're trying to "place irrigation," then we want irrigation to be there when we are finished.

<code>
function gen.placeIrrigation(tile)
tile = toTile(tile)
</code>

These lines open the function and convert a table of coordinates to a tile if necessary.

<code>
if tile.city then
return
end
</code>

If the tile has a city, return so nothing else is done in the function.

<code>
-- Set irrigation bit to 1
tile.improvements = tile.improvements | 0x04
-- Set mining bit to 0
tile.improvements = tile.improvements & ~0x08
end
</code>

Set the irrigation bit to 1 and the mining bit to 0.

The functions in this library don't have to be complex, and in fact, most probably shouldn't be. They just have to make life easier for the end user. If you reach this lesson before the General Library is considered "complete," your assignment now is to submit some work for it. If you don't feel comfortable doing bitwise operations, you can test the work of others or submit functions that simplify other tasks. However, there are also some helper functions in the library to facilitate changing bits, so you might also consider working on the unit type flags functions. Remember, if you want to make functions available to the console for testing purposes, they must be global variables.

=== The Threshold Table and First Look at Metatables===

Consider a scenario design situation that occurred in Over the Reich: a bomber is generating some bombs via a key press, and the number of bombs it should generate is dependant on its current remaining hitpoints. The more hitpoints the bomber has, the more bombs it should generate. What we want is to specify that if a bomber has between x and y hitpoints, it should produce 2 bombs. That is, for a given type of bomber, we want to have, for example,

hp >= 16 --> 4 bombs
16 > hp >= 12 --> 3 bombs
12 > hp >= 9 --> 2 bombs
9 > hp >= 4 --> 1 bomb
4 > hp >= 0 --> 0 bombs

Unfortunately, Lua tables do not naturally encode this kind of association by default. However, Lua does have a feature called metatables, which allows us to change the behaviour of tables. (This will be a much better way to make the specification than I ended up writing in Over the Reich.)

A metatable is a table that we can "attach" to another table, and then the metatable changes the behaviour of that table. We'll only look at metatables briefly here, but more information can be found [https://www.tutorialspoint.com/lua/lua_metatables.htm here].

What we want is a data structure that can accept numerical "key values" that are between the key values explicitly specified, and return the appropriate value for those keys. We will call this data structure a threshold table, since we are specifying threshold values as keys. We can do this by assigning the following metatable:

<code>
local mt = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
</code>

If we run <code> setmetatable(myTable,mt)</code>, then whenever we ask for an index from myTable and that index doesn't currently exist in myTable, the function assigned to __index will run. Now let us examine the function.

If the type of the key is not a number, then we return whatever the table value is for that key. We use the function rawget, because the standard <code>thresholdTable[key]</code> will invoke this function again if the key doesn't exist, and so never return an answer (when we want it to return nil).

If the key type is a number, then we look for the largest numerical index that is also less than or equal to the key value. We return a default value of false if the key submitted is smaller than all numerical values. False is chosen over nil, so that a maximum value can be set by setting the value of a numerical index to false. Using the key [-math.huge] allows a return value to be set for all numbers (since all numbers are greater than -math.huge).

Since we don't want scenario creators to have to re-create threshold tables every time they need them, we'll add this functionality to the General Library

<code>
local thresholdTableMetatable = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
-- gen.makeThresholdTable(table or nil)-->thresholdTable
function gen.makeThresholdTable(inputTable)
inputTable = inputTable or {}
return setmetatable(inputTable,thresholdTableMetatable)
end
</code>

[[File:GetStartedWithLuaLesson6-06-ThresholdTable.jpg]]

===A Munition Generation Module===

Now, let us write some re-usable code for a human player to generate units by pressing a key while an appropriate unit is active. This sort of code could be used for ranged attacks (generating a "munition") and also for recruiting mercenaries by paying gold.

The first thing we will want to do is to decide how our code will be used by the end user. This will, perhaps, change by the time we finish writing the code, but it will at least give us a starting point.

spawnUnit(generatingUnit, specificationTable)--> table of unitCreated

Our goal is that when a player attempts to generate a unit using another unit, they will provide the unit spawning the new unit, and a table of information specifying if a unit (or units) can be spawned and anything else that must happen while spawning (like paying money, expending movement points, etc.).

We have an option here. We could have the scenario creator provide the specification table as a required file for our module, or the creator can provide it at the time spawnUnit is called. I choose the latter for a couple of reasons. The first is that it allows the player to have more than one specification table, either because more than one key can spawn a unit, or because the specification can change over time. The other is reason is so that the creator can make the table in the events.lua file if desired (since our module can't require information from events.lua).

Having decided that our generateUnit events are going to be specified by a table, we have to decide what the contents of that table should be. It seems pretty reasonable to index the specificationTable with the index of the unit type of each unit that can generate using the information in the table. If a unit type id number is missing, that unit doesn't generate a munition (or recruit a unit).

The value for each unit type id in the specification table will be a table that specifies how and if that unit generates other units.

--specificationTable[unitType.id]={
--
-- goldCost = integer or nil
-- amount of gold it costs to generate a unit
-- absent means 0
-- minTreasury = integer or nil
-- minimum amount of gold in treasury to generate a unit
-- absent means refer to gold cost
-- (tribe will generate and be set to 0 if treasury is less than goldCost)
-- treasuryFailMessage = string or nil
-- A message to be displayed if the unit fails to spawn a unit due to an
-- insufficient treasury
-- nil means no message

-- There are three ways to specify move costs, in full movement points,
-- in "atomic" movement points, and as a fraction of total movement points for the
-- unit type. Use only one kind per unit type

-- moveCost = integer or nil
-- movement points to be expended generating the unit
-- "full" movement points
-- absent means 0
-- minMove = integer or nil
-- minimum remaining movement points to be allowed to generate a unit
-- "full" movement points
-- absent means any movement points for land/sea, 2 "atomic" for air units
-- postGenMinMove = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostAtomic = integer or nil
-- movement points to be expended generating the unit
-- refers to the unit.moveSpent movement points
-- absent means 0
-- minMoveAtomic = integer or nil
-- minumum remaining movement points to be allowed to generate a unit
-- referes to the unit.moveSpent movement points
-- absent means any movement points for land, 2 "atomic" for air units
-- postGenMinMoveAtomic = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostFraction = number in [0,1] or nil
-- fraction of unit's total movement points expended generating the unit
-- round up to nearest "atomic" movement point
-- absent means 0
-- minMoveFraction = number in [0,1] or nil
-- fraction of unit's total movement points that must remain to be allowed
-- to generate a unit
-- absent means any movement points for land, 2 "atomic" for air units
-- round up to nearest "atomic" movement point
-- postGenMinMoveFraction = number in [0,1] or nil
-- a unit will be left with at least this many movement points after
-- the generation function, round up to nearest "atomic" move point
-- absent means 0 for land/sea, 1 "atomic" for air units
-- roundFractionFull = bool or nil
-- fractional movement cost and minimum are rounded up to full movement point
-- instead of atomic movement point
-- nil/false means don't
-- roundFractionFullDown = bool or nil
-- fractional cost and minimum are rounded down to full move point
-- nil/false means don't
-- minMoveFailMessage = string or nil
-- a message to be displayed if a unit is not generated due to insufficient
-- movement points.
-- nil means no message

-- allowedTerrainTypes = table of integers or nil
-- a unit may only be generated if the tile it is standing on
-- corresponds to one of numbers in the table
-- nil means the unit can be generated on any terrain type
-- terrainTypeFailMessage = string or nil
-- message to be displayed if a unit is not generated due to standing
-- on the incorrect terrain

-- requiredTech = tech object or nil
-- the generating civ must have this technology in order to generate
-- the unit
-- nil means no requirement
-- techFailMessage = string or nil
-- message to be displayed if a unit is not generated due to not having
-- the correct technology

-- payload = boolean or string
-- if true, unit must have a home city in order to generate munitions
-- and generating munitions sets the home city to NONE
-- payloadFailMessage = string or nil
-- message to be displayed if a unit is not generated due to the
-- payload restriction
-- payloadRestrictionCheck = nil or function(unit)-->boolean
-- If function returns false, the home city is not valid for giving the
-- unit a payload. This will be checked when the unit is activated, when
-- the unit is given a new home city with the 'h' key and when the unit
-- tries to generate a munition
-- nil means no restriction
-- payloadRestrictionMessage = nil or string
-- message to show if a unit fails the payloadRestrictionCheck

-- canGenerateFunction = nil or function(unit)-->boolean
-- This function applied to the generating unit must return true in order
-- for a unit to be spawned. All other conditions still apply.
-- any failure message should be part of canGenerateFunction
-- absent means no extra conditions

-- generateUnitFunction = nil or function(unit)-->table of unit
-- This function creates the unit or units to be generated
-- and returns a table containing those units
-- Ignore any specifications prefixed with * if this is used
-- nil means use other specifications

--*generatedUnitType = unitType
-- The type of unit to be generated
-- can't be nil unless generateUnitFunction is used instead

--*giveVeteran = bool or nil
-- generated unit(s) given veteran status if true
-- nil or false means don't give vet status
-- if true, overrides copyVeteranStatus

--*copyVeteranStatus = bool or nil
-- generated unit(s) copy veteran status of generating unit if true
-- nil or false means don't give vet status

--*setHomeCityFunction = nil or function(generatingUnit)-->cityObject
-- determines what home city the spawned unit should have
-- nil means a home city of NONE

--*numberToGenerate = nil or number or thresholdTable or function(generatingUnit)-->number
-- if nil, generate 1 unit in all circumstances
-- if integer, generate that many units (generate 0 if number less than 0)
-- if number not integer, generate floor(number), and 1 more with
-- probability number-floor(number)
-- if thresholdTable, use remaining hp as the key, to get the number to create
-- if function, get the number as the returned value of the function

-- activate = bool or nil
-- Activates one of the generated units if true. If generateUnitFunction was used,
-- the unit at index 1 is activated, if index 1 has a value. (if not, any unit in
-- the list might be chosen)

The very last entry brings forward a change that must be made to our unit generation specification. Lua's activate unit command doesn't run the unit activation trigger, even though the active unit is changed. Therefore, we must do that manually. Hence,

<code>spawnUnit(generatingUnit, specificationTable)--> table of unitCreated</code>

becomes

<code>spawnUnit(generatingUnit,specificationTable,unitActivationCode)-->table of unitCreated</code>

Perhaps we will change it again later.

I've decided to try a different instructional technique for this section. Instead of writing the code and then going through it section by section, I've recorded a video of my coding and testing this module, and I attempt to explain some of the stuff that I do along the way.

I'm not sure of the value of the video. If you find that there seems to be little useful content relative to the time it takes to watch, then feel free to skip it and continue the lesson. I don't teach anything "new" in it, so you won't miss anything crucial. However, it should be pretty close to how programming Lua can actually happen in the "real world." While I did give some thought to how to write the module before I started, I do attempt to solve problems in real time, and make mistakes that are not discovered for a while (including one where I try to explain how I solve a problem and then not actually do a crucial part).

You can find the code [https://forums.civfanatics.com/threads/totpp-the-munitions-library.647910/ here]. Even if you decide not to watch the video, download the code and try testing some of the features based on the specification above. If you find any bugs, submit a fix (or at least report the issue).

The video can be found [https://youtu.be/XxPyNknGlAo here].

===A Unit Attack Bonus for Complementary Units in Square===

Something we might like to do is to give units an attack bonus if they attack from a square with some special unit, for example a "leader" unit. The [[Napoléon I]] scenario, for example, gives an attack bonus to units if a commander unit, such as Napoleon, is in the square when the unit is activated (the unit can subsequently move and still retain the bonus as long as no other unit is selected). We will now make a module providing the same functionality.

We first have to have a basic idea of how this functionality should work. When a unit is activated, the onActivateUnit event checks if the newly activated unit should get an attack bonus, based on the other units in the square. If the unit deserves an attack bonus, the corresponding unitType.attack entry is changed, and all the attack value of all other units is reset to the default value. If the activated unit also does not deserve an attack bonus, that value is also set to the default value.

This now leads us to some more possibilities. Should multiple bonus units lead to multiple bonuses or only apply the best one? For example, suppose a legion gets a bonus if an archer is also in the same square. Should two archers provide twice the bonus? Perhaps two archers should provide a larger bonus than one, but not twice as much. Perhaps a legion should also get a bonus if there is a catapult in the square, but that bonus should apply even if the maximum archer bonus is already achieved. It seems like perhaps there should be a "ranged unit" bonus, an "artillery unit" bonus and maybe a "cavalry" bonus which should all impact the legion's attack value. It's looking like we might end up demanding that a scenario creator make a big complicated table in order to use this functionality, even if they only have simple needs.

What we can do to alleviate this is to write a "simple" version of the event that is easy to use (and program), and also write a more complicated version that gives the expanded capability.

Specification Table for simpleAttackBonus

--simpleAttackBonusTable[activeUnit.type.id] ={[bonusUnitType.id]=bonusNumber}
--simpleAttackBonusTable.type = string
--if simpleAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if simpleAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
--if simpleAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- if simpleAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- if simpleAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
--simpleAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

The relevant first draft of the code is as follows:

<code>
local function simpleAttackBonus(activeUnit,simpleAttackBonusTable,defaultAttackTable)
-- reset all unit attack values
for unitTypeID,attackValue in pairs(defaultAttackTable) do
civ.getUnitType(unitTypeID).attack = attackValue
end
local unitBonusTable = simpleAttackBonusTable[activeUnit.type.id]
if not unitBonusTable then
-- unitBonusTable is nil (or false), so the active unit can't
-- get a bonus
return
end
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
local bestBonusSoFar = 0
for unit in activeUnit.location.units do
if unitBonusTable[unit.type.id] and unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
if bestBonusSoFar == 0 then
-- If no bonus unit is found, this will be true, so do nothing else
return
end
-- set the new attack and return
if string.lower(simpleAttackBonusTable.type) == "addBonus" then
activeUnit.type.attack = activeUnit.type.attack+bestBonusSoFar
return
end
local attackMultiplier = 1
if type(simpleAttackBonusTable.type) ~= "string" then
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
elseif string.lower(simpleAttackBonusTable.type) == "addpercent" then
attackMultiplier = (100+bestBonusSoFar)/100
elseif string.lower(simpleAttackBonusTable.type) == "addfraction" then
attackMultiplier = 1+bestBonusSoFar
elseif string.lower(simpleAttackBonusTable.type) == "multiplypercent" then
attackMultiplier = bestBonusSoFar/100
elseif string.lower(simpleAttackBonusTable.type) == "multiply" then
attackMultiplier = bestBonusSoFar
else
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
end
-- apply the bonus and round as appropriate
if type(simpleAttackBonusTable.round) ~= "string" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
elseif string.lower(simpleAttackBonusTable.round) == "up" then
activeUnit.type.attack = math.ceil(activeUnit.type.attack*attackMultiplier)
return
elseif string.lower(simpleAttackBonusTable.round) == "down" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier)
return
else
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
end
end
</code>

Now let us go over this section by section.

[[File:GetStartedWithLuaLesson6-07-AttackBonus1.jpg]]

The first thing we do is to reset all the attack values of all the unit types. That way, if a bonus existed for the last unit activated, that bonus no longer applies. If a unit type is not in the defaultAttackTable, then we don't have the information to reset the attack value anyway, so we can safely ignore it by using the pairs function to iterate over the table.

Now, we must find out if the newly activated unit deserves a bonus. For that, we get the table associated with the active unit's type. If the value is nil instead of a table, then the unit's type is not in the simpleAttackBonusTable, so there is no bonus to apply and the function returns.

If the unit is eligible for bonuses, we then check the units in the square to see if any bonuses actually apply. We've seen this kind of code before. If the unit in the stack can provide a bonus, and that bonus is better than the best bonus already found, the unit now provides the best bonus. All bonus types that we can have are better if they are larger, and we are not comparing between bonus types, so a simple numerical comparison will do. All bonuses are larger than 0 in our formulation, so 0 is a good starting value in the search.

If the best bonus so far is still 0, there is no bonus, so the function can return.

At this point, it occurs to me that when searching for the best bonus, we should exclude the active unit from the search. That way, you can have a "strength in numbers" bonus, for example. The relevant change to the code is:

<code>
for unit in activeUnit.location.units do
if unit ~= activeUnit and unitBonusTable[unit.type.id] and
unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
</code>

Next, consider

[[File:GetStartedWithLuaLesson6-08-AttackBonus2.jpg]]

Here, we apply the bonus that we've found. We use string.lower on simpleAttackBonusTable.type so that we don't have to worry about capitalization. That does, however, require a correction to "addBonus", since a lower case string will never be equal to that.

"addbonus" is the only type of bonus that is directly added to the existing attack value. All other bonus types are a form of multiplication. Since the addition is straightforward and doesn't require any rounding, the activeUnit's type attack value can be changed immediately, and the function execution ended with return.

When there is only one bonus being applied, all other types of bonus are different ways of expressing how to multiply the existing attack value to get a new one, so we simply convert to the appropriate multiplier, and provide an error message if the type of bonus is not one of the valid possibilities.

Finally, we round the attack value to an appropriate integer (since unit attack values must be integers), change the attack value of the active unit's type, and return to end the function execution.

Now, we integrate into events.lua by using

<code>
attackBonus = require("attackBonus")
</code>

The relevant integration code for events.lua is
<code>
local defaultAttackValueTable = {[unitAliases.legion.id]=4}
local simpleAttackBonusTable ={}
simpleAttackBonusTable.type = "addbonus"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=3,[unitAliases.musketeer.id]=4}

local function doOnActivation(unit,source)
munitions.payloadRestrictionCheck(unit,munitionSpecificationTable)
attackBonus.simpleAttackBonus(unit,simpleAttackBonusTable,defaultAttackValueTable)
end
</code>

We can check that the bonus is being applied correctly by checking the Civlopedia entry for legion and looking at the attack value. The following cases must be tested (remember that activating a unit from the city screen doesn't run the onActivation event, so activate from the map).

Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (7 attack)
Legion activated with musketeer, but no archer (8 attack)
Legion activated with archer and musketeer (8 attack)
Legion activated with 2 archer, no musketeer (7 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

I recommend making a stack for each of these cases and activating them one by one.
To facilitate the test, add the following line to doOnActivation

<code>
civ.ui.text(tostring(unit.type.attack))
</code>
You will want to comment out this line after testing.

Next, change simpleAttackBonusTable to do "addpercent"
<code>
simpleAttackBonusTable.type = "addpercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=30,[unitAliases.musketeer.id]=70}
</code>

With no rounding set, standard rounding is used
Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)
Legion activated with archer and musketeer (7 attack)
Legion activated with 2 archer, no musketeer (5 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

These numbers test both rounding up and rounding down.

Now, use
simpleAttackBonusTable.round="up"
Legion activated with archer, but no musketeer (6 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next,
simpleAttackBonusTable.round="down"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (6 (6.8) attack)

simpleAttackBonusTable.round="standard"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next, we test "addfraction". Since we've tested all the rounding options, we don't have to do that again.

<code>
simpleAttackBonusTable.type = "addfraction"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=0.3,[unitAliases.musketeer.id]=0.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiplypercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=130,[unitAliases.musketeer.id]=170}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiply"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Before we finish, we should test a legion bonus for the legion.
<code>
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.legion.id]=2,[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>

Legion alone should have 4 attack.
A second legion on the square should provide 8 attack instead.

Now, let us try to formulate a more complicated bonus system. One thing we mentioned is that we'd like the ability to get bonuses from multiple units, and to be able to get bonuses from different "classes" of units (like "artillery," "cavalry," and "ranged attackers." Something else we might want to do is to allow different kinds of bonuses. That is, maybe some units should provide a fixed +2 to any unit receiving the bonus, so that it is better at improving units with a low attack value, while other units should provide a percentage bonus (making them better at supporting units with an already high attack value). It turns out that both of these ideas are not too difficult to implement individually, but that trying to implement them together makes it problematic to find the best bonus.

Let us implement a bonus system with multiple categories but only one bonus type. In our specification, we will first specify a data type called "bonusCategory." It is still just a table (though we could add a metatable if we wanted), but it will help us make our specification clearer.

<code>
-- A "bonusCategory" is a table
-- bonusCategory = {[bonusUnitType.id]=bonusNumber, maxBonusUnits=integer or nil, nextBonusValue = fraction or nil}
-- In a bonusCategory, the value for bonusUnitType.id tells what the base bonus for that unit type is,
-- maxBonusUnits is the maximum number of units that can provide a bonus in this category,
-- nextBonusValue tells how much to reduce the bonus for each subsequent unit,
-- e.g. nextBonusValue = 0.7, and 5 units, which each have a bonusNumber=1
-- The total bonus is 1(0.7)^0+.7+(.7)(.7)+(.7)^3+(.7)^4 = 1+.7+.49+.343+.2401=2.7731
-- (which would be rounded as specified)
-- nil means nextBonusValue=1
--
-- If a unit type is in two bonus categories for the same unit, there is no guarantee that the
-- best bonus will be achieved
</code>

So, the bonus category is indexed by unitType id numbers for units that can give a bonus, and the corresponding bonus. It also specifies the maximum number of units that can give a bonus, and a number that governs how to reduce a bonus for extra units. That way, there can be diminishing returns for bonuses.

Next, we look at the specification for the categoryAttackBonusTable

<code>
--categoryAttackBonusTable[activeUnit.type.id] =table of bonusCategory
--categoryAttackBonusTable.type = string
--if categoryAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if categoryAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
-- for multiple unit bonuses, add up all the percents, then compute the bonus
-- i.e. 50% bonus and 50% bonus is 100% bonus, not 125%
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 50% bonus units become 50% + 25%
-- so attack 6 --> 10.5
--if categoryAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- for multiple unit bonuses, add up the fractions, then compute the bonus
-- i.e. .5 bonus and .5 bonus is 1+.5+.5= 2x bonus, not 2.25x
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 .5 bonus units become .5+.25
-- so attack 6 --> 10.5
-- if categoryAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- bonuses are multiplied together, i.e. 150% and 150% yields 225% of original value
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 100, i.e. nextBonusValue=.5 2 150% bonuses become 150% and 125%
-- so attack 6 --> 11.25
-- if categoryAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
-- bonuses are multiplied together, i.e. 1.5 and 1.5 yields 2.25x
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 1, i.e. nextBonusValue=.5 and two 1.5 bonuses become 1.5 and 1.25
-- so attack 6 --> 11.25
--categoryAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

-- If the active unit can get a bonus, go through each category and compute the bonus for that category.
-- Then, combine the bonuses for all categories to get the overall bonus, and round the result
</code>

With the bonusCategory defined, the value of the unit indices of categoryAttackBonusTable become easy to define. Most of the specification is showing what exactly the different bonus categories mean, so the end user can use them properly. It's not strictly necessary to offer so many choices to the end user on how to specify data, but it can be more convenient.

Here is the actual code (before testing) to implement this more general version of attack bonuses.

<code>
-- HELPER FUNCTION
-- findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable) --> number or false
-- usedUnitTable is indexed by the i.d. number of units, and if the value for a unit is true,
-- then it has already been used for a bonus (and, so, is not eligible)
-- The function returns the bonus (before nextBonusValue is applied) if there is one, and marks the
-- unit as used in the usedUnitTable
-- returns false if no unit qualifies
local function findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable)
local bestBonusSoFar = 0
local bestUnitSoFar = nil
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
for unit in tile.units do
if not usedUnitTable[unit.id] and bonusCategory[unit.type.id]
and bonusCategory[unit.type.id] > bestBonusSoFar then
bestUnitSoFar = unit
bestBonusSoFar = bonusCategory[unit.type.id]
end
end
if bestUnitSoFar then
usedUnitTable[bestUnitSoFar.id] = true
return bestBonusSoFar
else
return false
end
end

-- HELPER FUNCTION
-- computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
-- Computes the bonus that the active unit will receive from this category, taking into
-- account the type of bonus for the table
local function computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
local bonusThusFar = nil
if bonusType == "multiply" then
bonusThusFar = 1
elseif bonusType == "multiplypercent" then
bonusThusFar = 100
else
bonusThusFar = 0
end
local bonusDiscount = 1
for i=1,(bonusCategory.maxBonusUnits or 10000) do
local currentBonus =findBestBonusInUnitStack(activeUnit.location,bonusCategory,usedUnitTable)
if not currentBonus then
-- no more valid bonuses for this category
break
end
if bonusType == "multiply" then
bonusThusFar = bonusThusFar*((currentBonus-1)*bonusDiscount+1)
elseif bonusType =="multiplypercent" then
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
else
bonusThusFar = bonusThusFar+currentBonus*bonusDiscount
end
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
end
return bonusThusFar
end

local function categoryAttackBonus(activeUnit,categoryAttackBonusTable,defaultAttackTable)
local bonusInfoTable = categoryAttackBonusTable[activeUnit.type.id]
if not bonusInfoTable then
-- unit doesn't get a bonus
return
end
-- keep track of bonuses already computed
local bonusResultsTable = {}
-- keep track of units that have already been "used" for a bonus
local usedUnitTable = {[activeUnit.id]=true}
for index,bonusCategory in pairs(bonusInfoTable) do
bonusResultsTable[index]=computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
end
-- compute the bonus
local bonusType = string.lower(categoryAttackBonusTable.type)
local resultAttackBeforeRounding = nil
if bonusType == "multiply" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "multiplypercent" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult/100
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "addbonus" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack+bonus
elseif bonusType == "addfraction" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
elseif bonusType == "addpercent" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+(bonusResult/100)
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
else
error("categoryAttackBonus: categoryAttackBonusTable.type is not a valid value.")
end
-- apply the bonus and round as appropriate
local roundType = categoryAttackBonusTable.round
if type(roundType) ~= "string" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
elseif roundType == "up" then
activeUnit.type.attack = math.ceil(resultAttackBeforeRounding)
return
elseif roundType == "down" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding)
return
else
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
end
end
</code>

The two helper functions for computeCategoryBonus are only used once each in the code, so making them helper functions does not help us re-use code. However, what it does do is to break down the function design process into smaller tasks, which are each more manageable to complete. If you're trying to keep track of too many things in your program, try writing a few helper functions to handle individual tasks. We'll look at the helper functions when we actually arrive at them in the code.

[[File:GetStartedWithLuaLesson6-09-CategoryAtkBonus1.jpg]]

If there is no entry in the categoryAttackBonusTable or the active unit's type, then the function returns without doing anything further.

The bonusResultsTable keeps track of the total bonus from each category, so they can be added or multiplied together after all the category bonuses are applied. The usedUnitsTable keeps track of units that are no longer eligible to contribute to a bonus (such as if they have already contributed), and we initialize it with the active unit, so that it doesn't provide a bonus to itself.

The for loop computes the bonus for every category, and stores the value in the bonusResultsTable, for use later.Now, let us look at the helper functions.

First up is findBestBonusInUnitStack

[[File:GetStartedWithLuaLesson6-10-CategoryAtkBonus2.jpg]]

This basically does what it says in the name. For a bonusCategory, it finds the unit in the tile that provides the best bonus, and has not already provided a bonus elsewhere. If there is no qualifying unit, false is returned. If there is, that unit's bonus is returned, and the unit's id is entered into the usedUnitTable, so that unit can't provide another bonus for the active unit. We've searched for the best of something before, so there is little need to go over it again.

Next is computeCategoryBonus

[[File:GetStartedWithLuaLesson6-11-CategoryAtkBonus3.jpg]]

Here, we're computing the bonus for the entire bonusCategory. We need the bonus type in order to know what kind of math to do. The math itself is not very interesting. We also initialize the bonusDiscount, which keeps track of the fraction of the next unit's bonus that will actually be applied.

Next, we enter a for loop that will run one time for each possible bonus that there can be in a bonus category. If bonusCategory.maxBonusUnits is nil, then we set an arbitrary limit of 10000 units, which is very unlikely to happen in practice.

At each iteration of the loop, the best available bonus in the stack is found. If no unit was eligible to provide a bonus, then the current bonus is false, and the "break" command is issued. Break immediately exits the current loop. So, our program doesn't run 10000 loops if there is no maximum number of bonus units, it just breaks at an appropriate time.

After the bonus is found, it is added to or multiplied with the bonus already found. The bonus computed in this way will be the largest possible, since the bonus provided does not depend on the other units chosen (so we don't have a situation where "catapult" and "rock" are both useless, but "catapult" and "rock" chosen together are best). Also, since the best bonus is chosen first, the smallest bonus discount applies to it, so the cost imposed by the discounting is smallest.

Finally, we update the bonusDisount. Here, I notice a problem in the code as written, since bonusCategory.nextBonusValue is allowed to be nil. Replace
<code>
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
</code>
with
<code>
bonusDiscount = bonusDiscount*(bonusCategory.nextBonusValue or 1)
</code>
so that if there is no nextBonusValue, a default of 1 is used, and the bonusDiscount stays at 1 (i.e. no discount is applied).

We return to categoryAttackBonus to see

[[File:GetStartedWithLuaLesson6-12-CategoryAtkBonus4.jpg]]

From here, we combine the bonuses stored in bonusResultsTable, the exact way of doing so being dependant on the type of bonus involved. The math itself isn't very interesting, and doesn't seem all that likely to come up in this exact form elsewhere. If you need help with the mathematical details of some event you want to write, ask in the forums. There's a good chance someone has the skills to help you solve your specific problem.

For every type of bonus, the result is stored in resultAttackBeforeRounding, so that variable can be rounded up or down as specified by the rounding type.

Here, I notice another error. We should restrict the attack value for a unit to not exceed 98. We can do that with a math.min(value, 98).

Now, we need to test the various aspects of the attack bonus program, so we need an appropriate table
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addbonus"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=2,[unitAliases.chariot.id]=4,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=2,[unitAliases.musketeer.id]=4,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Also, comment out the old attack bonus line, and put in a new one
<code>
attackBonus.categoryAttackBonus(unit,categoryAttackBonusTable,defaultAttackValueTable)
</code>

Expected Test Results when type is "addbonus"
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

Already, we find a problem. Although there were no syntax errors to fix, I forgot to reset unit attack values. So, very quickly, the legions keep gathering extra attack values when they are activated (since the base attack is not reset to 4). Since this is happening anyway, I'll test the 98 attack value maximum. That appears to work, at least in the case of no specified rounding.

Cut and paste the appropriate lines from the simpleAttackBonus to the categoryAttackBonus, and save.

With that bug fixed, everything works as expected.

Next, we change the categoryAttackBonusTable to

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addpercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=50,[unitAliases.chariot.id]=100,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=50,[unitAliases.musketeer.id]=100,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>

Expected Test Results when type is "addpercent". These are the same, since adding we're adding percentages of the same base value of 4. So a value of 2 is the same as adding 50% of 4.
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

The results are the same.

Similarly,

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addfraction"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=.50,[unitAliases.chariot.id]=1.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=.50,[unitAliases.musketeer.id]=1.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

We'll have to do some new calculations, now, since multiply and multiplyfraction give different results than the various adding formulations.

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiply"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=1.50,[unitAliases.chariot.id]=2.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=1.50,[unitAliases.musketeer.id]=2.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Finally, we use multiplyPercent, and check for the same results
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=150,[unitAliases.musketeer.id]=200,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Quickly, I find that if a bonus applies, that bonus makes the attack value of a legion 98. I failed to multiply percents correctly in computeCategoryBonus. The Line
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
</code>
Is changed to
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+100)/100
</code>

Finally, Change archer bonus to 110 and musketeer bonus to 120 (so a unit will make a legion have 4.4 and 4.8 value before rounding), and test the rounding options. You will find they all work.

At the moment, we don't have a way to mix different types of bonuses. As said earlier, we might want this so that some units can be better at giving bonuses to low attack units than to high attack units, while others give a percentage bonus to everything. We could now write a bonus system that allows for multiple types of bonuses. However, the current bonus system allows for the bonus to change per unit. This means that we can, for example, convert a +2 attack bonus to a plus 100% bonus for a unit with 2 attack, and a plus 50% bonus for a unit with 4 attack. In the case of the multiplied bonuses, this will make the bonus more powerful if there is more than one. That is, 2 attack, +2 twice is 6, but if +2 is changed to x2, then the multiplied bonus brings the attack up to 8. However, this seems like it would be a relatively unlikely problem, and there are other things this code can't handle, so we'll let someone else make the code if they actually need it.

So, what we'll do is write a function that will change all appropriate entries in the categoryAttackBonusTable to reflect a different value. Hence,

<code>
-- plusFixed(unitType,number,categoryAttackBonusTable) --> void
-- changes the bonus given by unit type to any unit to be equivalent
-- to adding number to that unit's attack power
</code>

Here, an issue with tables arises. It is very likely that when someone defines their cateogryAttackBonusTable, they'll define it something like this
<code>
local rangeBonusCategory = {[unitAliases.archer.id]=.25,[unitAliases.musketeer.id]=.5}
local bonusTableForInfantry = {rangeBonusCategory}
local cABT = {type="addfraction"}
cABT[unitAliases.phalanx.id]=bonusTableForInfantry
cABT[unitAliases.legion.id] = bonusTableForInfantry
</code>
However, this means that both <code> cABT[unitAliases.legion.id] </code> and <code> cABT[unitAliases.phalanx.id] </code> actually refer to the same piece of memory, and changing cABT[unitAliases.legion.id][1][unitAliases.archer.id] will also change the value at cABT[unitAliases.phalanx.id][1][unitAliases.archer.id]. This is because of the way lua tables are designed. This design can be useful, for example it allowed us to make changes to usedUnitsTable in the last function without having to copy the table, make changes to the copy of the table, and then replace the original table with that copy as a return value. However, it also requires us to be careful when we make changes to entries in tables. In this case, we'll simply copy the table and all its sub values into a new table.

The code to do this is given by
<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

We will explain this code in the next section, since it involves a programming technique which we haven't discussed before.

For now, we analyze plusFixed:

<code>
-- plusFixed({[unitType1.id]=fixedBonus,[unitType2.id]=fixedBonus},categoryAttackBonusTable) --> void
-- changes the bonus given by unitTypeI.id to a unit to be equivalent to
-- to adding number to that unit's attack power. If the unit doesn't receive a bonus
-- from the unitType, then it won't after applying plusFixed.
-- The value of the existing bonus is ignored.

local function plusFixed(fixedUnitBonusTable,categoryAttackBonusTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
for bonusReceivingUnitTypeID,bonusTable in pairs(categoryAttackBonusTable) do
-- replace bonusTable with an equivalent table that is not referened
-- anywhere else, so that changes to it can be made without impacting
-- data elsewhere
categoryAttackBonusTable[bonusReceivingUnitTypeID] = duplicateTable(bonusTable)
-- make bonusTable refer to the "current" bonus table for the unit type
bonusTable =categoryAttackBonusTable[bonusReceivingUnitTypeID]
-- For each unit type in the fixedUnitBonusTable, check if any bonus category
-- in the bonusTable corresponds to it. If so, make the change
for bonusGivingUnitTypeID,fixedBonusValue in pairs(fixedUnitBonusTable) do
-- get the attack of the unit type
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
-- in each bonus category, check if the giver's unit type id is there,
-- if so, change to the correct attack
for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
if bonusCategory[bonusGivingUnitTypeID] then
-- change the bonus appropriately
if bonusType == "addbonus" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue
elseif bonusType == "addpercent" then
bonusCategory[bonusGivingUnitTypeID]=100*fixedBonusValue/baseAttack
elseif bonusType == "addfraction" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue/baseAttack
elseif bonusType == "multiplypercent" then
bonusCategory[bonusGivingUnitTypeID]=100*(fixedBonusValue+baseAttack)/baseAttack
elseif bonusType == "multiply" then
bonusCategory[bonusGivingUnitTypeID]=(fixedBonusValue+baseAttack)/baseAttach
else
error("pluxFixed: categoryAttackBonusTable.type does not have an acceptable value.")
end
end
end
end
end
end
</code>

[[File:GetStartedWithLuaLesson6-13-plusFixed1.jpg]]

As before, we save the bonusType in lower case, since we'll be using it a lot later. Next, we open a for loop, where the index is the id of the unit type receiving the bonus, and the value is the bonus table for that unit type. Next, we duplicate the bonus table, so that we have a table we can change without impacting anything elsewhere, and we store the duplicated table in categoryAttackBonusTable in place of the original bonusTable for the current bonus receiving unit id. Next, we assign this duplicated table to the variable bonusTable, so we can refer to it later in the code.

[[File:GetStartedWithLuaLesson6-14-plusFixed2.jpg]]

We now perform the following actions for each unitType.id and corresponding fixedBonusValue submitted in the fixedUnitBonusTable.

First, get the attack of the bonus receiving unit, since we'll need that in order to customize the bonus. Next, check each bonus category in the bonus table. If the bonus category has the current unitTypeID as a key, then replace the existing value with a bonus equivalent to adding a fixed value to the receiving unit's attack.

That's all that must be done, so end all the loops.

Now we test the function.

Add unitAliases.phalanx = civ.getUnitType(3) to the appropriate file.

<code>
defaultAttackValueTable[unitAliases.phalanx.id]=1
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,
nextBonusValue=0.5,maxBonusUnits=1}
local rangeBonusCategory = {[unitAliases.archer.id]=125,[unitAliases.musketeer.id]=150,
nextBonusValue=0.75,maxBonusUnits=1}
local standardBonus = {cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable[unitAliases.legion.id]=standardBonus
categoryAttackBonusTable[unitAliases.phalanx.id]=standardBonus
categoryAttackBonusTable.round="up"
attackBonus.plusFixed({[unitAliases.chariot.id]=2,[unitAliases.musketeer.id]=2},
categoryAttackBonusTable)
</code>
The chariot and the musketeer individually should each add 2 to both a phalanx and a legion,
so the phalanx should have an attack of 3, and the legion should have an attack of 6, if one bonus
is applied.

Since the bonus type is multiplypercent, together the phalanx would have an attack of 9, and the legion will also have an attack of 9.

In testing, we quickly get this error
<code>
You should see this in lua console if this worked
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: bad argument #1 to 'getUnitType' (number expected, got string)
stack traceback:
[C]: in function 'civ.getUnitType'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>

At line 356, which is

<code>
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
</code>

This must mean that bonusReceivingUnitTypeID is not a number. This is because we're looping over categoryAttackBonusTable, and that table has a couple of entries that are not integers ("type" and "round"). Therefore, we have to insert code to deal with this eventuality.

The simplest way is to put everything in the loop body into an if statement, so that it only runs when bonusGivingUnitTypeID is actually a number. You should be able to do this without detailed instructions, so do so (hint: use type function).

The next error is
<code>
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: bad argument #1 to 'pairs' (table expected, got nil)
stack traceback:
[C]: in function 'pairs'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>
<code>
360 for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
</code>

Here, we have a nil value for bonusTable. This turns out to be an error in duplicateTable. When I duplicated the table, I forgot to return that table. That is, both the if and else statement in that function need a return command, and I forgot to add <code> return duplicatedTable </code> in the if portion. Add this to the duplicate table function.

After this, our predictions are true. Testing the other types of bonus is left as an assignment. You can find the completed code [https://forums.civfanatics.com/threads/totpp-attack-bonus-library.648093/ here].

===Recursive Functions===

Let us return to the duplicateTable function. Recall that in the last section we added a line to it, so we'll restate it here:

<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
return duplicatedTable
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

[[File:GetStartedWithLuaLesson6-16-duplicateTable.jpg]]

The interesting thing about duplicateTable is that it invokes duplicateTable within its code. When we copy the key-value pairs into the new table, we run duplicateTable on the value. If the value is not a table, then we are in the else case, and the value is immediately returned to be inserted into the duplicated table. If the value is a table, that table is duplicated before anything else is done.

Let us look at a simple example of a recursive function, the factorial function N!. In lesson 3, we discussed the factorial function in the context of loops. Since N!=N*(N-1)*(N-2)*...*3*2*1, we can give another definition of N!:
N!=1 if N = 1
N!=N*(N-1)! if N > 1
Or, using the convention that 0!=1, we can state
N!=1 if N = 0
N!=N*(N-1)! if N > 0

The case where N =1 or N=0 is called the "base case." If we keep substituting N! as N*(N-1)!, then we won't go on forever, because we will eventually reach a point where N=0, and N! can be substituted as 1 instead of N*(N-1)!. As long as there is a base case, our program will eventually reach the base case(s), and begin "completing" evaluation.

<code>
function factorial(N)
if N>0 then
return N*factorial(N-1)
else
return 1
end
end
print(factorial(5))
print(factorial(6))
</code>

Run this in code in the lua demo website, or using the TOTPP lua interpreter.

Returning to our duplicateTable function, the base case is any time a table value is not itself a table. When that happens, the recursion "chain" ends, and everything can evaluated.

Although is shouldn't be a problem in this particular case, it should be noted that it is possible for there to not be a "base case" in the recursion style: if table, recur, if not return a value. Consider the following table system

<code>
a={}
b={[1]=a}
a[1]=b
</code>
In this case, the code would never end.

It is possible that even if the code could "theoretically" execute to completion, you run out of memory before that. This is called a "stack overflow," and if it occurs, you will have to think of an alternate way to solve your problem. It will probably be best to ask for help in that case (and it might be useful to provide others with an example of a problem that results in a stack overflow), but you might also look into "tail recursion", including http://www.lua.org/pil/6.3.html .

===Conclusion===

With the skills covered in this chapter, you now have the tools to split a large events file into multiple files that are more manageable. You also have the basics for how to write re-useable modules for your events, so that your work can be used by others. Remember that if someone else uses your implementation of a feature, they will spend much less time coding and testing it, allowing them to either finish the scenario sooner, or to introduce some other feature. So, it might very well pay to spend at least a little effort making your code into a reusable module. Perhaps you have an idea for a cool scenario mechanic, but don't have a scenario for it (or don't want to take the time to make it). If that's the case, just make the module and test it in a "toy" scenario (like Classic Rome) so that it can be used more or less "off the shelf" when someone needs it.

Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files

2019-07-26T15:09:13Z

Prof. Garfield: /* A Unit Attack Bonus for Complementary Units in Square */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This Lesson is under construction.

===Introduction===

In this lesson, we will take a look at how to split the code for a scenario's events into multiple files. There are several reasons to consider doing this.

The first reason is simply to organize your work. If you have a series of complicated events, the events.lua file can become very large very quickly. Once your events.lua file has thousands of lines of code in it, it may not be very obvious where the best place is to put that next helper function, or where to implement the function that runs a complicated event. Sometimes even finding the piece of code that has to be changed can be a bit of a hassle. In Over the Reich, I sometimes search for the associated civ.scen line, and then search for the exact name of the function I need. Occasionally, there may even be more searching to find what I actually have to change. With multiple files, it becomes easier to find things.

Another aspect of using multiple files is that you can make certain changes without worrying about breaking things elsewhere. If myBigComplicatedFunction relies on aModestHelperFunction for a certain part of its functionality, and a change to myBigComplicatedFunction also requires a change to aModestHelperFunction, you have to make sure that nothing else in your code also uses aModestHelperFunction, or, if something else does depend on it, that aModestHelperFunction either still provides the original functionality, or that all other functions that use aModestHelperFunction are suitably modified. If myBigComplicatedFunction is defined in its own lua module, then you don't have to worry about forgetting that aModestHelperFunction was used elsewhere, since it can't be accessed outside the module unless you specifically allow it to be.

A second reason to split events code into multiple files is to facilitate collaboration. If all of the events are in a single file, then only one person can make changes to the file at a time. If one partner starts changing an event, but has to do something else before finishing, everyone waits on one person's delay. However, if most aspects of the scenario are separated into individual files, everyone can work on his or her own piece of the puzzle without depriving others of the opportunity to work at that time.

A third reason to split events into multiple modules is to facilitate reusing code. If everything required to implement an event is in its own file (or files), it becomes much easier for other creators to use your functionality in their scenario. Since everything they need is already in one place, they don't have to find every last helper function, or concern themselves with naming conflicts.

===Two Simple Examples===

Let us look at the top of the events.lua file. You can get the version that I started lesson 6 with [[here]].

[[File:GetStartedWithLuaLesson6-01-DefaultRequire.jpg]]

We get code from other files by using the command <code>require</code> along with a string specifying the file name (except for the .lua extension). At the moment, we can only get code stored in the lua folder in the Test of Time directory. This is inconvenient if we're trying to distribute a scenario, since installing a scenario would require moving certain files to the lua directory, and those file names might conflict. Instead, we need to tell the Lua interpreter to search in the same folder that the events.lua folder is in.

To do this, we need the following code:
<code>
local eventsPath = string.gsub(debug.getinfo(1).source, "@", "")
local scenarioFolderPath = string.gsub(eventsPath, "events.lua", "?.lua")
if string.find(package.path, scenarioFolderPath, 1, true) == nil then
package.path = package.path .. ";" .. scenarioFolderPath
end
</code>

You can probably cut and paste this code before the require lines in your events.lua file and not worry about how it works. However, I'll provide a brief explanation for reference.

The first line stores the location of the of the current file as a string in eventsPath.

The second line replaces events.lua in the eventsPath with ?.lua, which will tell the Lua interpreter to look for .lua files in the current directory (that is to say, the directory with the events.lua file).

The if statement adds scenarioFolderPath to the places for the Lua interpreter to search for code, if that directory is not already in the search path. Since the search path is kept active by the Lua interpreter, it will not be necessary to repeat these lines of code in every file that performs a require action as long as you are running the file as part of events. If you are writing some other kind of code, you will need to substitute "events.lua" with the name of the file with the code you are running. Note that for some reason, events.lua is always provided in lower case. However, for use in other situations, debug.getinfo(1).source uses the correct case for event files. I have only briefly tested this, so you may have to do some testing yourself if this situation comes up (or ask for help in the forums).

Now that we've told Lua where to look for our extra code, we can begin moving code to other files. Think of require as telling Lua to run the entire contents of another file as a function. We can then assign a value to whatever that file returns, which will usually be a table. A couple of examples will clarify.

For our first example, we will move our scenario's parameters to a separate file, and access it via require. This may not seem worthwhile in this example, but tables like this can get large in a hurry. At the time of writing, Over the Reich has over 100 lines of parameters ("specialNumbers"), and parameters are something that a designer might like to play with while collaborators make other implementations. Also, parameters will have to be referenced by other parts of the code, and a file that is required by events.lua cannot, in turn, require events.lua in order to get information. That means that we'll have to keep our parameters in a separate file anyway.

Cut the parameters table definition and paste it into a new file, classicRomeParameters.lua. For the last line, write
<code>
return parameters
</code>

Now, Near the top of events.lua, where the existing require lines are, add the eventsPath code from above and also the line
<code>
local parameters = require("classicRomeParameters")
</code>

[[File:GetStartedWithLuaLesson6-02-RequireParameters.jpg]]

Open the classicRome scenario and test out a couple of events to make sure everything is the same.

We might find it convenient to put a few tables into the same file. For this, we will simply return a table containing these tables, and give each table a name in the events.lua file.

Create a file classicRomeAliases.lua and move all the "aliases" tables to that file. Also move the getCityAt function.

At the bottom of the file, put the following lines:
<code>
return {
unitAliases=unitAliases,
tribeAliases=tribeAliases,
tileAliases=tileAliases,
cityAliases=cityAliases,
textAliases=textAliases,
terrainAliases=terrainAliases,
improvementAliases=improvementAliases,
}
</code>

Then, add the following lines to events.lua (in the require section)
<code>
local aliases = require("classicRomeAliases")
local unitAliases,tribeAliases,tileAliases,cityAliases,textAliases,
terrainAliases,improvementAliases=aliases.unitAliases,aliases.tribeAliases,
aliases.tileAliases,aliases.cityAliases, aliases.textAliases,aliases.terrainAliases,
aliases.improvementAliases
</code>

Here, our classicRomeAliases module is returning a table with our "alias" tables. We then assign the entries in this returned table to local variables with the desired names. Here, I use multiple variable assignment, which I don't believe I've used before (even though Lua allows it), but these could just as simply have been assigned line by line.

[[File:GetStartedWithLuaLesson6-03-RequireAliases.jpg]]

Now, let us move the legion plundering code into its own file, which we'll call plunder.lua. First, copy over the legionPlunder function, and paste it near the bottom of the new file.

Now, let us go through the code of this function, and figure out what else we need in our plunder.lua module.

The very first part of the function is a check against unitAliases.legion. This means we need the unitAliases table, and so we copy the aliases require code to the top of plunder.lua. We don't need the path information, since that will be added in events.lua.

A few more lines down, we find that the function cityRadius is also used in legionPlunder. Therefore, we move that over as well. We also need the plunderValue function, so copy that over as well.

Next, we check if cityRadius relies on anything, but it doesn't.

Proceeding to plunderValue, we find that it relies on the parameters table, so require that as well. The function plunderValue does not appear to depend on anything else, so we're done moving functionality. If we missed something, the Lua interpreter will complain at some point anyway.

Next, we require the plunder module in events.lua, with the following line:

<code>
local plunder = require("plunder")
</code>

Next, for each of the functions in plunder.lua, we check if it is used somewhere in events.lua. We can do this by searching. plunderValue isn't used anywhere, so we're done with that. City radius is used. At the bottom of plunder.lua, we begin our return table, and have
<code>
return {
cityRadius=cityRadius,
}
</code>

Then, in events.lua, we replace the ocurance of cityRadius with plunder.cityRadius. Alternatively, we could have put
<code>
local cityRadius=plunder.cityRadius
</code>
after the line requiring plunder.

Similarly, for legionPlunder, we add <code>legionPlunder=legionPlunder</code> to the table that plunder.lua returns, and pre-append plunder. to legionPlunder in the one location where it occurs.

Now, we test the legion plunder function and the press 4 generate archers function to make sure everything works.

[[File:GetStartedWithLuaLesson6-04-RequirePlunder.jpg]]

===Working With a Library===

In programming terms, a "library" is a collection of code that can provide some specified functionality to a programmer without that programmer having to modify the code in the library. Thus far, you have been using the "civ" library to interact with the game, and there has been no need modify it in order to use it in our own events. (Unfortunately, in the case of the civ library, we don't actually know how to modify it.) This is in contrast to much of the code we have written thus far. For example, the code we wrote last lesson to make Selucid elephants attack Egypt is highly specific. You couldn't just cut and paste that code, change the argument of a single function, and get your own goto event. It is still a good example for how to write a goto event, but a user would still have to actually write the event.

If you plan to write some functionality for your scenario that others might find useful, it is worth spending a little extra effort to see if you can write that functionality in a form that will allow others to use it with minimal effort. If you can, then a little extra work on your part might save someone else the trouble of re-inventing the wheel, and allow them to complete their project sooner, or to work on some new feature for you to enjoy. Unfortunately, the Lua scenarios that have been completed at the time of writing haven't been that good at creating re-usable code, at least in part since we were all getting used to Lua. This will hopefully be improved in the future.

For now, we're going to look at a library which is called the General Library (unless someone comes up with a better name) and which can be found [https://forums.civfanatics.com/threads/totpp-the-general-library.647583/ here]. The purpose of this module is to provide relatively simple functionality that probably shouldn't be implemented every time it is needed. This is useful for our purposes, since we can look at relatively self contained and simple functions for our first examples. We'll create a library for generating munitions later.

This library would be used by invoking the line

<code>
local gen = require("generalLibrary")
</code>

If you wanted to make these functions available to the console for testing purposes, you would simply omit the local, thereby making gen a global variable.

Let us now take a look at a function provided by the General Library <code> gen.hasIrrigation(tile)-->boolean</code>. The very first line references the helper function <code> toTile(tile or table)-->tile</code>, so let us include that code, and look at it first.

<code>
-- toTile(tile or table)-->tile
-- gen.toTile(tile or table)-->tile
-- If given a tile object, returns the tile
-- If given coordinates for a tile, returns the tile
-- Causes error otherwise
-- Helper Function (provided to this library as toTile and gen.toTile)
local function toTile(input)
if civ.isTile(input) then
return input
elseif type(input) == "table" then
local xVal = input[1] or input["x"]
local yVal = input[2] or input["y"]
local zVal = input[3] or input["z"] or 0
if type(xVal)=="number" and type(yVal)=="number" and type(zVal)=="number" then
if civ.getTile(xVal,yVal,zVal) then
return civ.getTile(xVal,yVal,zVal)
else
error("Table with values {"..tostring(xVal)..","..tostring(yVal)..
","..tostring(zVal).."} does not correspond to a valid tile.")
end
else
error("Table did not correspond to tile coordinates")
end
else
error("Did not receive a tile object or table of coordinates.")
end
end
gen.toTile = toTile

-- gen.hasIrrigation(tile)-->boolean
-- returns true if tile has irrigation but no farm
-- returns false otherwise
function gen.hasIrrigation(tile)
tile = toTile(tile)
local improvements = tile.improvements
-- irrigation, but no mining, so not farmland
if improvements & 0x04 == 0x04 and improvements & 0x08 == 0 then
return true
else
return false
end
end
</code>

[[File:GetStartedWithLuaLesson6-05-HasIrrigation.jpg]]

Let us begin by looking at the function <code>toTile</code>. The purpose of this function is to allow other functions to accept tile coordinates in a table instead of an actual tile object. The function tries to be reasonably permissive in the coordinates it will accept, allowing both integer indices and lowercase string indices, and by assuming that a missing z value corresponds to map 0. The function also tries to give reasonably helpful errors.

This brings up something that should be considered when making reusable code: what to do if you don't get values you were expecting. One option is to throw an error and bring up the Lua console. This is good for scenario creators, so they know something is wrong, but not so great for end users because the error stops the rest of the event from happening, should the mistake slip through playtesting.

The other option is for the code to fail silently, and try to do what it can. This is the way the old Test of Time macro system often fails. If Civ II doesn't "understand" the event, it just doesn't happen, and doesn't bother the player with the error. This means that the scenario will still mostly work, but it is harder to catch issues during playtesting. Sometimes, this means doing something "sensible" if the input isn't of the expected type, and might make the code easier to write, since you don't have to handle inputs differently.

A third option is to write your code such that both things can be done. At the top of your code, you put in a variable named "debugMode" or something, and make all the functions throw errors when true, and fail silently when false. Then you playtest with debugMode set to true, and release with debug mode set to false. However, this means extra work in writing your code and you also have to test everything with debug mode off.

For toTile, I went with the fail with error option, since that will allow every function that uses toTile to assume it is receiving proper data. It also seems unlikely that people will be regularly trying to check tiles that don't exist or have tables with tiles and units and improvement objects all in one. And if they do, "guarding" is fairly straightforward anyway (as we've done in previous lessons).

Although toTile is mainly meant to be a helper function for the General Library, it is also put into the gen table to be made available to end users, since it offers useful functionality. Hence, <code> gen.toTile=toTile</code>. Note that we could have given toTile a different name in the gen table that this module will return, such as gen.tableToTile=toTile. In fact, we could refer to the same function with multiple keys in the gen table, if we want to.

Next, we will look at gen.hasIrrigation.

The first thing to notice is that local is not being used to define this function. That is because we're putting the function for gen.hasIrrigation directly into the gen table that this module will return. We could define hasIrrigation as a local variable and then copy it into the gen table. However, there is a decent chance that the General Library will have more than 200 functions by the time everything is complete, since it is meant to provide a lot of building block functionality and keep it in one place, and we will run into trouble if we assign 200 local variables in a single function (which a required lua file acts as).

Perhaps the most striking thing is that we begin by changing the value of tile, the argument of the function. It looks like we're making a global variable named tile, but we're not. When you specify the names of the arguments for a function (in this case tile), you create local variables for that function, which can be given new values just as if you had explicitly used the local keyword.

Beyond that, we extract the integer representing the tile improvements into a local variable (which upon later reflection isn't really necessary), and check that the irrigation bit is set to 1 and the mining bit is set to 0. Refer to lesson 5 for why this works. In fact, we could have simply returned the value of the if statement, rather than specifying return true and return false, although it is very slightly clearer what is going on in the expanded version of the code.

Now, let us write a function to place irrigation on a square. It seems pretty clear that we should do nothing if the tile has a city, but we also have to decide what to do if there is mining or farmland on the tile, since those interfere with placing irrigation. We'll just remove them, on the basis that if we're trying to "place irrigation," then we want irrigation to be there when we are finished.

<code>
function gen.placeIrrigation(tile)
tile = toTile(tile)
</code>

These lines open the function and convert a table of coordinates to a tile if necessary.

<code>
if tile.city then
return
end
</code>

If the tile has a city, return so nothing else is done in the function.

<code>
-- Set irrigation bit to 1
tile.improvements = tile.improvements | 0x04
-- Set mining bit to 0
tile.improvements = tile.improvements & ~0x08
end
</code>

Set the irrigation bit to 1 and the mining bit to 0.

The functions in this library don't have to be complex, and in fact, most probably shouldn't be. They just have to make life easier for the end user. If you reach this lesson before the General Library is considered "complete," your assignment now is to submit some work for it. If you don't feel comfortable doing bitwise operations, you can test the work of others or submit functions that simplify other tasks. However, there are also some helper functions in the library to facilitate changing bits, so you might also consider working on the unit type flags functions. Remember, if you want to make functions available to the console for testing purposes, they must be global variables.

=== The Threshold Table and First Look at Metatables===

Consider a scenario design situation that occurred in Over the Reich: a bomber is generating some bombs via a key press, and the number of bombs it should generate is dependant on its current remaining hitpoints. The more hitpoints the bomber has, the more bombs it should generate. What we want is to specify that if a bomber has between x and y hitpoints, it should produce 2 bombs. That is, for a given type of bomber, we want to have, for example,

hp >= 16 --> 4 bombs
16 > hp >= 12 --> 3 bombs
12 > hp >= 9 --> 2 bombs
9 > hp >= 4 --> 1 bomb
4 > hp >= 0 --> 0 bombs

Unfortunately, Lua tables do not naturally encode this kind of association by default. However, Lua does have a feature called metatables, which allows us to change the behaviour of tables. (This will be a much better way to make the specification than I ended up writing in Over the Reich.)

A metatable is a table that we can "attach" to another table, and then the metatable changes the behaviour of that table. We'll only look at metatables briefly here, but more information can be found [https://www.tutorialspoint.com/lua/lua_metatables.htm here].

What we want is a data structure that can accept numerical "key values" that are between the key values explicitly specified, and return the appropriate value for those keys. We will call this data structure a threshold table, since we are specifying threshold values as keys. We can do this by assigning the following metatable:

<code>
local mt = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
</code>

If we run <code> setmetatable(myTable,mt)</code>, then whenever we ask for an index from myTable and that index doesn't currently exist in myTable, the function assigned to __index will run. Now let us examine the function.

If the type of the key is not a number, then we return whatever the table value is for that key. We use the function rawget, because the standard <code>thresholdTable[key]</code> will invoke this function again if the key doesn't exist, and so never return an answer (when we want it to return nil).

If the key type is a number, then we look for the largest numerical index that is also less than or equal to the key value. We return a default value of false if the key submitted is smaller than all numerical values. False is chosen over nil, so that a maximum value can be set by setting the value of a numerical index to false. Using the key [-math.huge] allows a return value to be set for all numbers (since all numbers are greater than -math.huge).

Since we don't want scenario creators to have to re-create threshold tables every time they need them, we'll add this functionality to the General Library

<code>
local thresholdTableMetatable = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
-- gen.makeThresholdTable(table or nil)-->thresholdTable
function gen.makeThresholdTable(inputTable)
inputTable = inputTable or {}
return setmetatable(inputTable,thresholdTableMetatable)
end
</code>

[[File:GetStartedWithLuaLesson6-06-ThresholdTable.jpg]]

===A Munition Generation Module===

Now, let us write some re-usable code for a human player to generate units by pressing a key while an appropriate unit is active. This sort of code could be used for ranged attacks (generating a "munition") and also for recruiting mercenaries by paying gold.

The first thing we will want to do is to decide how our code will be used by the end user. This will, perhaps, change by the time we finish writing the code, but it will at least give us a starting point.

spawnUnit(generatingUnit, specificationTable)--> table of unitCreated

Our goal is that when a player attempts to generate a unit using another unit, they will provide the unit spawning the new unit, and a table of information specifying if a unit (or units) can be spawned and anything else that must happen while spawning (like paying money, expending movement points, etc.).

We have an option here. We could have the scenario creator provide the specification table as a required file for our module, or the creator can provide it at the time spawnUnit is called. I choose the latter for a couple of reasons. The first is that it allows the player to have more than one specification table, either because more than one key can spawn a unit, or because the specification can change over time. The other is reason is so that the creator can make the table in the events.lua file if desired (since our module can't require information from events.lua).

Having decided that our generateUnit events are going to be specified by a table, we have to decide what the contents of that table should be. It seems pretty reasonable to index the specificationTable with the index of the unit type of each unit that can generate using the information in the table. If a unit type id number is missing, that unit doesn't generate a munition (or recruit a unit).

The value for each unit type id in the specification table will be a table that specifies how and if that unit generates other units.

--specificationTable[unitType.id]={
--
-- goldCost = integer or nil
-- amount of gold it costs to generate a unit
-- absent means 0
-- minTreasury = integer or nil
-- minimum amount of gold in treasury to generate a unit
-- absent means refer to gold cost
-- (tribe will generate and be set to 0 if treasury is less than goldCost)
-- treasuryFailMessage = string or nil
-- A message to be displayed if the unit fails to spawn a unit due to an
-- insufficient treasury
-- nil means no message

-- There are three ways to specify move costs, in full movement points,
-- in "atomic" movement points, and as a fraction of total movement points for the
-- unit type. Use only one kind per unit type

-- moveCost = integer or nil
-- movement points to be expended generating the unit
-- "full" movement points
-- absent means 0
-- minMove = integer or nil
-- minimum remaining movement points to be allowed to generate a unit
-- "full" movement points
-- absent means any movement points for land/sea, 2 "atomic" for air units
-- postGenMinMove = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostAtomic = integer or nil
-- movement points to be expended generating the unit
-- refers to the unit.moveSpent movement points
-- absent means 0
-- minMoveAtomic = integer or nil
-- minumum remaining movement points to be allowed to generate a unit
-- referes to the unit.moveSpent movement points
-- absent means any movement points for land, 2 "atomic" for air units
-- postGenMinMoveAtomic = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostFraction = number in [0,1] or nil
-- fraction of unit's total movement points expended generating the unit
-- round up to nearest "atomic" movement point
-- absent means 0
-- minMoveFraction = number in [0,1] or nil
-- fraction of unit's total movement points that must remain to be allowed
-- to generate a unit
-- absent means any movement points for land, 2 "atomic" for air units
-- round up to nearest "atomic" movement point
-- postGenMinMoveFraction = number in [0,1] or nil
-- a unit will be left with at least this many movement points after
-- the generation function, round up to nearest "atomic" move point
-- absent means 0 for land/sea, 1 "atomic" for air units
-- roundFractionFull = bool or nil
-- fractional movement cost and minimum are rounded up to full movement point
-- instead of atomic movement point
-- nil/false means don't
-- roundFractionFullDown = bool or nil
-- fractional cost and minimum are rounded down to full move point
-- nil/false means don't
-- minMoveFailMessage = string or nil
-- a message to be displayed if a unit is not generated due to insufficient
-- movement points.
-- nil means no message

-- allowedTerrainTypes = table of integers or nil
-- a unit may only be generated if the tile it is standing on
-- corresponds to one of numbers in the table
-- nil means the unit can be generated on any terrain type
-- terrainTypeFailMessage = string or nil
-- message to be displayed if a unit is not generated due to standing
-- on the incorrect terrain

-- requiredTech = tech object or nil
-- the generating civ must have this technology in order to generate
-- the unit
-- nil means no requirement
-- techFailMessage = string or nil
-- message to be displayed if a unit is not generated due to not having
-- the correct technology

-- payload = boolean or string
-- if true, unit must have a home city in order to generate munitions
-- and generating munitions sets the home city to NONE
-- payloadFailMessage = string or nil
-- message to be displayed if a unit is not generated due to the
-- payload restriction
-- payloadRestrictionCheck = nil or function(unit)-->boolean
-- If function returns false, the home city is not valid for giving the
-- unit a payload. This will be checked when the unit is activated, when
-- the unit is given a new home city with the 'h' key and when the unit
-- tries to generate a munition
-- nil means no restriction
-- payloadRestrictionMessage = nil or string
-- message to show if a unit fails the payloadRestrictionCheck

-- canGenerateFunction = nil or function(unit)-->boolean
-- This function applied to the generating unit must return true in order
-- for a unit to be spawned. All other conditions still apply.
-- any failure message should be part of canGenerateFunction
-- absent means no extra conditions

-- generateUnitFunction = nil or function(unit)-->table of unit
-- This function creates the unit or units to be generated
-- and returns a table containing those units
-- Ignore any specifications prefixed with * if this is used
-- nil means use other specifications

--*generatedUnitType = unitType
-- The type of unit to be generated
-- can't be nil unless generateUnitFunction is used instead

--*giveVeteran = bool or nil
-- generated unit(s) given veteran status if true
-- nil or false means don't give vet status
-- if true, overrides copyVeteranStatus

--*copyVeteranStatus = bool or nil
-- generated unit(s) copy veteran status of generating unit if true
-- nil or false means don't give vet status

--*setHomeCityFunction = nil or function(generatingUnit)-->cityObject
-- determines what home city the spawned unit should have
-- nil means a home city of NONE

--*numberToGenerate = nil or number or thresholdTable or function(generatingUnit)-->number
-- if nil, generate 1 unit in all circumstances
-- if integer, generate that many units (generate 0 if number less than 0)
-- if number not integer, generate floor(number), and 1 more with
-- probability number-floor(number)
-- if thresholdTable, use remaining hp as the key, to get the number to create
-- if function, get the number as the returned value of the function

-- activate = bool or nil
-- Activates one of the generated units if true. If generateUnitFunction was used,
-- the unit at index 1 is activated, if index 1 has a value. (if not, any unit in
-- the list might be chosen)

The very last entry brings forward a change that must be made to our unit generation specification. Lua's activate unit command doesn't run the unit activation trigger, even though the active unit is changed. Therefore, we must do that manually. Hence,

<code>spawnUnit(generatingUnit, specificationTable)--> table of unitCreated</code>

becomes

<code>spawnUnit(generatingUnit,specificationTable,unitActivationCode)-->table of unitCreated</code>

Perhaps we will change it again later.

I've decided to try a different instructional technique for this section. Instead of writing the code and then going through it section by section, I've recorded a video of my coding and testing this module, and I attempt to explain some of the stuff that I do along the way.

I'm not sure of the value of the video. If you find that there seems to be little useful content relative to the time it takes to watch, then feel free to skip it and continue the lesson. I don't teach anything "new" in it, so you won't miss anything crucial. However, it should be pretty close to how programming Lua can actually happen in the "real world." While I did give some thought to how to write the module before I started, I do attempt to solve problems in real time, and make mistakes that are not discovered for a while (including one where I try to explain how I solve a problem and then not actually do a crucial part).

You can find the code [https://forums.civfanatics.com/threads/totpp-the-munitions-library.647910/ here]. Even if you decide not to watch the video, download the code and try testing some of the features based on the specification above. If you find any bugs, submit a fix (or at least report the issue).

The video can be found [https://youtu.be/XxPyNknGlAo here].

===A Unit Attack Bonus for Complementary Units in Square===

Something we might like to do is to give units an attack bonus if they attack from a square with some special unit, for example a "leader" unit. The [[Napoléon I]] scenario, for example, gives an attack bonus to units if a commander unit, such as Napoleon, is in the square when the unit is activated (the unit can subsequently move and still retain the bonus as long as no other unit is selected). We will now make a module providing the same functionality.

We first have to have a basic idea of how this functionality should work. When a unit is activated, the onActivateUnit event checks if the newly activated unit should get an attack bonus, based on the other units in the square. If the unit deserves an attack bonus, the corresponding unitType.attack entry is changed, and all the attack value of all other units is reset to the default value. If the activated unit also does not deserve an attack bonus, that value is also set to the default value.

This now leads us to some more possibilities. Should multiple bonus units lead to multiple bonuses or only apply the best one? For example, suppose a legion gets a bonus if an archer is also in the same square. Should two archers provide twice the bonus? Perhaps two archers should provide a larger bonus than one, but not twice as much. Perhaps a legion should also get a bonus if there is a catapult in the square, but that bonus should apply even if the maximum archer bonus is already achieved. It seems like perhaps there should be a "ranged unit" bonus, an "artillery unit" bonus and maybe a "cavalry" bonus which should all impact the legion's attack value. It's looking like we might end up demanding that a scenario creator make a big complicated table in order to use this functionality, even if they only have simple needs.

What we can do to alleviate this is to write a "simple" version of the event that is easy to use (and program), and also write a more complicated version that gives the expanded capability.

Specification Table for simpleAttackBonus

--simpleAttackBonusTable[activeUnit.type.id] ={[bonusUnitType.id]=bonusNumber}
--simpleAttackBonusTable.type = string
--if simpleAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if simpleAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
--if simpleAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- if simpleAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- if simpleAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
--simpleAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

The relevant first draft of the code is as follows:

<code>
local function simpleAttackBonus(activeUnit,simpleAttackBonusTable,defaultAttackTable)
-- reset all unit attack values
for unitTypeID,attackValue in pairs(defaultAttackTable) do
civ.getUnitType(unitTypeID).attack = attackValue
end
local unitBonusTable = simpleAttackBonusTable[activeUnit.type.id]
if not unitBonusTable then
-- unitBonusTable is nil (or false), so the active unit can't
-- get a bonus
return
end
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
local bestBonusSoFar = 0
for unit in activeUnit.location.units do
if unitBonusTable[unit.type.id] and unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
if bestBonusSoFar == 0 then
-- If no bonus unit is found, this will be true, so do nothing else
return
end
-- set the new attack and return
if string.lower(simpleAttackBonusTable.type) == "addBonus" then
activeUnit.type.attack = activeUnit.type.attack+bestBonusSoFar
return
end
local attackMultiplier = 1
if type(simpleAttackBonusTable.type) ~= "string" then
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
elseif string.lower(simpleAttackBonusTable.type) == "addpercent" then
attackMultiplier = (100+bestBonusSoFar)/100
elseif string.lower(simpleAttackBonusTable.type) == "addfraction" then
attackMultiplier = 1+bestBonusSoFar
elseif string.lower(simpleAttackBonusTable.type) == "multiplypercent" then
attackMultiplier = bestBonusSoFar/100
elseif string.lower(simpleAttackBonusTable.type) == "multiply" then
attackMultiplier = bestBonusSoFar
else
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
end
-- apply the bonus and round as appropriate
if type(simpleAttackBonusTable.round) ~= "string" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
elseif string.lower(simpleAttackBonusTable.round) == "up" then
activeUnit.type.attack = math.ceil(activeUnit.type.attack*attackMultiplier)
return
elseif string.lower(simpleAttackBonusTable.round) == "down" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier)
return
else
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
end
end
</code>

Now let us go over this section by section.

[[File:GetStartedWithLuaLesson6-07-AttackBonus1.jpg]]

The first thing we do is to reset all the attack values of all the unit types. That way, if a bonus existed for the last unit activated, that bonus no longer applies. If a unit type is not in the defaultAttackTable, then we don't have the information to reset the attack value anyway, so we can safely ignore it by using the pairs function to iterate over the table.

Now, we must find out if the newly activated unit deserves a bonus. For that, we get the table associated with the active unit's type. If the value is nil instead of a table, then the unit's type is not in the simpleAttackBonusTable, so there is no bonus to apply and the function returns.

If the unit is eligible for bonuses, we then check the units in the square to see if any bonuses actually apply. We've seen this kind of code before. If the unit in the stack can provide a bonus, and that bonus is better than the best bonus already found, the unit now provides the best bonus. All bonus types that we can have are better if they are larger, and we are not comparing between bonus types, so a simple numerical comparison will do. All bonuses are larger than 0 in our formulation, so 0 is a good starting value in the search.

If the best bonus so far is still 0, there is no bonus, so the function can return.

At this point, it occurs to me that when searching for the best bonus, we should exclude the active unit from the search. That way, you can have a "strength in numbers" bonus, for example. The relevant change to the code is:

<code>
for unit in activeUnit.location.units do
if unit ~= activeUnit and unitBonusTable[unit.type.id] and
unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
</code>

Next, consider

[[File:GetStartedWithLuaLesson6-08-AttackBonus2.jpg]]

Here, we apply the bonus that we've found. We use string.lower on simpleAttackBonusTable.type so that we don't have to worry about capitalization. That does, however, require a correction to "addBonus", since a lower case string will never be equal to that.

"addbonus" is the only type of bonus that is directly added to the existing attack value. All other bonus types are a form of multiplication. Since the addition is straightforward and doesn't require any rounding, the activeUnit's type attack value can be changed immediately, and the function execution ended with return.

When there is only one bonus being applied, all other types of bonus are different ways of expressing how to multiply the existing attack value to get a new one, so we simply convert to the appropriate multiplier, and provide an error message if the type of bonus is not one of the valid possibilities.

Finally, we round the attack value to an appropriate integer (since unit attack values must be integers), change the attack value of the active unit's type, and return to end the function execution.

Now, we integrate into events.lua by using

<code>
attackBonus = require("attackBonus")
</code>

The relevant integration code for events.lua is
<code>
local defaultAttackValueTable = {[unitAliases.legion.id]=4}
local simpleAttackBonusTable ={}
simpleAttackBonusTable.type = "addbonus"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=3,[unitAliases.musketeer.id]=4}

local function doOnActivation(unit,source)
munitions.payloadRestrictionCheck(unit,munitionSpecificationTable)
attackBonus.simpleAttackBonus(unit,simpleAttackBonusTable,defaultAttackValueTable)
end
</code>

We can check that the bonus is being applied correctly by checking the Civlopedia entry for legion and looking at the attack value. The following cases must be tested (remember that activating a unit from the city screen doesn't run the onActivation event, so activate from the map).

Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (7 attack)
Legion activated with musketeer, but no archer (8 attack)
Legion activated with archer and musketeer (8 attack)
Legion activated with 2 archer, no musketeer (7 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

I recommend making a stack for each of these cases and activating them one by one.
To facilitate the test, add the following line to doOnActivation

<code>
civ.ui.text(tostring(unit.type.attack))
</code>
You will want to comment out this line after testing.

Next, change simpleAttackBonusTable to do "addpercent"
<code>
simpleAttackBonusTable.type = "addpercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=30,[unitAliases.musketeer.id]=70}
</code>

With no rounding set, standard rounding is used
Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)
Legion activated with archer and musketeer (7 attack)
Legion activated with 2 archer, no musketeer (5 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

These numbers test both rounding up and rounding down.

Now, use
simpleAttackBonusTable.round="up"
Legion activated with archer, but no musketeer (6 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next,
simpleAttackBonusTable.round="down"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (6 (6.8) attack)

simpleAttackBonusTable.round="standard"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next, we test "addfraction". Since we've tested all the rounding options, we don't have to do that again.

<code>
simpleAttackBonusTable.type = "addfraction"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=0.3,[unitAliases.musketeer.id]=0.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiplypercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=130,[unitAliases.musketeer.id]=170}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiply"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Before we finish, we should test a legion bonus for the legion.
<code>
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.legion.id]=2,[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>

Legion alone should have 4 attack.
A second legion on the square should provide 8 attack instead.

Now, let us try to formulate a more complicated bonus system. One thing we mentioned is that we'd like the ability to get bonuses from multiple units, and to be able to get bonuses from different "classes" of units (like "artillery," "cavalry," and "ranged attackers." Something else we might want to do is to allow different kinds of bonuses. That is, maybe some units should provide a fixed +2 to any unit receiving the bonus, so that it is better at improving units with a low attack value, while other units should provide a percentage bonus (making them better at supporting units with an already high attack value). It turns out that both of these ideas are not too difficult to implement individually, but that trying to implement them together makes it problematic to find the best bonus.

Let us implement a bonus system with multiple categories but only one bonus type. In our specification, we will first specify a data type called "bonusCategory." It is still just a table (though we could add a metatable if we wanted), but it will help us make our specification clearer.

<code>
-- A "bonusCategory" is a table
-- bonusCategory = {[bonusUnitType.id]=bonusNumber, maxBonusUnits=integer or nil, nextBonusValue = fraction or nil}
-- In a bonusCategory, the value for bonusUnitType.id tells what the base bonus for that unit type is,
-- maxBonusUnits is the maximum number of units that can provide a bonus in this category,
-- nextBonusValue tells how much to reduce the bonus for each subsequent unit,
-- e.g. nextBonusValue = 0.7, and 5 units, which each have a bonusNumber=1
-- The total bonus is 1(0.7)^0+.7+(.7)(.7)+(.7)^3+(.7)^4 = 1+.7+.49+.343+.2401=2.7731
-- (which would be rounded as specified)
-- nil means nextBonusValue=1
--
-- If a unit type is in two bonus categories for the same unit, there is no guarantee that the
-- best bonus will be achieved
</code>

So, the bonus category is indexed by unitType id numbers for units that can give a bonus, and the corresponding bonus. It also specifies the maximum number of units that can give a bonus, and a number that governs how to reduce a bonus for extra units. That way, there can be diminishing returns for bonuses.

Next, we look at the specification for the categoryAttackBonusTable

<code>
--categoryAttackBonusTable[activeUnit.type.id] =table of bonusCategory
--categoryAttackBonusTable.type = string
--if categoryAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if categoryAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
-- for multiple unit bonuses, add up all the percents, then compute the bonus
-- i.e. 50% bonus and 50% bonus is 100% bonus, not 125%
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 50% bonus units become 50% + 25%
-- so attack 6 --> 10.5
--if categoryAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- for multiple unit bonuses, add up the fractions, then compute the bonus
-- i.e. .5 bonus and .5 bonus is 1+.5+.5= 2x bonus, not 2.25x
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 .5 bonus units become .5+.25
-- so attack 6 --> 10.5
-- if categoryAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- bonuses are multiplied together, i.e. 150% and 150% yields 225% of original value
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 100, i.e. nextBonusValue=.5 2 150% bonuses become 150% and 125%
-- so attack 6 --> 11.25
-- if categoryAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
-- bonuses are multiplied together, i.e. 1.5 and 1.5 yields 2.25x
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 1, i.e. nextBonusValue=.5 and two 1.5 bonuses become 1.5 and 1.25
-- so attack 6 --> 11.25
--categoryAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

-- If the active unit can get a bonus, go through each category and compute the bonus for that category.
-- Then, combine the bonuses for all categories to get the overall bonus, and round the result
</code>

With the bonusCategory defined, the value of the unit indices of categoryAttackBonusTable become easy to define. Most of the specification is showing what exactly the different bonus categories mean, so the end user can use them properly. It's not strictly necessary to offer so many choices to the end user on how to specify data, but it can be more convenient.

Here is the actual code (before testing) to implement this more general version of attack bonuses.

<code>
-- HELPER FUNCTION
-- findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable) --> number or false
-- usedUnitTable is indexed by the i.d. number of units, and if the value for a unit is true,
-- then it has already been used for a bonus (and, so, is not eligible)
-- The function returns the bonus (before nextBonusValue is applied) if there is one, and marks the
-- unit as used in the usedUnitTable
-- returns false if no unit qualifies
local function findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable)
local bestBonusSoFar = 0
local bestUnitSoFar = nil
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
for unit in tile.units do
if not usedUnitTable[unit.id] and bonusCategory[unit.type.id]
and bonusCategory[unit.type.id] > bestBonusSoFar then
bestUnitSoFar = unit
bestBonusSoFar = bonusCategory[unit.type.id]
end
end
if bestUnitSoFar then
usedUnitTable[bestUnitSoFar.id] = true
return bestBonusSoFar
else
return false
end
end

-- HELPER FUNCTION
-- computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
-- Computes the bonus that the active unit will receive from this category, taking into
-- account the type of bonus for the table
local function computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
local bonusThusFar = nil
if bonusType == "multiply" then
bonusThusFar = 1
elseif bonusType == "multiplypercent" then
bonusThusFar = 100
else
bonusThusFar = 0
end
local bonusDiscount = 1
for i=1,(bonusCategory.maxBonusUnits or 10000) do
local currentBonus =findBestBonusInUnitStack(activeUnit.location,bonusCategory,usedUnitTable)
if not currentBonus then
-- no more valid bonuses for this category
break
end
if bonusType == "multiply" then
bonusThusFar = bonusThusFar*((currentBonus-1)*bonusDiscount+1)
elseif bonusType =="multiplypercent" then
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
else
bonusThusFar = bonusThusFar+currentBonus*bonusDiscount
end
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
end
return bonusThusFar
end

local function categoryAttackBonus(activeUnit,categoryAttackBonusTable,defaultAttackTable)
local bonusInfoTable = categoryAttackBonusTable[activeUnit.type.id]
if not bonusInfoTable then
-- unit doesn't get a bonus
return
end
-- keep track of bonuses already computed
local bonusResultsTable = {}
-- keep track of units that have already been "used" for a bonus
local usedUnitTable = {[activeUnit.id]=true}
for index,bonusCategory in pairs(bonusInfoTable) do
bonusResultsTable[index]=computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
end
-- compute the bonus
local bonusType = string.lower(categoryAttackBonusTable.type)
local resultAttackBeforeRounding = nil
if bonusType == "multiply" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "multiplypercent" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult/100
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "addbonus" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack+bonus
elseif bonusType == "addfraction" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
elseif bonusType == "addpercent" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+(bonusResult/100)
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
else
error("categoryAttackBonus: categoryAttackBonusTable.type is not a valid value.")
end
-- apply the bonus and round as appropriate
local roundType = categoryAttackBonusTable.round
if type(roundType) ~= "string" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
elseif roundType == "up" then
activeUnit.type.attack = math.ceil(resultAttackBeforeRounding)
return
elseif roundType == "down" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding)
return
else
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
end
end
</code>

The two helper functions for computeCategoryBonus are only used once each in the code, so making them helper functions does not help us re-use code. However, what it does do is to break down the function design process into smaller tasks, which are each more manageable to complete. If you're trying to keep track of too many things in your program, try writing a few helper functions to handle individual tasks. We'll look at the helper functions when we actually arrive at them in the code.

[[File:GetStartedWithLuaLesson6-09-CategoryAtkBonus1.jpg]]

If there is no entry in the categoryAttackBonusTable or the active unit's type, then the function returns without doing anything further.

The bonusResultsTable keeps track of the total bonus from each category, so they can be added or multiplied together after all the category bonuses are applied. The usedUnitsTable keeps track of units that are no longer eligible to contribute to a bonus (such as if they have already contributed), and we initialize it with the active unit, so that it doesn't provide a bonus to itself.

The for loop computes the bonus for every category, and stores the value in the bonusResultsTable, for use later.Now, let us look at the helper functions.

First up is findBestBonusInUnitStack

[[File:GetStartedWithLuaLesson6-10-CategoryAtkBonus2.jpg]]

This basically does what it says in the name. For a bonusCategory, it finds the unit in the tile that provides the best bonus, and has not already provided a bonus elsewhere. If there is no qualifying unit, false is returned. If there is, that unit's bonus is returned, and the unit's id is entered into the usedUnitTable, so that unit can't provide another bonus for the active unit. We've searched for the best of something before, so there is little need to go over it again.

Next is computeCategoryBonus

[[File:GetStartedWithLuaLesson6-11-CategoryAtkBonus3.jpg]]

Here, we're computing the bonus for the entire bonusCategory. We need the bonus type in order to know what kind of math to do. The math itself is not very interesting. We also initialize the bonusDiscount, which keeps track of the fraction of the next unit's bonus that will actually be applied.

Next, we enter a for loop that will run one time for each possible bonus that there can be in a bonus category. If bonusCategory.maxBonusUnits is nil, then we set an arbitrary limit of 10000 units, which is very unlikely to happen in practice.

At each iteration of the loop, the best available bonus in the stack is found. If no unit was eligible to provide a bonus, then the current bonus is false, and the "break" command is issued. Break immediately exits the current loop. So, our program doesn't run 10000 loops if there is no maximum number of bonus units, it just breaks at an appropriate time.

After the bonus is found, it is added to or multiplied with the bonus already found. The bonus computed in this way will be the largest possible, since the bonus provided does not depend on the other units chosen (so we don't have a situation where "catapult" and "rock" are both useless, but "catapult" and "rock" chosen together are best). Also, since the best bonus is chosen first, the smallest bonus discount applies to it, so the cost imposed by the discounting is smallest.

Finally, we update the bonusDisount. Here, I notice a problem in the code as written, since bonusCategory.nextBonusValue is allowed to be nil. Replace
<code>
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
</code>
with
<code>
bonusDiscount = bonusDiscount*(bonusCategory.nextBonusValue or 1)
</code>
so that if there is no nextBonusValue, a default of 1 is used, and the bonusDiscount stays at 1 (i.e. no discount is applied).

We return to categoryAttackBonus to see

[[File:GetStartedWithLuaLesson6-12-CategoryAtkBonus4.jpg]]

From here, we combine the bonuses stored in bonusResultsTable, the exact way of doing so being dependant on the type of bonus involved. The math itself isn't very interesting, and doesn't seem all that likely to come up in this exact form elsewhere. If you need help with the mathematical details of some event you want to write, ask in the forums. There's a good chance someone has the skills to help you solve your specific problem.

For every type of bonus, the result is stored in resultAttackBeforeRounding, so that variable can be rounded up or down as specified by the rounding type.

Here, I notice another error. We should restrict the attack value for a unit to not exceed 98. We can do that with a math.min(value, 98).

Now, we need to test the various aspects of the attack bonus program, so we need an appropriate table
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addbonus"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=2,[unitAliases.chariot.id]=4,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=2,[unitAliases.musketeer.id]=4,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Also, comment out the old attack bonus line, and put in a new one
<code>
attackBonus.categoryAttackBonus(unit,categoryAttackBonusTable,defaultAttackValueTable)
</code>

Expected Test Results when type is "addbonus"
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

Already, we find a problem. Although there were no syntax errors to fix, I forgot to reset unit attack values. So, very quickly, the legions keep gathering extra attack values when they are activated (since the base attack is not reset to 4). Since this is happening anyway, I'll test the 98 attack value maximum. That appears to work, at least in the case of no specified rounding.

Cut and paste the appropriate lines from the simpleAttackBonus to the categoryAttackBonus, and save.

With that bug fixed, everything works as expected.

Next, we change the categoryAttackBonusTable to

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addpercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=50,[unitAliases.chariot.id]=100,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=50,[unitAliases.musketeer.id]=100,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>

Expected Test Results when type is "addpercent". These are the same, since adding we're adding percentages of the same base value of 4. So a value of 2 is the same as adding 50% of 4.
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

The results are the same.

Similarly,

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addfraction"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=.50,[unitAliases.chariot.id]=1.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=.50,[unitAliases.musketeer.id]=1.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

We'll have to do some new calculations, now, since multiply and multiplyfraction give different results than the various adding formulations.

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiply"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=1.50,[unitAliases.chariot.id]=2.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=1.50,[unitAliases.musketeer.id]=2.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Finally, we use multiplyPercent, and check for the same results
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=150,[unitAliases.musketeer.id]=200,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Quickly, I find that if a bonus applies, that bonus makes the attack value of a legion 98. I failed to multiply percents correctly in computeCategoryBonus. The Line
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
</code>
Is changed to
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+100)/100
</code>

Finally, Change archer bonus to 110 and musketeer bonus to 120 (so a unit will make a legion have 4.4 and 4.8 value before rounding), and test the rounding options. You will find they all work.

At the moment, we don't have a way to mix different types of bonuses. As said earlier, we might want this so that some units can be better at giving bonuses to low attack units than to high attack units, while others give a percentage bonus to everything. We could now write a bonus system that allows for multiple types of bonuses. However, the current bonus system allows for the bonus to change per unit. This means that we can, for example, convert a +2 attack bonus to a plus 100% bonus for a unit with 2 attack, and a plus 50% bonus for a unit with 4 attack. In the case of the multiplied bonuses, this will make the bonus more powerful if there is more than one. That is, 2 attack, +2 twice is 6, but if +2 is changed to x2, then the multiplied bonus brings the attack up to 8. However, this seems like it would be a relatively unlikely problem, and there are other things this code can't handle, so we'll let someone else make the code if they actually need it.

So, what we'll do is write a function that will change all appropriate entries in the categoryAttackBonusTable to reflect a different value. Hence,

<code>
-- plusFixed(unitType,number,categoryAttackBonusTable) --> void
-- changes the bonus given by unit type to any unit to be equivalent
-- to adding number to that unit's attack power
</code>

Here, an issue with tables arises. It is very likely that when someone defines their cateogryAttackBonusTable, they'll define it something like this
<code>
local rangeBonusCategory = {[unitAliases.archer.id]=.25,[unitAliases.musketeer.id]=.5}
local bonusTableForInfantry = {rangeBonusCategory}
local cABT = {type="addfraction"}
cABT[unitAliases.phalanx.id]=bonusTableForInfantry
cABT[unitAliases.legion.id] = bonusTableForInfantry
</code>
However, this means that both <code> cABT[unitAliases.legion.id] </code> and <code> cABT[unitAliases.phalanx.id] </code> actually refer to the same piece of memory, and changing cABT[unitAliases.legion.id][1][unitAliases.archer.id] will also change the value at cABT[unitAliases.phalanx.id][1][unitAliases.archer.id]. This is because of the way lua tables are designed. This design can be useful, for example it allowed us to make changes to usedUnitsTable in the last function without having to copy the table, make changes to the copy of the table, and then replace the original table with that copy as a return value. However, it also requires us to be careful when we make changes to entries in tables. In this case, we'll simply copy the table and all its sub values into a new table.

The code to do this is given by
<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

We will explain this code in the next section, since it involves a programming technique which we haven't discussed before.

For now, we analyze plusFixed:

<code>
-- plusFixed({[unitType1.id]=fixedBonus,[unitType2.id]=fixedBonus},categoryAttackBonusTable) --> void
-- changes the bonus given by unitTypeI.id to a unit to be equivalent to
-- to adding number to that unit's attack power. If the unit doesn't receive a bonus
-- from the unitType, then it won't after applying plusFixed.
-- The value of the existing bonus is ignored.

local function plusFixed(fixedUnitBonusTable,categoryAttackBonusTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
for bonusReceivingUnitTypeID,bonusTable in pairs(categoryAttackBonusTable) do
-- replace bonusTable with an equivalent table that is not referened
-- anywhere else, so that changes to it can be made without impacting
-- data elsewhere
categoryAttackBonusTable[bonusReceivingUnitTypeID] = duplicateTable(bonusTable)
-- make bonusTable refer to the "current" bonus table for the unit type
bonusTable =categoryAttackBonusTable[bonusReceivingUnitTypeID]
-- For each unit type in the fixedUnitBonusTable, check if any bonus category
-- in the bonusTable corresponds to it. If so, make the change
for bonusGivingUnitTypeID,fixedBonusValue in pairs(fixedUnitBonusTable) do
-- get the attack of the unit type
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
-- in each bonus category, check if the giver's unit type id is there,
-- if so, change to the correct attack
for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
if bonusCategory[bonusGivingUnitTypeID] then
-- change the bonus appropriately
if bonusType == "addbonus" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue
elseif bonusType == "addpercent" then
bonusCategory[bonusGivingUnitTypeID]=100*fixedBonusValue/baseAttack
elseif bonusType == "addfraction" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue/baseAttack
elseif bonusType == "multiplypercent" then
bonusCategory[bonusGivingUnitTypeID]=100*(fixedBonusValue+baseAttack)/baseAttack
elseif bonusType == "multiply" then
bonusCategory[bonusGivingUnitTypeID]=(fixedBonusValue+baseAttack)/baseAttach
else
error("pluxFixed: categoryAttackBonusTable.type does not have an acceptable value.")
end
end
end
end
end
end
</code>

[[File:GetStartedWithLuaLesson6-13-plusFixed1.jpg]]

As before, we save the bonusType in lower case, since we'll be using it a lot later. Next, we open a for loop, where the index is the id of the unit type receiving the bonus, and the value is the bonus table for that unit type. Next, we duplicate the bonus table, so that we have a table we can change without impacting anything elsewhere, and we store the duplicated table in categoryAttackBonusTable in place of the original bonusTable for the current bonus receiving unit id. Next, we assign this duplicated table to the variable bonusTable, so we can refer to it later in the code.

[[File:GetStartedWithLuaLesson6-14-plusFixed2.jpg]]

We now perform the following actions for each unitType.id and corresponding fixedBonusValue submitted in the fixedUnitBonusTable.

First, get the attack of the bonus receiving unit, since we'll need that in order to customize the bonus. Next, check each bonus category in the bonus table. If the bonus category has the current unitTypeID as a key, then replace the existing value with a bonus equivalent to adding a fixed value to the receiving unit's attack.

That's all that must be done, so end all the loops.

Now we test the function.

Add unitAliases.phalanx = civ.getUnitType(3) to the appropriate file.

<code>
defaultAttackValueTable[unitAliases.phalanx.id]=1
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,
nextBonusValue=0.5,maxBonusUnits=1}
local rangeBonusCategory = {[unitAliases.archer.id]=125,[unitAliases.musketeer.id]=150,
nextBonusValue=0.75,maxBonusUnits=1}
local standardBonus = {cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable[unitAliases.legion.id]=standardBonus
categoryAttackBonusTable[unitAliases.phalanx.id]=standardBonus
categoryAttackBonusTable.round="up"
attackBonus.plusFixed({[unitAliases.chariot.id]=2,[unitAliases.musketeer.id]=2},
categoryAttackBonusTable)
</code>
The chariot and the musketeer individually should each add 2 to both a phalanx and a legion,
so the phalanx should have an attack of 3, and the legion should have an attack of 6, if one bonus
is applied.

Since the bonus type is multiplypercent, together the phalanx would have an attack of 9, and the legion will also have an attack of 9.

In testing, we quickly get this error
<code>
You should see this in lua console if this worked
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: bad argument #1 to 'getUnitType' (number expected, got string)
stack traceback:
[C]: in function 'civ.getUnitType'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>

At line 356, which is

<code>
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
</code>

This must mean that bonusReceivingUnitTypeID is not a number. This is because we're looping over categoryAttackBonusTable, and that table has a couple of entries that are not integers ("type" and "round"). Therefore, we have to insert code to deal with this eventuality.

The simplest way is to put everything in the loop body into an if statement, so that it only runs when bonusGivingUnitTypeID is actually a number. You should be able to do this without detailed instructions, so do so (hint: use type function).

The next error is
<code>
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: bad argument #1 to 'pairs' (table expected, got nil)
stack traceback:
[C]: in function 'pairs'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>
<code>
360 for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
</code>

Here, we have a nil value for bonusTable. This turns out to be an error in duplicateTable. When I duplicated the table, I forgot to return that table. That is, both the if and else statement in that function need a return command, and I forgot to add <code> return duplicatedTable </code> in the if portion. Add this to the duplicate table function.

After this, our predictions are true. Testing the other types of bonus is left as an assignment. You can find the completed code [https://forums.civfanatics.com/threads/totpp-attack-bonus-library.648093/ here].

===Recursive Functions===

Let us return to the duplicateTable function. Recall that in the last section we added a line to it, so we'll restate it here:

<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
return duplicatedTable
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

[[File:GetStartedWithLuaLesson6-16-duplicateTable.jpg]]

The interesting thing about duplicateTable is that it invokes duplicateTable within its code. When we copy the key-value pairs into the new table, we run duplicateTable on the value. If the value is not a table, then we are in the else case, and the value is immediately returned to be inserted into the duplicated table. If the value is a table, that table is duplicated before anything else is done.

Let us look at a simple example of a recursive function, the factorial function N!. In lesson 3, we discussed the factorial function in the context of loops. Since N!=N*(N-1)*(N-2)*...*3*2*1, we can give another definition of N!:
N!=1 if N = 1
N!=N*(N-1)! if N > 1
Or, using the convention that 0!=1, we can state
N!=1 if N = 0
N!=N*(N-1)! if N > 0

The case where N =1 or N=0 is called the "base case." If we keep substituting N! as N*(N-1)!, then we won't go on forever, because we will eventually reach a point where N=0, and N! can be substituted as 1 instead of N*(N-1)!. As long as there is a base case, our program will eventually reach the base case(s), and begin "completing" evaluation.

<code>
function factorial(N)
if N>0 then
return N*factorial(N-1)
else
return 1
end
end
print(factorial(5))
print(factorial(6))
</code>

Run this in code in the lua demo website, or using the TOTPP lua interpreter.

Returning to our duplicateTable function, the base case is any time a table value is not itself a table. When that happens, the recursion "chain" ends, and everything can evaluated.

Although is shouldn't be a problem in this particular case, it should be noted that it is possible for there to not be a "base case" in the recursion style: if table, recur, if not return a value. Consider the following table system

<code>
a={}
b={[1]=a}
a[1]=b
</code>
In this case, the code would never end.

It is possible that even if the code could "theoretically" execute to completion, you run out of memory before that. This is called a "stack overflow," and if it occurs, you will have to think of an alternate way to solve your problem. It will probably be best to ask for help in that case (and it might be useful to provide others with an example of a problem that results in a stack overflow), but you might also look into "tail recursion", including http://www.lua.org/pil/6.3.html .

===Conclusion===

With the skills covered in this chapter, you now have the tools to split a large events file into multiple files that are more manageable. You also have the basics for how to write re-useable modules for your events, so that your work can be used by others. Remember that if someone else uses your implementation of a feature, they will spend much less time coding and testing it, allowing them to either finish the scenario sooner, or to introduce some other feature. So, it might very well pay to spend at least a little effort making your code into a reusable module. Perhaps you have an idea for a cool scenario mechanic, but don't have a scenario for it (or don't want to take the time to make it). If that's the case, just make the module and test it in a "toy" scenario (like Classic Rome) so that it can be used more or less "off the shelf" when someone needs it.

Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files

2019-07-26T14:38:01Z

Prof. Garfield: /* A Munition Generation Module */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This Lesson is under construction.

===Introduction===

In this lesson, we will take a look at how to split the code for a scenario's events into multiple files. There are several reasons to consider doing this.

The first reason is simply to organize your work. If you have a series of complicated events, the events.lua file can become very large very quickly. Once your events.lua file has thousands of lines of code in it, it may not be very obvious where the best place is to put that next helper function, or where to implement the function that runs a complicated event. Sometimes even finding the piece of code that has to be changed can be a bit of a hassle. In Over the Reich, I sometimes search for the associated civ.scen line, and then search for the exact name of the function I need. Occasionally, there may even be more searching to find what I actually have to change. With multiple files, it becomes easier to find things.

Another aspect of using multiple files is that you can make certain changes without worrying about breaking things elsewhere. If myBigComplicatedFunction relies on aModestHelperFunction for a certain part of its functionality, and a change to myBigComplicatedFunction also requires a change to aModestHelperFunction, you have to make sure that nothing else in your code also uses aModestHelperFunction, or, if something else does depend on it, that aModestHelperFunction either still provides the original functionality, or that all other functions that use aModestHelperFunction are suitably modified. If myBigComplicatedFunction is defined in its own lua module, then you don't have to worry about forgetting that aModestHelperFunction was used elsewhere, since it can't be accessed outside the module unless you specifically allow it to be.

A second reason to split events code into multiple files is to facilitate collaboration. If all of the events are in a single file, then only one person can make changes to the file at a time. If one partner starts changing an event, but has to do something else before finishing, everyone waits on one person's delay. However, if most aspects of the scenario are separated into individual files, everyone can work on his or her own piece of the puzzle without depriving others of the opportunity to work at that time.

A third reason to split events into multiple modules is to facilitate reusing code. If everything required to implement an event is in its own file (or files), it becomes much easier for other creators to use your functionality in their scenario. Since everything they need is already in one place, they don't have to find every last helper function, or concern themselves with naming conflicts.

===Two Simple Examples===

Let us look at the top of the events.lua file. You can get the version that I started lesson 6 with [[here]].

[[File:GetStartedWithLuaLesson6-01-DefaultRequire.jpg]]

We get code from other files by using the command <code>require</code> along with a string specifying the file name (except for the .lua extension). At the moment, we can only get code stored in the lua folder in the Test of Time directory. This is inconvenient if we're trying to distribute a scenario, since installing a scenario would require moving certain files to the lua directory, and those file names might conflict. Instead, we need to tell the Lua interpreter to search in the same folder that the events.lua folder is in.

To do this, we need the following code:
<code>
local eventsPath = string.gsub(debug.getinfo(1).source, "@", "")
local scenarioFolderPath = string.gsub(eventsPath, "events.lua", "?.lua")
if string.find(package.path, scenarioFolderPath, 1, true) == nil then
package.path = package.path .. ";" .. scenarioFolderPath
end
</code>

You can probably cut and paste this code before the require lines in your events.lua file and not worry about how it works. However, I'll provide a brief explanation for reference.

The first line stores the location of the of the current file as a string in eventsPath.

The second line replaces events.lua in the eventsPath with ?.lua, which will tell the Lua interpreter to look for .lua files in the current directory (that is to say, the directory with the events.lua file).

The if statement adds scenarioFolderPath to the places for the Lua interpreter to search for code, if that directory is not already in the search path. Since the search path is kept active by the Lua interpreter, it will not be necessary to repeat these lines of code in every file that performs a require action as long as you are running the file as part of events. If you are writing some other kind of code, you will need to substitute "events.lua" with the name of the file with the code you are running. Note that for some reason, events.lua is always provided in lower case. However, for use in other situations, debug.getinfo(1).source uses the correct case for event files. I have only briefly tested this, so you may have to do some testing yourself if this situation comes up (or ask for help in the forums).

Now that we've told Lua where to look for our extra code, we can begin moving code to other files. Think of require as telling Lua to run the entire contents of another file as a function. We can then assign a value to whatever that file returns, which will usually be a table. A couple of examples will clarify.

For our first example, we will move our scenario's parameters to a separate file, and access it via require. This may not seem worthwhile in this example, but tables like this can get large in a hurry. At the time of writing, Over the Reich has over 100 lines of parameters ("specialNumbers"), and parameters are something that a designer might like to play with while collaborators make other implementations. Also, parameters will have to be referenced by other parts of the code, and a file that is required by events.lua cannot, in turn, require events.lua in order to get information. That means that we'll have to keep our parameters in a separate file anyway.

Cut the parameters table definition and paste it into a new file, classicRomeParameters.lua. For the last line, write
<code>
return parameters
</code>

Now, Near the top of events.lua, where the existing require lines are, add the eventsPath code from above and also the line
<code>
local parameters = require("classicRomeParameters")
</code>

[[File:GetStartedWithLuaLesson6-02-RequireParameters.jpg]]

Open the classicRome scenario and test out a couple of events to make sure everything is the same.

We might find it convenient to put a few tables into the same file. For this, we will simply return a table containing these tables, and give each table a name in the events.lua file.

Create a file classicRomeAliases.lua and move all the "aliases" tables to that file. Also move the getCityAt function.

At the bottom of the file, put the following lines:
<code>
return {
unitAliases=unitAliases,
tribeAliases=tribeAliases,
tileAliases=tileAliases,
cityAliases=cityAliases,
textAliases=textAliases,
terrainAliases=terrainAliases,
improvementAliases=improvementAliases,
}
</code>

Then, add the following lines to events.lua (in the require section)
<code>
local aliases = require("classicRomeAliases")
local unitAliases,tribeAliases,tileAliases,cityAliases,textAliases,
terrainAliases,improvementAliases=aliases.unitAliases,aliases.tribeAliases,
aliases.tileAliases,aliases.cityAliases, aliases.textAliases,aliases.terrainAliases,
aliases.improvementAliases
</code>

Here, our classicRomeAliases module is returning a table with our "alias" tables. We then assign the entries in this returned table to local variables with the desired names. Here, I use multiple variable assignment, which I don't believe I've used before (even though Lua allows it), but these could just as simply have been assigned line by line.

[[File:GetStartedWithLuaLesson6-03-RequireAliases.jpg]]

Now, let us move the legion plundering code into its own file, which we'll call plunder.lua. First, copy over the legionPlunder function, and paste it near the bottom of the new file.

Now, let us go through the code of this function, and figure out what else we need in our plunder.lua module.

The very first part of the function is a check against unitAliases.legion. This means we need the unitAliases table, and so we copy the aliases require code to the top of plunder.lua. We don't need the path information, since that will be added in events.lua.

A few more lines down, we find that the function cityRadius is also used in legionPlunder. Therefore, we move that over as well. We also need the plunderValue function, so copy that over as well.

Next, we check if cityRadius relies on anything, but it doesn't.

Proceeding to plunderValue, we find that it relies on the parameters table, so require that as well. The function plunderValue does not appear to depend on anything else, so we're done moving functionality. If we missed something, the Lua interpreter will complain at some point anyway.

Next, we require the plunder module in events.lua, with the following line:

<code>
local plunder = require("plunder")
</code>

Next, for each of the functions in plunder.lua, we check if it is used somewhere in events.lua. We can do this by searching. plunderValue isn't used anywhere, so we're done with that. City radius is used. At the bottom of plunder.lua, we begin our return table, and have
<code>
return {
cityRadius=cityRadius,
}
</code>

Then, in events.lua, we replace the ocurance of cityRadius with plunder.cityRadius. Alternatively, we could have put
<code>
local cityRadius=plunder.cityRadius
</code>
after the line requiring plunder.

Similarly, for legionPlunder, we add <code>legionPlunder=legionPlunder</code> to the table that plunder.lua returns, and pre-append plunder. to legionPlunder in the one location where it occurs.

Now, we test the legion plunder function and the press 4 generate archers function to make sure everything works.

[[File:GetStartedWithLuaLesson6-04-RequirePlunder.jpg]]

===Working With a Library===

In programming terms, a "library" is a collection of code that can provide some specified functionality to a programmer without that programmer having to modify the code in the library. Thus far, you have been using the "civ" library to interact with the game, and there has been no need modify it in order to use it in our own events. (Unfortunately, in the case of the civ library, we don't actually know how to modify it.) This is in contrast to much of the code we have written thus far. For example, the code we wrote last lesson to make Selucid elephants attack Egypt is highly specific. You couldn't just cut and paste that code, change the argument of a single function, and get your own goto event. It is still a good example for how to write a goto event, but a user would still have to actually write the event.

If you plan to write some functionality for your scenario that others might find useful, it is worth spending a little extra effort to see if you can write that functionality in a form that will allow others to use it with minimal effort. If you can, then a little extra work on your part might save someone else the trouble of re-inventing the wheel, and allow them to complete their project sooner, or to work on some new feature for you to enjoy. Unfortunately, the Lua scenarios that have been completed at the time of writing haven't been that good at creating re-usable code, at least in part since we were all getting used to Lua. This will hopefully be improved in the future.

For now, we're going to look at a library which is called the General Library (unless someone comes up with a better name) and which can be found [https://forums.civfanatics.com/threads/totpp-the-general-library.647583/ here]. The purpose of this module is to provide relatively simple functionality that probably shouldn't be implemented every time it is needed. This is useful for our purposes, since we can look at relatively self contained and simple functions for our first examples. We'll create a library for generating munitions later.

This library would be used by invoking the line

<code>
local gen = require("generalLibrary")
</code>

If you wanted to make these functions available to the console for testing purposes, you would simply omit the local, thereby making gen a global variable.

Let us now take a look at a function provided by the General Library <code> gen.hasIrrigation(tile)-->boolean</code>. The very first line references the helper function <code> toTile(tile or table)-->tile</code>, so let us include that code, and look at it first.

<code>
-- toTile(tile or table)-->tile
-- gen.toTile(tile or table)-->tile
-- If given a tile object, returns the tile
-- If given coordinates for a tile, returns the tile
-- Causes error otherwise
-- Helper Function (provided to this library as toTile and gen.toTile)
local function toTile(input)
if civ.isTile(input) then
return input
elseif type(input) == "table" then
local xVal = input[1] or input["x"]
local yVal = input[2] or input["y"]
local zVal = input[3] or input["z"] or 0
if type(xVal)=="number" and type(yVal)=="number" and type(zVal)=="number" then
if civ.getTile(xVal,yVal,zVal) then
return civ.getTile(xVal,yVal,zVal)
else
error("Table with values {"..tostring(xVal)..","..tostring(yVal)..
","..tostring(zVal).."} does not correspond to a valid tile.")
end
else
error("Table did not correspond to tile coordinates")
end
else
error("Did not receive a tile object or table of coordinates.")
end
end
gen.toTile = toTile

-- gen.hasIrrigation(tile)-->boolean
-- returns true if tile has irrigation but no farm
-- returns false otherwise
function gen.hasIrrigation(tile)
tile = toTile(tile)
local improvements = tile.improvements
-- irrigation, but no mining, so not farmland
if improvements & 0x04 == 0x04 and improvements & 0x08 == 0 then
return true
else
return false
end
end
</code>

[[File:GetStartedWithLuaLesson6-05-HasIrrigation.jpg]]

Let us begin by looking at the function <code>toTile</code>. The purpose of this function is to allow other functions to accept tile coordinates in a table instead of an actual tile object. The function tries to be reasonably permissive in the coordinates it will accept, allowing both integer indices and lowercase string indices, and by assuming that a missing z value corresponds to map 0. The function also tries to give reasonably helpful errors.

This brings up something that should be considered when making reusable code: what to do if you don't get values you were expecting. One option is to throw an error and bring up the Lua console. This is good for scenario creators, so they know something is wrong, but not so great for end users because the error stops the rest of the event from happening, should the mistake slip through playtesting.

The other option is for the code to fail silently, and try to do what it can. This is the way the old Test of Time macro system often fails. If Civ II doesn't "understand" the event, it just doesn't happen, and doesn't bother the player with the error. This means that the scenario will still mostly work, but it is harder to catch issues during playtesting. Sometimes, this means doing something "sensible" if the input isn't of the expected type, and might make the code easier to write, since you don't have to handle inputs differently.

A third option is to write your code such that both things can be done. At the top of your code, you put in a variable named "debugMode" or something, and make all the functions throw errors when true, and fail silently when false. Then you playtest with debugMode set to true, and release with debug mode set to false. However, this means extra work in writing your code and you also have to test everything with debug mode off.

For toTile, I went with the fail with error option, since that will allow every function that uses toTile to assume it is receiving proper data. It also seems unlikely that people will be regularly trying to check tiles that don't exist or have tables with tiles and units and improvement objects all in one. And if they do, "guarding" is fairly straightforward anyway (as we've done in previous lessons).

Although toTile is mainly meant to be a helper function for the General Library, it is also put into the gen table to be made available to end users, since it offers useful functionality. Hence, <code> gen.toTile=toTile</code>. Note that we could have given toTile a different name in the gen table that this module will return, such as gen.tableToTile=toTile. In fact, we could refer to the same function with multiple keys in the gen table, if we want to.

Next, we will look at gen.hasIrrigation.

The first thing to notice is that local is not being used to define this function. That is because we're putting the function for gen.hasIrrigation directly into the gen table that this module will return. We could define hasIrrigation as a local variable and then copy it into the gen table. However, there is a decent chance that the General Library will have more than 200 functions by the time everything is complete, since it is meant to provide a lot of building block functionality and keep it in one place, and we will run into trouble if we assign 200 local variables in a single function (which a required lua file acts as).

Perhaps the most striking thing is that we begin by changing the value of tile, the argument of the function. It looks like we're making a global variable named tile, but we're not. When you specify the names of the arguments for a function (in this case tile), you create local variables for that function, which can be given new values just as if you had explicitly used the local keyword.

Beyond that, we extract the integer representing the tile improvements into a local variable (which upon later reflection isn't really necessary), and check that the irrigation bit is set to 1 and the mining bit is set to 0. Refer to lesson 5 for why this works. In fact, we could have simply returned the value of the if statement, rather than specifying return true and return false, although it is very slightly clearer what is going on in the expanded version of the code.

Now, let us write a function to place irrigation on a square. It seems pretty clear that we should do nothing if the tile has a city, but we also have to decide what to do if there is mining or farmland on the tile, since those interfere with placing irrigation. We'll just remove them, on the basis that if we're trying to "place irrigation," then we want irrigation to be there when we are finished.

<code>
function gen.placeIrrigation(tile)
tile = toTile(tile)
</code>

These lines open the function and convert a table of coordinates to a tile if necessary.

<code>
if tile.city then
return
end
</code>

If the tile has a city, return so nothing else is done in the function.

<code>
-- Set irrigation bit to 1
tile.improvements = tile.improvements | 0x04
-- Set mining bit to 0
tile.improvements = tile.improvements & ~0x08
end
</code>

Set the irrigation bit to 1 and the mining bit to 0.

The functions in this library don't have to be complex, and in fact, most probably shouldn't be. They just have to make life easier for the end user. If you reach this lesson before the General Library is considered "complete," your assignment now is to submit some work for it. If you don't feel comfortable doing bitwise operations, you can test the work of others or submit functions that simplify other tasks. However, there are also some helper functions in the library to facilitate changing bits, so you might also consider working on the unit type flags functions. Remember, if you want to make functions available to the console for testing purposes, they must be global variables.

=== The Threshold Table and First Look at Metatables===

Consider a scenario design situation that occurred in Over the Reich: a bomber is generating some bombs via a key press, and the number of bombs it should generate is dependant on its current remaining hitpoints. The more hitpoints the bomber has, the more bombs it should generate. What we want is to specify that if a bomber has between x and y hitpoints, it should produce 2 bombs. That is, for a given type of bomber, we want to have, for example,

hp >= 16 --> 4 bombs
16 > hp >= 12 --> 3 bombs
12 > hp >= 9 --> 2 bombs
9 > hp >= 4 --> 1 bomb
4 > hp >= 0 --> 0 bombs

Unfortunately, Lua tables do not naturally encode this kind of association by default. However, Lua does have a feature called metatables, which allows us to change the behaviour of tables. (This will be a much better way to make the specification than I ended up writing in Over the Reich.)

A metatable is a table that we can "attach" to another table, and then the metatable changes the behaviour of that table. We'll only look at metatables briefly here, but more information can be found [https://www.tutorialspoint.com/lua/lua_metatables.htm here].

What we want is a data structure that can accept numerical "key values" that are between the key values explicitly specified, and return the appropriate value for those keys. We will call this data structure a threshold table, since we are specifying threshold values as keys. We can do this by assigning the following metatable:

<code>
local mt = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
</code>

If we run <code> setmetatable(myTable,mt)</code>, then whenever we ask for an index from myTable and that index doesn't currently exist in myTable, the function assigned to __index will run. Now let us examine the function.

If the type of the key is not a number, then we return whatever the table value is for that key. We use the function rawget, because the standard <code>thresholdTable[key]</code> will invoke this function again if the key doesn't exist, and so never return an answer (when we want it to return nil).

If the key type is a number, then we look for the largest numerical index that is also less than or equal to the key value. We return a default value of false if the key submitted is smaller than all numerical values. False is chosen over nil, so that a maximum value can be set by setting the value of a numerical index to false. Using the key [-math.huge] allows a return value to be set for all numbers (since all numbers are greater than -math.huge).

Since we don't want scenario creators to have to re-create threshold tables every time they need them, we'll add this functionality to the General Library

<code>
local thresholdTableMetatable = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
-- gen.makeThresholdTable(table or nil)-->thresholdTable
function gen.makeThresholdTable(inputTable)
inputTable = inputTable or {}
return setmetatable(inputTable,thresholdTableMetatable)
end
</code>

[[File:GetStartedWithLuaLesson6-06-ThresholdTable.jpg]]

===A Munition Generation Module===

Now, let us write some re-usable code for a human player to generate units by pressing a key while an appropriate unit is active. This sort of code could be used for ranged attacks (generating a "munition") and also for recruiting mercenaries by paying gold.

The first thing we will want to do is to decide how our code will be used by the end user. This will, perhaps, change by the time we finish writing the code, but it will at least give us a starting point.

spawnUnit(generatingUnit, specificationTable)--> table of unitCreated

Our goal is that when a player attempts to generate a unit using another unit, they will provide the unit spawning the new unit, and a table of information specifying if a unit (or units) can be spawned and anything else that must happen while spawning (like paying money, expending movement points, etc.).

We have an option here. We could have the scenario creator provide the specification table as a required file for our module, or the creator can provide it at the time spawnUnit is called. I choose the latter for a couple of reasons. The first is that it allows the player to have more than one specification table, either because more than one key can spawn a unit, or because the specification can change over time. The other is reason is so that the creator can make the table in the events.lua file if desired (since our module can't require information from events.lua).

Having decided that our generateUnit events are going to be specified by a table, we have to decide what the contents of that table should be. It seems pretty reasonable to index the specificationTable with the index of the unit type of each unit that can generate using the information in the table. If a unit type id number is missing, that unit doesn't generate a munition (or recruit a unit).

The value for each unit type id in the specification table will be a table that specifies how and if that unit generates other units.

--specificationTable[unitType.id]={
--
-- goldCost = integer or nil
-- amount of gold it costs to generate a unit
-- absent means 0
-- minTreasury = integer or nil
-- minimum amount of gold in treasury to generate a unit
-- absent means refer to gold cost
-- (tribe will generate and be set to 0 if treasury is less than goldCost)
-- treasuryFailMessage = string or nil
-- A message to be displayed if the unit fails to spawn a unit due to an
-- insufficient treasury
-- nil means no message

-- There are three ways to specify move costs, in full movement points,
-- in "atomic" movement points, and as a fraction of total movement points for the
-- unit type. Use only one kind per unit type

-- moveCost = integer or nil
-- movement points to be expended generating the unit
-- "full" movement points
-- absent means 0
-- minMove = integer or nil
-- minimum remaining movement points to be allowed to generate a unit
-- "full" movement points
-- absent means any movement points for land/sea, 2 "atomic" for air units
-- postGenMinMove = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostAtomic = integer or nil
-- movement points to be expended generating the unit
-- refers to the unit.moveSpent movement points
-- absent means 0
-- minMoveAtomic = integer or nil
-- minumum remaining movement points to be allowed to generate a unit
-- referes to the unit.moveSpent movement points
-- absent means any movement points for land, 2 "atomic" for air units
-- postGenMinMoveAtomic = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostFraction = number in [0,1] or nil
-- fraction of unit's total movement points expended generating the unit
-- round up to nearest "atomic" movement point
-- absent means 0
-- minMoveFraction = number in [0,1] or nil
-- fraction of unit's total movement points that must remain to be allowed
-- to generate a unit
-- absent means any movement points for land, 2 "atomic" for air units
-- round up to nearest "atomic" movement point
-- postGenMinMoveFraction = number in [0,1] or nil
-- a unit will be left with at least this many movement points after
-- the generation function, round up to nearest "atomic" move point
-- absent means 0 for land/sea, 1 "atomic" for air units
-- roundFractionFull = bool or nil
-- fractional movement cost and minimum are rounded up to full movement point
-- instead of atomic movement point
-- nil/false means don't
-- roundFractionFullDown = bool or nil
-- fractional cost and minimum are rounded down to full move point
-- nil/false means don't
-- minMoveFailMessage = string or nil
-- a message to be displayed if a unit is not generated due to insufficient
-- movement points.
-- nil means no message

-- allowedTerrainTypes = table of integers or nil
-- a unit may only be generated if the tile it is standing on
-- corresponds to one of numbers in the table
-- nil means the unit can be generated on any terrain type
-- terrainTypeFailMessage = string or nil
-- message to be displayed if a unit is not generated due to standing
-- on the incorrect terrain

-- requiredTech = tech object or nil
-- the generating civ must have this technology in order to generate
-- the unit
-- nil means no requirement
-- techFailMessage = string or nil
-- message to be displayed if a unit is not generated due to not having
-- the correct technology

-- payload = boolean or string
-- if true, unit must have a home city in order to generate munitions
-- and generating munitions sets the home city to NONE
-- payloadFailMessage = string or nil
-- message to be displayed if a unit is not generated due to the
-- payload restriction
-- payloadRestrictionCheck = nil or function(unit)-->boolean
-- If function returns false, the home city is not valid for giving the
-- unit a payload. This will be checked when the unit is activated, when
-- the unit is given a new home city with the 'h' key and when the unit
-- tries to generate a munition
-- nil means no restriction
-- payloadRestrictionMessage = nil or string
-- message to show if a unit fails the payloadRestrictionCheck

-- canGenerateFunction = nil or function(unit)-->boolean
-- This function applied to the generating unit must return true in order
-- for a unit to be spawned. All other conditions still apply.
-- any failure message should be part of canGenerateFunction
-- absent means no extra conditions

-- generateUnitFunction = nil or function(unit)-->table of unit
-- This function creates the unit or units to be generated
-- and returns a table containing those units
-- Ignore any specifications prefixed with * if this is used
-- nil means use other specifications

--*generatedUnitType = unitType
-- The type of unit to be generated
-- can't be nil unless generateUnitFunction is used instead

--*giveVeteran = bool or nil
-- generated unit(s) given veteran status if true
-- nil or false means don't give vet status
-- if true, overrides copyVeteranStatus

--*copyVeteranStatus = bool or nil
-- generated unit(s) copy veteran status of generating unit if true
-- nil or false means don't give vet status

--*setHomeCityFunction = nil or function(generatingUnit)-->cityObject
-- determines what home city the spawned unit should have
-- nil means a home city of NONE

--*numberToGenerate = nil or number or thresholdTable or function(generatingUnit)-->number
-- if nil, generate 1 unit in all circumstances
-- if integer, generate that many units (generate 0 if number less than 0)
-- if number not integer, generate floor(number), and 1 more with
-- probability number-floor(number)
-- if thresholdTable, use remaining hp as the key, to get the number to create
-- if function, get the number as the returned value of the function

-- activate = bool or nil
-- Activates one of the generated units if true. If generateUnitFunction was used,
-- the unit at index 1 is activated, if index 1 has a value. (if not, any unit in
-- the list might be chosen)

The very last entry brings forward a change that must be made to our unit generation specification. Lua's activate unit command doesn't run the unit activation trigger, even though the active unit is changed. Therefore, we must do that manually. Hence,

<code>spawnUnit(generatingUnit, specificationTable)--> table of unitCreated</code>

becomes

<code>spawnUnit(generatingUnit,specificationTable,unitActivationCode)-->table of unitCreated</code>

Perhaps we will change it again later.

I've decided to try a different instructional technique for this section. Instead of writing the code and then going through it section by section, I've recorded a video of my coding and testing this module, and I attempt to explain some of the stuff that I do along the way.

I'm not sure of the value of the video. If you find that there seems to be little useful content relative to the time it takes to watch, then feel free to skip it and continue the lesson. I don't teach anything "new" in it, so you won't miss anything crucial. However, it should be pretty close to how programming Lua can actually happen in the "real world." While I did give some thought to how to write the module before I started, I do attempt to solve problems in real time, and make mistakes that are not discovered for a while (including one where I try to explain how I solve a problem and then not actually do a crucial part).

You can find the code [https://forums.civfanatics.com/threads/totpp-the-munitions-library.647910/ here]. Even if you decide not to watch the video, download the code and try testing some of the features based on the specification above. If you find any bugs, submit a fix (or at least report the issue).

The video can be found [https://youtu.be/XxPyNknGlAo here].

===A Unit Attack Bonus for Complementary Units in Square===

Something we might like to do is to give units an attack bonus if they attack from a square with some special unit, for example a "leader" unit. The [[Napoléon I]] scenario, for example, gives an attack bonus to units if a commander unit, such as Napoleon, is in the square when the unit is activated (the unit can subsequently move and still retain the bonus as long as no other unit is selected). We will now make a module providing the same functionality.

We first have to have a basic idea of how this functionality should work. When a unit is activated, the onActivateUnit event checks if the newly activated unit should get an attack bonus, based on the other units in the square. If the unit deserves an attack bonus, the corresponding unitType.attack entry is changed, and all the attack value of all other units is reset to the default value. If the activated unit also does not deserve an attack bonus, that value is also set to the default value.

This now leads us to some more possibilities. Should multiple bonus units lead to multiple bonuses or only apply the best one? For example, suppose a legion gets a bonus if an archer is also in the same square. Should two archers provide twice the bonus? Perhaps two archers should provide a larger bonus than one, but not twice as much. Perhaps a legion should also get a bonus if there is a catapult in the square, but that bonus should apply even if the maximum archer bonus is already achieved. It seems like perhaps there should be a "ranged unit" bonus, an "artillery unit" bonus and maybe a "cavalry" bonus which should all impact the legion's attack value. It's looking like we might end up demanding that a scenario creator make a big complicated table in order to use this functionality, even if they only have simple needs.

What we can do to alleviate this is to write a "simple" version of the event that is easy to use (and program), and also write a more complicated version that gives the expanded capability.

Specification Table for simpleAttackBonus

--simpleAttackBonusTable[activeUnit.type.id] ={[bonusUnitType.id]=bonusNumber}
--simpleAttackBonusTable.type = string
--if simpleAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if simpleAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
--if simpleAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- if simpleAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- if simpleAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
--simpleAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

The relevant first draft of the code is as follows:

<code>
local function simpleAttackBonus(activeUnit,simpleAttackBonusTable,defaultAttackTable)
-- reset all unit attack values
for unitTypeID,attackValue in pairs(defaultAttackTable) do
civ.getUnitType(unitTypeID).attack = attackValue
end
local unitBonusTable = simpleAttackBonusTable[activeUnit.type.id]
if not unitBonusTable then
-- unitBonusTable is nil (or false), so the active unit can't
-- get a bonus
return
end
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
local bestBonusSoFar = 0
for unit in activeUnit.location.units do
if unitBonusTable[unit.type.id] and unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
if bestBonusSoFar == 0 then
-- If no bonus unit is found, this will be true, so do nothing else
return
end
-- set the new attack and return
if string.lower(simpleAttackBonusTable.type) == "addBonus" then
activeUnit.type.attack = activeUnit.type.attack+bestBonusSoFar
return
end
local attackMultiplier = 1
if type(simpleAttackBonusTable.type) ~= "string" then
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
elseif string.lower(simpleAttackBonusTable.type) == "addpercent" then
attackMultiplier = (100+bestBonusSoFar)/100
elseif string.lower(simpleAttackBonusTable.type) == "addfraction" then
attackMultiplier = 1+bestBonusSoFar
elseif string.lower(simpleAttackBonusTable.type) == "multiplypercent" then
attackMultiplier = bestBonusSoFar/100
elseif string.lower(simpleAttackBonusTable.type) == "multiply" then
attackMultiplier = bestBonusSoFar
else
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
end
-- apply the bonus and round as appropriate
if type(simpleAttackBonusTable.round) ~= "string" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
elseif string.lower(simpleAttackBonusTable.round) == "up" then
activeUnit.type.attack = math.ceil(activeUnit.type.attack*attackMultiplier)
return
elseif string.lower(simpleAttackBonusTable.round) == "down" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier)
return
else
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
end
end
</code>

Now let us go over this section by section.

[[File:GetStartedWithLuaLesson6-07-AttackBonus1.jpg]]

The first thing we do is to reset all the attack values of all the unit types. That way, if a bonus existed for the last unit activated, that bonus no longer applies. If a unit type is not in the defaultAttackTable, then we don't have the information to reset the attack value anyway, so we can safely ignore it by using the pairs function to iterate over the table.

Now, we must find out if the newly activated unit deserves a bonus. For that, we get the table associated with the active unit's type. If the value is nil instead of a table, then the unit's type is not in the simpleAttackBonusTable, so there is no bonus to apply and the function returns.

If the unit is eligible for bonuses, we then check the units in the square to see if any bonuses actually apply. We've seen this kind of code before. If the unit in the stack can provide a bonus, and that bonus is better than the best bonus already found, the unit now provides the best bonus. All bonus types that we can have are better if they are larger, and we are not comparing between bonus types, so a simple numerical comparison will do. All bonuses are larger than 0 in our formulation, so 0 is a good starting value in the search.

If the best bonus so far is still 0, there is no bonus, so the function can return.

At this point, it occurs to me that when searching for the best bonus, we should exclude the active unit from the search. That way, you can have a "strength in numbers" bonus, for example. The relevant change to the code is:

<code>
for unit in activeUnit.location.units do
if unit ~= activeUnit and unitBonusTable[unit.type.id] and
unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
</code>

Next, consider

[[File:GetStartedWithLuaLesson6-08-AttackBonus2.jpg]]

Here, we apply the bonus that we've found. We use string.lower on simpleAttackBonusTable.type so that we don't have to worry about capitalization. That does, however, require a correction to "addBonus", since a lower case string will never be equal to that.

"addbonus" is the only type of bonus that is directly added to the existing attack value. All other bonus types are a form of multiplication. Since the addition is straightforward and doesn't require any rounding, the activeUnit's type attack value can be changed immediately, and the function execution ended with return.

When there is only one bonus being applied, all other types of bonus are different ways of expressing how to multiply the existing attack value to get a new one, so we simply convert to the appropriate multiplier, and provide an error message if the type of bonus is not one of the valid possibilities.

Finally, we round the attack value to an appropriate integer (since unit attack values must be integers), change the attack value of the active unit's type, and return to end the function execution.

Now, we integrate into events.lua by using

<code>
attackBonus = require("attackBonus")
</code>

The relevant integration code for events.lua is
<code>
local defaultAttackValueTable = {[unitAliases.legion.id]=4}
local simpleAttackBonusTable ={}
simpleAttackBonusTable.type = "addbonus"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=3,[unitAliases.musketeer.id]=4}

local function doOnActivation(unit,source)
munitions.payloadRestrictionCheck(unit,munitionSpecificationTable)
attackBonus.simpleAttackBonus(unit,simpleAttackBonusTable,defaultAttackValueTable)
end
</code>

We can check that the bonus is being applied correctly by checking the Civlopedia entry for legion and looking at the attack value. The following cases must be tested (remember that activating a unit from the city screen doesn't run the onActivation event, so activate from the map).

Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (7 attack)
Legion activated with musketeer, but no archer (8 attack)
Legion activated with archer and musketeer (8 attack)
Legion activated with 2 archer, no musketeer (7 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).
I recommend making a stack for each of these cases and activating them one by one.
To facilitate the test, add the following line to doOnActivation
<code>
civ.ui.text(tostring(unit.type.attack))
</code>
You will want to comment out this line after testing.

Next, change simpleAttackBonusTable to do "addpercent"
<code>
simpleAttackBonusTable.type = "addpercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=30,[unitAliases.musketeer.id]=70}
</code>

With no rounding set, standard rounding is used
Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)
Legion activated with archer and musketeer (7 attack)
Legion activated with 2 archer, no musketeer (5 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

These numbers test both rounding up and rounding down.

Now, use
simpleAttackBonusTable.round="up"
Legion activated with archer, but no musketeer (6 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next,
simpleAttackBonusTable.round="down"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (6 (6.8) attack)

simpleAttackBonusTable.round="standard"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next, we test "addfraction". Since we've tested all the rounding options, we don't have to do that again.

<code>
simpleAttackBonusTable.type = "addfraction"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=0.3,[unitAliases.musketeer.id]=0.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiplypercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=130,[unitAliases.musketeer.id]=170}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiply"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Before we finish, we should test a legion bonus for the legion.
<code>
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.legion.id]=2,[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>

Legion alone should have 4 attack.
A second legion on the square should provide 8 attack instead.

Now, let us try to formulate a more complicated bonus system. One thing we mentioned is that we'd like the ability to get bonuses from multiple units, and to be able to get bonuses from different "classes" of units (like "artillery," "cavalry," and "ranged attackers." Something else we might want to do is to allow different kinds of bonuses. That is, maybe some units should provide a fixed +2 to any unit receiving the bonus, so that it is better at improving units with a low attack value, while other units should provide a percentage bonus (making them better at supporting units with an already high attack value). It turns out that both of these ideas are not too difficult to implement individually, but that trying to implement them together makes it problematic to find the best bonus.

Let us implement a bonus system with multiple categories but only one bonus type. In our specification, we will first specify a data type called "bonusCategory." It is still just a table (though we could add a metatable if we wanted), but it will help us make our specification clearer.

<code>
-- A "bonusCategory" is a table
-- bonusCategory = {[bonusUnitType.id]=bonusNumber, maxBonusUnits=integer or nil, nextBonusValue = fraction or nil}
-- In a bonusCategory, the value for bonusUnitType.id tells what the base bonus for that unit type is,
-- maxBonusUnits is the maximum number of units that can provide a bonus in this category,
-- nextBonusValue tells how much to reduce the bonus for each subsequent unit,
-- e.g. nextBonusValue = 0.7, and 5 units, which each have a bonusNumber=1
-- The total bonus is 1(0.7)^0+.7+(.7)(.7)+(.7)^3+(.7)^4 = 1+.7+.49+.343+.2401=2.7731
-- (which would be rounded as specified)
-- nil means nextBonusValue=1
--
-- If a unit type is in two bonus categories for the same unit, there is no guarantee that the
-- best bonus will be achieved
</code>

So, the bonus category is indexed by unitType id numbers for units that can give a bonus, and the corresponding bonus. It also specifies the maximum number of units that can give a bonus, and a number that governs how to reduce a bonus for extra units. That way, there can be diminishing returns for bonuses.

Next, we look at the specification for the categoryAttackBonusTable

<code>
--categoryAttackBonusTable[activeUnit.type.id] =table of bonusCategory
--categoryAttackBonusTable.type = string
--if categoryAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if categoryAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
-- for multiple unit bonuses, add up all the percents, then compute the bonus
-- i.e. 50% bonus and 50% bonus is 100% bonus, not 125%
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 50% bonus units become 50% + 25%
-- so attack 6 --> 10.5
--if categoryAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- for multiple unit bonuses, add up the fractions, then compute the bonus
-- i.e. .5 bonus and .5 bonus is 1+.5+.5= 2x bonus, not 2.25x
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 .5 bonus units become .5+.25
-- so attack 6 --> 10.5
-- if categoryAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- bonuses are multiplied together, i.e. 150% and 150% yields 225% of original value
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 100, i.e. nextBonusValue=.5 2 150% bonuses become 150% and 125%
-- so attack 6 --> 11.25
-- if categoryAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
-- bonuses are multiplied together, i.e. 1.5 and 1.5 yields 2.25x
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 1, i.e. nextBonusValue=.5 and two 1.5 bonuses become 1.5 and 1.25
-- so attack 6 --> 11.25
--categoryAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

-- If the active unit can get a bonus, go through each category and compute the bonus for that category.
-- Then, combine the bonuses for all categories to get the overall bonus, and round the result
</code>

With the bonusCategory defined, the value of the unit indices of categoryAttackBonusTable become easy to define. Most of the specification is showing what exactly the different bonus categories mean, so the end user can use them properly. It's not strictly necessary to offer so many choices to the end user on how to specify data, but it can be more convenient.

Here is the actual code (before testing) to implement this more general version of attack bonuses.

<code>
-- HELPER FUNCTION
-- findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable) --> number or false
-- usedUnitTable is indexed by the i.d. number of units, and if the value for a unit is true,
-- then it has already been used for a bonus (and, so, is not eligible)
-- The function returns the bonus (before nextBonusValue is applied) if there is one, and marks the
-- unit as used in the usedUnitTable
-- returns false if no unit qualifies
local function findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable)
local bestBonusSoFar = 0
local bestUnitSoFar = nil
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
for unit in tile.units do
if not usedUnitTable[unit.id] and bonusCategory[unit.type.id]
and bonusCategory[unit.type.id] > bestBonusSoFar then
bestUnitSoFar = unit
bestBonusSoFar = bonusCategory[unit.type.id]
end
end
if bestUnitSoFar then
usedUnitTable[bestUnitSoFar.id] = true
return bestBonusSoFar
else
return false
end
end

-- HELPER FUNCTION
-- computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
-- Computes the bonus that the active unit will receive from this category, taking into
-- account the type of bonus for the table
local function computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
local bonusThusFar = nil
if bonusType == "multiply" then
bonusThusFar = 1
elseif bonusType == "multiplypercent" then
bonusThusFar = 100
else
bonusThusFar = 0
end
local bonusDiscount = 1
for i=1,(bonusCategory.maxBonusUnits or 10000) do
local currentBonus =findBestBonusInUnitStack(activeUnit.location,bonusCategory,usedUnitTable)
if not currentBonus then
-- no more valid bonuses for this category
break
end
if bonusType == "multiply" then
bonusThusFar = bonusThusFar*((currentBonus-1)*bonusDiscount+1)
elseif bonusType =="multiplypercent" then
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
else
bonusThusFar = bonusThusFar+currentBonus*bonusDiscount
end
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
end
return bonusThusFar
end

local function categoryAttackBonus(activeUnit,categoryAttackBonusTable,defaultAttackTable)
local bonusInfoTable = categoryAttackBonusTable[activeUnit.type.id]
if not bonusInfoTable then
-- unit doesn't get a bonus
return
end
-- keep track of bonuses already computed
local bonusResultsTable = {}
-- keep track of units that have already been "used" for a bonus
local usedUnitTable = {[activeUnit.id]=true}
for index,bonusCategory in pairs(bonusInfoTable) do
bonusResultsTable[index]=computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
end
-- compute the bonus
local bonusType = string.lower(categoryAttackBonusTable.type)
local resultAttackBeforeRounding = nil
if bonusType == "multiply" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "multiplypercent" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult/100
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "addbonus" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack+bonus
elseif bonusType == "addfraction" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
elseif bonusType == "addpercent" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+(bonusResult/100)
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
else
error("categoryAttackBonus: categoryAttackBonusTable.type is not a valid value.")
end
-- apply the bonus and round as appropriate
local roundType = categoryAttackBonusTable.round
if type(roundType) ~= "string" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
elseif roundType == "up" then
activeUnit.type.attack = math.ceil(resultAttackBeforeRounding)
return
elseif roundType == "down" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding)
return
else
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
end
end
</code>

The two helper functions for computeCategoryBonus are only used once each in the code, so making them helper functions does not help us re-use code. However, what it does do is to break down the function design process into smaller tasks, which are each more manageable to complete. If you're trying to keep track of too many things in your program, try writing a few helper functions to handle individual tasks. We'll look at the helper functions when we actually arrive at them in the code.

[[File:GetStartedWithLuaLesson6-09-CategoryAtkBonus1.jpg]]

If there is no entry in the categoryAttackBonusTable or the active unit's type, then the function returns without doing anything further.

The bonusResultsTable keeps track of the total bonus from each category, so they can be added or multiplied together after all the category bonuses are applied. The usedUnitsTable keeps track of units that are no longer eligible to contribute to a bonus (such as if they have already contributed), and we initialize it with the active unit, so that it doesn't provide a bonus to itself.

The for loop computes the bonus for every category, and stores the value in the bonusResultsTable, for use later.Now, let us look at the helper functions.

First up is findBestBonusInUnitStack

[[File:GetStartedWithLuaLesson6-10-CategoryAtkBonus2.jpg]]

This basically does what it says in the name. For a bonusCategory, it finds the unit in the tile that provides the best bonus, and has not already provided a bonus elsewhere. If there is no qualifying unit, false is returned. If there is, that unit's bonus is returned, and the unit's id is entered into the usedUnitTable, so that unit can't provide another bonus for the active unit. We've searched for the best of something before, so there is little need to go over it again.

Next is computeCategoryBonus

[[File:GetStartedWithLuaLesson6-11-CategoryAtkBonus3.jpg]]

Here, we're computing the bonus for the entire bonusCategory. We need the bonus type in order to know what kind of math to do. The math itself is not very interesting. We also initialize the bonusDiscount, which keeps track of the fraction of the next unit's bonus that will actually be applied.

Next, we enter a for loop that will run one time for each possible bonus that there can be in a bonus category. If bonusCategory.maxBonusUnits is nil, then we set an arbitrary limit of 10000 units, which is very unlikely to happen in practice.

At each iteration of the loop, the best available bonus in the stack is found. If no unit was eligible to provide a bonus, then the current bonus is false, and the "break" command is issued. Break immediately exits the current loop. So, our program doesn't run 10000 loops if there is no maximum number of bonus units, it just breaks at an appropriate time.

After the bonus is found, it is added to or multiplied with the bonus already found. The bonus computed in this way will be the largest possible, since the bonus provided does not depend on the other units chosen (so we don't have a situation where "catapult" and "rock" are both useless, but "catapult" and "rock" chosen together are best). Also, since the best bonus is chosen first, the smallest bonus discount applies to it, so the cost imposed by the discounting is smallest.

Finally, we update the bonusDisount. Here, I notice a problem in the code as written, since bonusCategory.nextBonusValue is allowed to be nil. Replace
<code>
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
</code>
with
<code>
bonusDiscount = bonusDiscount*(bonusCategory.nextBonusValue or 1)
</code>
so that if there is no nextBonusValue, a default of 1 is used, and the bonusDiscount stays at 1 (i.e. no discount is applied).

We return to categoryAttackBonus to see

[[File:GetStartedWithLuaLesson6-12-CategoryAtkBonus4.jpg]]

From here, we combine the bonuses stored in bonusResultsTable, the exact way of doing so being dependant on the type of bonus involved. The math itself isn't very interesting, and doesn't seem all that likely to come up in this exact form elsewhere. If you need help with the mathematical details of some event you want to write, ask in the forums. There's a good chance someone has the skills to help you solve your specific problem.

For every type of bonus, the result is stored in resultAttackBeforeRounding, so that variable can be rounded up or down as specified by the rounding type.

Here, I notice another error. We should restrict the attack value for a unit to not exceed 98. We can do that with a math.min(value, 98).

Now, we need to test the various aspects of the attack bonus program, so we need an appropriate table
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addbonus"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=2,[unitAliases.chariot.id]=4,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=2,[unitAliases.musketeer.id]=4,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Also, comment out the old attack bonus line, and put in a new one
<code>
attackBonus.categoryAttackBonus(unit,categoryAttackBonusTable,defaultAttackValueTable)
</code>

Expected Test Results when type is "addbonus"
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

Already, we find a problem. Although there were no syntax errors to fix, I forgot to reset unit attack values. So, very quickly, the legions keep gathering extra attack values when they are activated (since the base attack is not reset to 4). Since this is happening anyway, I'll test the 98 attack value maximum. That appears to work, at least in the case of no specified rounding.

Cut and paste the appropriate lines from the simpleAttackBonus to the categoryAttackBonus, and save.

With that bug fixed, everything works as expected.

Next, we change the categoryAttackBonusTable to

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addpercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=50,[unitAliases.chariot.id]=100,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=50,[unitAliases.musketeer.id]=100,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>

Expected Test Results when type is "addpercent". These are the same, since adding we're adding percentages of the same base value of 4. So a value of 2 is the same as adding 50% of 4.
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

The results are the same.

Similarly,

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addfraction"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=.50,[unitAliases.chariot.id]=1.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=.50,[unitAliases.musketeer.id]=1.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

We'll have to do some new calculations, now, since multiply and multiplyfraction give different results than the various adding formulations.

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiply"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=1.50,[unitAliases.chariot.id]=2.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=1.50,[unitAliases.musketeer.id]=2.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Finally, we use multiplyPercent, and check for the same results
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=150,[unitAliases.musketeer.id]=200,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Quickly, I find that if a bonus applies, that bonus makes the attack value of a legion 98. I failed to multiply percents correctly in computeCategoryBonus. The Line
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
</code>
Is changed to
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+100)/100
</code>

Finally, Change archer bonus to 110 and musketeer bonus to 120 (so a unit will make a legion have 4.4 and 4.8 value before rounding), and test the rounding options. You will find they all work.

At the moment, we don't have a way to mix different types of bonuses. As said earlier, we might want this so that some units can be better at giving bonuses to low attack units than to high attack units, while others give a percentage bonus to everything. We could now write a bonus system that allows for multiple types of bonuses. However, the current bonus system allows for the bonus to change per unit. This means that we can, for example, convert a +2 attack bonus to a plus 100% bonus for a unit with 2 attack, and a plus 50% bonus for a unit with 4 attack. In the case of the multiplied bonuses, this will make the bonus more powerful if there is more than one. That is, 2 attack, +2 twice is 6, but if +2 is changed to x2, then the multiplied bonus brings the attack up to 8. However, this seems like it would be a relatively unlikely problem, and there are other things this code can't handle, so we'll let someone else make the code if they actually need it.

So, what we'll do is write a function that will change all appropriate entries in the categoryAttackBonusTable to reflect a different value. Hence,

<code>
-- plusFixed(unitType,number,categoryAttackBonusTable) --> void
-- changes the bonus given by unit type to any unit to be equivalent
-- to adding number to that unit's attack power
</code>

Here, an issue with tables arises. It is very likely that when someone defines their cateogryAttackBonusTable, they'll define it something like this
<code>
local rangeBonusCategory = {[unitAliases.archer.id]=.25,[unitAliases.musketeer.id]=.5}
local bonusTableForInfantry = {rangeBonusCategory}
local cABT = {type="addfraction"}
cABT[unitAliases.phalanx.id]=bonusTableForInfantry
cABT[unitAliases.legion.id] = bonusTableForInfantry
</code>
However, this means that both <code> cABT[unitAliases.legion.id] </code> and <code> cABT[unitAliases.phalanx.id] </code> actually refer to the same piece of memory, and changing cABT[unitAliases.legion.id][1][unitAliases.archer.id] will also change the value at cABT[unitAliases.phalanx.id][1][unitAliases.archer.id]. This is because of the way lua tables are designed. This design can be useful, for example it allowed us to make changes to usedUnitsTable in the last function without having to copy the table, make changes to the copy of the table, and then replace the original table with that copy as a return value. However, it also requires us to be careful when we make changes to entries in tables. In this case, we'll simply copy the table and all its sub values into a new table.

The code to do this is given by
<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

We will explain this code in the next section, since it involves a programming technique which we haven't discussed before.

For now, we analyze plusFixed:

<code>
-- plusFixed({[unitType1.id]=fixedBonus,[unitType2.id]=fixedBonus},categoryAttackBonusTable) --> void
-- changes the bonus given by unitTypeI.id to a unit to be equivalent to
-- to adding number to that unit's attack power. If the unit doesn't receive a bonus
-- from the unitType, then it won't after applying plusFixed.
-- The value of the existing bonus is ignored.

local function plusFixed(fixedUnitBonusTable,categoryAttackBonusTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
for bonusReceivingUnitTypeID,bonusTable in pairs(categoryAttackBonusTable) do
-- replace bonusTable with an equivalent table that is not referened
-- anywhere else, so that changes to it can be made without impacting
-- data elsewhere
categoryAttackBonusTable[bonusReceivingUnitTypeID] = duplicateTable(bonusTable)
-- make bonusTable refer to the "current" bonus table for the unit type
bonusTable =categoryAttackBonusTable[bonusReceivingUnitTypeID]
-- For each unit type in the fixedUnitBonusTable, check if any bonus category
-- in the bonusTable corresponds to it. If so, make the change
for bonusGivingUnitTypeID,fixedBonusValue in pairs(fixedUnitBonusTable) do
-- get the attack of the unit type
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
-- in each bonus category, check if the giver's unit type id is there,
-- if so, change to the correct attack
for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
if bonusCategory[bonusGivingUnitTypeID] then
-- change the bonus appropriately
if bonusType == "addbonus" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue
elseif bonusType == "addpercent" then
bonusCategory[bonusGivingUnitTypeID]=100*fixedBonusValue/baseAttack
elseif bonusType == "addfraction" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue/baseAttack
elseif bonusType == "multiplypercent" then
bonusCategory[bonusGivingUnitTypeID]=100*(fixedBonusValue+baseAttack)/baseAttack
elseif bonusType == "multiply" then
bonusCategory[bonusGivingUnitTypeID]=(fixedBonusValue+baseAttack)/baseAttach
else
error("pluxFixed: categoryAttackBonusTable.type does not have an acceptable value.")
end
end
end
end
end
end
</code>

[[File:GetStartedWithLuaLesson6-13-plusFixed1.jpg]]

As before, we save the bonusType in lower case, since we'll be using it a lot later. Next, we open a for loop, where the index is the id of the unit type receiving the bonus, and the value is the bonus table for that unit type. Next, we duplicate the bonus table, so that we have a table we can change without impacting anything elsewhere, and we store the duplicated table in categoryAttackBonusTable in place of the original bonusTable for the current bonus receiving unit id. Next, we assign this duplicated table to the variable bonusTable, so we can refer to it later in the code.

[[File:GetStartedWithLuaLesson6-14-plusFixed2.jpg]]

We now perform the following actions for each unitType.id and corresponding fixedBonusValue submitted in the fixedUnitBonusTable.

First, get the attack of the bonus receiving unit, since we'll need that in order to customize the bonus. Next, check each bonus category in the bonus table. If the bonus category has the current unitTypeID as a key, then replace the existing value with a bonus equivalent to adding a fixed value to the receiving unit's attack.

That's all that must be done, so end all the loops.

Now we test the function.

Add unitAliases.phalanx = civ.getUnitType(3) to the appropriate file.

<code>
defaultAttackValueTable[unitAliases.phalanx.id]=1
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,
nextBonusValue=0.5,maxBonusUnits=1}
local rangeBonusCategory = {[unitAliases.archer.id]=125,[unitAliases.musketeer.id]=150,
nextBonusValue=0.75,maxBonusUnits=1}
local standardBonus = {cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable[unitAliases.legion.id]=standardBonus
categoryAttackBonusTable[unitAliases.phalanx.id]=standardBonus
categoryAttackBonusTable.round="up"
attackBonus.plusFixed({[unitAliases.chariot.id]=2,[unitAliases.musketeer.id]=2},
categoryAttackBonusTable)
</code>
The chariot and the musketeer individually should each add 2 to both a phalanx and a legion,
so the phalanx should have an attack of 3, and the legion should have an attack of 6, if one bonus
is applied.

Since the bonus type is multiplypercent, together the phalanx would have an attack of 9, and the legion will also have an attack of 9.

In testing, we quickly get this error
<code>
You should see this in lua console if this worked
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: bad argument #1 to 'getUnitType' (number expected, got string)
stack traceback:
[C]: in function 'civ.getUnitType'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>

At line 356, which is

<code>
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
</code>

This must mean that bonusReceivingUnitTypeID is not a number. This is because we're looping over categoryAttackBonusTable, and that table has a couple of entries that are not integers ("type" and "round"). Therefore, we have to insert code to deal with this eventuality.

The simplest way is to put everything in the loop body into an if statement, so that it only runs when bonusGivingUnitTypeID is actually a number. You should be able to do this without detailed instructions, so do so (hint: use type function).

The next error is
<code>
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: bad argument #1 to 'pairs' (table expected, got nil)
stack traceback:
[C]: in function 'pairs'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>
<code>
360 for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
</code>

Here, we have a nil value for bonusTable. This turns out to be an error in duplicateTable. When I duplicated the table, I forgot to return that table. That is, both the if and else statement in that function need a return command, and I forgot to add <code> return duplicatedTable </code> in the if portion. Add this to the duplicate table function.

After this, our predictions are true. Testing the other types of bonus is left as an assignment.

===Recursive Functions===

Let us return to the duplicateTable function. Recall that in the last section we added a line to it, so we'll restate it here:

<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
return duplicatedTable
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

[[File:GetStartedWithLuaLesson6-16-duplicateTable.jpg]]

The interesting thing about duplicateTable is that it invokes duplicateTable within its code. When we copy the key-value pairs into the new table, we run duplicateTable on the value. If the value is not a table, then we are in the else case, and the value is immediately returned to be inserted into the duplicated table. If the value is a table, that table is duplicated before anything else is done.

Let us look at a simple example of a recursive function, the factorial function N!. In lesson 3, we discussed the factorial function in the context of loops. Since N!=N*(N-1)*(N-2)*...*3*2*1, we can give another definition of N!:
N!=1 if N = 1
N!=N*(N-1)! if N > 1
Or, using the convention that 0!=1, we can state
N!=1 if N = 0
N!=N*(N-1)! if N > 0

The case where N =1 or N=0 is called the "base case." If we keep substituting N! as N*(N-1)!, then we won't go on forever, because we will eventually reach a point where N=0, and N! can be substituted as 1 instead of N*(N-1)!. As long as there is a base case, our program will eventually reach the base case(s), and begin "completing" evaluation.

<code>
function factorial(N)
if N>0 then
return N*factorial(N-1)
else
return 1
end
end
print(factorial(5))
print(factorial(6))
</code>

Run this in code in the lua demo website, or using the TOTPP lua interpreter.

Returning to our duplicateTable function, the base case is any time a table value is not itself a table. When that happens, the recursion "chain" ends, and everything can evaluated.

Although is shouldn't be a problem in this particular case, it should be noted that it is possible for there to not be a "base case" in the recursion style: if table, recur, if not return a value. Consider the following table system

<code>
a={}
b={[1]=a}
a[1]=b
</code>
In this case, the code would never end.

It is possible that even if the code could "theoretically" execute to completion, you run out of memory before that. This is called a "stack overflow," and if it occurs, you will have to think of an alternate way to solve your problem. It will probably be best to ask for help in that case (and it might be useful to provide others with an example of a problem that results in a stack overflow), but you might also look into "tail recursion", including http://www.lua.org/pil/6.3.html .

===Conclusion===

With the skills covered in this chapter, you now have the tools to split a large events file into multiple files that are more manageable. You also have the basics for how to write re-useable modules for your events, so that your work can be used by others. Remember that if someone else uses your implementation of a feature, they will spend much less time coding and testing it, allowing them to either finish the scenario sooner, or to introduce some other feature. So, it might very well pay to spend at least a little effort making your code into a reusable module. Perhaps you have an idea for a cool scenario mechanic, but don't have a scenario for it (or don't want to take the time to make it). If that's the case, just make the module and test it in a "toy" scenario (like Classic Rome) so that it can be used more or less "off the shelf" when someone needs it.

Get Started With Lua Events Lesson 6: Splitting Code into Multiple Files

2019-07-26T14:28:18Z

Prof. Garfield: /* The Threshold Table and First Look at Metatables */

[[Category:Lua Resources]]
Back to [[Get Started With Lua Events by Prof. Garfield| Get Started With Lua Events]]

This Lesson is under construction.

===Introduction===

In this lesson, we will take a look at how to split the code for a scenario's events into multiple files. There are several reasons to consider doing this.

The first reason is simply to organize your work. If you have a series of complicated events, the events.lua file can become very large very quickly. Once your events.lua file has thousands of lines of code in it, it may not be very obvious where the best place is to put that next helper function, or where to implement the function that runs a complicated event. Sometimes even finding the piece of code that has to be changed can be a bit of a hassle. In Over the Reich, I sometimes search for the associated civ.scen line, and then search for the exact name of the function I need. Occasionally, there may even be more searching to find what I actually have to change. With multiple files, it becomes easier to find things.

Another aspect of using multiple files is that you can make certain changes without worrying about breaking things elsewhere. If myBigComplicatedFunction relies on aModestHelperFunction for a certain part of its functionality, and a change to myBigComplicatedFunction also requires a change to aModestHelperFunction, you have to make sure that nothing else in your code also uses aModestHelperFunction, or, if something else does depend on it, that aModestHelperFunction either still provides the original functionality, or that all other functions that use aModestHelperFunction are suitably modified. If myBigComplicatedFunction is defined in its own lua module, then you don't have to worry about forgetting that aModestHelperFunction was used elsewhere, since it can't be accessed outside the module unless you specifically allow it to be.

A second reason to split events code into multiple files is to facilitate collaboration. If all of the events are in a single file, then only one person can make changes to the file at a time. If one partner starts changing an event, but has to do something else before finishing, everyone waits on one person's delay. However, if most aspects of the scenario are separated into individual files, everyone can work on his or her own piece of the puzzle without depriving others of the opportunity to work at that time.

A third reason to split events into multiple modules is to facilitate reusing code. If everything required to implement an event is in its own file (or files), it becomes much easier for other creators to use your functionality in their scenario. Since everything they need is already in one place, they don't have to find every last helper function, or concern themselves with naming conflicts.

===Two Simple Examples===

Let us look at the top of the events.lua file. You can get the version that I started lesson 6 with [[here]].

[[File:GetStartedWithLuaLesson6-01-DefaultRequire.jpg]]

We get code from other files by using the command <code>require</code> along with a string specifying the file name (except for the .lua extension). At the moment, we can only get code stored in the lua folder in the Test of Time directory. This is inconvenient if we're trying to distribute a scenario, since installing a scenario would require moving certain files to the lua directory, and those file names might conflict. Instead, we need to tell the Lua interpreter to search in the same folder that the events.lua folder is in.

To do this, we need the following code:
<code>
local eventsPath = string.gsub(debug.getinfo(1).source, "@", "")
local scenarioFolderPath = string.gsub(eventsPath, "events.lua", "?.lua")
if string.find(package.path, scenarioFolderPath, 1, true) == nil then
package.path = package.path .. ";" .. scenarioFolderPath
end
</code>

You can probably cut and paste this code before the require lines in your events.lua file and not worry about how it works. However, I'll provide a brief explanation for reference.

The first line stores the location of the of the current file as a string in eventsPath.

The second line replaces events.lua in the eventsPath with ?.lua, which will tell the Lua interpreter to look for .lua files in the current directory (that is to say, the directory with the events.lua file).

The if statement adds scenarioFolderPath to the places for the Lua interpreter to search for code, if that directory is not already in the search path. Since the search path is kept active by the Lua interpreter, it will not be necessary to repeat these lines of code in every file that performs a require action as long as you are running the file as part of events. If you are writing some other kind of code, you will need to substitute "events.lua" with the name of the file with the code you are running. Note that for some reason, events.lua is always provided in lower case. However, for use in other situations, debug.getinfo(1).source uses the correct case for event files. I have only briefly tested this, so you may have to do some testing yourself if this situation comes up (or ask for help in the forums).

Now that we've told Lua where to look for our extra code, we can begin moving code to other files. Think of require as telling Lua to run the entire contents of another file as a function. We can then assign a value to whatever that file returns, which will usually be a table. A couple of examples will clarify.

For our first example, we will move our scenario's parameters to a separate file, and access it via require. This may not seem worthwhile in this example, but tables like this can get large in a hurry. At the time of writing, Over the Reich has over 100 lines of parameters ("specialNumbers"), and parameters are something that a designer might like to play with while collaborators make other implementations. Also, parameters will have to be referenced by other parts of the code, and a file that is required by events.lua cannot, in turn, require events.lua in order to get information. That means that we'll have to keep our parameters in a separate file anyway.

Cut the parameters table definition and paste it into a new file, classicRomeParameters.lua. For the last line, write
<code>
return parameters
</code>

Now, Near the top of events.lua, where the existing require lines are, add the eventsPath code from above and also the line
<code>
local parameters = require("classicRomeParameters")
</code>

[[File:GetStartedWithLuaLesson6-02-RequireParameters.jpg]]

Open the classicRome scenario and test out a couple of events to make sure everything is the same.

We might find it convenient to put a few tables into the same file. For this, we will simply return a table containing these tables, and give each table a name in the events.lua file.

Create a file classicRomeAliases.lua and move all the "aliases" tables to that file. Also move the getCityAt function.

At the bottom of the file, put the following lines:
<code>
return {
unitAliases=unitAliases,
tribeAliases=tribeAliases,
tileAliases=tileAliases,
cityAliases=cityAliases,
textAliases=textAliases,
terrainAliases=terrainAliases,
improvementAliases=improvementAliases,
}
</code>

Then, add the following lines to events.lua (in the require section)
<code>
local aliases = require("classicRomeAliases")
local unitAliases,tribeAliases,tileAliases,cityAliases,textAliases,
terrainAliases,improvementAliases=aliases.unitAliases,aliases.tribeAliases,
aliases.tileAliases,aliases.cityAliases, aliases.textAliases,aliases.terrainAliases,
aliases.improvementAliases
</code>

Here, our classicRomeAliases module is returning a table with our "alias" tables. We then assign the entries in this returned table to local variables with the desired names. Here, I use multiple variable assignment, which I don't believe I've used before (even though Lua allows it), but these could just as simply have been assigned line by line.

[[File:GetStartedWithLuaLesson6-03-RequireAliases.jpg]]

Now, let us move the legion plundering code into its own file, which we'll call plunder.lua. First, copy over the legionPlunder function, and paste it near the bottom of the new file.

Now, let us go through the code of this function, and figure out what else we need in our plunder.lua module.

The very first part of the function is a check against unitAliases.legion. This means we need the unitAliases table, and so we copy the aliases require code to the top of plunder.lua. We don't need the path information, since that will be added in events.lua.

A few more lines down, we find that the function cityRadius is also used in legionPlunder. Therefore, we move that over as well. We also need the plunderValue function, so copy that over as well.

Next, we check if cityRadius relies on anything, but it doesn't.

Proceeding to plunderValue, we find that it relies on the parameters table, so require that as well. The function plunderValue does not appear to depend on anything else, so we're done moving functionality. If we missed something, the Lua interpreter will complain at some point anyway.

Next, we require the plunder module in events.lua, with the following line:

<code>
local plunder = require("plunder")
</code>

Next, for each of the functions in plunder.lua, we check if it is used somewhere in events.lua. We can do this by searching. plunderValue isn't used anywhere, so we're done with that. City radius is used. At the bottom of plunder.lua, we begin our return table, and have
<code>
return {
cityRadius=cityRadius,
}
</code>

Then, in events.lua, we replace the ocurance of cityRadius with plunder.cityRadius. Alternatively, we could have put
<code>
local cityRadius=plunder.cityRadius
</code>
after the line requiring plunder.

Similarly, for legionPlunder, we add <code>legionPlunder=legionPlunder</code> to the table that plunder.lua returns, and pre-append plunder. to legionPlunder in the one location where it occurs.

Now, we test the legion plunder function and the press 4 generate archers function to make sure everything works.

[[File:GetStartedWithLuaLesson6-04-RequirePlunder.jpg]]

===Working With a Library===

In programming terms, a "library" is a collection of code that can provide some specified functionality to a programmer without that programmer having to modify the code in the library. Thus far, you have been using the "civ" library to interact with the game, and there has been no need modify it in order to use it in our own events. (Unfortunately, in the case of the civ library, we don't actually know how to modify it.) This is in contrast to much of the code we have written thus far. For example, the code we wrote last lesson to make Selucid elephants attack Egypt is highly specific. You couldn't just cut and paste that code, change the argument of a single function, and get your own goto event. It is still a good example for how to write a goto event, but a user would still have to actually write the event.

If you plan to write some functionality for your scenario that others might find useful, it is worth spending a little extra effort to see if you can write that functionality in a form that will allow others to use it with minimal effort. If you can, then a little extra work on your part might save someone else the trouble of re-inventing the wheel, and allow them to complete their project sooner, or to work on some new feature for you to enjoy. Unfortunately, the Lua scenarios that have been completed at the time of writing haven't been that good at creating re-usable code, at least in part since we were all getting used to Lua. This will hopefully be improved in the future.

For now, we're going to look at a library which is called the General Library (unless someone comes up with a better name) and which can be found [https://forums.civfanatics.com/threads/totpp-the-general-library.647583/ here]. The purpose of this module is to provide relatively simple functionality that probably shouldn't be implemented every time it is needed. This is useful for our purposes, since we can look at relatively self contained and simple functions for our first examples. We'll create a library for generating munitions later.

This library would be used by invoking the line

<code>
local gen = require("generalLibrary")
</code>

If you wanted to make these functions available to the console for testing purposes, you would simply omit the local, thereby making gen a global variable.

Let us now take a look at a function provided by the General Library <code> gen.hasIrrigation(tile)-->boolean</code>. The very first line references the helper function <code> toTile(tile or table)-->tile</code>, so let us include that code, and look at it first.

<code>
-- toTile(tile or table)-->tile
-- gen.toTile(tile or table)-->tile
-- If given a tile object, returns the tile
-- If given coordinates for a tile, returns the tile
-- Causes error otherwise
-- Helper Function (provided to this library as toTile and gen.toTile)
local function toTile(input)
if civ.isTile(input) then
return input
elseif type(input) == "table" then
local xVal = input[1] or input["x"]
local yVal = input[2] or input["y"]
local zVal = input[3] or input["z"] or 0
if type(xVal)=="number" and type(yVal)=="number" and type(zVal)=="number" then
if civ.getTile(xVal,yVal,zVal) then
return civ.getTile(xVal,yVal,zVal)
else
error("Table with values {"..tostring(xVal)..","..tostring(yVal)..
","..tostring(zVal).."} does not correspond to a valid tile.")
end
else
error("Table did not correspond to tile coordinates")
end
else
error("Did not receive a tile object or table of coordinates.")
end
end
gen.toTile = toTile

-- gen.hasIrrigation(tile)-->boolean
-- returns true if tile has irrigation but no farm
-- returns false otherwise
function gen.hasIrrigation(tile)
tile = toTile(tile)
local improvements = tile.improvements
-- irrigation, but no mining, so not farmland
if improvements & 0x04 == 0x04 and improvements & 0x08 == 0 then
return true
else
return false
end
end
</code>

[[File:GetStartedWithLuaLesson6-05-HasIrrigation.jpg]]

Let us begin by looking at the function <code>toTile</code>. The purpose of this function is to allow other functions to accept tile coordinates in a table instead of an actual tile object. The function tries to be reasonably permissive in the coordinates it will accept, allowing both integer indices and lowercase string indices, and by assuming that a missing z value corresponds to map 0. The function also tries to give reasonably helpful errors.

This brings up something that should be considered when making reusable code: what to do if you don't get values you were expecting. One option is to throw an error and bring up the Lua console. This is good for scenario creators, so they know something is wrong, but not so great for end users because the error stops the rest of the event from happening, should the mistake slip through playtesting.

The other option is for the code to fail silently, and try to do what it can. This is the way the old Test of Time macro system often fails. If Civ II doesn't "understand" the event, it just doesn't happen, and doesn't bother the player with the error. This means that the scenario will still mostly work, but it is harder to catch issues during playtesting. Sometimes, this means doing something "sensible" if the input isn't of the expected type, and might make the code easier to write, since you don't have to handle inputs differently.

A third option is to write your code such that both things can be done. At the top of your code, you put in a variable named "debugMode" or something, and make all the functions throw errors when true, and fail silently when false. Then you playtest with debugMode set to true, and release with debug mode set to false. However, this means extra work in writing your code and you also have to test everything with debug mode off.

For toTile, I went with the fail with error option, since that will allow every function that uses toTile to assume it is receiving proper data. It also seems unlikely that people will be regularly trying to check tiles that don't exist or have tables with tiles and units and improvement objects all in one. And if they do, "guarding" is fairly straightforward anyway (as we've done in previous lessons).

Although toTile is mainly meant to be a helper function for the General Library, it is also put into the gen table to be made available to end users, since it offers useful functionality. Hence, <code> gen.toTile=toTile</code>. Note that we could have given toTile a different name in the gen table that this module will return, such as gen.tableToTile=toTile. In fact, we could refer to the same function with multiple keys in the gen table, if we want to.

Next, we will look at gen.hasIrrigation.

The first thing to notice is that local is not being used to define this function. That is because we're putting the function for gen.hasIrrigation directly into the gen table that this module will return. We could define hasIrrigation as a local variable and then copy it into the gen table. However, there is a decent chance that the General Library will have more than 200 functions by the time everything is complete, since it is meant to provide a lot of building block functionality and keep it in one place, and we will run into trouble if we assign 200 local variables in a single function (which a required lua file acts as).

Perhaps the most striking thing is that we begin by changing the value of tile, the argument of the function. It looks like we're making a global variable named tile, but we're not. When you specify the names of the arguments for a function (in this case tile), you create local variables for that function, which can be given new values just as if you had explicitly used the local keyword.

Beyond that, we extract the integer representing the tile improvements into a local variable (which upon later reflection isn't really necessary), and check that the irrigation bit is set to 1 and the mining bit is set to 0. Refer to lesson 5 for why this works. In fact, we could have simply returned the value of the if statement, rather than specifying return true and return false, although it is very slightly clearer what is going on in the expanded version of the code.

Now, let us write a function to place irrigation on a square. It seems pretty clear that we should do nothing if the tile has a city, but we also have to decide what to do if there is mining or farmland on the tile, since those interfere with placing irrigation. We'll just remove them, on the basis that if we're trying to "place irrigation," then we want irrigation to be there when we are finished.

<code>
function gen.placeIrrigation(tile)
tile = toTile(tile)
</code>

These lines open the function and convert a table of coordinates to a tile if necessary.

<code>
if tile.city then
return
end
</code>

If the tile has a city, return so nothing else is done in the function.

<code>
-- Set irrigation bit to 1
tile.improvements = tile.improvements | 0x04
-- Set mining bit to 0
tile.improvements = tile.improvements & ~0x08
end
</code>

Set the irrigation bit to 1 and the mining bit to 0.

The functions in this library don't have to be complex, and in fact, most probably shouldn't be. They just have to make life easier for the end user. If you reach this lesson before the General Library is considered "complete," your assignment now is to submit some work for it. If you don't feel comfortable doing bitwise operations, you can test the work of others or submit functions that simplify other tasks. However, there are also some helper functions in the library to facilitate changing bits, so you might also consider working on the unit type flags functions. Remember, if you want to make functions available to the console for testing purposes, they must be global variables.

=== The Threshold Table and First Look at Metatables===

Consider a scenario design situation that occurred in Over the Reich: a bomber is generating some bombs via a key press, and the number of bombs it should generate is dependant on its current remaining hitpoints. The more hitpoints the bomber has, the more bombs it should generate. What we want is to specify that if a bomber has between x and y hitpoints, it should produce 2 bombs. That is, for a given type of bomber, we want to have, for example,

hp >= 16 --> 4 bombs
16 > hp >= 12 --> 3 bombs
12 > hp >= 9 --> 2 bombs
9 > hp >= 4 --> 1 bomb
4 > hp >= 0 --> 0 bombs

Unfortunately, Lua tables do not naturally encode this kind of association by default. However, Lua does have a feature called metatables, which allows us to change the behaviour of tables. (This will be a much better way to make the specification than I ended up writing in Over the Reich.)

A metatable is a table that we can "attach" to another table, and then the metatable changes the behaviour of that table. We'll only look at metatables briefly here, but more information can be found [https://www.tutorialspoint.com/lua/lua_metatables.htm here].

What we want is a data structure that can accept numerical "key values" that are between the key values explicitly specified, and return the appropriate value for those keys. We will call this data structure a threshold table, since we are specifying threshold values as keys. We can do this by assigning the following metatable:

<code>
local mt = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
</code>

If we run <code> setmetatable(myTable,mt)</code>, then whenever we ask for an index from myTable and that index doesn't currently exist in myTable, the function assigned to __index will run. Now let us examine the function.

If the type of the key is not a number, then we return whatever the table value is for that key. We use the function rawget, because the standard <code>thresholdTable[key]</code> will invoke this function again if the key doesn't exist, and so never return an answer (when we want it to return nil).

If the key type is a number, then we look for the largest numerical index that is also less than or equal to the key value. We return a default value of false if the key submitted is smaller than all numerical values. False is chosen over nil, so that a maximum value can be set by setting the value of a numerical index to false. Using the key [-math.huge] allows a return value to be set for all numbers (since all numbers are greater than -math.huge).

Since we don't want scenario creators to have to re-create threshold tables every time they need them, we'll add this functionality to the General Library

<code>
local thresholdTableMetatable = { __index = function(thresholdTable,key)
if type(key) ~= "number" then
return rawget(thresholdTable,key)
else
local bestIndexSoFar = -math.huge
local bestValueSoFar = false
for index,value in pairs(thresholdTable) do
if type(index) == "number" and key >= index and index >= bestIndexSoFar then
bestIndexSoFar = index
bestValueSoFar = value
end
end
return bestValueSoFar
end
end,}
-- gen.makeThresholdTable(table or nil)-->thresholdTable
function gen.makeThresholdTable(inputTable)
inputTable = inputTable or {}
return setmetatable(inputTable,thresholdTableMetatable)
end
</code>

[[File:GetStartedWithLuaLesson6-06-ThresholdTable.jpg]]

===A Munition Generation Module===

Now, let us write some re-usable code for a human player to generate units by pressing a key while an appropriate unit is active. This sort of code could be used for ranged attacks (generating a "munition") and also for recruiting mercenaries by paying gold.

The first thing we will want to do is to decide how our code will be used by the end user. This will, perhaps, change by the time we finish writing the code, but it will at least give us a starting point.

spawnUnit(generatingUnit, specificationTable)--> table of unitCreated

Our goal is that when a player attempts to generate a unit using another unit, they will provide the unit spawning the new unit, and a table of information specifying if a unit (or units) can be spawned and anything else that must happen while spawning (like paying money, expending movement points, etc.).

We have an option here. We could have the scenario creator provide the specification table as a required file for our module, or the creator can provide it at the time spawnUnit is called. I choose the latter for a couple of reasons. The first is that it allows the player to have more than one specification table, either because more than one key can spawn a unit, or because the specification can change over time. The other is reason is so that the creator can make the table in the events.lua file if desired (since our module can't require information from events.lua).

Having decided that our generateUnit events are going to be specified by a table, we have to decide what the contents of that table should be. It seems pretty reasonable to index the specificationTable with the index of the unit type of each unit that can generate using the information in the table. If a unit type id number is missing, that unit doesn't generate a munition (or recruit a unit).

The value for each unit type id in the specification table will be a table that specifies how and if that unit generates other units.

--specificationTable[unitType.id]={
--
-- goldCost = integer or nil
-- amount of gold it costs to generate a unit
-- absent means 0
-- minTreasury = integer or nil
-- minimum amount of gold in treasury to generate a unit
-- absent means refer to gold cost
-- (tribe will generate and be set to 0 if treasury is less than goldCost)
-- treasuryFailMessage = string or nil
-- A message to be displayed if the unit fails to spawn a unit due to an
-- insufficient treasury
-- nil means no message

-- There are three ways to specify move costs, in full movement points,
-- in "atomic" movement points, and as a fraction of total movement points for the
-- unit type. Use only one kind per unit type

-- moveCost = integer or nil
-- movement points to be expended generating the unit
-- "full" movement points
-- absent means 0
-- minMove = integer or nil
-- minimum remaining movement points to be allowed to generate a unit
-- "full" movement points
-- absent means any movement points for land/sea, 2 "atomic" for air units
-- postGenMinMove = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostAtomic = integer or nil
-- movement points to be expended generating the unit
-- refers to the unit.moveSpent movement points
-- absent means 0
-- minMoveAtomic = integer or nil
-- minumum remaining movement points to be allowed to generate a unit
-- referes to the unit.moveSpent movement points
-- absent means any movement points for land, 2 "atomic" for air units
-- postGenMinMoveAtomic = integer or nil
-- a unit will be left with at least this many movement points after
-- the generation function
-- absent means 0 for land/sea, 1 "atomic" for air units
-- moveCostFraction = number in [0,1] or nil
-- fraction of unit's total movement points expended generating the unit
-- round up to nearest "atomic" movement point
-- absent means 0
-- minMoveFraction = number in [0,1] or nil
-- fraction of unit's total movement points that must remain to be allowed
-- to generate a unit
-- absent means any movement points for land, 2 "atomic" for air units
-- round up to nearest "atomic" movement point
-- postGenMinMoveFraction = number in [0,1] or nil
-- a unit will be left with at least this many movement points after
-- the generation function, round up to nearest "atomic" move point
-- absent means 0 for land/sea, 1 "atomic" for air units
-- roundFractionFull = bool or nil
-- fractional movement cost and minimum are rounded up to full movement point
-- instead of atomic movement point
-- nil/false means don't
-- roundFractionFullDown = bool or nil
-- fractional cost and minimum are rounded down to full move point
-- nil/false means don't
-- minMoveFailMessage = string or nil
-- a message to be displayed if a unit is not generated due to insufficient
-- movement points.
-- nil means no message

-- allowedTerrainTypes = table of integers or nil
-- a unit may only be generated if the tile it is standing on
-- corresponds to one of numbers in the table
-- nil means the unit can be generated on any terrain type
-- terrainTypeFailMessage = string or nil
-- message to be displayed if a unit is not generated due to standing
-- on the incorrect terrain

-- requiredTech = tech object or nil
-- the generating civ must have this technology in order to generate
-- the unit
-- nil means no requirement
-- techFailMessage = string or nil
-- message to be displayed if a unit is not generated due to not having
-- the correct technology

-- payload = boolean or string
-- if true, unit must have a home city in order to generate munitions
-- and generating munitions sets the home city to NONE
-- payloadFailMessage = string or nil
-- message to be displayed if a unit is not generated due to the
-- payload restriction
-- payloadRestrictionCheck = nil or function(unit)-->boolean
-- If function returns false, the home city is not valid for giving the
-- unit a payload. This will be checked when the unit is activated, when
-- the unit is given a new home city with the 'h' key and when the unit
-- tries to generate a munition
-- nil means no restriction
-- payloadRestrictionMessage = nil or string
-- message to show if a unit fails the payloadRestrictionCheck

-- canGenerateFunction = nil or function(unit)-->boolean
-- This function applied to the generating unit must return true in order
-- for a unit to be spawned. All other conditions still apply.
-- any failure message should be part of canGenerateFunction
-- absent means no extra conditions

-- generateUnitFunction = nil or function(unit)-->table of unit
-- This function creates the unit or units to be generated
-- and returns a table containing those units
-- Ignore any specifications prefixed with * if this is used
-- nil means use other specifications

--*generatedUnitType = unitType
-- The type of unit to be generated
-- can't be nil unless generateUnitFunction is used instead

--*giveVeteran = bool or nil
-- generated unit(s) given veteran status if true
-- nil or false means don't give vet status
-- if true, overrides copyVeteranStatus

--*copyVeteranStatus = bool or nil
-- generated unit(s) copy veteran status of generating unit if true
-- nil or false means don't give vet status

--*setHomeCityFunction = nil or function(generatingUnit)-->cityObject
-- determines what home city the spawned unit should have
-- nil means a home city of NONE

--*numberToGenerate = nil or number or thresholdTable or function(generatingUnit)-->number
-- if nil, generate 1 unit in all circumstances
-- if integer, generate that many units (generate 0 if number less than 0)
-- if number not integer, generate floor(number), and 1 more with
-- probability number-floor(number)
-- if thresholdTable, use remaining hp as the key, to get the number to create
-- if function, get the number as the returned value of the function

-- activate = bool or nil
-- Activates one of the generated units if true. If generateUnitFunction was used,
-- the unit at index 1 is activated, if index 1 has a value. (if not, any unit in
-- the list might be chosen)

The very last entry brings forward a change that must be made to our unit generation specification. Lua's activate unit command doesn't run the unit activation trigger, even though the active unit is changed. Therefore, we must do that manually. Hence,

<code>spawnUnit(generatingUnit, specificationTable)--> table of unitCreated</code>

becomes

<code>spawnUnit(generatingUnit,specificationTable,unitActivationCode)-->table of unitCreated</code>

Perhaps we will change it again later.

I've decided to try a different instructional technique for this section. Instead of writing the code and then going through it section by section, I've recorded a video of my coding and testing this module, and I attempt to explain some of the stuff that I do along the way.

I'm not sure of the value of the video. If you find that there is little useful content relative to the time it takes to watch, then feel free to skip it and continue the lesson. I don't teach anything "new" in it, so you won't miss anything crucial. However, it should be pretty close to how programming Lua can actually happen in the "real world." While I did give some thought to how to write the module before I started, I do attempt to solve problems in real time, and make mistakes that are not discovered for a while (including one where I try to explain how I solve a problem and then not actually do a crucial part).

You can find the code [[here]]. Even if you decide not to watch the video, download the code and try testing some of the features based on the specification above.

The link to the video is

https://youtu.be/XxPyNknGlAo

===A Unit Attack Bonus for Complementary Units in Square===

Something we might like to do is to give units an attack bonus if they attack from a square with some special unit, for example a "leader" unit. The [[Napoléon I]] scenario, for example, gives an attack bonus to units if a commander unit, such as Napoleon, is in the square when the unit is activated (the unit can subsequently move and still retain the bonus as long as no other unit is selected). We will now make a module providing the same functionality.

We first have to have a basic idea of how this functionality should work. When a unit is activated, the onActivateUnit event checks if the newly activated unit should get an attack bonus, based on the other units in the square. If the unit deserves an attack bonus, the corresponding unitType.attack entry is changed, and all the attack value of all other units is reset to the default value. If the activated unit also does not deserve an attack bonus, that value is also set to the default value.

This now leads us to some more possibilities. Should multiple bonus units lead to multiple bonuses or only apply the best one? For example, suppose a legion gets a bonus if an archer is also in the same square. Should two archers provide twice the bonus? Perhaps two archers should provide a larger bonus than one, but not twice as much. Perhaps a legion should also get a bonus if there is a catapult in the square, but that bonus should apply even if the maximum archer bonus is already achieved. It seems like perhaps there should be a "ranged unit" bonus, an "artillery unit" bonus and maybe a "cavalry" bonus which should all impact the legion's attack value. It's looking like we might end up demanding that a scenario creator make a big complicated table in order to use this functionality, even if they only have simple needs.

What we can do to alleviate this is to write a "simple" version of the event that is easy to use (and program), and also write a more complicated version that gives the expanded capability.

Specification Table for simpleAttackBonus

--simpleAttackBonusTable[activeUnit.type.id] ={[bonusUnitType.id]=bonusNumber}
--simpleAttackBonusTable.type = string
--if simpleAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if simpleAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
--if simpleAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- if simpleAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- if simpleAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
--simpleAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

The relevant first draft of the code is as follows:

<code>
local function simpleAttackBonus(activeUnit,simpleAttackBonusTable,defaultAttackTable)
-- reset all unit attack values
for unitTypeID,attackValue in pairs(defaultAttackTable) do
civ.getUnitType(unitTypeID).attack = attackValue
end
local unitBonusTable = simpleAttackBonusTable[activeUnit.type.id]
if not unitBonusTable then
-- unitBonusTable is nil (or false), so the active unit can't
-- get a bonus
return
end
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
local bestBonusSoFar = 0
for unit in activeUnit.location.units do
if unitBonusTable[unit.type.id] and unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
if bestBonusSoFar == 0 then
-- If no bonus unit is found, this will be true, so do nothing else
return
end
-- set the new attack and return
if string.lower(simpleAttackBonusTable.type) == "addBonus" then
activeUnit.type.attack = activeUnit.type.attack+bestBonusSoFar
return
end
local attackMultiplier = 1
if type(simpleAttackBonusTable.type) ~= "string" then
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
elseif string.lower(simpleAttackBonusTable.type) == "addpercent" then
attackMultiplier = (100+bestBonusSoFar)/100
elseif string.lower(simpleAttackBonusTable.type) == "addfraction" then
attackMultiplier = 1+bestBonusSoFar
elseif string.lower(simpleAttackBonusTable.type) == "multiplypercent" then
attackMultiplier = bestBonusSoFar/100
elseif string.lower(simpleAttackBonusTable.type) == "multiply" then
attackMultiplier = bestBonusSoFar
else
error([[simpleAttackBonus: simpleAttackBonusTable.type should be a string with
one of the following values: "addbonus", "addpercent", "addfraction", "multiplypercent"
or "multiply". Actual value is ]]..tostring(simpleAttackBonusTable.type))
end
-- apply the bonus and round as appropriate
if type(simpleAttackBonusTable.round) ~= "string" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
elseif string.lower(simpleAttackBonusTable.round) == "up" then
activeUnit.type.attack = math.ceil(activeUnit.type.attack*attackMultiplier)
return
elseif string.lower(simpleAttackBonusTable.round) == "down" then
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier)
return
else
activeUnit.type.attack = math.floor(activeUnit.type.attack*attackMultiplier+0.5)
return
end
end
</code>

Now let us go over this section by section.

[[File:GetStartedWithLuaLesson6-07-AttackBonus1.jpg]]

The first thing we do is to reset all the attack values of all the unit types. That way, if a bonus existed for the last unit activated, that bonus no longer applies. If a unit type is not in the defaultAttackTable, then we don't have the information to reset the attack value anyway, so we can safely ignore it by using the pairs function to iterate over the table.

Now, we must find out if the newly activated unit deserves a bonus. For that, we get the table associated with the active unit's type. If the value is nil instead of a table, then the unit's type is not in the simpleAttackBonusTable, so there is no bonus to apply and the function returns.

If the unit is eligible for bonuses, we then check the units in the square to see if any bonuses actually apply. We've seen this kind of code before. If the unit in the stack can provide a bonus, and that bonus is better than the best bonus already found, the unit now provides the best bonus. All bonus types that we can have are better if they are larger, and we are not comparing between bonus types, so a simple numerical comparison will do. All bonuses are larger than 0 in our formulation, so 0 is a good starting value in the search.

If the best bonus so far is still 0, there is no bonus, so the function can return.

At this point, it occurs to me that when searching for the best bonus, we should exclude the active unit from the search. That way, you can have a "strength in numbers" bonus, for example. The relevant change to the code is:

<code>
for unit in activeUnit.location.units do
if unit ~= activeUnit and unitBonusTable[unit.type.id] and
unitBonusTable[unit.type.id] > bestBonusSoFar then
bestBonusSoFar = unitBonusTable[unit.type.id]
end
end
</code>

Next, consider

[[File:GetStartedWithLuaLesson6-08-AttackBonus2.jpg]]

Here, we apply the bonus that we've found. We use string.lower on simpleAttackBonusTable.type so that we don't have to worry about capitalization. That does, however, require a correction to "addBonus", since a lower case string will never be equal to that.

"addbonus" is the only type of bonus that is directly added to the existing attack value. All other bonus types are a form of multiplication. Since the addition is straightforward and doesn't require any rounding, the activeUnit's type attack value can be changed immediately, and the function execution ended with return.

When there is only one bonus being applied, all other types of bonus are different ways of expressing how to multiply the existing attack value to get a new one, so we simply convert to the appropriate multiplier, and provide an error message if the type of bonus is not one of the valid possibilities.

Finally, we round the attack value to an appropriate integer (since unit attack values must be integers), change the attack value of the active unit's type, and return to end the function execution.

Now, we integrate into events.lua by using

<code>
attackBonus = require("attackBonus")
</code>

The relevant integration code for events.lua is
<code>
local defaultAttackValueTable = {[unitAliases.legion.id]=4}
local simpleAttackBonusTable ={}
simpleAttackBonusTable.type = "addbonus"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=3,[unitAliases.musketeer.id]=4}

local function doOnActivation(unit,source)
munitions.payloadRestrictionCheck(unit,munitionSpecificationTable)
attackBonus.simpleAttackBonus(unit,simpleAttackBonusTable,defaultAttackValueTable)
end
</code>

We can check that the bonus is being applied correctly by checking the Civlopedia entry for legion and looking at the attack value. The following cases must be tested (remember that activating a unit from the city screen doesn't run the onActivation event, so activate from the map).

Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (7 attack)
Legion activated with musketeer, but no archer (8 attack)
Legion activated with archer and musketeer (8 attack)
Legion activated with 2 archer, no musketeer (7 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).
I recommend making a stack for each of these cases and activating them one by one.
To facilitate the test, add the following line to doOnActivation
<code>
civ.ui.text(tostring(unit.type.attack))
</code>
You will want to comment out this line after testing.

Next, change simpleAttackBonusTable to do "addpercent"
<code>
simpleAttackBonusTable.type = "addpercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=30,[unitAliases.musketeer.id]=70}
</code>

With no rounding set, standard rounding is used
Legion activated with neither archer nor musketeer (4attack)
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)
Legion activated with archer and musketeer (7 attack)
Legion activated with 2 archer, no musketeer (5 attack)
Legion with no bonus, activated right after legion with bonus (4 attack)
Activate some other unit (should have regular attack value).

These numbers test both rounding up and rounding down.

Now, use
simpleAttackBonusTable.round="up"
Legion activated with archer, but no musketeer (6 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next,
simpleAttackBonusTable.round="down"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (6 (6.8) attack)

simpleAttackBonusTable.round="standard"
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Next, we test "addfraction". Since we've tested all the rounding options, we don't have to do that again.

<code>
simpleAttackBonusTable.type = "addfraction"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=0.3,[unitAliases.musketeer.id]=0.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiplypercent"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=130,[unitAliases.musketeer.id]=170}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

<code>
simpleAttackBonusTable.type = "multiply"
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>
Legion activated with archer, but no musketeer (5 (5.2) attack)
Legion activated with musketeer, but no archer (7 (6.8) attack)

Before we finish, we should test a legion bonus for the legion.
<code>
simpleAttackBonusTable[unitAliases.legion.id] = {[unitAliases.legion.id]=2,[unitAliases.archers.id]=1.3,[unitAliases.musketeer.id]=1.7}
</code>

Legion alone should have 4 attack.
A second legion on the square should provide 8 attack instead.

Now, let us try to formulate a more complicated bonus system. One thing we mentioned is that we'd like the ability to get bonuses from multiple units, and to be able to get bonuses from different "classes" of units (like "artillery," "cavalry," and "ranged attackers." Something else we might want to do is to allow different kinds of bonuses. That is, maybe some units should provide a fixed +2 to any unit receiving the bonus, so that it is better at improving units with a low attack value, while other units should provide a percentage bonus (making them better at supporting units with an already high attack value). It turns out that both of these ideas are not too difficult to implement individually, but that trying to implement them together makes it problematic to find the best bonus.

Let us implement a bonus system with multiple categories but only one bonus type. In our specification, we will first specify a data type called "bonusCategory." It is still just a table (though we could add a metatable if we wanted), but it will help us make our specification clearer.

<code>
-- A "bonusCategory" is a table
-- bonusCategory = {[bonusUnitType.id]=bonusNumber, maxBonusUnits=integer or nil, nextBonusValue = fraction or nil}
-- In a bonusCategory, the value for bonusUnitType.id tells what the base bonus for that unit type is,
-- maxBonusUnits is the maximum number of units that can provide a bonus in this category,
-- nextBonusValue tells how much to reduce the bonus for each subsequent unit,
-- e.g. nextBonusValue = 0.7, and 5 units, which each have a bonusNumber=1
-- The total bonus is 1(0.7)^0+.7+(.7)(.7)+(.7)^3+(.7)^4 = 1+.7+.49+.343+.2401=2.7731
-- (which would be rounded as specified)
-- nil means nextBonusValue=1
--
-- If a unit type is in two bonus categories for the same unit, there is no guarantee that the
-- best bonus will be achieved
</code>

So, the bonus category is indexed by unitType id numbers for units that can give a bonus, and the corresponding bonus. It also specifies the maximum number of units that can give a bonus, and a number that governs how to reduce a bonus for extra units. That way, there can be diminishing returns for bonuses.

Next, we look at the specification for the categoryAttackBonusTable

<code>
--categoryAttackBonusTable[activeUnit.type.id] =table of bonusCategory
--categoryAttackBonusTable.type = string
--if categoryAttackBonusTable.type == "addbonus" then
-- add the bonusNumber to the base attack
--if categoryAttackBonusTable.type == "addpercent"
-- add bonusNumber percent to the unit's attack
-- i.e. attack 6, bonusNumber 50, new attack 9
-- for multiple unit bonuses, add up all the percents, then compute the bonus
-- i.e. 50% bonus and 50% bonus is 100% bonus, not 125%
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 50% bonus units become 50% + 25%
-- so attack 6 --> 10.5
--if categoryAttackBonusTable.type == "addfraction"
-- add the fraction of the attack value to the attack,
-- i.e. attack 6, bonusNumber 0.5, new attack 9
-- for multiple unit bonuses, add up the fractions, then compute the bonus
-- i.e. .5 bonus and .5 bonus is 1+.5+.5= 2x bonus, not 2.25x
-- attack 6 --> attack 12
-- nextBonusValue applied directly to bonusNumber, i.e. nextBonusValue=.5 and 2 .5 bonus units become .5+.25
-- so attack 6 --> 10.5
-- if categoryAttackBonusTable.type == "multiplypercent" then
-- multiply the unit's attack by the bonusNumber precent
-- i.e. attack 6, bonusNumber 150, new attack 9
-- bonuses are multiplied together, i.e. 150% and 150% yields 225% of original value
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 100, i.e. nextBonusValue=.5 2 150% bonuses become 150% and 125%
-- so attack 6 --> 11.25
-- if categoryAttackBonusTable.type == "multiply" then
-- multiply the unit's attack by bonusNumber
-- i.e. attack 6, bonusNumber 1.5, new attack 9
-- bonuses are multiplied together, i.e. 1.5 and 1.5 yields 2.25x
-- attack 6 --> attack 13.5
-- nextBonusValue applied to bonusNumber in excess of 1, i.e. nextBonusValue=.5 and two 1.5 bonuses become 1.5 and 1.25
-- so attack 6 --> 11.25
--categoryAttackBonusTable.round = "up" or "down" or "standard" or nil
-- nil means "standard"
-- "up" means a fractional attack value after a bonus is rounded up
-- "down" means a fractional attack value after a bonus is rounded down
-- "standard" means a fractional attack value is rounded down
-- if fraction part is less than 0.5, and rounded up otherwise

-- If the active unit can get a bonus, go through each category and compute the bonus for that category.
-- Then, combine the bonuses for all categories to get the overall bonus, and round the result
</code>

With the bonusCategory defined, the value of the unit indices of categoryAttackBonusTable become easy to define. Most of the specification is showing what exactly the different bonus categories mean, so the end user can use them properly. It's not strictly necessary to offer so many choices to the end user on how to specify data, but it can be more convenient.

Here is the actual code (before testing) to implement this more general version of attack bonuses.

<code>
-- HELPER FUNCTION
-- findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable) --> number or false
-- usedUnitTable is indexed by the i.d. number of units, and if the value for a unit is true,
-- then it has already been used for a bonus (and, so, is not eligible)
-- The function returns the bonus (before nextBonusValue is applied) if there is one, and marks the
-- unit as used in the usedUnitTable
-- returns false if no unit qualifies
local function findBestBonusInUnitStack(tile,bonusCategory,usedUnitTable)
local bestBonusSoFar = 0
local bestUnitSoFar = nil
-- find the best bonus. For all bonus types, the bonus will be greater than 0,
-- and for all bonus types, a larger number means a better bonus
for unit in tile.units do
if not usedUnitTable[unit.id] and bonusCategory[unit.type.id]
and bonusCategory[unit.type.id] > bestBonusSoFar then
bestUnitSoFar = unit
bestBonusSoFar = bonusCategory[unit.type.id]
end
end
if bestUnitSoFar then
usedUnitTable[bestUnitSoFar.id] = true
return bestBonusSoFar
else
return false
end
end

-- HELPER FUNCTION
-- computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
-- Computes the bonus that the active unit will receive from this category, taking into
-- account the type of bonus for the table
local function computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
local bonusThusFar = nil
if bonusType == "multiply" then
bonusThusFar = 1
elseif bonusType == "multiplypercent" then
bonusThusFar = 100
else
bonusThusFar = 0
end
local bonusDiscount = 1
for i=1,(bonusCategory.maxBonusUnits or 10000) do
local currentBonus =findBestBonusInUnitStack(activeUnit.location,bonusCategory,usedUnitTable)
if not currentBonus then
-- no more valid bonuses for this category
break
end
if bonusType == "multiply" then
bonusThusFar = bonusThusFar*((currentBonus-1)*bonusDiscount+1)
elseif bonusType =="multiplypercent" then
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
else
bonusThusFar = bonusThusFar+currentBonus*bonusDiscount
end
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
end
return bonusThusFar
end

local function categoryAttackBonus(activeUnit,categoryAttackBonusTable,defaultAttackTable)
local bonusInfoTable = categoryAttackBonusTable[activeUnit.type.id]
if not bonusInfoTable then
-- unit doesn't get a bonus
return
end
-- keep track of bonuses already computed
local bonusResultsTable = {}
-- keep track of units that have already been "used" for a bonus
local usedUnitTable = {[activeUnit.id]=true}
for index,bonusCategory in pairs(bonusInfoTable) do
bonusResultsTable[index]=computeCategoryBonus(activeUnit,categoryAttackBonusTable,bonusCategory,usedUnitTable)
end
-- compute the bonus
local bonusType = string.lower(categoryAttackBonusTable.type)
local resultAttackBeforeRounding = nil
if bonusType == "multiply" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "multiplypercent" then
local bonus = 1
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus*bonusResult/100
end
resultAttackBeforeRounding = activeUnit.type.attack*bonus
elseif bonusType == "addbonus" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack+bonus
elseif bonusType == "addfraction" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+bonusResult
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
elseif bonusType == "addpercent" then
local bonus = 0
for __,bonusResult in pairs(bonusResultsTable) do
bonus = bonus+(bonusResult/100)
end
resultAttackBeforeRounding =activeUnit.type.attack*(1+bonus)
else
error("categoryAttackBonus: categoryAttackBonusTable.type is not a valid value.")
end
-- apply the bonus and round as appropriate
local roundType = categoryAttackBonusTable.round
if type(roundType) ~= "string" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
elseif roundType == "up" then
activeUnit.type.attack = math.ceil(resultAttackBeforeRounding)
return
elseif roundType == "down" then
activeUnit.type.attack = math.floor(resultAttackBeforeRounding)
return
else
activeUnit.type.attack = math.floor(resultAttackBeforeRounding+0.5)
return
end
end
</code>

The two helper functions for computeCategoryBonus are only used once each in the code, so making them helper functions does not help us re-use code. However, what it does do is to break down the function design process into smaller tasks, which are each more manageable to complete. If you're trying to keep track of too many things in your program, try writing a few helper functions to handle individual tasks. We'll look at the helper functions when we actually arrive at them in the code.

[[File:GetStartedWithLuaLesson6-09-CategoryAtkBonus1.jpg]]

If there is no entry in the categoryAttackBonusTable or the active unit's type, then the function returns without doing anything further.

The bonusResultsTable keeps track of the total bonus from each category, so they can be added or multiplied together after all the category bonuses are applied. The usedUnitsTable keeps track of units that are no longer eligible to contribute to a bonus (such as if they have already contributed), and we initialize it with the active unit, so that it doesn't provide a bonus to itself.

The for loop computes the bonus for every category, and stores the value in the bonusResultsTable, for use later.Now, let us look at the helper functions.

First up is findBestBonusInUnitStack

[[File:GetStartedWithLuaLesson6-10-CategoryAtkBonus2.jpg]]

This basically does what it says in the name. For a bonusCategory, it finds the unit in the tile that provides the best bonus, and has not already provided a bonus elsewhere. If there is no qualifying unit, false is returned. If there is, that unit's bonus is returned, and the unit's id is entered into the usedUnitTable, so that unit can't provide another bonus for the active unit. We've searched for the best of something before, so there is little need to go over it again.

Next is computeCategoryBonus

[[File:GetStartedWithLuaLesson6-11-CategoryAtkBonus3.jpg]]

Here, we're computing the bonus for the entire bonusCategory. We need the bonus type in order to know what kind of math to do. The math itself is not very interesting. We also initialize the bonusDiscount, which keeps track of the fraction of the next unit's bonus that will actually be applied.

Next, we enter a for loop that will run one time for each possible bonus that there can be in a bonus category. If bonusCategory.maxBonusUnits is nil, then we set an arbitrary limit of 10000 units, which is very unlikely to happen in practice.

At each iteration of the loop, the best available bonus in the stack is found. If no unit was eligible to provide a bonus, then the current bonus is false, and the "break" command is issued. Break immediately exits the current loop. So, our program doesn't run 10000 loops if there is no maximum number of bonus units, it just breaks at an appropriate time.

After the bonus is found, it is added to or multiplied with the bonus already found. The bonus computed in this way will be the largest possible, since the bonus provided does not depend on the other units chosen (so we don't have a situation where "catapult" and "rock" are both useless, but "catapult" and "rock" chosen together are best). Also, since the best bonus is chosen first, the smallest bonus discount applies to it, so the cost imposed by the discounting is smallest.

Finally, we update the bonusDisount. Here, I notice a problem in the code as written, since bonusCategory.nextBonusValue is allowed to be nil. Replace
<code>
bonusDiscount = bonusDiscount*bonusCategory.nextBonusValue
</code>
with
<code>
bonusDiscount = bonusDiscount*(bonusCategory.nextBonusValue or 1)
</code>
so that if there is no nextBonusValue, a default of 1 is used, and the bonusDiscount stays at 1 (i.e. no discount is applied).

We return to categoryAttackBonus to see

[[File:GetStartedWithLuaLesson6-12-CategoryAtkBonus4.jpg]]

From here, we combine the bonuses stored in bonusResultsTable, the exact way of doing so being dependant on the type of bonus involved. The math itself isn't very interesting, and doesn't seem all that likely to come up in this exact form elsewhere. If you need help with the mathematical details of some event you want to write, ask in the forums. There's a good chance someone has the skills to help you solve your specific problem.

For every type of bonus, the result is stored in resultAttackBeforeRounding, so that variable can be rounded up or down as specified by the rounding type.

Here, I notice another error. We should restrict the attack value for a unit to not exceed 98. We can do that with a math.min(value, 98).

Now, we need to test the various aspects of the attack bonus program, so we need an appropriate table
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addbonus"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=2,[unitAliases.chariot.id]=4,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=2,[unitAliases.musketeer.id]=4,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Also, comment out the old attack bonus line, and put in a new one
<code>
attackBonus.categoryAttackBonus(unit,categoryAttackBonusTable,defaultAttackValueTable)
</code>

Expected Test Results when type is "addbonus"
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

Already, we find a problem. Although there were no syntax errors to fix, I forgot to reset unit attack values. So, very quickly, the legions keep gathering extra attack values when they are activated (since the base attack is not reset to 4). Since this is happening anyway, I'll test the 98 attack value maximum. That appears to work, at least in the case of no specified rounding.

Cut and paste the appropriate lines from the simpleAttackBonus to the categoryAttackBonus, and save.

With that bug fixed, everything works as expected.

Next, we change the categoryAttackBonusTable to

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addpercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=50,[unitAliases.chariot.id]=100,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=50,[unitAliases.musketeer.id]=100,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>

Expected Test Results when type is "addpercent". These are the same, since adding we're adding percentages of the same base value of 4. So a value of 2 is the same as adding 50% of 4.
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

The results are the same.

Similarly,

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="addfraction"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=.50,[unitAliases.chariot.id]=1.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=.50,[unitAliases.musketeer.id]=1.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 10 attack
Legion+chariot+chariot+chariot: 11 attack
Legion+chariot+chariot+chariot+chariot+horseman: 11 (if maxBonusUnits not applied,11.5+2/16 rounds to 12)
Legion+musketeer+archer: 4+4+1.5=9.5 round to 10, (if archer computed first then 4+2+3 = 9 instead)
Legion+musketeer+chariot+chariot+chariot: 15 attack

We'll have to do some new calculations, now, since multiply and multiplyfraction give different results than the various adding formulations.

<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiply"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=1.50,[unitAliases.chariot.id]=2.00,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=1.50,[unitAliases.musketeer.id]=2.00,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Finally, we use multiplyPercent, and check for the same results
<code>
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,nextBonusValue=0.5,maxBonusUnits=3}
local rangeBonusCategory = {[unitAliases.archer.id]=150,[unitAliases.musketeer.id]=200,nextBonusValue=0.75,}
categoryAttackBonusTable[unitAliases.legion.id]={cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable.round="down"
</code>
Legion:4attack
Legion+chariot:8 attack
Legion+chariot+chariot: 12 attack
Legion+chariot+chariot+chariot: 15 attack
Legion+chariot+chariot+chariot+chariot+horseman: 15 (if maxBonusUnits not applied,~17 )
Legion+musketeer+archer: 4*2*(1.375) = 11 , (if archer computed first then 4*1.5*1.75 =10.5 instead, so use round down)
Legion+musketeer+chariot+chariot+chariot: 30 attack (4*2*2*1.5*1.25)

Quickly, I find that if a bonus applies, that bonus makes the attack value of a legion 98. I failed to multiply percents correctly in computeCategoryBonus. The Line
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+1)
</code>
Is changed to
<code>
bonusThusFar = bonusThusFar*((currentBonus-100)*bonusDiscount+100)/100
</code>

Finally, Change archer bonus to 110 and musketeer bonus to 120 (so a unit will make a legion have 4.4 and 4.8 value before rounding), and test the rounding options. You will find they all work.

At the moment, we don't have a way to mix different types of bonuses. As said earlier, we might want this so that some units can be better at giving bonuses to low attack units than to high attack units, while others give a percentage bonus to everything. We could now write a bonus system that allows for multiple types of bonuses. However, the current bonus system allows for the bonus to change per unit. This means that we can, for example, convert a +2 attack bonus to a plus 100% bonus for a unit with 2 attack, and a plus 50% bonus for a unit with 4 attack. In the case of the multiplied bonuses, this will make the bonus more powerful if there is more than one. That is, 2 attack, +2 twice is 6, but if +2 is changed to x2, then the multiplied bonus brings the attack up to 8. However, this seems like it would be a relatively unlikely problem, and there are other things this code can't handle, so we'll let someone else make the code if they actually need it.

So, what we'll do is write a function that will change all appropriate entries in the categoryAttackBonusTable to reflect a different value. Hence,

<code>
-- plusFixed(unitType,number,categoryAttackBonusTable) --> void
-- changes the bonus given by unit type to any unit to be equivalent
-- to adding number to that unit's attack power
</code>

Here, an issue with tables arises. It is very likely that when someone defines their cateogryAttackBonusTable, they'll define it something like this
<code>
local rangeBonusCategory = {[unitAliases.archer.id]=.25,[unitAliases.musketeer.id]=.5}
local bonusTableForInfantry = {rangeBonusCategory}
local cABT = {type="addfraction"}
cABT[unitAliases.phalanx.id]=bonusTableForInfantry
cABT[unitAliases.legion.id] = bonusTableForInfantry
</code>
However, this means that both <code> cABT[unitAliases.legion.id] </code> and <code> cABT[unitAliases.phalanx.id] </code> actually refer to the same piece of memory, and changing cABT[unitAliases.legion.id][1][unitAliases.archer.id] will also change the value at cABT[unitAliases.phalanx.id][1][unitAliases.archer.id]. This is because of the way lua tables are designed. This design can be useful, for example it allowed us to make changes to usedUnitsTable in the last function without having to copy the table, make changes to the copy of the table, and then replace the original table with that copy as a return value. However, it also requires us to be careful when we make changes to entries in tables. In this case, we'll simply copy the table and all its sub values into a new table.

The code to do this is given by
<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

We will explain this code in the next section, since it involves a programming technique which we haven't discussed before.

For now, we analyze plusFixed:

<code>
-- plusFixed({[unitType1.id]=fixedBonus,[unitType2.id]=fixedBonus},categoryAttackBonusTable) --> void
-- changes the bonus given by unitTypeI.id to a unit to be equivalent to
-- to adding number to that unit's attack power. If the unit doesn't receive a bonus
-- from the unitType, then it won't after applying plusFixed.
-- The value of the existing bonus is ignored.

local function plusFixed(fixedUnitBonusTable,categoryAttackBonusTable)
local bonusType = string.lower(categoryAttackBonusTable.type)
for bonusReceivingUnitTypeID,bonusTable in pairs(categoryAttackBonusTable) do
-- replace bonusTable with an equivalent table that is not referened
-- anywhere else, so that changes to it can be made without impacting
-- data elsewhere
categoryAttackBonusTable[bonusReceivingUnitTypeID] = duplicateTable(bonusTable)
-- make bonusTable refer to the "current" bonus table for the unit type
bonusTable =categoryAttackBonusTable[bonusReceivingUnitTypeID]
-- For each unit type in the fixedUnitBonusTable, check if any bonus category
-- in the bonusTable corresponds to it. If so, make the change
for bonusGivingUnitTypeID,fixedBonusValue in pairs(fixedUnitBonusTable) do
-- get the attack of the unit type
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
-- in each bonus category, check if the giver's unit type id is there,
-- if so, change to the correct attack
for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
if bonusCategory[bonusGivingUnitTypeID] then
-- change the bonus appropriately
if bonusType == "addbonus" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue
elseif bonusType == "addpercent" then
bonusCategory[bonusGivingUnitTypeID]=100*fixedBonusValue/baseAttack
elseif bonusType == "addfraction" then
bonusCategory[bonusGivingUnitTypeID]=fixedBonusValue/baseAttack
elseif bonusType == "multiplypercent" then
bonusCategory[bonusGivingUnitTypeID]=100*(fixedBonusValue+baseAttack)/baseAttack
elseif bonusType == "multiply" then
bonusCategory[bonusGivingUnitTypeID]=(fixedBonusValue+baseAttack)/baseAttach
else
error("pluxFixed: categoryAttackBonusTable.type does not have an acceptable value.")
end
end
end
end
end
end
</code>

[[File:GetStartedWithLuaLesson6-13-plusFixed1.jpg]]

As before, we save the bonusType in lower case, since we'll be using it a lot later. Next, we open a for loop, where the index is the id of the unit type receiving the bonus, and the value is the bonus table for that unit type. Next, we duplicate the bonus table, so that we have a table we can change without impacting anything elsewhere, and we store the duplicated table in categoryAttackBonusTable in place of the original bonusTable for the current bonus receiving unit id. Next, we assign this duplicated table to the variable bonusTable, so we can refer to it later in the code.

[[File:GetStartedWithLuaLesson6-14-plusFixed2.jpg]]

We now perform the following actions for each unitType.id and corresponding fixedBonusValue submitted in the fixedUnitBonusTable.

First, get the attack of the bonus receiving unit, since we'll need that in order to customize the bonus. Next, check each bonus category in the bonus table. If the bonus category has the current unitTypeID as a key, then replace the existing value with a bonus equivalent to adding a fixed value to the receiving unit's attack.

That's all that must be done, so end all the loops.

Now we test the function.

Add unitAliases.phalanx = civ.getUnitType(3) to the appropriate file.

<code>
defaultAttackValueTable[unitAliases.phalanx.id]=1
categoryAttackBonusTable = {}
categoryAttackBonusTable.type="multiplypercent"
local cavalryBonusCategory = {[unitAliases.horsemen.id]=150,[unitAliases.chariot.id]=200,
nextBonusValue=0.5,maxBonusUnits=1}
local rangeBonusCategory = {[unitAliases.archer.id]=125,[unitAliases.musketeer.id]=150,
nextBonusValue=0.75,maxBonusUnits=1}
local standardBonus = {cavalryBonusCategory,rangeBonusCategory}
categoryAttackBonusTable[unitAliases.legion.id]=standardBonus
categoryAttackBonusTable[unitAliases.phalanx.id]=standardBonus
categoryAttackBonusTable.round="up"
attackBonus.plusFixed({[unitAliases.chariot.id]=2,[unitAliases.musketeer.id]=2},
categoryAttackBonusTable)
</code>
The chariot and the musketeer individually should each add 2 to both a phalanx and a legion,
so the phalanx should have an attack of 3, and the legion should have an attack of 6, if one bonus
is applied.

Since the bonus type is multiplypercent, together the phalanx would have an attack of 9, and the legion will also have an attack of 9.

In testing, we quickly get this error
<code>
You should see this in lua console if this worked
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: bad argument #1 to 'getUnitType' (number expected, got string)
stack traceback:
[C]: in function 'civ.getUnitType'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:356: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>

At line 356, which is

<code>
local baseAttack = civ.getUnitType(bonusReceivingUnitTypeID).attack
</code>

This must mean that bonusReceivingUnitTypeID is not a number. This is because we're looping over categoryAttackBonusTable, and that table has a couple of entries that are not integers ("type" and "round"). Therefore, we have to insert code to deal with this eventuality.

The simplest way is to put everything in the loop body into an if statement, so that it only runs when bonusGivingUnitTypeID is actually a number. You should be able to do this without detailed instructions, so do so (hint: use type function).

The next error is
<code>
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: bad argument #1 to 'pairs' (table expected, got nil)
stack traceback:
[C]: in function 'pairs'
...rive_c\Test of Time\Scenario\ClassicRome\attackBonus.lua:360: in function 'attackBonus.plusFixed'
...e15\drive_c\Test of Time\Scenario\ClassicRome\events.lua:218: in main chunk
</code>
<code>
360 for bonusCategoryIndex,bonusCategory in pairs(bonusTable) do
</code>

Here, we have a nil value for bonusTable. This turns out to be an error in duplicateTable. When I duplicated the table, I forgot to return that table. That is, both the if and else statement in that function need a return command, and I forgot to add <code> return duplicatedTable </code> in the if portion. Add this to the duplicate table function.

After this, our predictions are true. Testing the other types of bonus is left as an assignment.

===Recursive Functions===

Let us return to the duplicateTable function. Recall that in the last section we added a line to it, so we'll restate it here:

<code>
-- duplicateTable(table or value) --> table or value
-- duplicates a table and all the other tables referenced in that table
-- this way, a change can be made to any element of the table,
-- and it won't impact data referenced anywhere else (unless this newly
-- created table is subsequently referenced)
-- if a non-table value is input, that value is returned
--
local function duplicateTable(input)
if type(input) == "table" then
-- the input value is a table, so create a new table
local duplicatedTable={}
-- and copy all the indexes and values into the new table,
-- making sure to duplicate any tables that appear as values
for index,value in pairs(input) do
duplicatedTable[index]=duplicateTable(value)
end
return duplicatedTable
else
-- the input value was not a table, so we return that value
return input
end
end
</code>

[[File:GetStartedWithLuaLesson6-16-duplicateTable.jpg]]

The interesting thing about duplicateTable is that it invokes duplicateTable within its code. When we copy the key-value pairs into the new table, we run duplicateTable on the value. If the value is not a table, then we are in the else case, and the value is immediately returned to be inserted into the duplicated table. If the value is a table, that table is duplicated before anything else is done.

Let us look at a simple example of a recursive function, the factorial function N!. In lesson 3, we discussed the factorial function in the context of loops. Since N!=N*(N-1)*(N-2)*...*3*2*1, we can give another definition of N!:
N!=1 if N = 1
N!=N*(N-1)! if N > 1
Or, using the convention that 0!=1, we can state
N!=1 if N = 0
N!=N*(N-1)! if N > 0

The case where N =1 or N=0 is called the "base case." If we keep substituting N! as N*(N-1)!, then we won't go on forever, because we will eventually reach a point where N=0, and N! can be substituted as 1 instead of N*(N-1)!. As long as there is a base case, our program will eventually reach the base case(s), and begin "completing" evaluation.

<code>
function factorial(N)
if N>0 then
return N*factorial(N-1)
else
return 1
end
end
print(factorial(5))
print(factorial(6))
</code>

Run this in code in the lua demo website, or using the TOTPP lua interpreter.

Returning to our duplicateTable function, the base case is any time a table value is not itself a table. When that happens, the recursion "chain" ends, and everything can evaluated.

Although is shouldn't be a problem in this particular case, it should be noted that it is possible for there to not be a "base case" in the recursion style: if table, recur, if not return a value. Consider the following table system

<code>
a={}
b={[1]=a}
a[1]=b
</code>
In this case, the code would never end.

It is possible that even if the code could "theoretically" execute to completion, you run out of memory before that. This is called a "stack overflow," and if it occurs, you will have to think of an alternate way to solve your problem. It will probably be best to ask for help in that case (and it might be useful to provide others with an example of a problem that results in a stack overflow), but you might also look into "tail recursion", including http://www.lua.org/pil/6.3.html .

===Conclusion===

With the skills covered in this chapter, you now have the tools to split a large events file into multiple files that are more manageable. You also have the basics for how to write re-useable modules for your events, so that your work can be used by others. Remember that if someone else uses your implementation of a feature, they will spend much less time coding and testing it, allowing them to either finish the scenario sooner, or to introduce some other feature. So, it might very well pay to spend at least a little effort making your code into a reusable module. Perhaps you have an idea for a cool scenario mechanic, but don't have a scenario for it (or don't want to take the time to make it). If that's the case, just make the module and test it in a "toy" scenario (like Classic Rome) so that it can be used more or less "off the shelf" when someone needs it.

File:GetStartedWithLuaLesson6-16-duplicateTable.jpg

2019-07-26T14:17:59Z

Prof. Garfield: