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. Can be called with or without a bound object.

property:addListener(callback: () -> ())
property:addListener(obj: any, callback: (any) -> ())

property:removeListener(callback)​

Removes a callback.

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

See Also: Input, ViewModel

Context​

Runtime context passed to init() in all script protocols.

Methods​

context:viewModel()​

Gets the main Artboard's ViewModel.

context:viewModel(): ViewModel?

context:rootViewModel()​

Gets the root ViewModel of the artboard hierarchy.

context:rootViewModel(): ViewModel?

context:dataContext()​

Gets the DataContext for hierarchy traversal.

context:dataContext(): DataContext?

context:image(name)​

Gets an image asset by name.

context:image(name: string): Image?

context:blob(name)​

Gets a blob (binary data) asset by name.

context:blob(name: string): Blob?

context:audio(name)​

Gets an audio source asset by name.

context:audio(name: string): AudioSource?

context:markNeedsUpdate()​

Requests an update on the next frame.

context:markNeedsUpdate()

See Also: ViewModel, DataContext, Image, Blob, AudioSource

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. Returns a PropertyViewModel wrapper (access the ViewModel via .value).

viewModel:getViewModel(name: string): PropertyViewModel?

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, context: Context): 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

DataContext​

Provides hierarchy traversal for data binding contexts. Obtained via context:dataContext().

Methods​

dataContext:parent()​

Gets the parent DataContext, or nil if at the root.

dataContext:parent(): DataContext?

dataContext:viewModel()​

Gets the ViewModel associated with this context level.

dataContext:viewModel(): ViewModel?

See Also: Context, ViewModel

Next Steps​