Codea icon Parameters

Reference › Live controls, watches, and custom parameter panels

Guides

Controlling a running project top ↑

Overview

Parameters put controls in the viewer so you can tune a project while it runs. Use sliders to adjust numbers, switches for booleans, color pickers for colors, and text fields for strings. Codea also supports vectors, dropdown choices, live Markdown, and custom drawn controls.

Create controls once, in setup(), rather than adding them every frame. A value control’s name is both its label and the name of a global variable. For example, parameter.number("Radius", 10, 200, 80) creates a control whose value you can read as Radius. A local variable with the same name is separate; it will not track the control.

Adjust a circle

Download project Open in Codea to run this example.

function setup()
    parameter.number("Radius", 10, 200, 80)
    parameter.color("Tint", color(255, 180, 60))
    parameter.boolean("Visible", true)
    parameter.watch("Radius * 2")
end

function draw()
    background(30)
    if Visible then
        style.fill(Tint).noStroke()
        ellipse(WIDTH/2, HEIGHT/2, Radius * 2)
    end
end

Globals and callbacks

Value controls synchronize with globals of the matching type. If a compatible global already exists, its value is preserved when the control is added; otherwise the supplied initial value initializes it. Assigning to that global later updates the displayed control. Names are literal global keys: "settings.speed" does not bind to a table field. Use a callback to update a local variable, table, entity, or component instead.

A value-control callback receives one argument of the control’s type. It runs immediately with the supplied initial value when you create the control, and again when the user edits it. The creation callback receives that initial argument even when an existing global is retained. Assigning the global from Lua does not invoke the callback. Initialize related objects before creating controls whose callbacks use them.

local settings = {speed = 2}
parameter.number("Speed", 0, 10, settings.speed, function(value)
    settings.speed = value
end)

Action buttons run their callback only when pressed and pass no arguments. Watches and documentation display live information without creating value globals. Use distinct names for different controls. Re-adding a name with the same control type updates that control; call parameter.clear() before rebuilding a list with different types.

Watching and explaining values

parameter.watch("expression") evaluates a Lua expression repeatedly and displays its result, including image previews. Expressions resolve in the global environment, so they cannot directly read a local variable. Keep watched expressions inexpensive and free of side effects.

parameter.doc() displays Markdown alongside controls. Strings can include @Name for a global value, @(expression) for a computed value, and @@ for a literal at sign. Alternatively, pass a function that returns Markdown; a closure can read local variables. Both forms update as the project runs.

parameter.doc("## Circle\nRadius: **@Radius**\nDiameter: @(Radius * 2)")

Clearing and rebuilding

parameter.clear() removes controls, watches, documentation, and custom controls. It leaves globals and their values intact. Reset a global explicitly if you want a fresh value before adding its control again. Clearing the parameter list does not clear printed output; use output.clear() for that.

Updating older parameter code

The familiar number, integer, boolean, color, text, action, watch, and clear functions remain, with some signature differences. Number and integer controls require either an initial value or a minimum and maximum; there is no name-only default range. Color controls require a color object, so wrap RGB values in color(...). Text controls require an initial string, including "" for an empty field. Boolean callbacks require an explicit initial boolean. Action callbacks receive no button-name argument.

Worked example

Use the supplied project to edit an entity’s name, height, visibility, and material color, enter a multiline expression, and trigger an animation.

Controlling a scene with parameters

Download project Open in Codea to run this example.

Show code (64 lines)
-- Use this function to perform your initial setup
function setup()
    print("Hello Parameters!")

    -- Create a simple scene containing a model to play with
    scn = scene.default3d()
    rig = scn.camera:add(camera.rigs.orbit)
    scn.camera:get(camera).clearMode = camera.depthAndColor

    -- Basic entity with a sphere mesh
    ent = scn:entity()
    ent:add(mesh.sphere())

    mat = material.lit()
    mat.color = color.red
    ent.material = mat
    ent.expr = function() return 1.5 end

    -- Draw some text above the entity
    function ent:draw()
        -- Distance-field text stays sharp at this small world-space size.
        style.depth(true).textRenderer(style.atlas).fill(255).fontSize(1)
        shapeMode(CENTER)
        textAlign(CENTER | MIDDLE)
        matrix.translate(0, self.expr(), 0)
        text(self.name)
    end

    -- Auto-update/draw the scene
    scene.main = scn


    parameter.text("Name", ent.name, function(value)
        ent.name = value
    end)

    -- Expression idiom (use multiline as well)
    parameter.text("Expression", "1.5", function(value)
        ent.expr = load("return "..value) or function() return 0 end
    end, true)

    -- Y value for the entity
    parameter.number("Y", 0, 10, 0, function(value)
        ent.y = value
    end)

    -- (De)activate entity
    parameter.boolean("Active", true, function(value)
        print(value and "On" or "Off")
        ent.active = value
    end)

    -- Adjust entity material color
    parameter.color("Color", color.yellow, function(value)
        mat.color = value
    end)

    -- Do a simple tween to squash and stretch
    parameter.action("Action", function()
        scn:tween(ent):punch{sx=2, sy=0.5}:time(1)
    end)

end

Parameters

parameter.number(name, min, max, initial, callback) top ↑

Static Method

Syntax

parameter.number(name, min, max, initial, callback)

Adds a number control. Supply a minimum and maximum for a slider, or just an initial value for an unrestricted numeric editor. With a range and no initial value, the initial value is the minimum.

The global variable and callback behavior is described in the Parameters overview.

Supported forms:

Parameters

name string.

Control label and global variable name.
min number.

Minimum value for the ranged form.
max number.

Maximum value for the ranged form.
initial number, optional.

Starting value; defaults to min only in the ranged form.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.number(name, initial)
parameter.number(name, initial, callback)
parameter.number(name, min, max)
parameter.number(name, min, max, initial)
parameter.number(name, min, max, initial, callback)
parameter.number("Speed", 0, 10, 2)

parameter.integer(name, min, max, initial, callback) top ↑

Static Method

Syntax

parameter.integer(name, min, max, initial, callback)

Adds a integer control. Supply a minimum and maximum for a slider, or just an initial value for an unrestricted numeric editor. With a range and no initial value, the initial value is the minimum.

The global variable and callback behavior is described in the Parameters overview.

Supported forms:

Parameters

name string.

Control label and global variable name.
min integer.

Minimum value for the ranged form.
max integer.

Maximum value for the ranged form.
initial integer, optional.

Starting value; defaults to min only in the ranged form.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.integer(name, initial)
parameter.integer(name, initial, callback)
parameter.integer(name, min, max)
parameter.integer(name, min, max, initial)
parameter.integer(name, min, max, initial, callback)
parameter.integer("Count", 0, 10, 2)

parameter.boolean(name, initial, callback) top ↑

Static Method

Syntax

parameter.boolean(name, initial, callback)

Adds an on/off switch. The initial value defaults to false. To supply a callback, also supply the initial boolean.

Parameters

name string.

Control label and global variable name.
initial boolean, optional.

Starting value; false if omitted.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.boolean("Enabled", true, function(value)
    print(value)
end)

parameter.vec2(name, initial, callback) top ↑

Static Method

Syntax

parameter.vec2(name, initial, callback)

Adds a vec2 editor. The optional ranged form takes minimum and maximum vectors, with one limit per component. The initial value and callback argument are both vec2 values.

Supported forms:

Parameters

name string.

Control label and global variable name.
initial vec2.

Starting vector.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.vec2(name, initial)
parameter.vec2(name, initial, callback)
parameter.vec2(name, min, max, initial)
parameter.vec2(name, min, max, initial, callback)
parameter.vec2("Offset", vec2(0))

parameter.vec3(name, initial, callback) top ↑

Static Method

Syntax

parameter.vec3(name, initial, callback)

Adds a vec3 editor. The optional ranged form takes minimum and maximum vectors, with one limit per component. The initial value and callback argument are both vec3 values.

Supported forms:

Parameters

name string.

Control label and global variable name.
initial vec3.

Starting vector.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.vec3(name, initial)
parameter.vec3(name, initial, callback)
parameter.vec3(name, min, max, initial)
parameter.vec3(name, min, max, initial, callback)
parameter.vec3("Offset", vec3(0))

parameter.vec4(name, initial, callback) top ↑

Static Method

Syntax

parameter.vec4(name, initial, callback)

Adds a vec4 editor. The optional ranged form takes minimum and maximum vectors, with one limit per component. The initial value and callback argument are both vec4 values.

Supported forms:

Parameters

name string.

Control label and global variable name.
initial vec4.

Starting vector.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.vec4(name, initial)
parameter.vec4(name, initial, callback)
parameter.vec4(name, min, max, initial)
parameter.vec4(name, min, max, initial, callback)
parameter.vec4("Offset", vec4(0))

parameter.color(name, initial, callback) top ↑

Static Method

Syntax

parameter.color(name, initial, callback)

Adds a color picker. Pass a color object, rather than separate red, green, blue, or alpha arguments.

Parameters

name string.

Control label and global variable name.
initial color.

Starting value; required.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.color("Tint", color(255, 100, 50, 255))

parameter.text(name, initial, callback, multiline) top ↑

Static Method

Syntax

parameter.text(name, initial, callback, multiline)

Adds a text field. Set multiline to true for a multiline editor. The multiline form requires a callback; use an empty function if no extra work is needed. Without multiline, the field is single-line.

Parameters

name string.

Control label and global variable name.
initial string.

Starting text; use an empty string for an empty field.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.
multiline boolean, optional.

Whether to allow multiple lines; false by default.

 
parameter.text("Notes", "", function(value)
    -- Notes is also updated automatically
end, true)

parameter.option(name, choices, initial, callback) top ↑

Static Method

Syntax

parameter.option(name, choices, initial, callback)

Adds a dropdown of string labels. The global and callback contain the selected index, starting at 1, rather than the label. Use a non-empty choices list and an initial index between 1 and the number of choices. If omitted, the initial index is 1.

Supported forms:

Parameters

name string.

Control label and global variable name.
choices table.

Ordered array of string labels.
initial integer, optional.

Selected index, starting at 1; defaults to 1.
callback function, optional.

Optional function called with the initial value on creation and the new value on user edits.

 
parameter.option(name, choices)
parameter.option(name, choices, initial)
parameter.option(name, choices, callback)
parameter.option(name, choices, initial, callback)
local modes = {"Slow", "Normal", "Fast"}
parameter.option("Mode", modes, 2, function(index)
    print(modes[index])
end)

parameter.action(name, callback) top ↑

Static Method

Syntax

parameter.action(name, callback)

Adds a button that calls callback() when pressed. It creates no global variable, does not call the callback during creation, and passes no arguments.

Parameters

name string.

Button label.
callback function.

Function to run when pressed.

 
parameter.action("Clear Output", function()
    output.clear()
end)

parameter.watch(expression) top ↑

Static Method

Syntax

parameter.watch(expression)

Displays the current result of a Lua expression. Pass the expression as a string, not its evaluated value. It is evaluated in the global environment as the project runs. Images appear as image previews; other results are displayed as strings. This is read-only and creates no global variable.

Parameters

expression string.

Lua expression to evaluate repeatedly.

 
parameter.watch("Radius * 2")
parameter.watch("WIDTH")

parameter.doc(content) top ↑

Static Method

Syntax

parameter.doc(content)

Adds live Markdown to the parameter list. Pass a template string or a function returning Markdown. Templates substitute @name with a global, @(expression) with an expression result, and @@ with a literal @. Values are converted to strings; a missing global displays nil. Use a generator function for more complex formatting or access to local variables.

A generator is called on creation and as the project runs. Keep it inexpensive and free of side effects. Its first return value is used and converted to a string if needed. Returning no values produces empty content.

Parameters

content string or function.

Markdown template or function returning Markdown.

 
parameter.doc("## Settings\nCurrent speed: **@Speed**")
parameter.doc(function()
    return string.format("Double speed: %.2f", Speed * 2)
end)

parameter.custom(object) top ↑

Static Method

Syntax

parameter.custom(object)

Adds a custom drawn control backed by a Lua table. This embeds a drawing surface in the parameter list; it does not automatically generate fields for the table. For object property inspection, see inspector.set().

Define methods using colon syntax so they receive self. Optional setup() runs once before the first draw. draw() renders the control using Codea drawing commands. size() returns two numbers, width and height, in points; the default is 200 by 200. touched(touch) receives touches in the control. Set self.needsLayout = true when its desired size changes; Codea clears the flag after requesting layout. No global variable or value callback is created.

Parameters

object table.

Table implementing the custom control methods.

 
local control = {}
function control:size()
    return 200, 80
end
function control:draw()
    background(40)
    style.fill(255).noStroke()
    ellipse(40, 40, 30)
end
function control:touched(touch)
    print(touch.x, touch.y)
end
parameter.custom(control)

parameter.clear() top ↑

Static Method

Syntax

parameter.clear()

Removes all parameters, including actions, watches, Markdown, and custom controls. Globals retain their current values. You can then add a new list of controls.

parameter.clear()
Speed = 2
parameter.number("Speed", 0, 10, Speed)