Skip to main content

Data & Input

APIs for script inputs, properties, runtime context, and data binding.

Input​

Generic script input exposed to the editor. Input<T> is read directly as a value of type T in scripts.

Supported Types​

Input<number>
Input<boolean>
Input<string>
Input<Color>
Input<Data.ViewModelName>
Input<Artboard<Data.ViewModelName>>

Access​

Inputs are intended to be read-only from scripts and accessed directly (for example, self.speed, not self.speed.value). While you can technically assign to Input fields at runtime, this is not enforced and doing so bypasses the editor's data binding.

Note: ViewModel properties (Property<T>) use .value. Inputs do not.

Change Handling​

Use update(self) to react to input changes, or cache the previous value on self and compare it each update.

Note: While Input values can technically be reassigned at runtime, this bypasses the binding system. Use ViewModel properties (Property<T>) for two-way binding.

See Also: Property, ViewModel

Property​

Mutable property with change notification.

Attributes​

property.value​

The property value. Type: T (read/write)

Methods​

property:addListener(callback)​

Registers a change callback.

property:addListener(callback: () -> ())

property:removeListener(callback)​

Removes a callback.

property:removeListener(callback: () -> ())

See Also: Input, ViewModel

Context​

Runtime context available in lifecycle functions.

Methods​

context:viewModel()​

Gets the main Artboard's ViewModel.

context:viewModel(): ViewModel?

context:markNeedsUpdate()​

Requests an update on the next frame.

context:markNeedsUpdate()

See Also: ViewModel

ViewModel​

Connects editor elements to data and code. Provides access to bound properties by type.

Attributes​

viewModel.name​

The name of the ViewModel. Type: string (read-only)

Methods​

viewModel:getNumber(name)​

Gets a numeric property by name.

viewModel:getNumber(name: string): Property<number>?

viewModel:getString(name)​

Gets a string property by name.

viewModel:getString(name: string): Property<string>?

viewModel:getBoolean(name)​

Gets a boolean property by name.

viewModel:getBoolean(name: string): Property<boolean>?

viewModel:getColor(name)​

Gets a color property by name.

viewModel:getColor(name: string): Property<Color>?

viewModel:getTrigger(name)​

Gets a trigger property by name.

viewModel:getTrigger(name: string): PropertyTrigger?

viewModel:getList(name)​

Gets a list property by name.

viewModel:getList(name: string): PropertyList?

viewModel:getViewModel(name)​

Gets a nested ViewModel by name.

viewModel:getViewModel(name: string): ViewModel?

viewModel:getEnum(name)​

Gets an enum property by name.

viewModel:getEnum(name: string): PropertyEnum?

viewModel:instance()​

Creates an independent instance of the ViewModel.

viewModel:instance(): ViewModel

Example​

function init(self: MyScript): boolean
    local vm = context:viewModel()

    -- Get typed properties
    local score = vm:getNumber("score")
    local playerName = vm:getString("playerName")
    local isActive = vm:getBoolean("isActive")

    -- Read values
    if score then
        print(`Score: {score.value}`)
    end

    -- Listen for changes
    if playerName then
        playerName:addListener(function()
            print(`Name changed to: {playerName.value}`)
        end)
    end

    return true
end

See Also: Property, Context, PropertyTrigger

Next Steps​