Lua API

• Index

Contents

• Functions

Modules

• Array
• Builder
• Building
• Car
• City
• DSA
• Debug
• Draft
• Drawing
• GUI
• NeighborCity
• Runtime
• Script
• TheoTown
• Tile
• Util
• Vector
• string

Topics

• Introduction
• Lua

Module Building

Building library for TheoTown

A building is a representation object for single buildings in a city.

You can use it for convenience instead of using the building related functions in the Tile module directly.

Usage:

local building = Tile.getBuilding(x, y)
print('Building: '..building:getX()..', '..building:getY())

Functions

abandon ()	Abandons this (RCI) building.
extinguish ()	Extinguishes the fire of this building in case it's burning.
getAnimationColor ([slot=1])	Gets the color of an animation of the building.
getAnimationFrame ([slot=1])	Returns the current frame of an animation that is attached to this building.
getBuildHeight ()	Returns the height of the building.
getDaysBuilt ()	Returns the number of days since this building was constructed.
getDraft ()	Returns the draft of the building.
getDrawXY ()	Returns the draw pivot position of this building.
getFrame ()	Returns the current frame of the building.
getHeight ()	Returns the height of the base area of the building.
getIcon (x, y)	Gets a set custom building icon.
getId ()	Shortcut for the id of the building's draft.
getName ()	Gets the name of this building.
getPerformance ()	Returns the current performance of this building.
getStorage ()	Returns the storage table of the building.
getText ()	Returns the text set to the building.
getWidth ()	Returns the width of the base area of the building.
getX ()	Returns the x position of this building.
getXY ()	Returns the pivot position of this building.
getY ()	Returns the y position of this building.
hasNeededRoad ()	Returns true iff this building needs a road connection and also has a road connection.
hasRoad ()	Returns true iff this building has a road connection (even if it doesn't require one according to its json).
hasUpgrade (upgradeId)	Returns true iff this building has a specific upgrade applied to it.
isAnimationPaused ([slot=1])	Resumes an animation that is attached to this building.
isBurning ()	Returns true iff this building is burning right now.
isEmpty ()	Returns true iff this building is empty right now.
isFullOfDeadPeople ()	Returns true iff this building has transport issues with dead bodies right now.
isFullOfWaste ()	Returns true iff this building is full of garbage right now.
isIll ()	Returns true iff this building contains ill people right now.
isInConstruction ()	Returns true iff this building is in construction right now.
isUntouchable ()	Determines whether this (RCI) building is untouchable.
isUpgradeInConstruction ()	Returns true iff this building has a pending upgrade right now.
isWorking ()	Returns true iff this building is working right now.
pauseAnimation ([slot=1])	Pauses an animation that is attached to this building.
resumeAnimation ([slot=1[, speed=1.0]])	Resumes an animation that is attached to this building.
setAnimationColor (red, green, blue[, alpha=255[, slot=1]])	Sets the color of an animation of the building.
setAnimationFrame (frame[, slot=1])	Sets the current frame of an animation regardless of whether the animation is playing right now.
setFrame (frame)	Sets the current frame of the building.
setIcon (icon)	Sets a building icon.
setName (name)	Sets the name of this building.
setPerformance (performance)	Sets the performance of this building.
setText (text)	Sets a building text or resets it.
setUntouchable ([state=true])	Marks this (RCI) building as untouchable or touchable.

Functions

abandon ()

Abandons this (RCI) building. It will be empty afterwards.

extinguish ()

Extinguishes the fire of this building in case it's burning.

getAnimationColor ([slot=1])

Gets the color of an animation of the building. The default color is white which is expressed as 255,255,255,255.

New feature:

This is a new feature that was added in version 1.10.49

Parameters:

• slot int The index of the animation to pause. 1 is the first attached animation. (default 1)

Returns:

int,int,int,int or nil If the operation was successful the color is returned as four integer numbers.

getAnimationFrame ([slot=1])

Returns the current frame of an animation that is attached to this building.

Parameters:

• slot int The index of the animation to pause. 1 is the first attached animation. (default 1)

Returns:

int or nil The current frame of the animation or nil if something went wrong.

getBuildHeight ()

Returns the height of the building. Multiply by 8 to get an estimation for actual pixel height.

Returns:

int The building's height.

getDaysBuilt ()

Returns the number of days since this building was constructed. Negative values indicate non finished buildings.

Returns:

int Days since the building was built/completed.

getDraft ()

Returns the draft of the building.

Returns:

draft The draft object.

getDrawXY ()

Returns the draw pivot position of this building. You can use the result for use in Drawing.setTile() to get rotation independent drawing based on the building's left most point.

New feature:

This is a new feature that was added in version 1.11.09

Returns:

int,int X and Y component of the drawing tile position of the building.

getFrame ()

Returns the current frame of the building.

Returns:

int The index of the current frame.

getHeight ()

Returns the height of the base area of the building.

Returns:

int Height of the base area.

getIcon (x, y)

Gets a set custom building icon.

New feature:

This is a new feature that was added in version 1.11.61

Parameters:

• x
• y

Returns:

draft The currently used animation draft or nil.

getId ()

Shortcut for the id of the building's draft.

Returns:

string Draft ID of the building's building draft.

getName ()

Gets the name of this building.

Returns:

string or nil Name of the building or nil if no name is set.

getPerformance ()

Returns the current performance of this building. 1.0 represents 100%.

Returns:

float Performance of this building.

getStorage ()

Returns the storage table of the building. Storage tables can be used to save information into cities/buildings/roads permanently.

Returns:

table The storage table.

getText ()

Returns the text set to the building.

Returns:

string or nil The text of the building or nil if none was set.

getWidth ()

Returns the width of the base area of the building.

Returns:

int Width of the base area.

getX ()

Returns the x position of this building.

Returns:

int X component of the pivot position of this building.

getXY ()

Returns the pivot position of this building. The returned point can differ from the location used to retrieve this building object for buildings that have a size bigger than 1.

Returns:

1. int X component and
2. int the Y component of the pivot position of this building.

getY ()

Returns the y position of this building.

Returns:

int Y component of the pivot position of this building.

hasNeededRoad ()

Returns true iff this building needs a road connection and also has a road connection.

Returns:

bool Whether the building has road or doesn't need it.

hasRoad ()

Returns true iff this building has a road connection (even if it doesn't require one according to its json).

Returns:

bool Whether the building has road.

hasUpgrade (upgradeId)

Returns true iff this building has a specific upgrade applied to it.

Parameters:

• upgradeId string ID of an upgrade.

Returns:

bool Whether the building has the specified upgrade.

isAnimationPaused ([slot=1])

Resumes an animation that is attached to this building.

Parameters:

• slot int The index of the animation to pause. 1 is the first attached animation. (default 1)

Returns:

bool or nil Whether the specified animation is paused right now, nil if an error occurred.

isBurning ()

Returns true iff this building is burning right now.

Returns:

bool Whether this building is burning right now.

isEmpty ()

Returns true iff this building is empty right now. This means that people left it. Only happens for RCI buildings.

Returns:

bool Whether the building is empty.

isFullOfDeadPeople ()

Returns true iff this building has transport issues with dead bodies right now.

Returns:

bool Whether the building has dead people in it.

isFullOfWaste ()

Returns true iff this building is full of garbage right now.

Returns:

bool Whether the building is full of garbage.

isIll ()

Returns true iff this building contains ill people right now.

Returns:

bool Whether there are ill people.

isInConstruction ()

Returns true iff this building is in construction right now.

Returns:

bool Whether the building is in construction.

isUntouchable ()

Determines whether this (RCI) building is untouchable. An untouchable building is protected in terms of it won't be replaced by automatically spawned buildings.

Returns:

bool Whether the building is untouchable.

isUpgradeInConstruction ()

Returns true iff this building has a pending upgrade right now.

Returns:

bool Whether the building has an upgrade in progress.

isWorking ()

Returns true iff this building is working right now. A working building has road connection if needed, is not in construction and is not empty. It also has power and water if needed.

Returns:

bool Whether the building is working.

pauseAnimation ([slot=1])

Pauses an animation that is attached to this building.

Parameters:

• slot int The index of the animation to pause. 1 is the first attached animation. (default 1)

Returns:

int or nil The current frame of the animation or nil if something went wrong.

resumeAnimation ([slot=1[, speed=1.0]])

Resumes an animation that is attached to this building.

Parameters:

• slot int The index of the animation to pause. 1 is the first attached animation. (default 1)
• speed float A speed multiplier for the animation. (default 1.0)

Returns:

int or nil The current frame of the animation or nil if something went wrong.

setAnimationColor (red, green, blue[, alpha=255[, slot=1]])

Sets the color of an animation of the building. The default color is white which is expressed as 255,255,255 or 255,255,255,255.

New feature:

This is a new feature that was added in version 1.10.49

Parameters:

• red int The red color component.
• green int The green color component.
• blue int The blue color component.
• alpha int The alpha color component that is considered as transparency. (default 255)
• slot int The index of the animation to pause. 1 is the first attached animation. (default 1)

Returns:

bool or nil Only true if the operation was successful.

setAnimationFrame (frame[, slot=1])

Sets the current frame of an animation regardless of whether the animation is playing right now.

Parameters:

• frame int The frame to set.
• slot int The index of the animation to pause. 1 is the first attached animation. (default 1)

Returns:

bool or nil Whether the operation was successful.

setFrame (frame)

Sets the current frame of the building.

Parameters:

• frame int The frame index to set. Starts at 0.

setIcon (icon)

Sets a building icon. Note that game icons have higher precedence than custom ones.

New feature:

This is a new feature that was added in version 1.11.61

Parameters:

• icon string or draft An animation draft to use as icon. Use nil to reset.

setName (name)

Sets the name of this building.

Parameters:

• name string or nil The name that should be used for the building. Use nil to reset it.

setPerformance (performance)

Sets the performance of this building. The performance value will be clipped by the min and max value defined in the building's json.

Parameters:

• performance float The performance to set. 1.0 represents 100%.

setText (text)

Sets a building text or resets it.

Parameters:

• text string The text to apply to the buiding. Use nil to remove it.

setUntouchable ([state=true])

Marks this (RCI) building as untouchable or touchable. An untouchable building is protected in terms of it won't be replaced by automatically spawned buildings.

Parameters:

• state bool The untouchable state to set for the building. (default true)