Skip to content

Animation#

Animation drafts allow you to create custom night lights.

Animation drafts have the type of animation.

Attributes#

active#

Type: boolean

Whether the draft is active and should be loaded by the game.

additive#

Type: boolean

Whether to draw the animation frames using additive blending.

By default, the value will be false.

alias#

Type: string

aliases#

Type: string array

Same as alias, but for multiple IDs.

animation#

Type: Animation array

Allows you to define an animation for animation.

author#

Type: string

The name of the author behind the draft.

category#

Type: string

ID of the category the draft should be contained in.

category from#

Type: string

Draft ID to grab category from and use for the draft.

color#

Type: Color

A color that can be used to tint the animation.

colors#

Type: Color array

An array of colors that can be used to tint the animation.

If multiple colors were provided a random color will be picked for an animation spot based on building location and seed.

dev#

Type: boolean

final#

Type: boolean

If set to true, the draft can no longer be overridden.

frame animation indices#

Type: integer 2D array

Must be used together with the animation attribute.

frames#

Type: Frame array

Graphic frames definition to use for the animation.

Each frame will be displayed in sequence to create an animation effect. The frames should be provided in the order they should be displayed.

By default, the value will be [null].

frames winter#

Type: Frame array

handle interpolation#

Type: boolean

If the value is greater than 1, the game will generate additional frames that gradually transition between two consecutive frames.

By default, the value will be 1.

hidden#

Type: boolean

Whether the draft shows up in the toolbar. If set to true, the draft will not be available in the toolbar.

hide id#

Type: boolean

Whether to hide the draft ID even when the debug mode is enabled. This will automatically be set to true if final is set to true or if your draft is part of an encrypted plugin file.

icon frames#

Type: Frame array

Frames that will be used for the top left corner of the building dialog.

Size of the frames should be 26x26 pixels.

icon frames winter#

Type: Frame array

Frames that will be used during winter for the top left corner of the building dialog.

Size of the frames should be 26x26 pixels.

id#

Type: string

Unique identifier of the draft.

index#

Type: boolean

Whether to allow the draft to be indexed by Lua methods.

By default, the value will be true unless the draft is scenario draft.

Changed in version 1.12.12:

The default value was changed to false for script, data and scenario drafts.

Changed in version 1.12.13:

The default value was changed to true for script and data drafts.

inherit#

Type: boolean

Whether to modify a draft of the same ID by inheriting values.

light#

Type: boolean

If set to true the game's shading (ie for night) will not be applied to the animation.

By default, the value will be false.

light switching#

Type: boolean

If set to true the animation will only be shown during night with some probabilistic switching behaviour dependent on the using object.

By default, the value will be false.

loop#

Type: boolean

Must be used together with the handle interpolation attribute.

By default, the value will be true.

max version#

Type: integer

The maximum game version that will run the draft.

meta#

Type: Meta

A special attribute that allows you to store additional metadata about the draft.

Read more about it in the Meta documentation.

min version#

Type: integer

The minimum game version required to run the draft.

mute#

Type: boolean

Whether to suppress any errors that have occurred while loading the draft.

mute lua#

Type: boolean

night light probability#

Type: float

The probability of the light to turn on during night. 1 means it will always switch on. Smaller values mean that location and spot seed will be used to determine whether to switch it on.

By default, the value will be 1.

not implemented#

Type: boolean

Whether the draft has to be inherited to be considered implemented. Will cause an error otherwise.

once#

Type: boolean

Whether the draft should be loaded once.

What this means is that if another draft is encountered with the same ID, the game will ignore loading it rather than failing with an error message.

ordinal#

Type: integer

Position of the draft in a category. Lower ordinal value will list the draft higher. Negative values are allowed.

ordinal from#

Type: string

ID of the draft to grab ordinal from. Must be used in combination with the ordinal attribute.

override#

Type: boolean

Whether to modify a draft of the same ID by replacing values.

Rather than replacing the values, you may want to add or only change specific values of the draft. For that, refer to the inherit attribute.

ping pong#

Type: boolean

If true, the animation will loop back-and-forth to create the "ping pong" effect, where the sequence of frames goes forward and then reverses direction, offering a bouncing effect.

By default, the value will be false.

premium#

Type: boolean

Whether the draft is premium. A premium draft will not be active in non premium versions of the game.

premium requirement#

Type: Nested requirement

Requirements that need to be fulfilled for the draft on premium platforms.

If platform is premium, this attribute will be loaded over the regular requirement attribute. On non-premium platforms, this attribute will be ignored.

premium requirements#

Type: Requirement array

Requirements that need to be fulfilled for the draft on premium platforms.

If platform is premium, this attribute will be loaded over the regular requirement attribute. On non-premium platforms, this attribute will be ignored.

preview frames#

Type: Frame array

Frames that will be used for preview in the toolbar instead of regular frames.

preview frames winter#

Type: Frame array

Frames that will be used for preview in the toolbar instead of regular frames during winter.

privileged#

Type: string

Privileged key for your draft. Allows the use of special features, which are restricted to trusted plugin creators only.

Deprecated

Due to a change in how the privilege system works, you are now recommended to use require privileges or require super privileges.

require privileges#

Type: boolean

Whether the draft requires features such as monthly income, frame placement, etc.

Added in version 1.11.73

require scenario#

Type: string or string array

Array of scenario IDs in which this draft can be used. It will be unloaded when entering a city that is not one of these scenarios.

Privileged context is required to use this attribute as it could be used to cheat inside a scenario.

Added in version 1.12.12

require super privileges#

Type: boolean

Whether the draft requires features that are restricted to official game content such as DSA.

Added in version 1.11.73

requirement#

Type: Nested requirement

Requirements that need to be fulfilled for the draft.

requirements#

Type: Requirement array

Requirements that need to be fulfilled for the draft.

rotation aware#

Type: boolean

If set to true the animation is considered to be animation aware. This means that the frames are assigned into groups. The group to draw will depend on the rotation of the underlying building.

Ie if 8 frames were defined then frames 0,1 will be used for the first rotation and so on.

By default, the value will be false.

script#

Type: string

Used to attach a script to the current draft.

Supported modes of operation#

  • Loading the script from file: 

    {
  "script": "script.lua"
}

  • Declaring the script inline: 

    {
  "script": "function script:lateInit() Debug.toast('Late init called') end"
}

  • Using a helper script #LuaWrapper for Real time script editing: 

    {
  "script": "#LuaWrapper",
  "meta": {
    "luawrapper": {
      "script": "script.lua",
      "dev": true
    }
  }
}

scripts#

Type: string array

Like script, but for multiple scripts.

searchable#

Type: boolean

Whether the draft can be searched in the toolbar.

separator#

Type: boolean

Whether to separate the draft from others in a category.

show new marker#

Type: boolean

Whether the draft will show a new marker in the toolbar.

sound click#

Type: obj

This sound will be played when clicked on the draft in default mode.

Example#

One may refer to a file locally: 

{
  "sound click": {
    "file": "path to file.mp3"
  }
}

Or a game resource: 

{
  "sound click": {
    "res": "SOUND_CHRISTMAS_HOHOO"
  }
}

speed#

Type: float

Animation speed multiplier.

By default, the value will be 1.

strict lua#

Type: boolean

template#

Type: string

ID of the template draft to inherit the implementation from.

template prefix#

Type: string

Has effect only when using templates.

templates#

Type: string array

Like template, but accepts multiple IDs.

text#

Type: string

Description, usually of the building. Should be English if distributed.

By default, the value will be null.

text id#

Type: string

title#

Type: string

Title, usually of the building. Should be English if distributed.

By default, the value will be null.

title id#

Type: string

type#

Type: string

A special attribute that determines what kind of attributes and abilities a draft has.