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_PLACED Will be called for building and road drafts right after placement.
EVENT_FINISHED Will be called for building and road drafts right after construction.
EVENT_CAR_SPAWNED Will be called for building with car spawner whenever a car was spawned.
EVENT_CAR_REACHED Will be called for building with car spawner whenever a car reached it's target.
EVENT_CAR_DESPAWNED Will be called for building with car spawner whenever a car was despawned.
EVENT_TOOL_ENTER Will be called for scripts attached to a generic tool when users selects the tool.
EVENT_REMOVE Will be called for scripts attached to a building before it gets removed.
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:getId () Every script is uniquely identified by a single number.
Script:getDraft () Returns the draft the script is attached to.
Script:getName () Returns the name of the script.
Script:getPath () Returns the relative path of the script.
Script:getLocation () Returns a readable location identifier that contains the draft id.
Script:getParents () Returns an array of all parent scripts.
Script:getParent () Returns the parent script if there is any, **nil** otherwise.
Script:setActive (state) Activates or disables the script.
Script:isActive () Determines whether the script is active right now.
Script:addTag (tag) Adds a tag to this script.
Script:getTags () Returns an array that contains the tags that have been defined for that script.
Script:addScript (name, draft[, initializer]) Adds a script to a draft.

Event functions

script:earlyInit () Will be called on all scripts before script:init().
script:init () Will be called once after all drafts and scripts have been loaded.
script:lateInit () Will be called once after script:init() has been called on all scripts.
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:daily (x, y, level) Will be called on a daily basis for every building or road that are instances of the owning draft.
script:click (x, y, level) Will be called when the user taps on a building or road that is an instance of the owning draft.
script:event (x, y, level, Event) Will be called for building/road/tool events of instances of the owning draft.
script:draw (x, y, level) Will be called after a building/road instance has been drawn.
script:random (x, y) Will be called every day for scripts whose owning draft is a building or road.
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:update () Will be called per frame for each script while a city is open.
script:click (x, y) Will be called when users taps on a building/road of this draft while being in default tool.
script:earlyTap (tileX, tileY, x, y) Will be called when the user taps on the map.
script:tap (tileX, tileY, x, y) Will be called when the user taps on the map.
script:enterCity () Will be called when the user enters a city.
script:leaveCity () Will be called when the user leaves the city.
script:enterCityGeneration (phase) Will be called right before a new city is generated.
script:leaveCityGeneration (phase) Will be called after city generation process was completed.
script:save () Will be called just before the city is saved.
script:enable () Will be called when this script is about to be enabled.
script:disable () Will be called when this script is about to be disabled.
script:overlay () Will be called once per frame after UI has been drawn.
script:enterStage () Will be called whenever the user enters a stage.
script:leaveStage () Will be called whenever the user leaves a stage.


Event types

EVENT_PLACED
Will be called for building and road drafts right after placement.

See also:

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.
EVENT_CAR_SPAWNED
Will be called for building with car spawner whenever a car was spawned.
EVENT_CAR_REACHED
Will be called for building with car spawner whenever a car reached it's target.
EVENT_CAR_DESPAWNED
Will be called for building with car spawner whenever a car was despawned.
EVENT_TOOL_ENTER
Will be called for scripts attached to a generic tool when users selects the tool.
EVENT_REMOVE
Will be called for scripts attached to a building before it gets removed.
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: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:

    number
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:getName ()
Returns the name of the script. E.g. the name of a script >folder/test.lua is just `test`.

Returns:

    string
Script:getPath ()
Returns the relative path of the script.

Returns:

    string
Script:getLocation ()
Returns a readable location identifier that contains the draft id.

Returns:

    string
Script:getParents ()
Returns an array of all parent scripts.

Returns:

    array
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: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
Script:isActive ()
Determines whether the script is active right now.

Returns:

    bool
Script:addTag (tag)
Adds a tag to this script. Tags can be used to find scripts by using `getScripts(tag)`.

Parameters:

  • tag
Script:getTags ()
Returns an array that contains the tags that have been defined for that script.

Returns:

    array
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

Event functions

script:earlyInit ()
Will be called on all scripts before script:init(). Use this method to set up early things.
script:init ()
Will be called once after all drafts and scripts have been loaded.
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: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 number
  • y number
  • level 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 number
  • y number
  • level number
script:click (x, y, level)
Will be called when the user taps on a building or road that is an instance of the owning draft. Level is 0 for buildings.

Parameters:

  • x number
  • y number
  • level number
script:event (x, y, level, Event)
Will be called for building/road/tool events of instances of the owning draft. Level is 0 for buildings.

Parameters:

  • x number
  • y number
  • level number
  • Event number number (see listing above)

See also:

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.

Parameters:

  • x number
  • y number
  • level number
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: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: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.
script:click (x, y)
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
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.

Parameters:

  • tileX number
  • tileY number
  • x number
  • y number
script:tap (tileX, tileY, x, y)
Will be called when the user taps on the map. Will be called just after the tap is handled by the current tool.

Parameters:

  • tileX number
  • tileY number
  • x number
  • y number
script:enterCity ()
Will be called when the user enters a city.
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: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:leaveCityGeneration (phase)
Will be called after city generation process was completed.

Parameters:

  • phase
script:save ()
Will be called just before the city is saved.
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:disable ()
Will be called when this script is about to be disabled.
script:overlay ()
Will be called once per frame after UI has been drawn. Will also be called outside of cities.
script:enterStage ()
Will be called whenever the user enters a stage. A stage is for example a city, the settings screen or the gallery.
script:leaveStage ()
Will be called whenever the user leaves a stage. A stage is for example a city, the settings screen or the gallery.
generated by LDoc 1.4.3 Last updated 2019-10-28 15:18:26