1. We have added a Gift Upgrades feature that allows you to gift an account upgrade to another member, just in time for the holiday season. You can see the gift option when going to the Account Upgrades screen, or on any user profile screen.
    Dismiss Notice

[TOTPP] Lua function reference

Discussion in 'Civ2 - General Discussions' started by TheNamelessOne, Oct 29, 2015.

  1. TheNamelessOne

    TheNamelessOne Chieftain

    Joined:
    Dec 18, 2013
    Messages:
    196
    Here's the complete (work in progress :p) reference of all Lua functions and data that can be used to interact with the game.

    With v0.15 of ToTPP, scenario designers are able to change otherwise static rules during the course of the game. These changes are ephemeral, i.e. they only last for the current session, and will be restored to their default values on load. It is up to the designer to persist these changes, and apply them again in the onLoad trigger of the scenario. Such properties are marked below with 'Ephemeral'.


    The civ library


    addImprovement
    civ.addImprovement(city, improvement)

    Adds city improvement `improvement` to city `city`.


    canEnter
    civ.canEnter(unittype, tile) -> boolean

    Returns `true` if the given unittype can enter tile `tile`, `false` otherwise.


    captureCity
    civ.captureCity(city, tribe)

    Captures city `city` for tribe `tribe`.


    createCity
    civ.createCity(tribe, tile) -> city

    Creates a city owned by `tribe` at the location given by `tile`. Returns `nil` if a city could not be created.


    createUnit
    civ.createUnit(unittype, tribe, tile) -> unit

    Creates a unit of type `unittype`, owned by `tribe`, at the location given by `tile`.


    deleteCity
    civ.deleteCity(city)

    Deletes city `city` from the game.


    deleteUnit
    civ.deleteUnit(unit)

    Deletes unit `unit` from the game.


    destroyWonder
    civ.destroyWonder(wonder)

    Destroys wonder `wonder`, removing it from the game, and marking it as 'lost'.


    enableTechGroup
    civ.enableTechGroup(tribe, techgroup, value)

    Sets the value of tech group `techgroup` (0-7) to value `value` (0-2, 0 = can research, can own, 1 = can't research, can own, 2 = can't research, can't own) for tribe `tribe`.


    endGame
    civ.endGame(endscreens=false)

    Ends the game. `endscreens` is a boolean that determines whether to show the powergraph and related screens.


    getActiveUnit
    civ.getActiveUnit() -> unit

    Returns the currently active unit.


    getCity
    civ.getCity(id) -> city

    Returns the city with id `id`, or `nil` if it doesn't exist.


    getCurrentTile
    civ.getCurrentTile() -> tile

    Returns the currently selected tile.


    getCurrentTribe
    civ.getCurrentTribe() -> tribe

    Returns the currently active tribe.


    getGameYear
    civ.getGameYear() -> integer

    Returns the current game year.


    getImprovement
    civ.getImprovement(id) -> improvement

    Returns the improvement with id `id` (0-39), or `nil` if it doesn't exist.


    getMapDimensions
    civ.getMapDimensions() -> width, height, number_of_maps

    Returns three integers, the width and height of the map and the number of maps.


    getPlayerTribe
    civ.getPlayerTribe() -> tribe

    Returns the player's tribe.


    getTech
    civ.getTech(id) -> tech

    Returns the tech with id `id` (0-99), or `nil` if it doesn't exist.


    getTile
    civ.getTile(x, y, z) -> tile

    Returns the tile with coordinates `x`, `y`, `z`, or `nil` if it doesn't exist.


    getToTDir
    civ.getToTDir() -> string

    Returns the absolute path of the ToT installation directory.


    getTribe
    civ.getTribe(id) -> tribe

    Returns the tech with id `id` (0-7), or `nil` if it doesn't exist.


    getTurn
    civ.getTurn() -> integer

    Returns the current turn number.


    getUnit
    civ.getUnit(id) -> integer

    Returns the unit with id `id`, or `nil` if it doesn't exist.


    getUnitType
    civ.getUnitType(id) -> unittype

    Returns the unit type with id `id`, or `nil` if it doesn't exist.


    getWonder
    civ.getWonder(id) -> wonder

    Returns the wonder with id `id` (0-27), or `nil` if it doesn't exist.


    giveTech
    civ.giveTech(tribe, tech)

    Gives tech `tech` to tribe `tribe`.


    hasImprovement
    civ.hasImprovement(city, improvement)

    Returns `true` if city `city` has improvement `improvement`, `false` otherwise.


    hasTech
    civ.hasTech(tribe, tech) -> boolean

    Returns `true` if tribe `tribe` has tech `tech`, `false` otherwise.


    isCity
    civ.isCity(object) -> boolean

    Returns `true` if `object` is a city, `false` otherwise.


    isImprovement
    civ.isImprovement(object) -> boolean

    Returns `true` if `object` is a city improvement, `false` otherwise.


    isLeader
    civ.isLeader(object) -> boolean

    Returns `true` if `object` is a leader, `false` otherwise.


    isTech
    civ.isTech(object) -> boolean

    Returns `true` if `object` is a tech, `false` otherwise.


    isTile
    civ.isTile(object) -> boolean

    Returns `true` if `object` is a tile, `false` otherwise.


    isTribe
    civ.isTribe(object) -> boolean

    Returns `true` if `object` is a tribe, `false` otherwise.


    isUnit
    civ.isUnit(object) -> boolean

    Returns `true` if `object` is a unit, `false` otherwise.


    isUnitType
    civ.isUnitType(object) -> boolean

    Returns `true` if `object` is a unit type, `false` otherwise.


    isWonder
    civ.isWonder(object) -> boolean

    Returns `true` if `object` is a wonder, `false` otherwise.


    iterateCities
    civ.iterateCities() -> iterator

    Returns an iterator yielding all cities in the game.


    iterateUnits
    civ.iterateUnits() -> iterator

    Returns an iterator yielding all units in the game.


    killTribe
    civ.killTribe(tribe)

    Removes tribe `tribe` from the game. All its cities and units are removed.


    makeAggression
    civ.makeAggression(who, whom)

    Cancels any peace treaties between tribe `who` and tribe `whom`, and make `who` declare war on `whom`.


    playMusic
    civ.playMusic(trackNo or filename)

    Plays CD track `trackNo`, or with the DirectShow music patch enabled, play the file given by `filename`, where `filename` is relative to the 'Music' directory.


    playSound
    civ.playSound(filename)

    Plays the sound file given by `filename`.


    playVideo
    civ.playVideo(filename)

    Plays the video file given by `filename`.


    removeImprovement
    civ.removeImprovement(city, improvement)

    Removes city improvement `improvement` from city `city`.


    sleep
    civ.sleep(milliseconds)

    Sleeps for the given number of milliseconds.


    takeTech
    civ.takeTech(tribe, tech, collapse=false)

    Takes away tech `tech` from tribe `tribe`, the optional `collapse` parameter determines whether to take away all techs that have `tech` as a prerequisite somewhere up the tree.


    teleportUnit
    civ.teleportUnit(unit, tile)

    Teleports (i.e. moves at no cost) unit `unit` to tile `tile`. The unit is moved regardless of whether it is a valid location for the unit. To check this, see `civ.canEnter` and `civlua.isValidUnitLocation`.


    The civ.ui library


    centerView
    civ.ui.centerView(tile)

    Centers the map on the given tile.


    redrawMap
    civ.ui.redrawMap()

    Redraws the entire map.


    redrawTile
    civ.ui.redrawTile(tile)

    Redraws the given tile.


    setZoom
    civ.ui.setZoom(integer)

    Sets the zoom level (range from -7 (max zoom out) to 8 (max zoom in)).


    text
    civ.ui.text(string)

    Display a pop-up text box with the given string as text.


    zoomIn
    civ.ui.zoomIn()

    Zooms in on the map (increases zoom level by 1).

    zoomOut
    civ.ui.zoomOut()

    Zooms out of the map (decreases zoom level by 1).

    loadTerrain
    civ.ui.loadTerrain(map, filename1, filename2)

    Replaces terrain graphics for map number `map`, loading graphics from `filename1` (corresponding to "TERRAIN1.BMP") and `filename2` (corresponding to "TERRAIN2.BMP")

    createDialog
    civ.ui.createDialog() -> dialog

    Creates and initializes a dialog. See the dialog section for more details.


    The city object


    id (get)
    city.id -> integer

    Returns the city's id.


    name (get/set)
    city.name -> string

    Returns the city's name.


    location (get)
    city.location -> tile

    Returns the city's location. See the `relocate` method for a way to set this.


    size (get/set)
    city.size -> integer

    Returns the city's size.


    attributes (get/set)
    city.attributes -> integer

    Returns the city's attributes (bitmask).


    owner (get/set)
    city.owner -> tribe

    Returns the city's owner.


    originalOwner (get/set)
    city.originalOwner -> tribe

    Returns the city's original owner. This can be different from `owner` if the city was captured in the past.


    turnsSinceCapture (get/set)
    city.turnsSinceCapture -> integer

    Returns the number of turns since the city was last captured.


    knownTo (get/set)
    city.knownTo -> integer

    Returns a bitmask indicating the tribes that have knowledge of this city.


    specialists (get/set)
    city.specialists -> integer

    Returns the city's specialists as a integer, 16 x 2 bits per specialist (0 - No specialist, 1 - Entertainer, 2 - Taxman, 3 - Scientist)


    food (get/set)
    city.food -> integer

    Returns the quantity of food in store.


    shields (get/set)
    city.shields -> integer

    Returns the number of shields towards the current item in production.


    baseTrade (get)
    city.baseTrade -> integer

    Returns the number of trade arrows before trade routes.


    workers (get/set)
    city.workers -> integer

    Returns a bitmask with the workers and specialists of the city.


    numTradeRoutes (get)
    city.numTradeRoutes -> integer

    Returns the number of trade routes of the city.


    science (get)
    city.science -> integer

    Returns the amount of science the city produces.


    tax (get)
    city.tax -> integer

    Returns the amount of tax the city produces.


    totalTrade (get)
    city.totalTrade -> integer

    Returns the total amount of trade arrows the city produces (including trade routes).


    totalFood (get)
    city.totalFood -> integer

    Returns the total amount of food the city produces.


    totalShield (get)
    city.totalShield -> integer

    Returns the total amount of shields the city produces.


    numHappy (get)
    city.numHappy -> integer

    Returns the number of happy citizens.


    numUnhappy (get)
    city.numUnhappy -> integer

    Returns the number of unhappy citizens.


    coastal (get)
    city.coastal -> boolean

    Returns whether or not the city is on a coast (can build coastal improvements).


    addImprovement
    city:addImprovement(improvement)

    Alias for `civ.addImprovement(city, improvement)`.


    hasImprovement
    city:hasImprovement(improvement) -> boolean

    Alias for `civ.hasImprovement(city, improvement)`.


    removeImprovement
    city:removeImprovement(improvement)

    Alias for `civ.removeImprovement(city, improvement)`.


    relocate
    city:relocate(tile) -> boolean

    Relocates the city to the location given by `tile`. Returns `true` if successful, `false` otherwise (if a city is already present for example).


    canBuild
    city:canBuild(item) -> boolean

    Returns whether or not `item` can currently be built in the city. `item` can be a unittype, improvement or wonder.



    The tile object


    x (get)
    tile.x -> integer

    Returns the `x` coordinate of the tile.


    y (get)
    tile.y -> integer

    Returns the `y` coordinate of the tile.


    z (get)
    tile.z -> integer

    Returns the `z` coordinate of the tile (map number).


    terrainType (get/set)
    tile.terrainType -> integer

    Returns the terrain type of the tile.


    owner (get)
    tile.owner -> tribe

    Returns the tribe owning the tile.


    improvements (get/set)
    tile.improvements -> integer

    Returns the tile's improvements (bitmask).


    fertility (get/set)
    tile.fertility -> integer

    Returns the tile's fertility.


    landmass (get/set)
    tile.landmass -> integer

    Returns the tile's landmass index.


    city (get)
    tile.city -> city

    Returns the city at the tile's location, or `nil` if there's no city there.


    units (get)
    tile.units -> iterator

    Returns an iterator yielding all units at the tile's location.


    defender (get)
    tile.defender -> tribe

    Returns the tile's defender.


    The unit object


    id (get)
    unit.id -> integer

    Returns the unit's id.


    type (get)
    unit.type -> unittype

    Returns the unit's type.


    location (get)
    unit.location -> tile

    Returns the unit's location.


    homeCity (get/set)
    unit.homeCity -> city

    Returns the unit's home city, or `nil` if it doesn't have one.


    damage (get/set)
    unit.damage -> integer

    Returns the damage taken by the unit in hitpoints.


    hitpoints (get)
    unit.hitpoints -> integer

    Returns the number of hitpoints left. It is defined as unit.type.hitpoints - unit.damage.


    moveSpent (get/set)
    unit.moveSpent -> integer

    Returns the number of moves spent by the unit.


    order (get/set)
    unit.order -> integer

    Returns the current order of the unit.


    carriedBy (get)
    unit.carriedBy -> unit

    Returns the carrying unit if this unit is currently on board, `nil` otherwise.


    attributes (get/set)
    unit.attributes -> integer

    Returns the attributes of the unit (bitmask).


    veteran (get/set)
    unit.veteran -> boolean

    Returns the veteran status of the unit.


    gotoTile (get/set)
    unit.gotoTile -> tile

    Returns the tile the unit is moving to under the goto order, or `nil` if it doesn't have the goto order.


    activate
    unit:activate()

    Activates a unit, clearing its orders, and, if it has a human owner and movement points left, selects it on the map.


    teleport
    unit:teleport(tile)
    Alias for `civ.teleportUnit(unit, tile)`.



    The unittype object


    id (get)
    unittype.id -> integer

    Returns the id of the unit type.


    name (get)
    unittype.name -> string

    Returns the name of the unit type.


    prereq (get/set)
    unittype.prereq -> tech

    Returns the prerequisite technology of the unit type, or `nil` if it doesn't have one. Ephemeral.


    domain (get/set)
    unittype.domain -> integer

    Returns the domain of the unit type (0 - Ground, 1 - Air, 2 - Sea). Ephemeral.


    attack (get/set)
    unittype.attack -> integer

    Returns the attack factor of the unit type. Ephemeral.


    defense (get/set)
    unittype.defense -> integer

    Returns the defense factor of the unit type. Ephemeral.


    hitpoints (get/set)
    unittype.hitpoints -> integer

    Returns the number of hit points of the unit type. Ephemeral.


    firepower (get/set)
    unittype.firepower -> integer

    Returns the firepower of the unit type. Ephemeral.


    move (get/set)
    unittype.move -> integer

    Returns the movement rate of the unit type. Ephemeral.


    range (get/set)
    unittype.range -> integer

    Returns the range of the unit type. Ephemeral.


    expires (get/set)
    unittype.expires -> tech

    Returns the tech that renders the unit obsolete, or `nil` if there isn't any. Ephemeral.


    cost (get/set)
    unittype.cost -> integer

    Returns the cost of the unit type. Ephemeral.


    hold (get/set)
    unittype.hold -> integer

    Returns the number of holds of the unit type. Ephemeral.


    role (get/set)
    unittype.role -> integer

    Returns the role of the unit type. Ephemeral.


    flags (get/set)
    unittype.flags -> integer

    Returns the flags of the unit type (bitmask). Ephemeral.


    nativeTransport (get/set)
    unittype.nativeTransport -> integer

    Returns the 'native transport' settings of the unit type (bitmask).


    buildTransport (get/set)
    unittype.buildTransport -> integer

    Returns the 'build transport site' settings of the unit type (bitmask).


    useTransport (get/set)
    unittype.useTransport -> integer

    Returns the 'use transport site' settings of the unit type (bitmask).


    canEnter
    unittype:canEnter(tile) -> boolean

    Alias for `civ.canEnter(unittype, tile)`


    The tribe object


    id (get)
    tribe.id -> integer

    Returns the id of the tribe.


    name (get/set)
    tribe.name -> string

    Returns the name of the tribe (e.g. "Romans").


    adjective (get/set)
    tribe.adjective -> string

    Returns the adjectival form of the tribe's name (e.g. "Roman").


    leader (get)
    tribe.leader -> leader

    Returns the leader of the tribe.


    isHuman (get)
    tribe.isHuman -> boolean

    Returns whether the tribe is a/the human player.


    active (get)
    tribe.active -> boolean

    Returns whether the tribe is active, i.e. a human or AI player in the current game.


    money (get/set)
    tribe.money -> integer

    Returns the amount of money/gold in the tribe's treasury.


    numCities (get)
    tribe.numCities -> integer

    Returns the number of cities the tribe has.


    numUnits (get)
    tribe.numUnits -> integer

    Returns the number of units the tribe has.


    numTechs (get)
    tribe.numTechs -> integer

    Returns the number of techs the tribe has.


    government (get/set)
    tribe.government -> integer

    Returns the government (0 - 6) of the tribe.


    betrayals (get/set)
    tribe.betrayals -> integer

    Returns the number of times the tribe has betrayed another tribe.


    patience (get/set)
    tribe.patience -> integer

    Returns the tribe's patience.


    attitude (get/set)
    tribe.attitude[otherTribe] -> integer

    Returns the tribe's attitude to `otherTribe`.


    reputation (get/set)
    tribe.reputation[otherTribe] -> integer

    Returns the tribe's reputation with `otherTribe`.


    treaties (get/set)
    tribe.treaties[otherTribe] -> integer

    Returns the tribe's treaties with `otherTribe`.


    researching (get/set)
    tribe.researching -> tech

    Returns the tech the tribe is currently researching.


    researchProgress (get/set)
    tribe.researchProgress -> integer

    Returns the progress towards the current research (range between 0 and tribe.researchCost).


    researchCost (get)
    tribe.researchCost -> integer

    Returns the research cost of the tribe.


    futureTechs (get/set)
    tribe.futureTechs -> integer

    Returns the number of future techs the tribe has researched.


    scienceRate (get)
    tribe.scienceRate -> integer

    Returns the science rate of the tribe.


    taxRate (get)
    tribe.taxRate -> integer

    Returns the tax rate of the tribe.


    spaceship (get)
    tribe.spaceship -> spaceship

    Returns the space ship object of the tribe.


    enableTechGroup
    tribe:enableTechGroup(techgroup, value)

    Alias for `civ.enableTechGroup(tribe, techgroup, value)`.


    giveTech
    tribe:giveTech(tech)

    Alias for `civ.giveTech(tribe, tech)`.


    hasTech
    tribe:hasTech(tech) -> boolean

    Alias for `civ.hasTech(tribe, tech)`.


    kill
    tribe:kill()

    Alias for `civ.killTribe(tribe)`.


    takeTech
    tribe:takeTech(tech, collapse=false)

    Alias for `civ.takeTech(tribe, tech, collapse=false)`.


    The improvement object


    id (get)
    improvement.id -> integer

    Returns the id of the improvement.


    name (get)
    improvement.name -> string

    Returns the name of the improvement (e.g. "Barracks").


    prereq (get/set)
    improvement.prereq -> tech

    Returns the prerequisite tech of the improvement. Ephemeral.


    cost (get/set)
    improvement.cost -> integer

    Returns the cost of the improvement in rows. Multiply by civ.cosmic.shieldRows for the actual production cost. Ephemeral.


    cantSell (get/set)
    improvement.cantSell -> boolean

    Returns `true` if the improvement cannot be sold, `false` otherwise. Requires the "Improvement flags" patch. Ephemeral.


    onCapture (get/set)
    improvement.onCapture -> integer

    Returns what happens to this improvement when a city is captured (0 - Default, 1 - Preserve, 2 - Destroy, 3 - Random). Requires the "Improvement flags" patch. Ephemeral.



    The tech object


    id (get)
    tech.id -> integer

    Returns the id of the tech.


    name (get)
    tech.name -> string

    Returns the name of the tech.


    prereq1 (get/set)
    tech.prereq1 -> tech

    Returns the first prerequisite of the tech. Ephemeral.


    prereq2 (get/set)
    tech.prereq2 -> tech

    Returns the second prerequisite of the tech. Ephemeral.


    aiValue (get/set)
    tech.aiValue -> integer

    Returns the AI value of the tech. Ephemeral.


    modifier (get/set)
    tech.modifier -> integer

    Returns the modifier to the AI value based on leader personality. Ephemeral.


    epoch (get/set)
    tech.epoch -> integer

    Returns the epoch of the tech. Ephemeral.


    category (get/set)
    tech.category -> integer

    Returns the category of the tech. Ephemeral.


    group (get/set)
    tech.group -> integer

    Returns the group of the tech. Ephemeral.


    researched (get)
    tech.researched -> boolean

    Returns whether or not any tribe has researched the tech.


    The leader object


    id (get)
    leader.id -> integer

    Returns the id of the leader.


    name (get/set)
    leader.name -> string

    Returns the name of the leader.


    female (get/set)
    leader.female -> boolean

    Returns whether or not the leader is female.


    attack (get/set)
    leader.attack -> integer

    Returns the "attack" value of the leader's personality. Ephemeral.


    expand (get/set)
    leader.expand -> integer

    Returns the "expand" value of the leader's personality. Ephemeral.


    civilize (get/set)
    leader.civilize -> integer

    Returns the "civilize" value of the leader's personality. Ephemeral.


    color (get/set)
    leader.color -> integer

    Returns the leader's color. Ephemeral.


    cityStyle (get/set)
    leader.cityStyle -> integer

    Returns the leader's city style. Ephemeral.


    The cosmic object


    roadMultiplier (get/set)
    civ.cosmic.roadMultiplier -> integer

    Returns the road movement multiplier. Ephemeral.


    triremeLost (get/set)
    civ.cosmic.triremeLost -> integer

    Returns the 1 in x chance of a trireme getting lost at sea. Ephemeral.


    foodEaten (get/set)
    civ.cosmic.foodEaten -> integer

    Returns the amount of food eaten by each citizen each turn. Ephemeral.


    foodRows (get/set)
    civ.cosmic.foodRows -> integer

    Returns the number of rows in the food box. Ephemeral.


    shieldRows (get/set)
    civ.cosmic.shieldRows -> integer

    Returns the number of rows in the shield box. Ephemeral.


    settlersEatLow (get/set)
    civ.cosmic.settlersEatLow -> integer

    Returns the amount of food eaten by settlers for governments ≤ Monarchy. Ephemeral.


    settlersEatHigh (get/set)
    civ.cosmic.settlersEatHigh -> integer

    Returns the amount of food eaten by settlers for governments ≥ Communism. Ephemeral.


    sizeUnhappiness (get/set)
    civ.cosmic.sizeUnhappiness -> integer

    Returns the city size at which the first unhappy citizen appears at Chieftain difficulty. Ephemeral.


    riotFactor (get/set)
    civ.cosmic.riotFactor -> integer

    Returns the riot factor based on the number of cities. Ephemeral.


    sizeAquaduct (get/set)
    civ.cosmic.sizeAquaduct -> integer

    Returns the city size that cannot be exceeded without an Aquaduct. Ephemeral.


    sizeSewer (get/set)
    civ.cosmic.sizeSewer -> integer

    Returns the city size that cannot be exceeded without a Sewer System. Ephemeral.


    techParadigm (get/set)
    civ.cosmic.techParadigm -> integer

    Returns the tech paradigm. Scenarios use civ.scen.params.techParadigm instead of this value. Ephemeral.


    transformBase (get/set)
    civ.cosmic.transformBase -> integer

    Returns the base time needed for engineers to transform terrain. Ephemeral.


    supportMonarchy (get/set)
    civ.cosmic.supportMonarchy -> integer

    Returns the number of units that are free of support under Monarchy. Ephemeral.


    supportCommunism (get/set)
    civ.cosmic.supportCommunism -> integer

    Returns the number of units that are free of support under Communism. Ephemeral.


    supportMonarchy (get/set)
    civ.cosmic.supportMonarchy -> integer

    Returns the number of units that are free of support under Monarchy. Ephemeral.


    supportFundamentalism (get/set)
    civ.cosmic.supportFundamentalism -> integer

    Returns the number of units that are free of support costs under Fundamentalism. Ephemeral.


    communismPalaceDistance (get/set)
    civ.cosmic.communismPalaceDistance -> integer

    Returns the distance from palace used in happiness calculations under Communism. Ephemeral.


    scienceLostFundamentalism (get/set)
    civ.cosmic.scienceLostFundamentalism -> integer

    Returns the percentage of science lost under Fundamentalism. Ephemeral.


    prodChangePenalty (get/set)
    civ.cosmic.prodChangePenalty -> integer

    Returns the shield penalty percentage for changing production types. Ephemeral.


    paradropRange (get/set)
    civ.cosmic.paradropRange -> integer

    Returns the maximum paradrop range. Ephemeral.


    massThrustParadigm (get/set)
    civ.cosmic.massThrustParadigm -> integer

    Returns the mass/thrust paradigm. Ephemeral.


    scienceRateFundamentalism (get/set)
    civ.cosmic.scienceRateFundamentalism -> integer

    Returns the maximum effective science rate under Fundamentalism. Ephemeral.


    scoreCitizen (get/set)
    civ.cosmic.scoreCitizen -> integer

    Returns the civilization score for each citizen. Ephemeral.


    scoreWonder (get/set)
    civ.cosmic.scoreWonder -> integer

    Returns the civilization score for each wonder. Ephemeral.


    scoreCentauri (get/set)
    civ.cosmic.scoreCentauri -> integer

    Returns the civilization score for each landing on Alpha Centauri first. Multiplied by number of habitats and success probability. Ephemeral.


    scorePollution (get/set)
    civ.cosmic.scorePollution -> integer

    Returns the civilization score for each extant non-AI controlled polluted tile. Normally a negative value, i.e. a penalty. Ephemeral.


    scorePeace (get/set)
    civ.cosmic.scorePeace -> integer

    Returns the civilization score for each turn of peace after turn 199. Ephemeral.


    scoreFutureTech (get/set)
    civ.cosmic.scoreFutureTech -> integer

    Returns the civilization score for each future technology researched. Ephemeral.


    penaltyBetrayal (get/set)
    civ.cosmic.penaltyBetrayal -> integer

    Returns the penalty to the civilization score for each betrayal of another tribe. Ephemeral.


    scoreUnitKilled (get/set)
    civ.cosmic.scoreUnitKilled -> integer

    Returns the civilization score for each unit killed. Ephemeral.


    goodieHutsMask (get/set)
    civ.cosmic.goodieHutsMask -> integer

    Returns the bitmask for goodie huts. Ephemeral.


    helisPickupHuts (get/set)
    civ.cosmic.helisPickupHuts -> integer

    Returns whether helicopters (domain 1, range 0 units) pick up huts or not. Ephemeral.


    numberOfUnitTypes (get)
    civ.cosmic.numberOfUnitTypes -> integer

    Returns the number of unit types from the @COSMIC2 key of the same name.


    The game object


    turnsElapsed (get/set)
    civ.game.turnsElapsed -> integer

    Returns the number of turns elapsed.


    gameYear (get/set)
    civ.game.turnsElapsed -> integer

    Returns the game year, or for scenarios with monthly increments, the number of months * 12.


    humanTribe (get)
    civ.game.humanTribe -> tribe

    Returns the last active human tribe.


    revealMap (get/set)
    civ.game.revealMap -> boolean

    Returns whether or not the full map is revealed.


    difficulty (get/set)
    civ.game.difficulty -> integer

    Returns the difficulty level.


    barbarianActivity (get/set)
    civ.game.barbarianActivity -> integer

    Returns the level of barbarian activity.


    activeTribes (get/set)
    civ.game.activeTribes -> integer

    Returns the active tribe mask.


    humanPlayers (get/set)
    civ.game.humanPlayers -> integer

    Returns the human players mask.


    peaceTurns (get/set)
    civ.game.peaceTurns -> integer

    Returns the number of turns of peace.


    The wonder object


    id (get)
    wonder.id -> integer

    Returns the id of the wonder.


    name (get)
    wonder.name -> string

    Returns the name of the wonder.


    city (get/set)
    wonder.city -> city

    Returns the city that has built the wonder, `nil` if not built yet or destroyed.


    destroyed (get)
    wonder.destroyed -> boolean

    Returns whether or not the wonder is destroyed. Use wonder:destroy() to set this field.


    prereq (get/set)
    wonder.prereq -> tech

    Returns the prerequisite technology of the wonder. Ephemeral.


    cost (get/set)
    wonder.cost -> integer

    Returns the cost of the wonder. Ephemeral.


    expires (get/set)
    wonder.expires -> tech

    Returns the tech that renders the wonder obsolete, or `nil` if there isn't any. Ephemeral.


    destroy
    wonder:destroy()

    Alias for `civ.destroyWonder(wonder)`.


    The spaceship object



    The dialog object


    title (get/set)
    dialog.title -> string

    Returns the title of the dialog.


    width (get/set)
    dialog.width -> integer

    Returns the width of the dialog.


    height (get/set)
    dialog.height -> integer

    Returns the height of the dialog. Normally this does not need to be set, since the height is automatically calculated from the height of the items.


    addText
    dialog:addText(string)

    Adds a static text string to the dialog.


    addOption
    dialog:addOption(string, id)

    Adds a selectable option to the dialog, with label given by `string`. `id` is an integer value returned by dialog:show if this option was selected. Can not be used in conjunction with dialog:addCheckbox.


    addCheckbox
    dialog:addCheckbox(string, id, initial=false)

    Adds a checkbox to the dialog, with label given by `string`. `id` is an integer value that can be used in dialog:getCheckboxState to retrieve the state after calling dialog:show. `initial` is an optional boolean parameter, if set to `true` the checkbox will be checked initially. Can not be used in conjunction with dialog:addOption.


    getCheckboxState
    dialog:getCheckboxState(id) -> boolean

    Returns the state of the checkbox identified by `id` after dialog:show has been called.


    show
    dialog:show() -> integer

    Renders the dialog on screen. If this is an option dialog, returns the id of the selected option (see dialog:addOption). If this is a checkbox dialog, returns 0 if OK was pressed, -1 if Exit was pressed. Use dialog:getCheckboxState to query the individual checkboxes.
    This method can only be called once per dialog. It will return an error if invoked a second time.

    Example:
    Code:
    dialog = civ.ui.createDialog()
    dialog.title = "My first dialog"
    dialog.width = 250
    dialog:addOption("Foo", 1)
    dialog:addOption("Bar", 2)
    dialog:show()
    

    The scenario library


    onTurn
    civ.scen.onTurn(function (turn) -> void)


    onUnitKilled
    civ.scen.onUnitKilled(function (defender, attacker) -> void)


    onScenarioLoaded
    civ.scen.onScenarioLoaded(function () -> void)


    onNegotiation
    civ.scen.onNegotiation(function (talker, listener) -> boolean)


    onSchism
    civ.scen.onSchism(function (tribe) -> boolean)


    onCityTaken
    civ.scen.onCityTaken(function (city, defender) -> void)


    onCityProduction
    civ.scen.onCityProduction(function (city, prod) -> void)


    onCentauriArrival
    civ.scen.onCentauriArrival(function (tribe) -> void)


    onCityDestroyed
    civ.scen.onCityDestroyed(function (city) -> void)


    onBribeUnit
    civ.scen.onBribeUnit(function (unit, previousOwner) -> void)


    onGameEnds
    civ.scen.onGameEnds(function (reason) -> boolean)


    onKeyPress
    civ.scen.onKeyPress(function (keyCode) -> void)

    Registers a function to be called every time a key is pressed.

    onActivateUnit
    civ.scen.onActivateUnit(function (unit, source) -> void)

    Registers a function to be called every time a unit is activated. The callback takes the unit activated as a parameter, and the source of unit activation. Source is `true` if activated by keyboard or mouse click, `false` if activated by the game itself.

    onCityFounded
    civ.scen.onCityFounded(function (city) -> void)

    Registers a function to be called every time a city is founded. The callback takes the city as a parameter.

    onResolveCombat
    civ.scen.onResolveCombat(function (defaultResolutionFunction, attacker, defender) -> boolean)

    Registers a function to be called during every combat turn. The first parameter of the callback is the default resolution function, as implemented by the game. It takes the attacker and defender as parameters. You can call this to produce a result for cases you don't need to handle yourself.
    Return `true` to continue combat, `false` to stop.

    onCanBuild
    civ.scen.onCanBuild(function (defaultBuildFunction, city, item) -> boolean)

    Registers a function to be called every time a check is done whether a city can build something or not. It is called for all unit types, improvements and wonders. The first parameter of the callback is the default build function, as implemented by the game. It takes the city and item as parameters. You can call this to produce a result for cases you don't need to handle yourself. `item` can be a unittype, improvement or wonder.
    Return `true` if `city` is allowed to produce `item`, `false` if not.


    The totpp library


    The `totpp` library is available for individual ToTPP patches to register sub-libraries in, to allow interacting with them from the game.


    totpp.movementMultipliers (provided by the Movement multipliers patch)


    road (get/set)
    totpp.movementMultipliers.road -> integer

    Returns the road movement multiplier if it is set, `nil` otherwise. Ephemeral.

    railroad (get/set)
    totpp.movementMultipliers.railroad -> integer

    Returns the railroad movement multiplier if it is set, `nil` otherwise. Ephemeral.

    alpine (get/set)
    totpp.movementMultipliers.alpine -> integer

    Returns the alpine movement multiplier if it is set, `nil` otherwise. Ephemeral.

    river (get/set)
    totpp.movementMultipliers.river -> integer

    Returns the river movement multiplier if it is set, `nil` otherwise. Ephemeral.

    aggregate (get)
    totpp.movementMultipliers.aggregate -> integer

    Returns the aggregate movement multiplier (the lcm of the four multipliers above). This value is recalculated when setting any of the individual multipliers. This is an alias for `civ.cosmic.roadMultiplier`.
     
    Last edited: Apr 22, 2018
    Civinator and JPetroski like this.
  2. McMonkey

    McMonkey ----Evertonian---- SLeague Staff

    Joined:
    May 9, 2005
    Messages:
    2,876
    Location:
    Cardiff
    Just printed this off to have a proper study. Is there any possibility of posting a small example of an event file with a few basic events so I can get my head around how it would be laid out? For example the Macro events always start @BEGINEVENTS. Does Lua have similar rules? Once I have an example to reverse engineer from I should be able to work the rest out and do some testing.

    EDIT: Just seen this in Tootal's guide. Will take a look now: Examples and documentation on writing events be found in `Scifi\events.lua' and 'lua\migrating events to lua.txt', both distributed with the project. For more documentation, see the civfanatics forums.
     
  3. Grishnach

    Grishnach Chieftain

    Joined:
    May 15, 2006
    Messages:
    51
    TNO, one comment from my side: as far as I've seen "unit" also has a method "owner" to get the tribe number owning the unit (now that I think about it I did not test if it can also be used to set the information ...) - in case you get around to continuing this great reference, perhaps you can add it for completion?

    And a more general question - would it be possible to get a generic "hex read/write" functionality? Like, for each of the object there is a method "Byte(i)" where the i'th byte after the beginning of the structure can be read (and preferbly set)? That's of course a very dangerous tool and one would have to know very well what one is doing ... but it would provide massive flexibility without you having to create additional interfaces (for example I'd love to be able to read the number of specialists in a city or the number of trade arrows etc - e.g. from Catfishs save game format I have an idea how to hex edit ist, but it would open extreme possibilities to get this information into lua events...)
     
  4. PlutonianEmpire

    PlutonianEmpire Socially Awkward Goofball

    Joined:
    Mar 11, 2004
    Messages:
    4,773
    Gender:
    Male
    Location:
    MinneSNOWta
    Has anyone been able to complete this list in their own research/time? :)
     
  5. PlutonianEmpire

    PlutonianEmpire Socially Awkward Goofball

    Joined:
    Mar 11, 2004
    Messages:
    4,773
    Gender:
    Male
    Location:
    MinneSNOWta
    In the civ.ui library, how do the redrawMap and redrawTile work?
     
  6. KathleenArgent

    KathleenArgent Chieftain

    Joined:
    Mar 7, 2018
    Messages:
    11
    Gender:
    Female
    Wait a minute - so I can build a function such that if the item is unittype.name=="Cavalry" and the city.improvements do not contain, say improvement 5(="Stables") then it returns false, else return defaultBuildFunction?
    So I can couple the possibility to build certain items to arbitrary conditions?

    And if one manages to create a data structure which checks if the city tile is connected by roads to a certain special resource, then one could also build that into the condition? ie the CivX (X larger then 2) special resource mechanic is possible in principle?
    :eek::eek::eek:
     
  7. TheNamelessOne

    TheNamelessOne Chieftain

    Joined:
    Dec 18, 2013
    Messages:
    196
    Absolutely.

    If one would be so inclined, definitely.
     
    Knighttime likes this.
  8. Knighttime

    Knighttime Chieftain

    Joined:
    Sep 20, 2002
    Messages:
    103
    Has anyone had success working with this function yet? Or perhaps, TheNamelessOne (if you have a moment), could you explain your vision behind why this was added, and how you expect it to be used?

    In my testing, it seems first of all that the "attacker" and "defender" parameters are reversed -- the first unit seems to be the defending one.

    But more importantly: it seems that this essentially runs after each combat round, and allows me to override the game's determination of whether or not the battle should continue into further rounds. Civ2's normal rule, of course, is that the battle should continue until one unit has 0 HP remaining.

    If only one unit has HP remaining, and I intercept the "false" result to return "true" instead, this seems to lead to an endless loop where Civ2 hangs or crashes, and I have to kill the process.

    If both units have HP remaining, I can intercept the "true" result to return "false" instead, which does seem to stop a battle prematurely -- although so far, it seems that one unit is still always destroyed. I haven't had instances where a battle ended with both units alive and with partial HP.

    I feel like this function is really close to being incredibly powerful and valuable, but unfortunately doesn't seem nearly as useful in its current form.

    One thing I was hoping I could do, is intercept the normal battle logic and block even the first round of combat from taking place -- in other words, intercepting an intended attack before the game had a chance to run or apply any damage calculations. I'd like to have Lua run some other code, and then return "false" to prevent the battle from beginning at all. The in-game behavior would be as if the attacking unit had never moved -- as if it attempted to move into an invalid or impassable tile.

    A second thing I was hoping I could do, is to evaluate the two units and break off a battle after a few combat rounds but before either unit was totally destroyed -- leaving both units alive, with one or both having reduced HP. I could then apply additional Lua commands causing one unit to retreat, for example (there are myriad other possibilities).

    Would something like what I'm proposing be possible? I'd welcome any discussion on this topic!
     
  9. Prof. Garfield

    Prof. Garfield Chieftain Supporter

    Joined:
    Mar 6, 2004
    Messages:
    2,163
    Location:
    Ontario
  10. Prof. Garfield

    Prof. Garfield Chieftain Supporter

    Joined:
    Mar 6, 2004
    Messages:
    2,163
    Location:
    Ontario
    I think this might run before the round of combat. In Over the Reich, we wanted to prevent bombs from killing aircraft on the ground at night (map 2). Under the correct conditions, this sets the bomb's hp to 0. If it happened after the combat round, then bombs would still sometimes do damage to the unit they are attacking. However, in my tests the defending unit always had full hp at the end of combat.

    Code:
    local function combatResolutionFunction(defaultResolutionFunction,defender,attacker)
        if attacker.location.z == 2 then
            local aType = attacker.type
            local dType = defender.type
            if (aType == unitAliases.TwoHundredFiftylb or aType == unitAliases.FiveHundredlb
                or aType == unitAliases.Thousandlb) and not(dType == unitAliases.SpecialTarget
                or dType == unitAliases.Urban1 or dType == unitAliases.Urban2
                or dType == unitAliases.Urban3) then
                attacker.damage = attacker.type.hitpoints
                return false
            end
        end
        return defaultResolutionFunction(attacker,defender)
    end
    
    civ.scen.onResolveCombat(combatResolutionFunction)
    
    
    It looks like we could pretty easily have any combat calculation we like as long as a unit dies at the end. Perform the calculation, set the damage to the attacker and defender, and return false. The unit with 0 hp dies, and the combat is complete.
     
  11. Knighttime

    Knighttime Chieftain

    Joined:
    Sep 20, 2002
    Messages:
    103
    Thanks for this update. It's been awhile, so I don't remember all of the ways in which I tested this, but I recall that at one point I simply set onResolveCombat() to do nothing except return false (meaning, don't continue the battle into another round), without calling defaultResolutionFunction() at all. Yet one unit still took damage and died while the other retained all its HP. I took that to mean that the game was running the first round of battle before I was able to intercept and block it, and the unit which lost that first round was the one which was destroyed. But it's entirely possible that I reached an incorrect conclusion, or that I didn't set up enough different tests to really understand what was happening. In my defense :) I'll just say that my main goal at the time wasn't really to rewrite the game's battle logic, but simply to see if I could get around the rule that "one unit has to die".

    Feel free to correct me if I'm mistaken here: I think that the way the game normally works, onResolveCombat() (or perhaps I should just say, the defaultResolutionFunction()since you don't need to use onResolveCombat() at all) is called separately for each round of a battle, and a single round results in one of the two units losing X HP, where X is equal to the FP of the other (winning) unit. The battle then continues into another round unless the losing unit has 0 HP remaining. In terms of probability, this multi-round battle system makes it much harder for a weaker unit to defeat a stronger unit. I've read that the Civ 2 developers implemented this system in order to improve on the way Civ 1 worked, where an ancient unit like a phalanx would sometimes defeat a modern tank. I'm only pointing this out because it sounds like you're proposing an approach which condenses the battle to only a single round, at least as far as the Civ 2 engine would know.

    I agree, though, that what you're proposing certainly seems possible -- and extensive efforts here could revolutionize battle within Civ 2 as we know it (some examples that have crossed my mind: custom bonuses or win probabilities depending on the specific matchup of unit types; new impacts for terrain types and/or improvements such as fortresses; revised or more nuanced effects for things like city walls and SAM batteries; revised impact of veteran status, or perhaps even another "tier" of veterancy such as "elite"; etc.). My only caution would be that in order to avoid falling back into the Civ 1 trap, it might be wise if "any combat calculation we like" still included multiple rounds of calculation internally, which would be aggregated into a single result. A loop within the code of onResolveCombat() could accomplish this easily enough.

    In the project I'm currently working on, I decided I could live with the results provided by defaultResolutionFunction(), so I set aside research and experimentation on this topic for the time being. But I'll certainly watch with interest to see what you're able to do here... I do think there's a lot of potential. My previous comment to TNO ("I feel like this function is really close to being incredibly powerful and valuable, but unfortunately doesn't seem nearly as useful in its current form.") was probably far too negative. :)
     
    Last edited: May 22, 2019

Share This Page