Module City

This library contains functions to access and modfiy city information, general buildings and roads.

Functions

alert (actionPlaceType, x, y) Sets an action marker (or removes the one previously set there).
canSpend (amount) Returns true if the specified amount of money can be spend by the city.
countBuildings ([draft]) Returns the overall amount of buildings.
countBuildingsOfType (type[, level]) Returns the number of buildings of a specific building type.
countCars () Returns number of cars that are active right now.
countRoads ([draft]) Returns the overall amount of roads.
earnCurrency (name, amount) Earns amount of the currency named name.
earnMoney (amount[, x[, y[, showOverlay=false[, budgetItem]]]]) Earns some money.
enableDisaster (name[, state]) Enables or disables the automatic disaster of the given name.
execute (cmd, receiver) Executes a command as if it was entered into the console.
exit ([save=false]) Closes the current city and will go back to region view.
getAbsoluteDay () Returns the current absolute day of the city.
getAuthor () Returns the name of the author that the player entered
getBackground () Returns the current background draft of the city.
getBuilding (index[, draft]) Gets the position of a specific building of a specific draft by it's index.
getCommercialJobs ([level[, progress=false]]) Returns the total commercial jobs per level.
getCurrency (name) Returns the available amount of the currency of the given name.
getDay () Returns the current day of the month of the city.
getDayPart () Returns the current part of the day with 0 being the start and 1 being the end.
getDisaster () Returns the name of the curretly active disaster or nil if no disaster is is active right now.
getFileName () Returns the name of the file of the city.
getFunVar (name[, fallbackValue]) Returns the value of the classic fun variable of the given name or fallbackValue if no such variable has been defined, yet.
getHappiness ([happinessType]) Returns the average happiness.
getHeight () Height of the city in tiles
getIncome () Returns the monthly income of the city.
getIndustrialJobs ([level[, progress=false]]) Returns the total industrial jobs per level.
getMoney () Returns the estate of the city.
getMonth () Returns the current month of the city.
getName () Name of the current city
getOwnerId () Returns the id of the owner of the city if the city is online.
getOwnerName () Returns the name of the owner of the city if the city is online.
getPeople (level) Returns the number of the specified level (0, 1 or 2).
getPlayTime () Returns the play time in this city in seconds.
getRank () Returns the current rank draft and the rank index.
getRegionId () Returns the id of the region or nil if the city is not in a region.
getRegionName () Returns the name of the region this city is located in.
getResidentialSpace ([level[, progress=false]]) Returns the residential space (in buildings) per level.
getRoad (index[, draft]) Gets the position and level of a specific road (of a specific draft) by it's index.
getRotation () Returns the current rotation of the city.
getSeed () Returns the seed that was used to generate the city
getSpeed () Returns the current simulation speed of the city.
getStorage () Use this storage table to save things city wide
getTime () Returns the animation time of the game in milliseconds.
getView () Returns the tile position the camera is currently looking at as well as the current scale.
getWidth () Width of the city in tiles
getXp () Returns the amount of xp of the city.
getYear () Returns the current year of the city.
isOnline () Indicates whether this city is an online city.
isReadonly () Indicates whether this city is readonly.
isSandbox () Determines whether the city is in free or sandbox mode
isUber () Returns true if uber is activated for that city.
issueDisaster (name[, x=-1[, y=-1[, radius=20[, radioactive=true]]]]) Issues the disaster of the given name at the given position x, y.
load (path[, overwrite[, private[, target]]]) Loads a city file provided by the plugin.
noise (x, y[, z[, w]]) Returns a noise value for the specified coordinates.
playSound (sound, x, y[, volume=1[, loop=false]]) Plays a sound.
save ([enforce=false]) Saves the city if the user has autosave enabled.
setAuthor (name) Sets a new author name for the city.
setBackground (draft) Sets a background.
setFunVar (name, value) Sets the value of a classic fun variable called name.
setName (newName) Sets a new city name
setRotation (r) Sets the rotation of the city
setSpeed (speed) Sets the simulation speed of the city.
setView (x, y[, scale]) Sets the view to a specified tile x, y using the provided scale.
setXp (xp) Sets the amount of xp of the city.
showNotification (tableOfArguments) Shows a notification.
spawnCar (carDraft, startX, startY, targetX, targetY[, frame]) Spawns a car at a given position / position of a building that drives to the given target / building at the target.
spendCurrency (name, amount) Spends amount of the currency named name.
spendMoney (amount[, x[, y[, budgetItem]]]) Spends some money.

Fields

ACTIONPLACE_FIRE Action place for fire alerts.
ACTIONPLACE_GARBAGE Action place for garbage alerts.
ACTIONPLACE_MEDIC Action place for medic alerts.
ACTIONPLACE_POLICE Action place for police alerts.
ACTIONPLACE_SWAT Action place for swat alerts.
DISASTER_BLIZZARD Identifier for blizzard disaster.
DISASTER_CRIME Identifier for crime disaster.
DISASTER_EARTHQUAKE Identifier for earthquake disaster.
DISASTER_FIRE Identifier for fire disaster.
DISASTER_FLOODING Identifier for flooding disaster.
DISASTER_GREEN_SLIME Identifier for green slime disaster.
DISASTER_ILLNESS Identifier for illness disaster.
DISASTER_METEOR Identifier for meteorite disaster.
DISASTER_NUKE Identifier for nuke disaster.
DISASTER_PINK_SLIME Identifier for pink slime disaster.
DISASTER_RIOT Identifier for riot disaster.
DISASTER_TORNADO Identifier for tornado disaster.
DISASTER_UFO Identifier for ufo disaster.
HAPPINESS_EDUCATION Name of education happiness
HAPPINESS_ENVIRONMENT Name of environment happiness
HAPPINESS_FIREDEPARTMENT Name of fire deparment happiness
HAPPINESS_FREETIME Name of free time happiness
HAPPINESS_GENERAL Name of general happiness
HAPPINESS_HEALTH Name of health happiness
HAPPINESS_LEVEL Name of level happiness.
HAPPINESS_PARK Name of park happiness
HAPPINESS_POLICE Name of police happiness
HAPPINESS_RELIGION Name of religion happiness
HAPPINESS_SPORT Name of sport happiness
HAPPINESS_SUPPLY Name of supply happiness
HAPPINESS_TAXES Name of taxes happiness
HAPPINESS_TRANSPORT Name of transport happiness
HAPPINESS_WASTE Name of waste happiness
HAPPINESS_ZONE Name of zone happiness.


Functions

alert (actionPlaceType, x, y)
Sets an action marker (or removes the one previously set there).

Parameters:

  • actionPlaceType integer
  • x integer
  • y integer
canSpend (amount)
Returns true if the specified amount of money can be spend by the city.

Parameters:

  • amount number The amount to query whether it can be spent.
countBuildings ([draft])
Returns the overall amount of buildings. Optionally of a specific draft. This can for example be used to iterate over all buildings of a draft by using City.getBuilding(index, draft).

Parameters:

  • draft draft A building draft. (optional)

Returns:

    number Amount of buildings.
countBuildingsOfType (type[, level])
Returns the number of buildings of a specific building type.

Parameters:

  • type string The building type to count. Can be one of "residential", "commercial", "industrial", "farm", "harbor ind", "harbor pier", "park", "sport", "public", "religion", "award", "energy", "water", "medic", "police", "swat", "fire brigade", "education", "bus depot", "destroyed", "decoratoin", "buoy", "railway station", "waste disposal", "body disposal", "military", "airport", "terrain", "landmark" or "building" (this one being a placeholder).
  • level number The level the buildings should have. If not specified the level of the buildings is ignored. Level 0 would be first level. (optional)

Returns:

    number The number of buildings of the specified type (and level).
countCars ()
Returns number of cars that are active right now. This includes operatonal cars and trains.

Returns:

    number Cars in the city.
countRoads ([draft])
Returns the overall amount of roads. Optionally of a specific draft. This can for example be used to iterate over all roads (of a draft) by using City.getRoad(index, draft).

Parameters:

  • draft draft A road draft. (optional)

Returns:

    number Amount of roads.
earnCurrency (name, amount)
Earns amount of the currency named name. Requires privileged rights.

Parameters:

  • name string
  • amount number
earnMoney (amount[, x[, y[, showOverlay=false[, budgetItem]]]])
Earns some money. If x, y is provided (and >= 0) then the money will be drawn as if it was earned at the provided place (green text). If showOverlay is true and overlay for the money will be shown (default is false). Requires privileged rights.

Parameters:

  • amount number
  • x number (optional)
  • y number (optional)
  • showOverlay bool (default false)
  • budgetItem draft (optional)
enableDisaster (name[, state])
Enables or disables the automatic disaster of the given name.

Parameters:

  • name string
  • state bool true by default. (optional)
execute (cmd, receiver)
Executes a command as if it was entered into the console.

Parameters:

  • cmd string The command to execute.
  • receiver function A function with one parameter that will be called for any feedback.
exit ([save=false])
Closes the current city and will go back to region view.

Parameters:

  • save bool Whether to save the city before exiting it. (default false)
getAbsoluteDay ()
Returns the current absolute day of the city.

Returns:

    number
getAuthor ()
Returns the name of the author that the player entered

Returns:

    string
getBackground ()
Returns the current background draft of the city.

Returns:

    draft
getBuilding (index[, draft])
Gets the position of a specific building of a specific draft by it's index. The index starts with 1 and ranges up to City.countBuildings(draft).

Parameters:

  • index number Index of the building, starting with 1.
  • draft draft (optional)

Returns:

    number, number
getCommercialJobs ([level[, progress=false]])
Returns the total commercial jobs per level.

Parameters:

  • level number The level, 0, 1 or 2. If no level is provided the sum of all levels will be used. (optional)
  • progress bool If true, buildings that are in building process will be included. (default false)

Returns:

    number Amount of total commercial jobs.
getCurrency (name)
Returns the available amount of the currency of the given name. E.g. City.getCurreny('bus currency')

Parameters:

  • name string

Returns:

    number, string
getDay ()
Returns the current day of the month of the city. The value ranges from 1 to 30.

Returns:

    number
getDayPart ()
Returns the current part of the day with 0 being the start and 1 being the end. You can use City.getDay() + City.getDayPart() as a game speed dependent time source that does not wrap around like City.getTime() does.

Returns:

    number
getDisaster ()
Returns the name of the curretly active disaster or nil if no disaster is is active right now.

Returns:

    string
getFileName ()
Returns the name of the file of the city.

Returns:

    string
getFunVar (name[, fallbackValue])
Returns the value of the classic fun variable of the given name or fallbackValue if no such variable has been defined, yet. fallbackValue is 0 by default. Note that fun variables can only contain numbers. Use City.getStorage() or TheoTown.getStorage() to store more fancy stuff. Global fun variables are indicated by a leading ! in it's name.

Parameters:

  • name string
  • fallbackValue number (optional)

Returns:

    number
getHappiness ([happinessType])
Returns the average happiness.

Parameters:

  • happinessType string Type of a happiness, e.g. City.HAPPINESS_PARK. If not provided the general happiness will be returned. Be cautious, the calculcation for a specific type can be time consuming and should not be done every frame. (optional)

Returns:

    number 0..1 with 1 being happy

Usage:

    City.getHappiness(City.HAPPINESS_PARK)
getHeight ()
Height of the city in tiles

Returns:

    number
getIncome ()
Returns the monthly income of the city.

Returns:

    number Income of the city in Theons.
getIndustrialJobs ([level[, progress=false]])
Returns the total industrial jobs per level.

Parameters:

  • level number The level, 0, 1 or 2. If no level is provided the sum of all levels will be used. (optional)
  • progress bool If true, buildings that are in building process will be included. (default false)

Returns:

    number Amount of total residential jobs.
getMoney ()
Returns the estate of the city.

Returns:

    number The money of the city in Theon.
getMonth ()
Returns the current month of the city. The value ranges from 1 to 12.

Returns:

    number
getName ()
Name of the current city

Returns:

    string
getOwnerId ()
Returns the id of the owner of the city if the city is online.

Returns:

    string
getOwnerName ()
Returns the name of the owner of the city if the city is online.

Returns:

    string
getPeople (level)
Returns the number of the specified level (0, 1 or 2). Returns the number of all people if no level was specified.

Parameters:

  • level number optional

Returns:

    number
getPlayTime ()
Returns the play time in this city in seconds.

Returns:

    number Time in seconds.
getRank ()
Returns the current rank draft and the rank index.

Returns:

  1. draft The rank draft of the city.
  2. number Index of the rank, starts with 0 for the first one.
getRegionId ()
Returns the id of the region or nil if the city is not in a region. The id of a reqion is (in theory) unique. For online regions it is just a number.

Returns:

    string The id of the region or nil.
getRegionName ()
Returns the name of the region this city is located in. Returns nil for for individual cities.

Returns:

    string Name of the region or nil.
getResidentialSpace ([level[, progress=false]])
Returns the residential space (in buildings) per level.

Parameters:

  • level number The level, 0, 1 or 2. If no level is provided the sum of all levels will be used. (optional)
  • progress bool If true, buildings that are in building process will be included. (default false)

Returns:

    number Amount of residential space (unit is people).
getRoad (index[, draft])
Gets the position and level of a specific road (of a specific draft) by it's index.

Parameters:

  • index number
  • draft draft (optional)

Returns:

  1. number X location
  2. number Y location
  3. number Level
getRotation ()
Returns the current rotation of the city. City rotation is expressed with an integer number 0 (unrotated), ..., 3

Returns:

    number {0, 1, 2, 3}
getSeed ()
Returns the seed that was used to generate the city

Returns:

    string
getSpeed ()
Returns the current simulation speed of the city.

Returns:

    number The speed value.

See also:

getStorage ()
Use this storage table to save things city wide

Returns:

    table
getTime ()
Returns the animation time of the game in milliseconds.

Returns:

    number
getView ()
Returns the tile position the camera is currently looking at as well as the current scale. Format: x, y, scale

Returns:

    number,number,number
getWidth ()
Width of the city in tiles

Returns:

    number
getXp ()
Returns the amount of xp of the city.

Returns:

    integer
getYear ()
Returns the current year of the city. The value starts at 1.

Returns:

    number
isOnline ()
Indicates whether this city is an online city.

Returns:

    bool True iff the city is online
isReadonly ()
Indicates whether this city is readonly. Cities that are readonly can not be saved. For example foreign cities in online regions are read only.

Returns:

    bool True iff the city is readonly
isSandbox ()
Determines whether the city is in free or sandbox mode

Returns:

    bool
isUber ()
Returns true if uber is activated for that city.

Returns:

    true iff city is uber
issueDisaster (name[, x=-1[, y=-1[, radius=20[, radioactive=true]]]])
Issues the disaster of the given name at the given position x, y. Returns true iff disaster was issued successfully.

Parameters:

  • name string The name of a disaster, e.g. City.DISASTER_FIRE
  • x number X position. Random by default. (default -1)
  • y number Y position. Random by default. (default -1)
  • radius number Radius for nuke disaster. (default 20)
  • radioactive bool Radioactivity for nuke disaster. (default true)

Returns:

    bool

Usage:

    function script:earlyTap(x, y)
      City.issueDisaster(City.DISASTER_RIOT, x + 1, y)
      City.issueDisaster(City.DISASTER_RIOT, x - 1, y)
      City.issueDisaster(City.DISASTER_RIOT, x, y + 1)
      City.issueDisaster(City.DISASTER_RIOT, x, y - 1)
      City.issueDisaster(City.DISASTER_FIRE, x, y)
      return false -- Prevent it from open dialog for the tile
    end
    
load (path[, overwrite[, private[, target]]])
Loads a city file provided by the plugin. path is the file of the city file (thus it includes the .city file ending). Prior to loading the city will be copied to maps or private maps folder first (depending on private value). If a city of similar file name already exists at that directory it will be overridden if overwrite flag is set. The target file name can be changed by specifieing a target name.

Parameters:

  • path string
  • overwrite bool (optional)
  • private bool (optional)
  • target string (optional)
noise (x, y[, z[, w]])
Returns a noise value for the specified coordinates.

Parameters:

  • x number
  • y number
  • z number (optional)
  • w number (optional)

Returns:

    number Ranges from -1 to 1
playSound (sound, x, y[, volume=1[, loop=false]])
Plays a sound.

Parameters:

  • sound draft A sound draft or id of a sound draft.
  • x integer X coordinate of the sound's origin tile.
  • y integer Y coordinate of the sound's origin tile.
  • volume number A value between 0 and 1. (default 1)
  • loop boolean Whether or not to loop the sound. (default false)

Returns:

    table A table that contains functions to control the sound.
save ([enforce=false])
Saves the city if the user has autosave enabled. If enforce is set the city will even be saved if the user has autosave disabled.

Parameters:

  • enforce bool Whether to enforce saving. (default false)
setAuthor (name)
Sets a new author name for the city.

Parameters:

  • name string Name of the author
setBackground (draft)
Sets a background.

Parameters:

  • draft draft An animation draft or it's id as a string. Use nil to set default background.
setFunVar (name, value)
Sets the value of a classic fun variable called name. Note that fun variables can only contain numbers. Use City.getStorage() or TheoTown.getStorage() to store more fancy stuff. Global fun variables are indicated by a leading ! in it's name.

Parameters:

setName (newName)
Sets a new city name

Parameters:

  • newName string
setRotation (r)
Sets the rotation of the city

Parameters:

  • r

Returns:

    number {0, 1, 2, 3}
setSpeed (speed)
Sets the simulation speed of the city. The following values are allowed:

0 for paused

1 for slow

2 for normal

3 for fast

4 for ultra fast

Parameters:

  • speed number One of the values above.

See also:

setView (x, y[, scale])
Sets the view to a specified tile x, y using the provided scale. If no scale is provided the current scale will be used. Scale 1 means no scaling, 2 times scaling etc.

Parameters:

  • x number
  • y number
  • scale number (optional)
setXp (xp)
Sets the amount of xp of the city.

Parameters:

  • xp integer
showNotification (tableOfArguments)
Shows a notification. See here for an example.

Parameters:

  • tableOfArguments table A table that contains all of the arguments that should be used for the notification.

Usage:

    City.showNotification{
    
      -- Image for the notification, can be extracted from a draft using :getFrame
      icon = frameDraft:getFrame(1),
    
      -- Text of the notification
      text = 'hi',
    
    
      -- All of the following attributes are optional...
    
      -- Title in case of an immersive notification
      title = 'Title of the window',
    
      -- Whether to draw it with a red background (default: false)
      important = true,
    
      -- Whether to offer yes and no buttons (default: false)
      question = true,
    
      -- Whether to offer an 'ok' button (default: value of question)
      optionOk = true,
    
      -- Whether to offer a close/cancel button (default: true)
      closeable = true,
    
      -- If defined: offer a location button that will jump to that location
      locationX = 42, locationY = 42,
    
      -- If true: shows the notification as a dialog (default: false)
      immersive = false,
    
      -- Will be called if the ok button was pressed
      onOk = function() Debug.toast('Ok') end,
    
      -- Will be called if the cancel button was pressed
      onCancel = function() Debug.toast('Cancel') end,
    
      -- Will be called if the notification was closed without a button press
      onClose = function() Debug.toast('Closed') end,
    
      -- A new feature of version 1.8.78 that allows to add own buttons
      actions = {
        {
          -- Image for the button
          icon = frameDraft:getFrame(2),
          -- Will be called when button is pressed
          onClick = function() Debug.toast('Triangle was clicked') end
        },
        {
          icon = frameDraft:getFrame(3),
          onClick = function() Debug.toast('Circle was clicked') end
        },
        {
          icon = frameDraft:getFrame(4),
          onClick = function() Debug.toast('Cross was clicked') end
        }
      }
    }
    
spawnCar (carDraft, startX, startY, targetX, targetY[, frame])
Spawns a car at a given position / position of a building that drives to the given target / building at the target. The car will actually not spawned immediately but after a path has been calculated. This happens asynchronously since path calculation is heavy on computation. You can provide a frame to determine the actualy type of the car. It will be random by default.

Parameters:

  • carDraft draft
  • startX number
  • startY number
  • targetX number
  • targetY number
  • frame number (optional)
spendCurrency (name, amount)
Spends amount of the currency named name.

Parameters:

  • name string
  • amount number
spendMoney (amount[, x[, y[, budgetItem]]])
Spends some money. If x, y is specified it will show a red price at that location.

Parameters:

  • amount number
  • x number (optional)
  • y number (optional)
  • budgetItem draft (optional)

Fields

ACTIONPLACE_FIRE
Action place for fire alerts. Used for action place markers.
ACTIONPLACE_GARBAGE
Action place for garbage alerts.
ACTIONPLACE_MEDIC
Action place for medic alerts.
ACTIONPLACE_POLICE
Action place for police alerts.
ACTIONPLACE_SWAT
Action place for swat alerts.
DISASTER_BLIZZARD
Identifier for blizzard disaster.
DISASTER_CRIME
Identifier for crime disaster.
DISASTER_EARTHQUAKE
Identifier for earthquake disaster.
DISASTER_FIRE
Identifier for fire disaster. Used by City.getDisaster and City.issueDisaster.
DISASTER_FLOODING
Identifier for flooding disaster.
DISASTER_GREEN_SLIME
Identifier for green slime disaster.
DISASTER_ILLNESS
Identifier for illness disaster.
DISASTER_METEOR
Identifier for meteorite disaster.
DISASTER_NUKE
Identifier for nuke disaster.
DISASTER_PINK_SLIME
Identifier for pink slime disaster.
DISASTER_RIOT
Identifier for riot disaster.
DISASTER_TORNADO
Identifier for tornado disaster.
DISASTER_UFO
Identifier for ufo disaster.
HAPPINESS_EDUCATION
Name of education happiness
HAPPINESS_ENVIRONMENT
Name of environment happiness
HAPPINESS_FIREDEPARTMENT
Name of fire deparment happiness
HAPPINESS_FREETIME
Name of free time happiness
HAPPINESS_GENERAL
Name of general happiness
HAPPINESS_HEALTH
Name of health happiness
HAPPINESS_LEVEL
Name of level happiness. This is a hidden happiness which means that it is used for internal calculcations, only.
HAPPINESS_PARK
Name of park happiness
HAPPINESS_POLICE
Name of police happiness
HAPPINESS_RELIGION
Name of religion happiness
HAPPINESS_SPORT
Name of sport happiness
HAPPINESS_SUPPLY
Name of supply happiness
HAPPINESS_TAXES
Name of taxes happiness
HAPPINESS_TRANSPORT
Name of transport happiness
HAPPINESS_WASTE
Name of waste happiness
HAPPINESS_ZONE
Name of zone happiness. This is a hidden happiness which means that it is used for internal calculcations, only.
generated by LDoc 1.4.3 Last updated 2020-11-25 06:27:19