Lua Scenario Template Documentation

Home

General Library

local gen = require("generalLibrary")

The General Library offers a variety of tools to make it easier to build events. These functions are divided into several sections:

Replacement Functions

These functions should be used in place of the similar tools provided by the civ library.

gen.activate(unit)-->void

gen.activate(unit)-->void
Use to activate a unit. This assumes that the 'source' of the activation is true (i.e. human generated). Use gen.activateWithSource if false might be needed.
Valid Arguments: unit: unitType Note: unit:activate() doesn't run the code for the Unit Activation execution point, hence why this is preferred.
Link to Here.

gen.activateSource(unit,source)-->void

gen.activateSource(unit,source)-->void Use to activate a unit.
Valid Arguments: unit: unitType source: boolean Note: unit:activate() doesn't run the code for the Unit Activation execution point, hence why this is preferred.
Link to Here.

gen.playMusic(fileName)

gen.playMusic(fileName) Plays the sound in the file "fileName" as in game music (rather than sound). Searches for the file in the Sound folder within the scenario folder.
Valid Arguments: fileName: string (including file extension) The function civ.playMusic(filename) plays music from <Test Of Time Dir>\Music, which is not very useful for distributing custom sounds to play.
The directory to within which to find the music file can be changed by gen.setMusicDirectory.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.defeatUnit(loser,winner,aggressor,victim, loserLocation,winnerVetStatus,loserVetStatus)-->unit or nil

gen.defeatUnit(loser,winner,aggressor,victim, loserLocation,winnerVetStatus,loserVetStatus)-->unit or nil "Defeats" the loser, deletes the loser, and returns a unit if and only if the loser was "demoted" to that unit. Otherwise, nil is returned. This function integrates the various unit death execution points along with the Promotion and Demotion Module.
This function is suitable if you have a "combat-like" event.
Valid Arguments: loser: unitObject winner: unitObject aggressor: unitObject victim: unitObject loserLocation: tileObject winnerVetStatus: boolean loserVetStatus: boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.killUnit(dyingUnit)-->void

gen.killUnit(dyingUnit)-->void Kills "dyingUnit". This function integrates the various unit death execution points along with the Promotion and Demotion Module.
Valid Arguments: dyingUnit: unitObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.deleteUnit(deletedUnit,replacementUnit)-->void

gen.deleteUnit(deletedUnit)-->void gen.deleteUnit(deletedUnit,replacementUnit)-->void This function integrates the unit deleted execution point.
Valid Arguments: deletedUnit: unitObject replacementUnit: unitObject or nil
Link to here. (Click link, then copy the link from your browser address bar.)

gen.replaceUnit(oldUnit,replacementType)--> unit

gen.replaceUnit(oldUnit,replacementType)--> unit Creates a unit to replace "oldUnit," copies the oldUnit's attributes, and deletes the oldUnit (applying gen.deleteUnit.
Returns the newly created unit.
Valid Arguments: oldUnit: unitObject replacementType: unitTypeObject
Link to here. (Click link, then copy the link from your browser address bar.)

Building Blocks

These are miscellaneous functions that are likely to be useful in building larger events or other modules.

gen.applyWonderBonus(wonder,tribe)-->boolean

gen.applyWonderBonus(wonder,tribe)-->boolean
Returns true if the wonder has been built, has not expired or been destroyed, and is owned by the tribe.
Valid Arguments: wonder: wonderObject, integer (wonder.id) tribe: tribeObject, integer (tribe.id)
Link to Here.

gen.toTile(tileOrTable)-->tile

gen.toTile(tileOrTable)-->tile
Accepts a tile object or table representing coordinates as an argument, and returns the corresponding tile. Returns a useful error if an invalid argument is provided, for easier debugging.
If 2 only coordinates are provided in the table, the third is assumed to be 0.
Valid Arguments: tileOrTable: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord}
Link to Here.

gen.distance(objectA,objectB)-->integer

gen.distance(objectA,objectB)-->integer gen.distance(objectA,objectB,zDist)-->integer Returns the distance in tiles between objects A and B, if they have a natural location. Also accepts tables of coordinates. The 'vertical' distance between maps is 0 by default, but the optional argument zDist can change this. zDist is the distance in tiles, not "coordinates."
Valid Arguments: objectA,objectB: tileObject, unitObject, cityObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} zDist: integer,nil Notes: This doesn't compute the distance using the typical "Euclidean Distance" that you might be familiar with, but rather the "Taxicab Distance," so that the result is the number of tiles an air unit would have to cross to get from A to B. The distance between adjacent tiles on the same map is always 2 in the "Taxicab Distance," even diagonal movement. This function divides the coordinate distance by 2 to get the result in terms of tiles.
Link to Here. (Click link, then copy the link from your Browser URL Bar.)

gen.tileDist(tileA,tileB)

gen.tileDist(tileA,tileB)-->integer gen.tileDist(tileA,tileB,zDist)-->integer
Computes the distance in tiles between tileA and tileB. Does not pre-process arguments like gen.distance, so might be slightly quicker (though this will probably never matter). By default, the vertical distance between maps is 0 tiles, but this can be changed with the optional argument zDist.
Valid Arguments: tileA,tileB: tileObject zDist: integer, nil Notes: This doesn't compute the distance using the typical "Euclidean Distance" that you might be familiar with, but rather the "Taxicab Distance," so that the result is the number of tiles an air unit would have to cross to get from A to B. The distance between adjacent tiles on the same map is always 2 in the "Taxicab Distance," even diagonal movement. This function divides the coordinate distance by 2 to get the result in terms of tiles.
Link to Here. (Click link, then copy the link from your Browser URL Bar.)

gen.gameMechanicDistance(objectA,objectB)-->integer

gen.gameMechanicDistance(objectA,objectB)-->integer Computes a distance between objectA and objectB. This is believed to be the distance the game uses for purposes like calculating city corruption and the nearest city of newly created units. Under this calculation, "diagonal" (using keys 1,3,7,9) movement has a cost of 1, and horizontal and vertical movement (using keys 2,4,6,8) has a cost of 1.5. The final total is rounded down to the nearest integer.
Valid Arguments: objectA,objectB: tileObject, unitObject, cityObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} Notes: This computation is similar to the distance using the typical "Euclidean Distance" that you might be familiar with, but doesn't reflect the number of squares a unit must cross to get from A to B. If that is what you want, consider the gen.distance function.
This is based on Knighttime's work on corruption.
Link to Here. (Click link, then copy the link from your Browser URL Bar.)

gen.wonderModifiedMoves(unit) --> integer

gen.wonderModifiedMoves(unit) -->integer Returns the movement allowance of a unit, after taking into account nuclear power and wonders.
Returns "atomic" movement points.
Valid Arguments: unit: unitObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.maxMoves(unit) --> integer

gen.maxMoves(unit) --> integer Returns movement allowance for a unit after taking damage into account. Also accounts for Lighthouse, Magellan's Expedition, and Nuclear Power.
Returns "atomic" movement points.
Valid Arguments: unit: unitObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.moveRemaining(unit) --> integer

gen.moveRemaining(unit) --> integer Returns the remaining movement allowance for the unit this turn.
Returns "atomic" movement points.
Valid Arguments: unit: unitObject Note: Returns `gen.maxMoves(unit)-unit.moveSpent`
Link to here. (Click link, then copy the link from your browser address bar.)

gen.inPolygon(tile,tableOfCoordinates)-->bool

gen.inPolygon(tile,tableOfCoordinates)-->bool Considers a polygon with corners given by the tableOfCoordinates. Function returns true if the tile is within that polygon, and false if it is not. Map is not considered for this function, even if the coordinates provided have entries for a z coordinate, so you must check it separately.
The Polygon Maker script will produce valid polygon coordinate tables for you.
Valid Arguments: tile: tileObject tableOfCoordinates: Table with integer keys starting at 1, with no gaps. Values for these keys are tables {[1]=xCoord,[2]=yCoord}. Optional key is "doesNotCrossThisX", which has a number value. Notes: The order of the coordinates is the order that you would reach the corners of the polygon if you were drawing its edges without lifting your pen off the paper. The key "doesNotCrossThisX" represents an x coordinate on the map that the polygon doesn't cross over. If it is absent, 0 is used.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.cityCanSupportAnotherUnit(city)-->bool

gen.cityCanSupportAnotherUnit(city)-->bool Returns true if the city has enough production to support all existing units and at least one other unit. Units that get free support under fundamentalism are still counted as "supported," since they still take up a free support "slot" if they are among the first 8 units supported by the city.
Valid Arguments: city: cityObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.homeToNearestCity(unit)-->void

gen.homeToNearestCity(unit)-->void
Finds the nearest city (of the same tribe) that can support another unit, and sets the unit's home city to that city. If there is no suitable city, the unit's home city isn't changed. (It is not set to nil in this case, so if you want that functionality, use unit.homeCity=nil on the previous line.)
Valid Arguments: unit: unitObject Note: The distance is computed using gen.tileDist.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getActivationFunction()-->function(unit,source)

gen.getActivationFunction()-->function(unit,source) Returns the code to be run when a unit is activated.
Valid Arguments: unit: unitType source: boolean Note: Some code might not be available if it isn't necessary to run every single time a unit is activated, such as, for example, the code associated with the After Production execution point. The function returned is the one provided through gen.linkActivationFunction.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getTileID(tile)-->int

gen.getTileID(tile)-->int gen.getTileID(x,y)-->int gen.getTileID(x,y,z)-->int Returns a single-value numeric key that uniquely identifies a tile on any map. Very useful if you want to store a tile as a key in a table. If providing x and y provided, but not z, z is set to 0.
Valid Arguments: tile: tileObject x,y: integers representing map coordinates x,y,z: integers representing map coordinates. Notes: ID numbers will not be the same in different scenarios (if maps are different sizes). Function created by Knighttime, and modified by Prof. Garfield.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getTileId(tile)-->int

gen.getTileID(tile)-->int gen.getTileID(x,y)-->int gen.getTileID(x,y,z)-->int Returns a single-value numeric key that uniquely identifies a tile on any map. Very useful if you want to store a tile as a key in a table. If providing x and y provided, but not z, z is set to 0.
Valid Arguments: tile: tileObject x,y: integers representing map coordinates x,y,z: integers representing map coordinates.
Notes: ID numbers will not be the same in different scenarios (if maps are different sizes). Function created by Knighttime, and modified by Prof. Garfield.
Same function as above, so that you don't have to remember if it is ID or Id.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getTileFromID(tileID) --> tileObject

gen.getTileFromID(tileID) --> tileObject Reverses the function gen.getTileID.
Valid Arguments: tileID: integer representing an ID created by gen.getTileID
Link to here. (Click link, then copy the link from your browser address bar.) Note: ID numbers will not be the same in different scenarios (if maps are different sizes).

gen.getTileFromId(tileID) --> tileObject

gen.getTileFromId(tileID) --> tileObject Reverses the function gen.getTileID.
Valid Arguments: tileID: integer representing an ID created by gen.getTileID Note: ID numbers will not be the same in different scenarios (if maps are different sizes).
Link to here. (Click link, then copy the link from your browser address bar.)
Same function as above, so that you don't have to remember if it is ID or Id.

gen.unitTypeOnTile(tile,unitType)-->bool

gen.unitTypeOnTile(tile,unitType)-->bool gen.unitTypeOnTile(tile,unitTypeTable)-->bool
Returns true if the tile has the unit type, or any of the unit types listed in the table, if a table is provided.
Returns false otherwise
Valid Arguments: tile: tileObject unitType: unitTypeObject unitTypeTable: table with all values unitTypeObject Link to here. (Click link, then copy the link from your browser address bar.)

gen.getAdjacentTiles(tile)-->tableOfTiles

gen.getAdjacentTiles(tile)-->tableOfTiles Returns a table (indexed by integers) with all adjacent tiles to the input tile. Table is indexed this way: # # # # # # # # 7 # # 8 6 # 1 tile 5 # 2 4 # # 3 # # # # # # # # If any keys do not correspond to a valid tile (at edge of map), the corresponding value for that key is nil.
Valid Arguments: tile: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} Link to here. (Click link, then copy the link from your browser address bar.)

gen.cityRadiusTiles(location) --> table

gen.cityRadiusTiles(location) --> table Returns a table (indexed by integers) with all the tiles a city radius of the location. The table is indexed as show below, which is based on how city.workers determines which tiles a city is working. The key 21 corresponds to the tile itself. # # # # # # # # # # # # # # # # 20 13 # # # 12 8 9 # 19 7 1 14 # # 6 21 2 # 18 5 3 15 # # 11 4 10 # # 17 16 # # # # # # # # # # # # If any tile in this radius doesn't exist, the corresponding key has a nil value.
Valid Arguments: location: cityObject, tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} Link to here. (Click link, then copy the link from your browser address bar.)

gen.getTilesInRadius(center,radius) --> table

gen.getTilesInRadius(center,radius) --> table gen.getTilesInRadius(center,radius,minRadius) --> table gen.getTilesInRadius(center,radius,minRadius,maps) --> table Returns a tiles nearby to "center," indexed by integers, with the first index 1, and no missing indices (if the ring goes off the map, the next valid tile gets the next index). A smaller index means a tile closer to the "center" tile (or, at least, not any farther away, and assuming there to be 0 distance in the z direction).
The "radius" is the distance (in tiles) from the "center" to the furthest tiles desired.
The "minRadius" is the distance (in tiles) from the "center" to the nearest tiles to be included. (E.g. if you don't want the center" itself, set minRadius=1.) tiles. If you only want a 'ring' of tiles, set minRadius=radius. By default, this is 0, meaning we collect the "center" tile.
"maps" determines which maps we collect tiles from. By default, it is the map the "center" is on. If integer, use that map. If table of integers, use the integers appearing as values in the table. E.g. {1,3} means get tiles from maps 1 and 3.
Valid Arguments: center: tile, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} radius: integer minRadius: integer or nil maps: nil, integer in 0-3, table of integers Note: If minRadius > radius, an empty table is returned.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.moveUnitAdjacent(unit)-->tile or false

gen.moveUnitAdjacent(unit)-->tile or false gen.moveUnitAdjacent(unit,destRankFn)-->tile or false Moves unit off its current tile to an adjacent tile. If the move is successful, the destination tile is returned. If not, false is returned.
The destRankFn determines the square to move the unit, choosing one of the tiles with the lowest rank. If destRankFn returns false, the unit won't be moved to that tile under any circumstances.
Valid Arguments: unit: unitObject destRankFn: function(unitToMove,candidateTile) --> integer or false (unitToMove:unitObject, candidateTile: tileObject) The default destRankFn ranks empty tiles as 0 (most preferred), tiles occupied by friendly units as 1, and tiles with enemy units or cities as false (can't move there).
Link to here. (Click link, then copy the link from your browser address bar.)

gen.inTable(object,table)--> bool

gen.inTable(object,table)--> bool Returns true if the object is a value for any key in the table, and false otherwise.
Valid Arguments: object: any Lua data type except nil table: table Link to here. (Click link, then copy the link from your browser address bar.)

gen.copyTable(table)-->table

gen.copyTable(table)-->table Constructs and returns a new table with the same keys and values as the input table. If the value is a table, that table (and any tables within it) is also copied into a new table.
Valid Arguments: table: table Note: This function is necessary because when you store a table in a variable, you are storing its "name", or a reference to it, rather than the table itself (this is different from a number or a string). Hence, when you copy table to a new variable, you are only copying its name, and changes to the orignal table also change the copy (and vice versa). E.g. local myTable = {1,2,3} local myOtherTable = myTable myTable[2] = "Not Two" print(myTable[2]) print(myOtherTable[2]) Outputs: Not Two Not Two However, local myTable = {1,2,3} local myOtherTable = gen.copyTable(myTable) myTable[2] = "Not Two" print(myTable[2]) print(myOtherTable[2]) Outputs: Not Two 2 As we might want.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearGapsInArray(table,lowestIndex)-->void

gen.clearGapsInArray(table)-->void gen.clearGapsInArray(table,lowestIndex)-->void Re-indexes all integer keys and their corresponding values in the table, so that there are no gaps. Starts at "lowestIndex" and maintains the order of the values with integer keys. Non-integer keys (including other numbers) and their values are left unchanged. Integer keys below lowestIndex and their values are left unchanged also. By default, lowestIndex equals 1.
Valid Arguments: table: table lowestIndex: integer or nil Link to here. (Click link, then copy the link from your browser address bar.)

gen.makeArrayOneToN(table)

gen.makeArrayOneToN(table) All integer key and their associated values are re-indexed so that the keys start at 1 and proceed without gaps (maintaining the prior ordering of the keys).
All non-integer keys (including other numbers) and their values are ignored.
Valid Arguments: table: table
Link to here. (Click link, then copy the link from your browser address bar.)

gen.tableWrap(item)-->table

gen.tableWrap(item)-->table gen.tableWrap(item,needsWrapFn)-->table or item Determines if "item" should be "wrapped" in a table or not, using "needsWrapFn".
If item is "wrapped", a table is returned with item as the value of the first key. That is, {[1]=item}. Otherwise, the item itself is returned. By default, any item that is not already a table is wrapped, so a table is always returned. Submitting a "needsWrapFn" allows alternate behaviour, either wrapping some tables (e.g. coordinates), or not wrapping items that are not tables. "needsWrapFn" should return true when the item should be wrapped, and false otherwise.
Valid Arguments: item: any Lua value needsWrapFn: nil or function(item)-->boolean (item: any Lua value) Link to here. (Click link, then copy the link from your browser address bar.)

gen.isEmpty(table)-->bool

gen.isEmpty(table)-->bool Returns true if the table has no keys and values, and false otherwise.
Valid Arguments: table: table Note: I got this idea from this Stackoverflow question.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.mergeTableValues(table,table) --> table

gen.mergeTableValues(table,table) --> table gen.mergeTableValues(table,table,...) --> table Accepts an arbitrary number of tables as arguments, and returns a table with all the values from all the tables. Table keys are lost, and replaced by integers starting at 1. Duplicate values will appear multiple times.
Valid Arguments: table: table
Link to here. (Click link, then copy the link from your browser address bar.)

gen.limitedExecutions(key,maxTimes,limitedFunction)--> void

gen.limitedExecutions(key,maxTimes,limitedFunction)--> void Executes the "limitedFunction" if and only if gen.limitedExecutions has been called (and executed a function) less than "maxTimes" for the provided "key".
Valid Arguments: key: string or integer maxTimes: integer limitedFunction: function() --> void Notes: This works by maintaining a table within the state table that counts each time limitedExecutions has been called (and executed) for that key.
In principle, you could have 2 or more locations in code with different functions provided for "limitedFunction," and all of them together would be executed at most maxTimes.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.justOnce(key,limitedFunction) --> void

gen.justOnce(key,limitedFunction) --> void Executes limitedFunction if and only if gen.justOnce has never been executed with the current "key."
Valid Arguments: key: string or integer limitedFunction: function() --> void Notes: This is a wrapper for gen.limitedExecution, so an execution with the same key in that function will also stop execution with gen.justOnce. Using the same key for multiple events will result in only the first of those events happening, which might be useful.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isSinglePlayerGame() --> boolean

gen.isSinglePlayerGame() --> boolean Returns true if there is exactly one human player, false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.copyUnitAttributes(parent,child)-->void

gen.copyUnitAttributes(parent,child)-->void Copies the attributes of the 'parent' unit to the 'child' unit.
All attributes accessible through Lua are copied (except unit type, and unit id number, and carriedBy).
If you are replacing the "parent," you should probably use gen.replaceUnit instead.
Valid Arguments: parent: unitObject child: unitObject Link to here. (Click link, then copy the link from your browser address bar.)

gen.nearbyUnits(center,radius) --> iterator providing units

gen.nearbyUnits(center,radius) --> iterator providing units Provides an iterator returning all the units within "radius" tiles of the "center" tile. Finds the units on all maps.
Valid Arguments: center: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} radius: integer
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getTileProduction(tile,city) --> integer (food), integer(shields), integer(trade)

gen.getTileProduction(tile,city) --> integer (food), integer(shields), integer(trade) Returns the "tile" production values, presuming that the "city" given is the wone owrking the tile. That is to say, returns the values that would be seen on the tile in the city's worker allocation window. Doesn't check if the city is actually working the tile.
Valid Arguments: tile: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} city: cityObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.computeBaseProduction(city)-->integer(food), integer(shields), integer(trade)

gen.computeBaseProduction(city)-->integer(food), integer(shields), integer(trade) Computes the resources harvested by the city from the terrain. Includes superhighway/supermarket/railroad bonuses, but not factories/powerplants.
Valid Arguments: city: cityObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getState()

gen.getState() Returns a table within the state table, enabling the user to save data without relying on a separate module. Important: gen.getState() must be in each function that accesses it; it doesn't provide the state table during the initialization of the events.
Use: local function myFunction(key) local state=gen.getState() print(state[key]) end and NOT: local state=gen.getState() local function myFunction(key) print(state[key]) end Notes: Returns the table submitted to gen.linkState, not which is not the entire State Table in the Lua Scenario Template (to avoid key conflicts).
If you are writing a "module" that you intend to be used by others, consider using a "linkState" system to avoid accidental key conflicts. The General Library code provides an example of this, so search for gen.linkState in the code.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getEphemeralTable()-->table

gen.getEphemeralTable()-->table Returns the "Ephemeral Table." The "Ephemeral Table" is a table for shared data. Since it is not saved, it doesn't have to be serializeable, so you don't have to worry about limiting keys and values to text and numbers. However, the information will not be preserved after a save and load.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.makeAllowedTerrainFunction(allowedTilesTable) --> function(tile)-->bool

gen.makeAllowedTerrainFunction() --> function(tile)-->true gen.makeAllowedTerrainFunction(allowedTilesTable) --> function(tile)-->bool Generates a function that determines if tile.terrainType % 16 was in the list of integers provided by "allowedTilesTable." If so, the function returns true, if not, it returns false. If "allowedTilesTable" is nil, the output funciton returns true for all 16 terrain types.
Valid Arguments: allowedTilesTable: table with integer values or nil
Link to here. (Click link, then copy the link from your browser address bar.)

gen.nearbyUnoccupiedTiles(tile,distance,allowedTiles) --> table

gen.nearbyUnoccupiedTiles(tile,distance) --> table gen.nearbyUnoccupiedTiles(tile,distance,allowedTiles) --> table Returns a table of tiles near "tile" that are unoccupied, on the same map. Indices start at 1 and have no gaps, but the tiles are in no particular order.
"tile" is the tile you wish to find other tiles nearby to.
"distance" is the number of squares away from "tile" to search.
"allowedTiles" determines which tiles are allowed (nil means all allowed).
Valid Arguments: tile: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} distance: integer allowedTiles: nil, table with integer values, function(potentialTile)-->bool (potentialTile: tile; return true if potentialTile is allowed, false if not) Link to here. (Click link, then copy the link from your browser address bar.)

gen.getRandomNearbyUnoccupiedTile(tile,distance,allowedTiles) --> tile

gen.getRandomNearbyUnoccupiedTile(tile,distance) --> tile gen.getRandomNearbyUnoccupiedTile(tile,distance,allowedTiles) --> tile Returns a random tileObject that is nearby to "tile," and unoccupied.
"tile" is the tile you wish to find another tile nearby to.
"distance" is the number of squares away from "tile" to search.
"allowedTiles" determines which tiles are allowed (nil means all allowed).
Valid Arguments: tile: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} distance: integer allowedTiles: nil, table with integer values, function(potentialTile)-->bool (potentialTile: tile; return true if potentialTile is allowed, false if not) Note: gen.nearbyUnoccupiedTiles generates the list of tiles from which the returned tile is selected.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.nearbyOpenTilesForTribe(tile,distance,allowedTiles,tribe)

gen.nearbyOpenTilesForTribe(tile,distance,allowedTiles,tribe) Returns a table of tiles near "tile" that are unoccupied or are occupied by "tribe," on the same map. Indices start at 1 and have no gaps, but the tiles are in no particular order.
"tile" is the tile you wish to find other tiles nearby to.
"distance" is the number of squares away from "tile" to search.
"allowedTiles" determines which tiles are allowed (nil means all allowed).
"tribe" is the tribe that can occupy the tiles.
Valid Arguments: tile: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} distance: integer allowedTiles: nil, table with integer values, function(potentialTile)-->bool (potentialTile: tile; return true if potentialTile is allowed, false if not) tribe: tribeObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.getRandomNearbyOpenTileForTribe(tile,distance,allowedTiles,tribe) --> tile

gen.getRandomNearbyOpenTileForTribe(tile,distance,allowedTiles,tribe) --> tile Returns a random tile near "tile," that is unoccupied or occupied by "tribe," on the same map.
"tile" is the tile you wish to find a random tile nearby to.
"distance" is the number of squares away from "tile" to search.
"allowedTiles" determines which tiles are allowed (nil means all allowed).
"tribe" is the tribe that can occupy the tile.
Valid Arguments: tile: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} distance: integer allowedTiles: nil, table with integer values, function(potentialTile)-->bool (potentialTile: tile; return true if potentialTile is allowed, false if not) tribe: tribeObject
Link to here. (Click link, then copy the link from your browser address bar.)

gen.createUnit(unitType,tribe,locations,options) --> table of units

gen.createUnit(unitType,tribe,locations,options) --> table of units Creates one or several units. Meant to provide improve upon civlua.createUnit. Returns a table of units, indexed by integers starting at 1 (unless no units were created, in which case an empty table is returned, and a message printed to the console, but no error is generated). "unitType" is the unit type that will be created. "tribe" is the tribe that will own the unit(s). "locations" specifies where the unit will be created. If a table is provided, this is the order in which to try to place the units, unless a different option is specified in "options." "options" a table with various keys and values. See the Valid Arguments section.
Valid Arguments: unitType: unitTypeObject tribe: tribeObject locations: a tile object, a table of 3 elements, (indexed by integers 1,2,3) corresponding to x,y,z coordinate, a table of tile objects (indexed by integers) a table of coordinate triple tables (indexed by integers) options: a table with the following keys: count = integer the number of units to create nil means 1 randomize = bool or nil if true, randomize the list of locations if false or nil, try to place at the tile with the smallest index in table first scatter = bool or nil if true, and if randomize is true, each unit is created on a random tile in the location table inCapital = bool or nil if true, attempt to place in the capital before other locations in case of multiple capitals, capitals are ranked with smallest city id first randomize/scatter applies to list of capitals if this is selected veteran = bool or fraction in 0-1 or integer or nil if true, make the created unis veteran if a fraction in 0-1, each unit created has that chance of being veteran if number >= 1, this many of the count are veteran (take floor) nil or false means no veterans homeCity = city or true or nil if city, that city is the home city if true, the game selects the home city (probably the same way a city is chosen if you create a unit by using the cheat menu) if nil, no home city overrideCanEnter = bool or nil if true, unit will be placed even if unitType:canEnter(tile) returns false false or nil means follow the restriction civ.canEnter appears to check if the terrain is impassible, or the unit can cross impassible overrideDomain = bool or nil if true, sea units can be created on land outside cities, and land units at sea false or nil means units can only be created where they could travel naturally overrideDefender = bool or nil if true, unit can be placed on tiles with enemy units or cities false or nil means the tile must have no enemy cities, and no enemy defender
Link to here. (Click link, then copy the link from your browser address bar.)

Data Structures

These functions provide tools for creating and manipulating special data structures.
Threshold Tables
Persistent Random Numbers
Tables With Nil Value Errors

Threshold Tables

A “Threshold Table” is a table modified such that if the value of numerical key is requested, and that numerical key doesn’t correspond to key in the table, the value of the largest numerical index in the table that is less than the requested key is used. If there is no numerical index smaller than the key, false is returned (nil is returned for non-numerical keys not in table). Use a key -math.huge to provide values for arbitrarily small numerical keys.
Example:

myTable = gen.makeThresholdTable({[-1]=-1,[0]=0,[1]=1,})
myTable[-2] --> false
myTable[-1] --> -1
myTable[-0.6] --> -1
myTable[3.5] --> 1
myTable["three"] --> nil
myTable[0.5] --> 0
gen.makeThresholdTable(table)-->thresholdTable

gen.makeThresholdTable()-->thresholdTable gen.makeThresholdTable(table)-->thresholdTable Transforms the submitted table into a threshold table, and returns that table. If no table is submitted, a new (empty) threshold table is created and returned.
Valid Arguments: table: table or nil The Threshold Table functionality is achieved by using a metatable, the details of which can be found in the code.
Link to here. (Click link, then copy the link from your browser address bar.)

Persistent Random Numbers

Random numbers allow for events to sometimes happen, and sometimes not happen. The most basic too that Lua has for randomness, math.random, generates a new random number every time. However, sometimes we want to use the same random number several times, and only generate it once.

Example of use: WWII scenario with seasons

You may want to have some games where the 1941 spring starts in April, and other games where it starts in May. When determining whether to load winter or summer terrain stats during 1941, you would use gen.persistentRandom("EarlySpring1941") < 0.5 as part of the season check in April, and load summer if the value is less than 0.5 and winter otherwise. This way, every time the game is loaded that month, the season will always be the same.

gen.persistentRandom(key) --> number between 0 and 1

gen.persistentRandom(key) --> number between 0 and 1 checks the 'persistentRandom table' (within the state table) for a value associated with key. If it exits, the value is returned. If it does not exist, a random number between 0 and 1 is generated, stored in the table under the key, and also returned
Valid Arguments: key: string or integer Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearPersistentRandom(key) --> void

gen.clearPersistentRandom(key) --> void Clears the value associated with the key in the persistentRandom table. (That is, sets it to nil) This could either be for reuse of the key, or to prevent the key from staying in the state table indefinitely, if it is no longer needed.
Valid Arguments: key: string or integer Link to here. (Click link, then copy the link from your browser address bar.)

gen.getPersistentRandomTable() --> table

gen.getPersistentRandomTable() --> table Returns the table that stores the Persistent Random Values. Note: Not clear why you would want this, but it is available just in case.
Link to here. (Click link, then copy the link from your browser address bar.)

Tables With Nil Value Errors

It occasionally happens that we want our tables to cause errors when we try to read or write to keys with nil values. This is because we’ve written our program in such a way that keys with nil values shouldn’t be accessed, and trying to access them is an indication that our program has some sort of error in it.

gen.errorForNilKey(table,tableName)-->void

gen.errorForNilKey(table,tableName)-->void Generates an error when a key with a nil value is accessed from the table. Useful for debugging in certain circumstances. The "tableName" provides a name for the table in the error that is produced. It is recommended that you use the variable name you've given the table, to help you find and correct your error.
Valid Arguments: table: table talbeName: string Note: This is achieved with a metatable.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.noNewKey(table,tableName)-->void

gen.noNewKey(table,tableName)-->void Causes an error to be generated if the program attempts to set a value for a key that is not already in the table. Useful for debugging in certain circumstances. The "tableName" provides a name for the table in the error that is produced. It is recommended that you use the variable name you've given the table, to help you find and correct your error.
Valid Arguments: table: table talbeName: string Note: This is achieved with a metatable.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.noGlobal()

gen.noGlobal()-->void After gen.noGlobal()-->void is run, errors will be generated when trying to create a new global variable, or when attempting to reference a global variable that does not already exist. Errors explaining the problem will be generated.
This is run in events.lua in the Lua Scenario Template, after createing 2 global variables console and global. Various commands that you might want to run from the Lua Console are stored as values in the "console" table, and "global" is provided in case you decide that you do want some global variables.
If you need temporary access to global variables (perhaps you're working in the Lua Console, which doesn't let you use local variables), you can run the command console.restoreGlobal(), which runs gen.restoreGlobal.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.restoreGlobal()

gen.restoreGlobal() Restores the ability to use global variables, after gen.noGlobal has been used.
The Lua Scenario Template makes this accessible through the console via console.restoreGlobal.
Link to here. (Click link, then copy the link from your browser address bar.)

Flag Functions

These facilitate working with the many attributes that Civilization II stores as 0’s and 1’s in memory, and which Lua groups together and provides as integers.
Bitwise Tools
Terrain Improvements
Unit Orders
Unit Type Flags
City Attribute Flags

Bitwise Tools

gen.checkBits(integer,string) --> boolean

gen.checkBits(integer,string)-->boolean Compares the binary representation of an integer with a string. If the string has a 1 in a given place, the binary representation of the integer should also have a 1. If the string has a 0 in a given place, the binary representation should also have a 0. Any other character in the string means the integer can have a 0 or a 1. If the integer representation is longer than the string, the string is aligned with the smallest part of the integer.
Examples: gen.checkBits(0b10101011,"xx10xwqp")-->true gen.checkBits(0b10101011,"xx11xwqp")-->false gen.checkBits(0b011110101011,"xx10xwqp")-->true gen.checkBits(0b011110101011,"xx10xwqp")-->true Note: Lua does not actually allow you to type in integers specified in binary (though it does allow you to type in hexidecimal by prefixing 0x)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setBits(integer,string)-->integer

gen.setBits(integer,string)-->integer Sets binary bits in an integer to 1 or 0 based on the information provided by a string. Characters in the string that are not 1 or 0 leave the corresponding bit unchanged. The last character of the string corresponds to the 1's bit in the integer (string lines up to the least significant part of the number).
Examples: gen.setBits(0b00000000,"xx10xxxx")-->0b00100000 gen.setBits(0b00000000,"xx10xx")-->0b00001000 gen.setBits(0b11111100,"xx0011xx")-->0b11001100 gen.setBits(0b10101011,"xx10xwqp")-->0b10101011 gen.setBits(0b10101011,"xx11xwqp")-->0b10111011 Note: Lua does not actually allow you to type in integers specified in binary (though it does allow you to type in hexidecimal by prefixing 0x)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.printBits(integer) --> string

gen.printBits(integer) --> string gen.printBits(integer,numOfBits) --> string Returns a string corresponding to the binary representation of the integer. String is 32 characters long if numOfBits isn't specified. If numOfBits is specified, that the least significant bits are printed.
Examples: gen.printBits(0b11110000) --> "00000000000000000000000011110000" gen.printBits(0b11110000,8) --> "11110000" gen.printBits(0b11110000,4) --> "0000" Note: Lua does not actually allow you to type in integers specified in binary (though it does allow you to type in hexidecimal by prefixing 0x)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBit1(integer,bitPosition)--> boolean

gen.isBit1(integer,bitPosition)--> boolean Tells if the binary representation of integer has a 1 in the position given by bitPosition. bitPosition==1 corresponds to the ones position in the binary representation of integer.
Examples: gen.isBit1(0b00000010,2) --> true gen.isBit1(0b00000010,1) --> false Note: Lua does not actually allow you to type in integers specified in binary (though it does allow you to type in hexidecimal by prefixing 0x)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBit0(integer,bitPosition)--> boolean

gen.isBit0(integer,bitPosition)--> boolean Tells if the binary representation of integer has a 0 in the position given by bitPosition. bitposition==1 corresponds to the ones position in the binary representation of integer.
Examples: gen.isBit1(0b11111101,2) --> true gen.isBit1(0b11111101,1) --> false Note: Lua does not actually allow you to type in integers specified in binary (though it does allow you to type in hexidecimal by prefixing 0x)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setBit1(integer,bitPosition)-->integer

gen.setBit1(integer,bitPosition)-->integer The input integer is returned modified such that the binary representation of the integer now has a 1 in the position given by bitPosition. bitposition==1 corresponds to the ones position in the binary representation of integer.
Examples: gen.setBit1(0b11000000,2) --> 0b11000010 gen.setBit1(0b11000010,2) --> 0b11000010 gen.setBit1(0b11000000,1) --> 0b11000001 gen.setBit1(0b11000001,1) --> 0b11000001 Note: Lua does not actually allow you to type in integers specified in binary (though it does allow you to type in hexidecimal by prefixing 0x)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setBit0(integer,bitPosition)-->integer

gen.setBit1(integer,bitPosition)-->integer The input integer is returned modified such that the binary representation of the integer now has a 0 in the position given by bitPosition. bitposition==1 corresponds to the ones position in the binary representation of integer.
Examples: gen.setBit0(0b11001111,2) --> 0b11001101 gen.setBit0(0b11001101,2) --> 0b11001101 gen.setBit0(0b11001111,1) --> 0b11001110 gen.setBit0(0b11001110,1) --> 0b11001110 Note: Lua does not actually allow you to type in integers specified in binary (though it does allow you to type in hexidecimal by prefixing 0x)
Link to here. (Click link, then copy the link from your browser address bar.)

Terrain Improvements

Any function here that accepts a tile will also accept a table {[1]=x,[2]=y,[3]=z}, a table {[1]=x,[2]=y} and assume z = 0, or a table {x=x,y=y,z=z}, or a table {x=x,y=y} and assume z = 0

gen.hasIrrigation(tile)-->boolean

gen.hasIrrigation(tile)-->boolean Returns true if tile has irrigation but no farmland.
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeIrrigation(tile)-->void

gen.placeIrrigation(tile)-->void Places irrigation on the tile provided.
Removes mines and farmland if present.
Does nothing if tile has a city.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeIrrigation(tile)-->void

gen.removeIrrigation(tile)-->void If tile has irrigation but no farmland, removes the irrigation.
Does nothing to farmland.
Does nothing if tile has a city.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasMine(tile)-->boolean

gen.hasMine(tile)-->boolean Returns true if the tile has a mine, and false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeMine(tile)-->void

gen.placeMine(tile)-->void Places mines on the tile provided.
Removes irrigation and farmland if present.
Does nothing if tile has city.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeMineUnderCity(tile) --> void

gen.placeMineUnderCity(tile) --> void Places mine on a tile, even if a city is present.
Removes irrigation and farmland if present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeMine(tile)-->void

gen.removeMine(tile)-->void If tile has mining but no farmland, removes mines.
Does nothing to farmland.
Does nothing if tile has a city.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeMineUnderCity(tile)-->void

gen.removeMineUnderCity(tile)-->void If tile has mining but no farmland, removes mines.
Does nothing to farmland.
Removes mine even if tile has a city.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasFarmland(tile)-->boolean

gen.hasFarmland(tile)-->boolean Returns true if the tile has farmland.
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeFarmland(tile)-->void

gen.placeFarmland(tile)-->void Places farmland on a tile (removing mining if present).
Does nothing if a city is present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeFarmland(tile)-->void

gen.removeFarmland(tile)-->void Removes farmland if present.
Does nothing to irrigation or mining.
Does nothing if city present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasAgriculture(tile)-->bool

gen.hasAgriculture(tile)-->bool Returns true if tile has irrigation or farmland.
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.improveAgriculture(tile) --> void

gen.improveAgriculture(tile) --> void If tile has no irrigation, places irrigation (even if mining present).
If tile has irrigation, places farmland.
If city present, does nothing.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.degradeAgriculture(tile) --> void

gen.degradeAgriculture(tile) --> void If tile has farmland, reduces it to irrigation.
If tile has irrigation, removes it.
Does nothing if city present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeAgriculture(tile) --> void

gen.removeAgriculture(tile) --> void Removes farmland and irrigation if present.
Does nothing to mining.
Does nothing if city present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasRoad(tile)-->boolean

gen.hasRoad(tile)-->boolean Returns true if tile has a road.
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeRoad(tile)-->void

gen.placeRoad(tile)-->void Places a road on the tile.
Does nothing if city present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeRoad(tile)-->void

gen.removeRoad(tile)-->void Removes a road if there is a road but no rail. Doesn't touch rail or cities.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasRailroad(tile)-->boolean

gen.hasRailroad(tile)-->boolean Returns true if a tile has a railroad (and road).
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeRailroad(tile)-->void

gen.placeRailroad(tile)-->void Places a railroad (and road) on a tile.
Does nothing if city is present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeRailroad(tile)-->void

gen.removeRailroad(tile)-->void Removes railroad from a tile if it exits, leaving road intact (if there is already road there).
Does nothing if a city is present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasTransportation(tile) --> boolean

gen.hasTransportation(tile) --> boolean Returns true if tile has road or rail, (but not if city, unless an event has placed a road).
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.upgradeTransportation(tile) --> void

gen.upgradeTransportation(tile) --> void Places railroad if road exists, otherwise places road.
Does nothing if city present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.degradeTransportation(tile) --> void

gen.degradeTransportation(tile) --> void Reduces railroad to road, if rail exists.
If no rail but road, removes road.
If no transportation, does nothing.
If city does nothing.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeTransportation(tile) -->void

gen.removeTransportation(tile) -->void Removes road and rail, if it exists.
Does nothing if city present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasFortress(tile)-->boolean

gen.hasFortress(tile)-->boolean Returns true if the tile has a fortress (and not an airbase).
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeFortress(tile)-->void

gen.placeFortress(tile)-->void Places a fortress on a square, unless there is already a city, transporter, or airbase on the tile.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeFortressForce(tile)-->void

gen.placeFortressForce(tile)-->void Places fortress on a tile (replacing airbase/transporter if necessary). If city on tile, does nothing.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeFortress(tile)-->void

gen.removeFortress(tile)-->void Checks that a fortress is in place (so as not to change other terrain improvements), and if so, removes the fortress.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasAirbase(tile)-->boolean

gen.hasAirbase(tile)-->boolean Returns true if a tile has an airbase.
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeAirbase(tile)--> void

gen.placeAirbase(tile)--> void Places an airbase on a tile as long as there is not already pollution, fortress, or transporter on the tile.
Does nothing if city present
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placeAirbaseForce(tile)-->void

gen.placeAirbaseForce(tile)-->void Places airbase, removing fortress/transporter/pollution if necessary.
If city on tile, nothing happens.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeAirbase(tile)-->void

gen.removeAirbase(tile)-->void Removes airbase, if one is on tile (so that something else doesn't get removed).
Nothing happens if tile has a city.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasPollution(tile)-->boolean

gen.hasPollution(tile)-->boolean Returns true if a tile has pollution.
Returns false othrewise.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placePollution(tile)-->void

gen.placePollution(tile)-->void Places pollution, unless the tile has a city, airbase or transporter.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.placePollutionForce(tile)-->void

gen.placePollutionForce(tile)-->void Places pollution, unless the tile has a city.
Transporters and airbases are removed, if present.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removePollution(tile)-->void

gen.removePollution(tile)-->void Checks if tile has pollution, and if so, removes it.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.hasTransporter(tile)-->boolean

gen.hasTransporter(tile)-->boolean Returns true if the tile has a transporter.
Returns false otherwise.
Link to here. (Click link, then copy the link from your browser address bar.)

Transporters can not be placed by events.


gen.removeTransporter(tile)-->void

gen.removeTransporter(tile)-->void Removes transporter from tile if present.
Does nothing if city present.
Link to here. (Click link, then copy the link from your browser address bar.)

Unit Orders

gen.isFortifying(unit)-->boolean

gen.isFortifying(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToFortifying(unit)-->void

gen.setToFortifying(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isFortified(unit)-->boolean

gen.isFortified(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToFortified(unit)-->void

gen.setToFortified(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isSleeping(unit)-->boolean

gen.isSleeping(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToSleeping(unit)-->void

gen.setToSleeping(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBuildingFortress(unit) --> boolean

gen.isBuildingFortress(unit) --> boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToBuildingFortress(unit)-->void

gen.setToBuildingFortress(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBuildingRoad(unit) --> boolean

gen.isBuildingRoad(unit) --> boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToBuildingRoad(unit)-->void

gen.setToBuildingRoad(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isIrrigating(unit)-->boolean

gen.isIrrigating(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToIrrigating(unit)-->void

gen.setToIrrigating(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isMining(unit)-->boolean

gen.isMining(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToMining(unit)-->void

gen.setToMining(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isTransformingTerrain(unit)-->boolean

gen.isTransformingTerrain(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToTransformingTerrain(unit)-->void

gen.setToTransformingTerrain(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isCleaningPollution(unit)-->boolean

gen.isCleaningPollution(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToCleaningPollution(unit)-->void

gen.setToCleaningPollution(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBuildingAirbase(unit)-->boolean

gen.isBuildingAirbase(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToBuildingAirbase(unit)-->void

gen.setToBuildingAirbase(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBuildingTransporter(unit)-->boolean

gen.isBuildingTransporter(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToBuildingTransporter(unit)-->void

gen.setToBuildingTransporter(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isGoingTo(unit)-->boolean

gen.isGoingTo(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToGoingTo(unit,tile or nil)-->void

gen.setToGoingTo(unit,tile or nil)-->void Gives the unit a goto order for the tile.
If nil is submitted, and the unit already has a goto order, the unit will be changed to no orders.
(setting unit.gotoTile=nil results in an error)
If nil is submitted, and the unit already has some other order, it will keep that order.
Note: this function also accepts a table of coordinates as a tile (just as all other tile functions do in the General Library).
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isNoOrder(unit)-->boolean

gen.isNoOrder(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToNoOrders(unit)-->void

gen.setToNoOrders(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isWaiting(unit)-->bool

gen.isWaiting(unit)-->bool
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setToWaiting(unit)-->void

gen.setToWaiting(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearWaiting(unit)-->void

gen.clearWaiting(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isParadropped(unit)-->boolean

gen.isParadropped(unit)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setParadropped(unit)-->void

gen.setParadropped(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

en.clearParadropped(unit)-->void

gen.clearParadropped(unit)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isMoved(unit)-->boolean

gen.isMoved(unit)-->boolean The game sets this flag when a unit moves (even if no movement point is spent, such as when travelling on a railroad).
The unit won't heal on the next turn if this flag is set.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setMoved(unit)-->void

gen.setMoved(unit)-->void The game sets this flag when a unit moves (even if no movement point is spent, such as when travelling on a railroad).
The unit won't heal on the next turn if this flag is set.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearMoved(unit)-->void

gen.clearMoved(unit)-->void The game sets this flag when a unit moves (even if no movement point is spent, such as when travelling on a railroad).
The unit won't heal on the next turn if this flag is set.
Link to here. (Click link, then copy the link from your browser address bar.)

Unit Type Flags

gen.isSeeTwoSpaces(unitType)-->boolean

gen.isSeeTwoSpaces(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveSeeTwoSpaces(unitType)-->void

gen.giveSeeTwoSpaces(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeSeeTwoSpaces(unitType)-->void

gen.removeSeeTwoSpaces(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isIgnoreZOC(unitType)-->boolean

gen.isIgnoreZOC(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveIgnoreZOC(unitType)-->void

gen.giveIgnoreZOC(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeIgnoreZOC(unitType)-->void

gen.removeIgnoreZOC(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAmphibious(unitType)-->boolean

gen.isAmphibious(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveAmpibious(unitType)-->void

gen.giveAmpibious(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeAmphibious(unitType)-->void

gen.removeAmphibious(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isSubmarine(unitType)-->boolean

gen.isSubmarine(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveSubmarine(unitType)-->void

gen.giveSubmarine(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeSubmarine(unitType)-->void

gen.removeSubmarine(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttackAir(unitType)-->boolean

gen.isAttackAir(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveAttackAir(unitType)-->void

gen.giveAttackAir(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeAttackAir(unitType)-->void

gen.removeAttackAir(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isCoastal(unitType)-->boolean

gen.isCoastal(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveCoastal(unitType)-->void

gen.giveCoastal(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeCoastal(unitType)-->void

gen.removeCoastal(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isIgnoreWalls(unitType)-->boolean

gen.isIgnoreWalls(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveIngoreWalls(unitType)-->void

gen.giveIngoreWalls(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeIgnoreWalls(unitType)-->void

gen.removeIgnoreWalls(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isCarryAir(unitType)-->boolean

gen.isCarryAir(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveCarryAir(unitType)-->void

gen.giveCarryAir(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeCarryAir(unitType)-->void

gen.removeCarryAir(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isParadrop(unitType)-->boolean

gen.isParadrop(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveParadrop(unitType)-->void

gen.giveParadrop(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeParadrop(unitType)-->void

gen.removeParadrop(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAlpine(unitType)-->boolean

gen.isAlpine(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveAlpine(unitType)-->void

gen.giveAlpine(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeAlpine(unitType)-->void

gen.removeAlpine(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBonusAgainstHorse(unitType)-->boolean

gen.isBonusAgainstHorse(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveBonusAgainstHorse(unitType)-->void

gen.giveBonusAgainstHorse(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeBonusAgainstHorse(unitType)-->void

gen.removeBonusAgainstHorse(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isFreeSupportUnderFundamentalism(unitType)-->boolean

gen.isFreeSupportUnderFundamentalism(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveFreeSupportUnderFundamentalism(unitType)-->void

gen.giveFreeSupportUnderFundamentalism(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeFreeSupportUnderFundamentalism(unitType)-->void

gen.removeFreeSupportUnderFundamentalism(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isDestroyedAfterAttacking(unitType)-->boolean

gen.isDestroyedAfterAttacking(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveDestroyedAfterAttacking(unitType)-->void

gen.giveDestroyedAfterAttacking(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeDestroyedAfterAttacking(unitType)-->void

gen.removeDestroyedAfterAttacking(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBonusAgainstAir(unitType)-->boolean

gen.isBonusAgainstAir(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveBonusAgainstAir(unitType)-->void

gen.giveBonusAgainstAir(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeBonusAgainstAir(unitType)-->void

gen.removeBonusAgainstAir(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isSpotSubmarines(unitType)-->boolean

gen.isSpotSubmarines(unitType)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.giveSpotSubmarines(unitType)-->void

gen.giveSpotSubmarines(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.removeSpotSubmarines(unitType)-->void

gen.removeSpotSubmarines(unitType)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

City Attribute Flags

The functions of many of the city attribute flags are unknown at this time. As more functionality is discovered, these functions will be given properly descriptive names. However, for backwards compatibility, gen.commandAttributeXX will remain available in the General Library (though it may be removed from this document). If you discover the purpose of a flag, please report it in this Civfanatics Forum Thread.

gen.isCivilDisorder(city)-->boolean

gen.isCivilDisorder(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setCivilDisorder(city)-->void

gen.setCivilDisorder(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearCivilDisorder(city)-->void

gen.clearCivilDisorder(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isWeLoveTheKing(city)-->boolean

gen.isWeLoveTheKing(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setWeLoveTheKing(city)-->void

gen.setWeLoveTheKing(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearWeLoveTheKing(city)-->void

gen.clearWeLoveTheKing(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isImprovementSold(city)-->boolean

gen.isImprovementSold(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setImprovementSold(city)-->void

gen.setImprovementSold(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearImprovementSold(city)-->void

gen.clearImprovementSold(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isTechnologyStolen(city)-->boolean

gen.isTechnologyStolen(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setTechnologyStolen(city)-->void

gen.setTechnologyStolen(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearTechnologyStolen(city)-->void

gen.clearTechnologyStolen(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAutoBuild(city)-->boolean

gen.isAutoBuild(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAutoBuild(city)-->void

gen.setAutoBuild(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAutoBuild(city)-->void

gen.clearAutoBuild(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute6(city)-->boolean

gen.isAttribute6(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute6(city)-->void

gen.setAttribute6(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute6(city)-->void

gen.clearAttribute6(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute7(city)-->boolean

gen.isAttribute7(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute7(city)-->void

gen.setAttribute7(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute7(city)-->void

gen.clearAttribute7(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBuildCoastal(city)-->boolean

gen.isBuildCoastal(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setBuildCoastal(city)-->void

gen.setBuildCoastal(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearBuildCoastal(city)-->void

gen.clearBuildCoastal(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute9(city)-->boolean

gen.isAttribute9(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute9(city)-->void

gen.setAttribute9(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute9(city)-->void

gen.clearAttribute9(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute10(city)-->boolean

gen.isAttribute10(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute10(city)-->void

gen.setAttribute10(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute10(city)-->void

gen.clearAttribute10(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute11(city)-->boolean

gen.isAttribute11(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute11(city)-->void

gen.setAttribute11(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute11(city)-->void

gen.clearAttribute11(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBuildHydroPlant(city)-->boolean

gen.isBuildHydroPlant(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setBuildHydroPlant(city)-->void

gen.setBuildHydroPlant(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearBuildHydroPlant(city)-->void

gen.clearBuildHydroPlant(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute13(city)-->boolean

gen.isAttribute13(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute13(city)-->void

gen.setAttribute13(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute13(city)-->void

gen.clearAttribute13(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute14(city)-->boolean

gen.isAttribute14(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute14(city)-->void

gen.setAttribute14(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute14(city)-->void

gen.clearAttribute14(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute15(city)-->boolean

gen.isAttribute15(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute15(city)-->void

gen.setAttribute15(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute15(city)-->void

gen.clearAttribute15(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute16(city)-->boolean

gen.isAttribute16(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute16(city)-->void

gen.setAttribute16(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute16(city)-->void

gen.clearAttribute16(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isUsedAirport(city)-->boolean

gen.isUsedAirport(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setUsedAirport(city)-->void

gen.setUsedAirport(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearUsedAirport(city)-->void

gen.clearUsedAirport(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute18(city)-->boolean

gen.isAttribute18(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute18(city)-->void

gen.setAttribute18(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute18(city)-->void

gen.clearAttribute18(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute19(city)-->boolean

gen.isAttribute19(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute19(city)-->void

gen.setAttribute19(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute19(city)-->void

gen.clearAttribute19(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute20(city)-->boolean

gen.isAttribute20(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute20(city)-->void

gen.setAttribute20(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute20(city)-->void

gen.clearAttribute20(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute21(city)-->boolean

gen.isAttribute21(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute21(city)-->void

gen.setAttribute21(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute21(city)-->void

gen.clearAttribute21(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isBuildShips(city)-->boolean

gen.isBuildShips(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setBuildShips(city)-->void

gen.setBuildShips(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearBuildShips(city)-->void

gen.clearBuildShips(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isCityInvestigated(city)-->boolean

gen.isCityInvestigated(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setCityInvestigated(city)-->void

gen.setCityInvestigated(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearCityInvestigated(city)-->void

gen.clearCityInvestigated(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute24(city)-->boolean

gen.isAttribute24(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute24(city)-->void

gen.setAttribute24(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute24(city)-->void

gen.clearAttribute24(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isMilitaryAutoBuild(city)-->boolean

gen.isMilitaryAutoBuild(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setMilitaryAutoBuild(city)-->void

gen.setMilitaryAutoBuild(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearMilitaryAutoBuild(city)-->void

gen.clearMilitaryAutoBuild(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isDomesticAutoBuild(city)-->boolean

gen.isDomesticAutoBuild(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setDomesticAutoBuild(city)-->void

gen.setDomesticAutoBuild(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearDomesticAutoBuild(city)-->void

gen.clearDomesticAutoBuild(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isObjective(city)-->boolean

gen.isObjective(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setObjective(city)-->void

gen.setObjective(city)-->void Sets the city as a scenario "objective."
Removes the major objective flag if it is set, since the objective flag overrides it.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearObjective(city)-->void

gen.clearObjective(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute28(city)-->boolean

gen.isAttribute28(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute28(city)-->void

gen.setAttribute28(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute28(city)-->void

gen.clearAttribute28(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isMajorObjective(city)-->boolean

gen.isMajorObjective(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setMajorObjective(city)-->void

gen.setMajorObjective(city)-->void Sets the city as a scenario "Major Objective.
Clears the regular objective flag if it exists, since the objective flag overrides the major objective flag.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearMajorObjective(city)-->void

gen.clearMajorObjective(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isUsedTransporter(city)-->boolean

gen.isUsedTransporter(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setUsedTransporter(city)-->void

gen.setUsedTransporter(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearUsedTransporter(city)-->void

gen.clearUsedTransporter(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute31(city)-->boolean

gen.isAttribute31(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute31(city)-->void

gen.setAttribute31(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute31(city)-->void

gen.clearAttribute31(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isAttribute32(city)-->boolean

gen.isAttribute32(city)-->boolean
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setAttribute32(city)-->void

gen.setAttribute32(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAttribute32(city)-->void

gen.clearAttribute32(city)-->void
Link to here. (Click link, then copy the link from your browser address bar.)

Small Features

These functions create features for the Lua Scenario Template that are too small to merit a separate module.

Re-Home Units When City Captured

Description

In standard Civilization II, when a city is captured, the units supported by that city are immediately disbanded. It is possible to override that feature of the game with Lua. With this feature, units supported by a captured city are re-homed to a nearby friendly city that can support them.

To activate this feature, open the simpleSettings.lua file in the LuaRulesEvents directory, and change the line

simpleSettings.rehomeUnitsOnCityCapture = false

to

simpleSettings.rehomeUnitsOnCityCapture = true

Functions

gen.rehomeUnitsInCapturedCity(city,defender) --> void

gen.rehomeUnitsInCapturedCity(city,defender) --> void
When the city is captured from the defender tribe, all units supported by that city are re-homed to the nearest friendly city that has extra production to support them.
Valid Arguments: city: cityObject defender: tribeObject Note: Should be placed in the City Captured execution point if not using the Lua Scenario Template.
Link to here. (Click link, then copy the link from your browser address bar.)

Custom Unit Activation

Description

Changes the way the next active unit is selected by the game, so that the annoying behavior of units activating far away or on different maps is minimized. Occasionally, there is a bug where pressing ‘W’ makes it appear that only a couple nearby units are the only ones that haven’t moved, but there are other units elsewhere that are still available.

To activate this feature, open the simpleSettings.lua file in the LuaRulesEvents directory, and change the line

simpleSettings.enableCustomUnitSelection = false

to

simpleSettings.enableCustomUnitSelection = true

If you want to modify how the unit is selected, write a function of the form

weightFunction(unit,activeUnit)-->integer

and place it as the value for this line in simpleSettings.lua.

simpleSettings.doNotDeleteAITextArchives = nil

The weightFunction gives every unit that could be activated a ‘weight,’ based on the unit that was just activated, and chooses the unit with the smallest ‘weight’ to be activated next (assuming it hasn’t already been told to wait).

By default, a weightFunction is used that adds 1 if the unit is a different type than the activeUnit, adds 2 times the distance between the units, and 10000 if the units are on different maps.

Functions

gen.selectNextActiveUnit(activeUnit,source,customWeightFn)-->void

gen.selectNextActiveUnit(activeUnit,source)-->void gen.selectNextActiveUnit(activeUnit,source,customWeightFn)-->void Uses a "weightFunction" to determine the 'best' unit to activate next, and gives all other units owned by the active unit's tribe the `wait` command, so they don't activate instead. If no weightFunction is provided, the weight is +1 if the unit isn't the same type as the active unit, +2 per square of distance between the units, and +10000 if the units are on different maps. The 'source' argument is a boolean, the same as the 'source' in the Unit Activation execution point.
No effect on AI controlled tribes.
Valid Arguments: activeUnit: unitType source: boolean customWeightFn: function(unit,ActiveUnit)-->integer (both arguments are unitType objects) Notes: If implementing outside the Lua Scenario template, use as the first line inside the function provided to civ.scen.onActivateUnit(function(unit,source)-->void)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.betterUnitManualWait() --> void

gen.betterUnitManualWait() --> void
Makes the `W` key work for Custom Unit Activation (by storing waiting units in a table), since the actual 'waiting' flag is manipulated.
Notes: If implementing outside of the Lua Scenario Template, this should be run when there is an active unit, and the key pressed has id 87. (keyboard.w) E.g.: if civ.getActiveUnit() and keyID == 87 then gen.betterUnitManualWait() end
Link to here. (Click link, then copy the link from your browser address bar.)

Unprotecting Stacks

Description

The Lua Scenario Template provides a built in way to thwart stacking air units on ground units for protection. When a unit is activated, all adjacent tiles are checked to determine if any are air protected stacks, and if so, the air units are moved to alternate tiles. (The human player will have to use ‘V’ and ‘A’ to activate the unit again, but AI units are activated every square, so it will happen automatically for them.)

To activate this feature, open the simpleSettings.lua file in the LuaRulesEvents directory, and change the lines

simpleSettings.clearAdjacentAirProtectionAI = false
simpleSettings.clearAdjacentAirProtectionHuman = false

to

simpleSettings.clearAdjacentAirProtectionAI = true
simpleSettings.clearAdjacentAirProtectionHuman = true

If you only want the AI (or only Human players) to have adjacent air protection removed, only set one of the lines to true. The first line will clear air protection beside any AI unit that is activated.

You can create other forms of stack “unprotecting” by using the functions in the next section. Perhaps you have a unit type that shouldn’t be able to ‘hide’ behind a strong defender, for example.

Functions

gen.unprotectTile(tile,isProtectingUnit,isProtectedUnit, isProtectedTile,destRankFn)-->void

gen.unprotectTile(tile,isProtectingUnit, isProtectedUnit,isProtectedTile)-->void gen.unprotectTile(tile,isProtectingUnit,isProtectedUnit, isProtectedTile,destRankFn)-->void
Valid Arguments: tile: tileObject isProtectingUnit: function(unitObject) --> bool isProtectedUnit: function(unitObject) --> bool isProtectedTile: function(tileObject) --> bool destRankFn: function(unitToMove,candidateTile) --> integer or false (unitToMove:unitObject, candidateTile: tileObject) This code checks all the units on a tile. If there are any "protecting" units (air units in air protected stacks) on the tile and also any "protected" units (land/sea units in air protected stacks) and finally the tile is "protected" (doesn't have city/airbase or carrier unit in air protected stacks), then the "protecting" units are moved off the tile. If any of these conditions are not met, the units stay where they are. isProtectingUnit(unitObject): returns true if unit is a "protecting" unit isProtectedUnit(unitObject): returns true if unit is a unit that can be "protected" isProtectedTile(tileObject): returns true if the tile can be "protected" See gen.moveUnitAdjacent for the destRankFn explanation and behaviour if absent. Here are the functions used for unprotecting air protected stacks: local function isProtectedTile(tile) if tile.city or gen.hasAirbase(tile) then return false end for unit in tile.units do if gen.isCarryAir(unit.type) then return false end end return true end local function isProtectingUnit(unit) if unit.type.domain == 1 and unit.type.range >= 2 then return true else return false end end local function isProtectedUnit(unit) return not isProtectingUnit(unit) end local function tileHasGroundUnit(tile) for unit in tile.units do if isProtectedUnit(unit) then return true end end return false end local function destRankFn(unit,tile) -- don't want an air unit to be moved to a -- city, airbase, or carrier if not isProtectedTile(tile) then return false end if (tile.defender and tile.defender ~=unit.owner) or (tile.city and tile.city.owner ~= unit.owner) or (not civ.canEnter(unit.type,tile)) then return false end if tile.defender == nil then return 0 elseif tileHasGroundUnit(tile) then return 2 else return 1 end end
Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAirProtection(tile)-->void

gen.clearAirProtection(tile)-->void If the tile is an air protected stack, the air units are moved off the stack.
Valid Arguments: tile: tileObject Link to here. (Click link, then copy the link from your browser address bar.)

gen.clearAdjacentAirProtection(unit) -->void

gen.clearAdjacentAirProtection(unit) -->void Clears air protection (by moving air units) from all tiles adjacent to the unit, except for those tiles defended by the unit's owner.
Valid Arguments: unit: unitObject Notes: This is the function used by the Lua Scenario Template to implement clearing air protection (though it is built with the functions described above. In the Lua Scenario Template, this function is included in the Unit Activation execution point (though in the part in events.lua). This works for the AI, since the Unit Activation execution point triggers on every tile for AI units.
Link to here. (Click link, then copy the link from your browser address bar.)

Technical Functions

These functions are necessary to integrate the General Library with the Lua Events. You are unlikely to need these working with the Lua Scenario Template.

gen.linkActivationFunction(unitActivationFunction)-->void

gen.linkActivationFunction(unitActivationFunction)-->void Links the function to be run every time a unit is activated. The TOTPP method unit:activate() doesn't trigger the Unit Activation execution point, so the general library provides gen.activate and gen.activateSource instead. This function provides the code these functions will run once the unit is activated. It is not necessary to provide the code for the execution point.
Valid Arguments: unitActivationFunction: function(unit,source)-->void (unit: unitType, source: boolean)
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setMusicDirectory(path)-->void

gen.setMusicDirectory(path)-->void Sets the directory path where gen.playMusic will look for files. This is set relative to <Test Of Time Dir>\Music, which is where civ.playMusic(filename) looks for music. In the Lua Scenario Template, this is set in the events.lua file.
Valid Arguments: path: string (valid folder path) In the Lua Scenario Template, this is the relevant code: local eventsPath = string.gsub(debug.getinfo(1).source, "@", "") local musicFolder= string.gsub(eventsPath,civ.getToTDir(),"..") musicFolder= string.gsub(musicFolder,"events.lua","").."\\Sound" gen.setMusicDirectory(musicFolder) gen.playMusic(fileName) is then equivalent to civ.playMusic(musicFolder.."\\"..fileName). Link to here. (Click link, then copy the link from your browser address bar.)

gen.setDeathFunctions(defeatFunction,deathFunction, deletionFunction, deathNoCombatFn) --> void

gen.setDeathFunctions(defeatFunction,deathFunction, deletionFunction, deathNoCombatFn) --> void Registers functions to be performed when a unit is defeated (either in game combat or events) or deleted by events in some other way
Arguments: defeatFunction(loser,winner,aggressor,victim,loserLocation,winnerVetStatus,loserVetStatus)--> nil or unit function for when a unit is defeated either in game combat or in an event representing combat if a unit is returned, that is a replacement unit for demotion deathFunction(dyingUnit) --> void for when a unit 'dies', either in standard or event combat, or through some other event 'kill' deletionFunction(deletedUnit,replacingUnit=nil) --> void maintenance for when a unit is deleted, either because of combat, death, replacement or some other 'administrative' situation. If no replacing unit, the replacingUnit argument is nil deathNoCombatFn(dyingUnit) --> void for when a unit dies, but not in combat or through the gen.defeatUnit function
Link to here. (Click link, then copy the link from your browser address bar.)

gen.linkState(stateTable)

gen.linkState(stateTable) Links the state table to the General Library so that gen.getState() can provide it.
Valid Arguments: stateTable: table within the State Table Notes: The link is within events.lua, found within linkStateTableToModules(). Actually links a sub table within the State Table, so that key choice doesn't override keys for other modules.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.linkGeneralLibraryState(stateTable) --> void

gen.linkGeneralLibraryState(stateTable) --> void Links the General Library to the state table, for the purposes of internal functionality that requires saving data. E.g. limited executions and persistent random.
Valid Arguments: stateTable: table within the State Table Notes: The link is within events.lua, found within linkStateTableToModules().
Link to here. (Click link, then copy the link from your browser address bar.)

Obsolete Functions

These functions have functionality that has been rendered obsolete by more recent developments. They are still included in the General Library for backwards compatibility.

gen.isMapFlat()-->boolean

gen.isMapFlat()-->boolean Returns true if map is flat, and false if it is round.
Use civ.game.rules.flatWorld instead.
Note: This function simply returns the above code now.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.isMapRound()-->boolean

gen.isMapRound()-->boolean Returns true if the map is round, and false if it is flat.
Use not civ.game.rules.flatWorld instead.
Note: This function simply returns the above code now.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.declareMapFlat()-->void

gen.declareMapFlat()-->void No effect. Prior to TOTPP v0.16, it changed a variable referenced by gen.isMapRound and gen.isMapFlat.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.declareMapRound()-->void

gen.declareMapRound()-->void No effect. Prior to TOTPP v0.16, it changed a variable referenced by gen.isMapRound and gen.isMapFlat.
Link to here. (Click link, then copy the link from your browser address bar.)

gen.setTerrainType(tile,terrainID)-->void

gen.setTerrainType(tile,terrainID)-->void This was supposed to "future proof" setting terrain types, but I don't think it was ever used. I (Prof. Garfield, who wrote this Library) forgot about it. With TOTPP v0.16, we now have the new method to change terrain anyway.
This is what my documentation said about it: changes the terrain type of tile to terrainID have this function, so that if terrainType key functionality is changed, this function can change instead of all code everywhere
Valid Arguments: tile: tileObject, {[1]=xCoord,[2]=yCoord}, {[1]=xCoord,[2]=yCoord, [3]=zCoord}, {["x"]=xCoord,["y"]=yCoord}, {["x"]=xCoord,["y"]=yCoord,["z"]=zCoord} terrainID: integer from 0 to 15
Link to here. (Click link, then copy the link from your browser address bar.)