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 thecivlibrary. - Building Blocks
These are miscellaneous functions that are likely to be useful in building larger events or other modules. - Data Structures
These functions provide tools for creating and manipulating special data structures. - 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.
- Small Features
These functions create features for the Lua Scenario Template that are too small to merit a separate module. - 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. - 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.
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.)