Module Script
The unit scripts are organized in.
Scripting is organized in single scripts that can be attached to draft objects. At runtime the script's methods get called at certain points in time and therefore allow the script to run.
Usage:
local x = 0
function script:init()
Debug.toast('init')
end
function script:update()
Debug.info(x)
x = x + 1
end
Event types
| EVENT_ALIGNED | Will be called for alignable buildings when their alignment was updated. |
| EVENT_CAR_DESPAWNED | Will be called for building with car spawner whenever a car was despawned. |
| EVENT_CAR_REACHED | Will be called for building with car spawner whenever a car reached it's target. |
| EVENT_CAR_SPAWNED | Will be called for building with car spawner whenever a car was spawned. |
| EVENT_FINISHED | Will be called for building and road drafts right after construction. |
| EVENT_PLACED | Will be called for building and road drafts right after placement. |
| EVENT_REMOVE | Will be called for scripts attached to a building or road the moment before it gets removed. |
| EVENT_REPLACED | Will be called for building and road drafts after they have been built again either by user issued undo or redo action. |
| EVENT_TOOL_ENTER | Will be called for scripts attached to a generic tool when users selects the tool. |
| EVENT_TOOL_LEAVE | Will be called for scripts attached to a generic tool when users closes the tool. |
| EVENT_UPGRADE | Will be called for scripts attached to a building after an upgarde of it was finished. |
Functions
| getScript () | Returns the current script or nil if no script is running right now. |
| getScripts ([tag]) | Returns an array of all scripts, or, if tag is specified, an array of all scripts that defined the given tag. |
Class Script
| Script:addScript (name, draft[, initializer]) | Adds a script to a draft. |
| Script:addTag (tag) | Adds a tag to this script. |
| Script:getDraft () | Returns the draft the script is attached to. |
| Script:getId () | Every script is uniquely identified by a single number. |
| Script:getLocation () | Returns a readable location identifier that contains the draft id. |
| Script:getName () | Returns the name of the script. |
| Script:getParent () | Returns the parent script if there is any, nil otherwise. |
| Script:getParents () | Returns an array of all parent scripts. |
| Script:getPath () | Returns the relative path of the script. |
| Script:getTags () | Returns an array that contains the tags that have been defined for that script. |
| Script:isActive () | Determines whether the script is active right now. |
| Script:setActive (state) | Activates or disables the script. |
Event functions
| script:afterToolDrawing (x, y, frame, buildable, draft) | For building drafts: Will be called by the building tool the moment after drawing the building preview. |
| script:beforeToolDrawing (x, y, frame, buildable, draft) | For building drafts: Will be called by the building tool the moment before drawing the building preview. |
| script:buildCityGUI () | Will be called after the city GUI was built. |
| script:click (x, y, level) | Will be called when users taps on a building/road of this draft while being in default tool. |
| script:clickAny (tileX, tileY) | Will be called when the user taps on the map and the current tool did not handle it. |
| script:daily (x, y, level) | Will be called on a daily basis for every building or road that are instances of the owning draft. |
| script:disable () | Will be called when this script is about to be disabled. |
| script:draw (x, y, level) | Will be called after a building/road instance has been drawn. |
| script:drawCity () | This event function will be called right after the city was drawn. |
| script:earlyInit () | Will be called on all scripts before script:init(). |
| script:earlyTap (tileX, tileY, x, y) | Will be called when the user taps on the map. |
| script:enable () | Will be called when this script is about to be enabled. |
| script:enterCity () | Will be called when the user enters a city. |
| script:enterCityGeneration (phase) | Will be called right before a new city is generated. |
| script:enterStage (name) | Will be called whenever the user enters a stage. |
| script:event (x, y, level, event, source) | Will be called for building/road/tool events of instances of the owning draft. |
| script:exit () | Will be called when the game gets closed. |
| script:finishInformationDialog (x, y, lvl, dialog) | Gets called after the information dialog for buildings and/or roads was built. |
| script:init () | Will be called once after all drafts and scripts have been loaded. |
| script:isBuildable (x, y, level) | For buildings and roads only: Will be queried to determine if a building/road can be built at a specific location. |
| script:lateInit () | Will be called once after script:init() has been called on all scripts. |
| script:leaveCity () | Will be called when the user leaves the city. |
| script:leaveCityGeneration (phase) | Will be called after city generation process was completed. |
| script:leaveStage () | Will be called whenever the user leaves a stage. |
| script:load () | Will be called after lateInit and when the draft is reloaded after it was unloaded e.g. |
| script:nextDay () | Will be called on a daily basis for each script. |
| script:nextMonth () | Will be called on a monthly basis for each script. |
| script:nextYear () | Will be called on a yearly basis for each script. |
| script:onCarDespawned (car) | Gets called for smart cars when the car was despawned. |
| script:onCarFoundNoWay (car) | Gets called for smart cars when a car did not find a way. |
| script:onCarFoundWay (car) | Gets called for smart cars when the car found a way to a destination. |
| script:onCarNotSpawned (storage) | Gets called for smart cars when the car could not be spawned. |
| script:onCarReached (car) | Gets called for smart cars when the car reached it's destination. |
| script:onCarSpawned (car) | Gets called for smart cars when the car was spawned. |
| script:overlay () | Will be called once per frame after UI has been drawn. |
| script:random (x, y) | Will be called every day for scripts whose owning draft is a building or road. |
| script:save () | Will be called just before the city is saved. |
| script:settings () | Will be called when rebuilding the settings page of the game. |
| script:tap (tileX, tileY, x, y) | Will be called when the user taps on the map. |
| script:unload () | Will be called before the plugin get's unloaded. |
| script:update () | Will be called per frame for each script while a city is open. |
Event types
- EVENT_ALIGNED
-
Will be called for alignable buildings when their alignment was updated.
New feature:
-
This is a new feature that was added in version 1.11.09
See also:
- EVENT_CAR_DESPAWNED
- Will be called for building with car spawner whenever a car was despawned.
- EVENT_CAR_REACHED
- Will be called for building with car spawner whenever a car reached it's target.
- EVENT_CAR_SPAWNED
- Will be called for building with car spawner whenever a car was spawned.
- EVENT_FINISHED
-
Will be called for building and road drafts right after construction.
That is immediately after placements for roads and for buildings witht zero
buildtime.
Note that this function will also be called after a building was built after it was moved. If there is no build time, e.g. in sandbox mode, this call happens immediately after EVENT_PLACED and does not reflect the final properties of the building like upgrades. For that you could use Runtime.postpone to do the check for properties a bit later.
- EVENT_PLACED
-
Will be called for building and road drafts right after placement.
Note that this function will also be called after a building was moved.
See also:
- EVENT_REMOVE
- Will be called for scripts attached to a building or road the moment before it gets removed.
- EVENT_REPLACED
-
Will be called for building and road drafts after they have been built again
either by user issued undo or redo action.
New feature:
-
This is a new feature that was added in version 1.10.79
See also:
- EVENT_TOOL_ENTER
- Will be called for scripts attached to a generic tool when users selects the tool.
- EVENT_TOOL_LEAVE
- Will be called for scripts attached to a generic tool when users closes the tool. Be aware of that the tool will not be closes automatically when the user leaves the city.
- EVENT_UPGRADE
- Will be called for scripts attached to a building after an upgarde of it was finished.
Functions
- getScript ()
-
Returns the current script or nil if no script is running right now.
Since scripts are executed synchronously to avoid race conditions there
can only be one script running.
Returns:
-
script
- getScripts ([tag])
-
Returns an array of all scripts, or, if tag is specified, an array of all
scripts that defined the given tag.
Don't manipulate the returned array directly.
Parameters:
- tag (optional)
Returns:
-
array
Class Script
Here you see the methods that a script object offers.- Script:addScript (name, draft[, initializer])
-
Adds a script to a draft. Only call this method in the init or lateInit
methods to ensure that it will be executed correctly.
However, init and/or lateInit might not be called on the new script
automatically.
Format of initializer: initializer(script)
If no initializer is provided the own initializer will be used.
Returns the newly created script.
Parameters:
- name string
- draft draft
- initializer function (optional)
Returns:
-
script
- Script:addTag (tag)
-
Adds a tag to this script. Tags can be used to find scripts by using
getScripts(tag).Parameters:
- tag
- Script:getDraft ()
-
Returns the draft the script is attached to. Every script instance is
attached to exactly one draft. However, multiple instances of the same
script may be attached to different drafts.
Returns:
-
draft
- Script:getId ()
-
Every script is uniquely identified by a single number.
Note that this identifier is only constant during runtime.
It may be different in the next session, therefore you shouldn't rely
on it.
Returns:
-
int
- Script:getLocation ()
-
Returns a readable location identifier that contains the draft id.
Returns:
- Script:getName ()
-
Returns the name of the script. E.g. the name of a script
folder/test.lua
is just
test.Returns:
- Script:getParent ()
-
Returns the parent script if there is any, nil otherwise.
A parent script is the script that instantiated this script using
script:addScript()Scripts are usually not instantiated by other scripts.Returns:
-
script
- Script:getParents ()
-
Returns an array of all parent scripts.
Returns:
-
array
- Script:getPath ()
-
Returns the relative path of the script.
Returns:
- Script:getTags ()
-
Returns an array that contains the tags that have been defined for that script.
Returns:
-
array
- Script:isActive ()
-
Determines whether the script is active right now.
Returns:
-
bool
- Script:setActive (state)
-
Activates or disables the script. No event methods will be called on
disabled scripts. A disabled script cannot re-enable itself since it won't
be updated anymore.
Parameters:
- state bool
Event functions
- script:afterToolDrawing (x, y, frame, buildable, draft)
-
For building drafts: Will be called by the building tool the moment
after drawing the building preview.
New feature:
-
This is a new feature that was added in version 11.10.79
Parameters:
- x int The x coordinate where the building is intended to be built.
- y int The y coordinate where the building is intended to be built.
- frame int The current frame that will be used to draw the building.
- buildable bool Signals if the building is currently considered buildable.
- draft draft The building that is about to be built.
- script:beforeToolDrawing (x, y, frame, buildable, draft)
-
For building drafts: Will be called by the building tool the moment
before drawing the building preview.
New feature:
-
This is a new feature that was added in version 11.10.79
Parameters:
- x int The x coordinate where the building is intended to be built.
- y int The y coordinate where the building is intended to be built.
- frame int The current frame that will be used to draw the building.
- buildable bool Signals if the building is currently considered buildable.
- draft draft The building that is about to be built.
- script:buildCityGUI ()
- Will be called after the city GUI was built. When entering the city stage this method will not always be called due to GUI caching.
- script:click (x, y, level)
-
Will be called when users taps on a building/road of this draft while being
in default tool.
Return false to prevent opening the default tile dialog.
You should favor this method over earlyTap() and tap() as they operate
indepently of tile dialog and selected tool and don't take the own draft
into consideration.
This method will also be called for custom tools if user taps on a tile
and script:isBuildable() returned true for it.
Parameters:
- x number
- y number
- level number
- script:clickAny (tileX, tileY)
-
Will be called when the user taps on the map and the current tool did not
handle it.
This is useful as earlyTap does not know if the current tool will handle
the event (for example build tools build things upon tap).
So this callback function can be used to implement 'default tap behavior'.
If the function returns false no further processing will happen
(ie calling click or showing the tile dialog.)
New feature:
-
This is a new feature that was added in version 1.12.18
Parameters:
- tileX number
- tileY number
- script:daily (x, y, level)
-
Will be called on a daily basis for every building or road that are
instances of the owning draft. Level is 0 for buildings.
Parameters:
- x int
- y int
- level int
- script:disable ()
- Will be called when this script is about to be disabled.
- script:draw (x, y, level)
-
Will be called after a building/road instance has been drawn.
Will also be called on all visible tiles for custom tools.
For tools, instead of level there are two integer parameters tx, ty which are
either -1,-1 if no mouse pointer is present, or the tile coords the mouse
pointer is currently over.
Parameters:
- x int
- y int
- level int
- script:drawCity ()
- This event function will be called right after the city was drawn. If you want to draw something directly on top of the city it's a good idea to do it in here.
- script:earlyInit ()
- Will be called on all scripts before script:init(). Use this method to set up early things.
- script:earlyTap (tileX, tileY, x, y)
-
Will be called when the user taps on the map. Will be called just before
the tap is handled by the current tool.
Let it return false in case you do not want the current tool to handle
this tap.
Parameters:
- tileX number
- tileY number
- x number
- y number
- script:enable ()
- Will be called when this script is about to be enabled. Scripts are enabled by definiton right after their creation so this method won't be called then.
- script:enterCity ()
- Will be called when the user enters a city.
- script:enterCityGeneration (phase)
-
Will be called right before a new city is generated.
Parameters:
- phase number Will be 0 for first pass and 1 for decoration creation
- script:enterStage (name)
-
Will be called whenever the user enters a stage. A stage is for example
a city, the settings screen or the gallery.
Parameters:
- name string A readable name of the stage.
- script:event (x, y, level, event, source)
-
Will be called for building/road/tool events of instances of the owning
draft.
Level is 0 for buildings.
Be careful not to do any meaningful work when receiving removal event since
that could cause cassade enless calling of event functions.
Use Runtime.postpone() to prevent that.
Changes:
-
1.10.07: Add level and source values for car related events.
Parameters:
- x int The x location of the event. The targeted building's pivot x location for car related events.
- y int Same as x but for y coordinate.
- level int The level of the event. The selected car frame for car related events.
- event int Event number (see listing above)
- source draft The car draft in case of car events, nil otherwise.
See also:
- script:exit ()
-
Will be called when the game gets closed. There is no guarantee that This
function will actually be called.
New feature:
-
This is a new feature that was added in version 1.9.80
- script:finishInformationDialog (x, y, lvl, dialog)
-
Gets called after the information dialog for buildings and/or roads
was built.
Only gets called for buildings/roads this script is attached to.
Parameters:
- x number X coordinate of the building or road.
- y number Y coordinate of the building or road.
- lvl number For roads only: the level of the road.
- dialog table A dialog table as it is returned by GUI.createTable(...).
- script:init ()
- Will be called once after all drafts and scripts have been loaded.
- script:isBuildable (x, y, level)
-
For buildings and roads only:
Will be queried to determine if a building/road can be built at a specific
location. To prevent buildability just let it return false.
Is also queried for custom tools to determine buildability.
Parameters:
- x int
- y int
- level int
- script:lateInit ()
- Will be called once after script:init() has been called on all scripts. Use this method for things that relay on other scripts' setup.
- script:leaveCity ()
- Will be called when the user leaves the city. Don't rely on this method to permanently save state since there's no guarantee that this method will be called.
- script:leaveCityGeneration (phase)
-
Will be called after city generation process was completed.
Parameters:
- phase
- script:leaveStage ()
- Will be called whenever the user leaves a stage. A stage is for example a city, the settings screen or the gallery.
- script:load ()
-
Will be called after lateInit and when the draft is reloaded after it was
unloaded e.g. for an online mode region that does not allow plugins.
New feature:
-
This is a new feature that was added in version 1.9.80
- script:nextDay ()
- Will be called on a daily basis for each script.
- script:nextMonth ()
- Will be called on a monthly basis for each script.
- script:nextYear ()
- Will be called on a yearly basis for each script.
- script:onCarDespawned (car)
-
Gets called for smart cars when the car was despawned.
New feature:
-
This is a new feature that was added in version 1.10.51
Parameters:
- car car A car object that can be used to control the car.
- script:onCarFoundNoWay (car)
-
Gets called for smart cars when a car did not find a way.
New feature:
-
This is a new feature that was added in version 1.10.51
Parameters:
- car car A car object that can be used to control the car.
- script:onCarFoundWay (car)
-
Gets called for smart cars when the car found a way to a destination.
New feature:
-
This is a new feature that was added in version 1.10.51
Parameters:
- car car A car object that can be used to control the car.
- script:onCarNotSpawned (storage)
-
Gets called for smart cars when the car could not be spawned.
The provided storage table of the not spawned car can be used to identify
which City.spawnCar request failed.
New feature:
-
This is a new feature that was added in version 1.10.51
Parameters:
- storage table The storage table that was used in City.spawnCar(...)
- script:onCarReached (car)
-
Gets called for smart cars when the car reached it's destination.
New feature:
-
This is a new feature that was added in version 1.10.51
Parameters:
- car car A car object that can be used to control the car.
- script:onCarSpawned (car)
-
Gets called for smart cars when the car was spawned.
New feature:
-
This is a new feature that was added in version 1.10.51
Parameters:
- car car A car object that can be used to control the car.
- script:overlay ()
- Will be called once per frame after UI has been drawn. Will also be called outside of cities.
- script:random (x, y)
-
Will be called every day for scripts whose owning draft is a building or
road. x and y is a random (valid) postion on the map.
Parameters:
- x number
- y number
- script:save ()
- Will be called just before the city is saved.
- script:settings ()
- Will be called when rebuilding the settings page of the game. Can return a table contains settings items that will then be displayed. See here on how to use it.
- script:tap (tileX, tileY, x, y)
-
Will be called when the user taps on the map. Will be called just after
the tap was handled by the current tool.
Parameters:
- tileX number
- tileY number
- x number
- y number
- script:unload ()
-
Will be called before the plugin get's unloaded. This happens for example
when the user enters a city in online mode that doesn't allow plugins.
New feature:
-
This is a new feature that was added in version 1.9.80
- script:update ()
- Will be called per frame for each script while a city is open. Can be used to draw stuff on the screen (under the UI). Use overlay() do draw on top of UI and/or outside of cities.