Module Builder
Functions to create and destroy buildings, roads, trees and more.
For convenience you can provide the id of a draft as a string instead of the draft itself whenever a draft is needed. There are different types of drafts. Ensure that you use the correct functions to build them. For example you cannot build $park00 by using Builder.buildRoad. Since it's a build you would have to use Builder.buildBuilding instead.
For each type of object that can be built there's typically a function to check in advance whether the actual building process will be successful. It's good style to use these checks, even though the builder functions check validity on their own.
Usage:
if Builder.isBuildingBuildable('$tree00', 2, 4) then
Builder.buildBuilding('$tree00', 2, 4)
end
Functions
| buildBuilding (draft, x, y[, frame]) | Tries to build the given building draft at the specified position and sets it's frame if a frame was specified. |
| buildBuildingUpgrade (draft, x, y) | Applies a building upgrade to a building. |
| buildBusStop (draft, x, y[, level=0]) | Tries to build the given bus stop draft on the road on the specified location. |
| buildFence (fence, x, y, edge) | Builds fence on the specified edge of a tile. |
| buildFenceAround (fence, x, y, width, height) | Builds fence around the specified rectangle area. |
| buildGround (draft, x, y) | Builds the specified ground draft and returns true iff building was successful. |
| buildPipe (draft, x0, y0[, x1=x0[, y1=y0]]) | Tries to build the given pipe draft along the given line. |
| buildRoad (draft, x0, y0, x1, y1[, level0=0[, level1=0[, bridge=false]]]) | Tries to build the given road draft along the given line. |
| buildRoadDeco (draft, x, y, level[, index=nil]) | Tries to build the given road decoration draft on the road on the specified location. |
| buildTree (draft, x, y[, frame]) | Tries to build the given tree draft at the specified position x, y and return true iff this was successful. |
| buildWire (draft, x0, y0[, x1[, y1]]) | Tries to build the given wire draft along the given line. |
| buildZone (draft, x, y) | Builds the specified zone draft or removes it if draft is nil. |
| getBuildingPrice (draft, x, y) | Returns the price of the building. |
| getBuildingUpgradePrice (draft, x, y) | Returns the price of applying an upgrade to a building. |
| getBusStopPrice (draft, x, y[, level=0]) | Returns the price of the bus stop. |
| getGroundPrice (draft, x, y) | Returns the price of the ground. |
| getPipePrice (draft, x0, y0[, x1=x0[, y1=y0]]) | Returns the price to build a pipe. |
| getRoadDecoPrice (draft, x, y, level) | Returns the price of the road deco. |
| getRoadPrice (draft, x0, y0, x1, y1[, level0=0[, level1=0[, bridge=false]]]) | Returns the price of the road. |
| getTerrainHeightPrice (x, y, height) | Queries the expected price to build the terrain height as specified. |
| getTreePrice (draft, x, y) | Returns the price of the tree. |
| getWirePrice (draft, x0, y0[, x1=x0[, y1=y0]]) | Returns the price to build a wire. |
| getZonePrice (draft, x, y) | Returns the price to build the given zone. |
| isBuildingBuildable (draft, x, y[, checkZone=true[, checkRoad=true]]) | Checks whether the specified building draft can be built at the given position x, y. |
| isBusStopBuildable (draft, x, y[, level=0]) | Checks whether the specified bus stop draft can be built on the road at the specified location and level. |
| isFenceBuildable (fence, x, y, edge) | Checks whether the fence can be built on the specified edge of a tile. |
| isGroundBuildable (draft, x, y) | Returns true iff the ground draft can be built at the given location. |
| isPipeBuildable (draft, x0, y0[, x1=x0[, y1=y0]]) | Checks whether the specified pipe draft can be build along the given line x0,y0 - x1,y1. |
| isRoadBuildable (draft, x0, y0, x1, y1[, level0=0[, level1=0[, bridge=false]]]) | Checks whether the specified road draft can be build along the given line x0,y0 - x1,y1. |
| isRoadDecoBuildable (draft, x, y, level) | Returns true iff the given road decoration can be applied to the road at the specified location. |
| isTerrainHeightBuildable (x, y, height) | Queries whether the terrain height can be built as specified. |
| isTreeBuildable (draft, x, y) | Checks whether the specified tree draft can be built at the specified position. |
| isWireBuildable (draft, x0, y0[, x1=x0[, y1=y0]]) | Checks whether the specified wire draft can be build along the given line x0,y0 - x1,y1. |
| remove (x, y) | Removes anything from the specified location. |
| removeBuildingUpgrade (draft, x, y) | Removes a building upgrade from a building. |
| removeBusStop (x, y[, level=0]) | Removes the bus stop from a specified road. |
| removeFence (x, y[, edge]) | Removes the fence on the specified edge of a tile. |
| removeFenceWithin (x, y, width, height) | Removes any fence within the specified rectangle area. |
| removeGround (x, y) | Removes the ground decal at the given position if there is any. |
| removePipe (x, y) | Dedicated remove function to remove pipes only. |
| removeRoadDeco (x, y[, level=0[, index=nil]]) | Removes all or a specific road decoration from a specified road. |
| removeWire (x, y, level) | Dedicated remove function to remove wires only. |
| setTerrainHeight (x, y, height) | Tries to set the terrain height of the given location to the given height. |
Functions
- buildBuilding (draft, x, y[, frame])
-
Tries to build the given building draft at the specified position and
sets it's frame if a frame was specified. Returns true iff the build was
was successful.
Parameters:
- draft draft
- x int
- y int
- frame int The frame to use for the building. If no frame was specified a random frame will be used (in case the building has multiple frames). (optional)
Returns:
-
bool
Whether the building has been built successfully.
- buildBuildingUpgrade (draft, x, y)
-
Applies a building upgrade to a building.
An upgrade can only be applied iff the building exists, the upgrade was not
applied to it already and the building upgrade was actually defined for that
building.
The upgrade will be applied as pending and may therefor not be visible
immediately. On top of that, it may be subject to a build time.
Applying an upgrade may remove other upgrades in the future dependent on
their respective settings.
Parameters:
- draft draft Draft of the upgrade to apply.
- x int X component of the building position.
- y int Y component of the building position.
Returns:
-
bool
True iff the upgrade was applied.
- buildBusStop (draft, x, y[, level=0])
-
Tries to build the given bus stop draft on the road on the specified
location. Returns true iff this was successful.
New feature:
-
This is a new feature that was added in version 1.11.40
Parameters:
- draft draft A bus stop draft.
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level. (default 0)
Returns:
-
bool
Whether the bus stop has been built.
- buildFence (fence, x, y, edge)
-
Builds fence on the specified edge of a tile.
New feature:
-
This is a new feature that was added in version 1.9.99
Parameters:
- fence draft A fence draft.
- x int X component of the target position.
- y int Y component of the target position.
- edge int Fences can be located at all four edges of a tile. The edges are indexed as follows (for non rotated city): 0 is south-east, 1 is north-east, 2 is north-west, 3 is south-west
Returns:
-
bool
Whether the fence has been built.
- buildFenceAround (fence, x, y, width, height)
-
Builds fence around the specified rectangle area.
New feature:
-
This is a new feature that was added in version 1.9.99
Parameters:
- fence draft A fence draft.
- x int X component of the target position.
- y int Y component of the target position.
- width int Width of the target area in tiles.
- height int Height of the target area in tiles.
Returns:
-
bool
Whether at least one fence has been built.
- buildGround (draft, x, y)
-
Builds the specified ground draft and returns true iff building was
successful.
Parameters:
- draft draft A ground draft. You can alternatively provide true for water or false for land. A generic ground draft will be used then. If this is a ground decal it will be placed on the ground below it.
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
bool
Whether the ground has been built.
- buildPipe (draft, x0, y0[, x1=x0[, y1=y0]])
-
Tries to build the given pipe draft along the given line. Returns true if
building was successful.
Parameters:
- draft draft Draft of the pipe to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position. (default x0)
- y1 int Y component of the end position. (default y0)
Returns:
-
bool
Whether the pipe has been built successfully.
- buildRoad (draft, x0, y0, x1, y1[, level0=0[, level1=0[, bridge=false]]])
-
Tries to build the given road draft along the given line. Returns true if
building was successful.
Parameters:
- draft draft Draft of the road to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position.
- y1 int Y component of the end position.
- level0 int Level at the start position. Default value is 0. (default 0)
- level1 int Level at the end position. Default value is 0. (default 0)
- bridge bool Specifies whether a bridge should be built. For this option to work level0 and level1 must be equal. Default is false. (default false)
Returns:
-
bool
Whether the road has been built successfully.
- buildRoadDeco (draft, x, y, level[, index=nil])
-
Tries to build the given road decoration draft on the road on the specified
location. Returns true iff this was successful.
Parameters:
- draft draft A road decoration draft.
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level.
- index int If specified the decoration will be place at the given index if possible (starting with 1). (default nil)
Returns:
-
bool
Whether the road decoration has been built.
- buildTree (draft, x, y[, frame])
-
Tries to build the given tree draft at the specified position x, y and
return true iff this was successful. If frame is specified it also tries
to set the frame of the tree accordingly.
Parameters:
- draft draft The tree draft that should be used.
- x int X component of the target position.
- y int Y component of the target position.
- frame int The frame to use for the tree. A random frame will be picked if it isn't specified. (optional)
Returns:
-
bool
Whether the tree can be built.
- buildWire (draft, x0, y0[, x1[, y1]])
-
Tries to build the given wire draft along the given line. Returns true if
building was successful.
Parameters:
- draft draft Draft of the wire to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position. (optional)
- y1 int Y component of the end position. (optional)
Returns:
-
bool
Whether the wire has been built successfully.
- buildZone (draft, x, y)
-
Builds the specified zone draft or removes it if draft is nil.
Parameters:
- draft draft A zone draft or nil.
- x int X component of the target position.
- y int Y component of the target position.
- getBuildingPrice (draft, x, y)
-
Returns the price of the building. May change with time.
Parameters:
- draft draft
- x int
- y int
Returns:
-
int
The price in Theons.
- getBuildingUpgradePrice (draft, x, y)
-
Returns the price of applying an upgrade to a building.
Parameters:
- draft draft Draft of the upgrade to apply.
- x int X component of the building position.
- y int Y component of the building position.
Returns:
-
int or nil
The price in Theons or nil if there is no such building or
the upgrade was applied to it already.
- getBusStopPrice (draft, x, y[, level=0])
-
Returns the price of the bus stop.
New feature:
-
This is a new feature that was added in version 1.11.40
Parameters:
- draft draft A bus stop draft.
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level. (default 0)
Returns:
-
int
The price in Theons.
- getGroundPrice (draft, x, y)
-
Returns the price of the ground. May change with time.
Parameters:
- draft draft A ground draft. You can alternatively provide true for water or false for land. A generic ground draft will be used then.
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
int
The price in Theons.
- getPipePrice (draft, x0, y0[, x1=x0[, y1=y0]])
-
Returns the price to build a pipe. May change with time.
Parameters:
- draft draft Draft of the pipe to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position. (default x0)
- y1 int Y component of the end position. (default y0)
Returns:
-
int
The price in Theons.
- getRoadDecoPrice (draft, x, y, level)
-
Returns the price of the road deco. May change with time.
Parameters:
- draft draft A road decoration draft.
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level.
Returns:
-
int
The price in Theons.
- getRoadPrice (draft, x0, y0, x1, y1[, level0=0[, level1=0[, bridge=false]]])
-
Returns the price of the road. May change with time.
Parameters:
- draft draft Draft of the road to probe.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position.
- y1 int Y component of the end position.
- level0 int Level at the start position. Default value is 0. (default 0)
- level1 int Level at the end position. Default value is 0. (default 0)
- bridge bool Specifies whether a bridge should be built. For this option to work level0 and level1 must be equal. Default is false. (default false)
Returns:
-
int
The price in Theons.
- getTerrainHeightPrice (x, y, height)
-
Queries the expected price to build the terrain height as specified.
New feature:
-
This is a new feature that was added in version 1.10.87
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
- height int The height that should be tried to set.
Returns:
-
int
The expected price.
- getTreePrice (draft, x, y)
-
Returns the price of the tree. May change with time.
Parameters:
- draft draft The tree draft that should be used.
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
int
The price in Theons.
- getWirePrice (draft, x0, y0[, x1=x0[, y1=y0]])
-
Returns the price to build a wire. May change with time.
Parameters:
- draft draft Draft of the wire to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position. (default x0)
- y1 int Y component of the end position. (default y0)
Returns:
-
int
The price in Theons.
- getZonePrice (draft, x, y)
-
Returns the price to build the given zone. May change with time.
Parameters:
- draft draft A zone draft.
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
int
The price in Theons.
- isBuildingBuildable (draft, x, y[, checkZone=true[, checkRoad=true]])
-
Checks whether the specified building draft can be built at the given
position x, y. Returns true iff the building can be built.
Parameters:
- draft draft A building draft.
- x int
- y int
- checkZone bool If true and the building needs a specific zone then the function will only return true if that zone is already present or can be built without replacing another zone type. (default true)
- checkRoad bool If true and the building needs a road connection then the function will only return true if there is road nearby. (default true)
Returns:
-
bool
Whether the building can be built.
- isBusStopBuildable (draft, x, y[, level=0])
-
Checks whether the specified bus stop draft can be built on the road
at the specified location and level.
New feature:
-
This is a new feature that was added in version 1.11.40
Parameters:
- draft draft A bus stop draft.
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level. (default 0)
Returns:
-
bool
Whether the bus stop can be built.
- isFenceBuildable (fence, x, y, edge)
-
Checks whether the fence can be built on the specified edge of a tile.
New feature:
-
This is a new feature that was added in version 1.9.99
Parameters:
- fence draft A fence draft.
- x int X component of the target position.
- y int Y component of the target position.
- edge int Fences can be located at all four edges of a tile. The edges are indexed as follows (for non rotated city): 0 is south-east, 1 is north-east, 2 is north-west, 3 is south-west
Returns:
-
bool
Whether the fence can be built.
- isGroundBuildable (draft, x, y)
-
Returns true iff the ground draft can be built at the given location.
Parameters:
- draft draft A ground draft. You can alternatively provide true for water or false for land. A generic ground draft will be used then.
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
bool
Whether the ground can be built.
- isPipeBuildable (draft, x0, y0[, x1=x0[, y1=y0]])
-
Checks whether the specified pipe draft can be build along the given line
x0,y0 - x1,y1. A valid line has to fulfill the property x0 == x1 or y0 == y1.
Parameters:
- draft draft Draft of the pipe to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position. (default x0)
- y1 int Y component of the end position. (default y0)
Returns:
-
bool
Whether the pipe can be built.
- isRoadBuildable (draft, x0, y0, x1, y1[, level0=0[, level1=0[, bridge=false]]])
-
Checks whether the specified road draft can be build along the given line
x0,y0 - x1,y1. To build a bridge manually you have to set
level0 = level1 and bridge = true
Only a single lane will be built so a valid line has to fulfill the property
x0 == x1 or y0 == y1
Parameters:
- draft draft Draft of the road to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position.
- y1 int Y component of the end position.
- level0 int Level at the start position. Default value is 0. (default 0)
- level1 int Level at the end position. Default value is 0. (default 0)
- bridge bool Specifies whether a bridge should be built. For this option to work level0 and level1 must be equal. Default is false. (default false)
Returns:
-
bool
Whether the road can be built.
- isRoadDecoBuildable (draft, x, y, level)
-
Returns true iff the given road decoration can be applied to the road at
the specified location.
Parameters:
- draft draft A road decoration draft.
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level.
Returns:
-
bool
Whether the road decoration can be built.
- isTerrainHeightBuildable (x, y, height)
-
Queries whether the terrain height can be built as specified.
This does not consider the price of the action.
New feature:
-
This is a new feature that was added in version 1.10.87
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
- height int The height that should be tried to set.
Returns:
-
bool
True iff the terrain height is buildable as specified.
- isTreeBuildable (draft, x, y)
-
Checks whether the specified tree draft can be built at the specified
position.
Parameters:
- draft draft The tree draft that should be used.
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
bool
Whether the tree can be built.
- isWireBuildable (draft, x0, y0[, x1=x0[, y1=y0]])
-
Checks whether the specified wire draft can be build along the given line
x0,y0 - x1,y1. A valid line has to fulfill the property x0 == x1 or y0 == y1.
Parameters:
- draft draft Draft of the wire to build.
- x0 int X component of the starting position.
- y0 int Y component of the starting position.
- x1 int X component of the end position. (default x0)
- y1 int Y component of the end position. (default y0)
Returns:
-
bool
Whether the wire can be built.
- remove (x, y)
-
Removes anything from the specified location.
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
bool
Whether something was removed.
- removeBuildingUpgrade (draft, x, y)
-
Removes a building upgrade from a building.
Pending upgrades cannot be removed or probed.
Parameters:
- draft draft Draft of the upgrade to remove.
- x int X component of the building position.
- y int Y component of the building position.
Returns:
-
bool
True iff the upgrade was removed.
- removeBusStop (x, y[, level=0])
-
Removes the bus stop from a specified road.
New feature:
-
This is a new feature that was added in version 1.11.40
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level. (default 0)
Returns:
-
bool
True iff the bus stop was removed.
- removeFence (x, y[, edge])
-
Removes the fence on the specified edge of a tile.
New feature:
-
This is a new feature that was added in version 1.9.99
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
- edge int Fences can be located at all four edges of a tile. The edges are indexed as follows (for non rotated city): 0 is south-east, 1 is north-east, 2 is north-west, 3 is south-west. If not specified all fences on the tile will be removed. (optional)
Returns:
-
bool
Whether a fence was removed.
- removeFenceWithin (x, y, width, height)
-
Removes any fence within the specified rectangle area.
New feature:
-
This is a new feature that was added in version 1.9.99
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
- width int Width of the target area in tiles.
- height int Height of the target area in tiles.
Returns:
-
bool
Whether at least one fence has been removed.
- removeGround (x, y)
-
Removes the ground decal at the given position if there is any.
New feature:
-
This is a new feature that was added in version 1.10.59
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
Returns:
-
bool
Whether a ground decal was removed.
- removePipe (x, y)
-
Dedicated remove function to remove pipes only.
Parameters:
- x int X component of a tile.
- y int Y component of a tile.
Returns:
-
bool
Whether the pipe was removed.
- removeRoadDeco (x, y[, level=0[, index=nil]])
-
Removes all or a specific road decoration from a specified road.
New feature:
-
This is a new feature that was added in version 1.9.96
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
- level int Road level of the target position with 0 being ground level. (default 0)
- index int Index of the road decoration to remove starting with 1, or nil to remove all road decorations on the road (default nil)
Returns:
-
bool
True iff at least one road decoration was removed.
- removeWire (x, y, level)
-
Dedicated remove function to remove wires only.
Parameters:
- x int X component of a tile.
- y int Y component of a tile.
- level int Level of the wire to remove. The level of normal wires is 0 (-1 for underground and 1 for long distance wires).
Returns:
-
bool
Whether the wire was removed.
- setTerrainHeight (x, y, height)
-
Tries to set the terrain height of the given location to the given height.
New feature:
-
This is a new feature that was added in version 1.10.87
Parameters:
- x int X component of the target position.
- y int Y component of the target position.
- height int The height that should be tried to set.