# Parameters
Live controls, watches, and custom parameter panels
[Reference](index.md)
## Guides
### Controlling a running project
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](data/downloads/Adjust-a-circle-c1d618c246c5.zip) — Open in Codea to run this example.
```lua
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.
```lua
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.
```lua
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](data/downloads/Controlling-a-scene-with-parameters-a0497fd80798.zip) — Open in Codea to run this example.
```lua
-- 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)
```lua
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:
adds a number control
#### 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.
#### Example
```lua
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)
```
#### Example
```lua
parameter.number("Speed", 0, 10, 2)
```
### parameter.integer(name, min, max, initial, callback)
```lua
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:
adds a integer control
#### 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.
#### Example
```lua
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)
```
#### Example
```lua
parameter.integer("Count", 0, 10, 2)
```
### parameter.boolean(name, initial, callback)
```lua
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.
adds an on/off switch
#### 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.
#### Example
```lua
parameter.boolean("Enabled", true, function(value)
print(value)
end)
```
### parameter.vec2(name, initial, callback)
```lua
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:
adds a vec2 editor
#### 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.
#### Example
```lua
parameter.vec2(name, initial)
parameter.vec2(name, initial, callback)
parameter.vec2(name, min, max, initial)
parameter.vec2(name, min, max, initial, callback)
```
#### Example
```lua
parameter.vec2("Offset", vec2(0))
```
### parameter.vec3(name, initial, callback)
```lua
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:
adds a vec3 editor
#### 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.
#### Example
```lua
parameter.vec3(name, initial)
parameter.vec3(name, initial, callback)
parameter.vec3(name, min, max, initial)
parameter.vec3(name, min, max, initial, callback)
```
#### Example
```lua
parameter.vec3("Offset", vec3(0))
```
### parameter.vec4(name, initial, callback)
```lua
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:
adds a vec4 editor
#### 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.
#### Example
```lua
parameter.vec4(name, initial)
parameter.vec4(name, initial, callback)
parameter.vec4(name, min, max, initial)
parameter.vec4(name, min, max, initial, callback)
```
#### Example
```lua
parameter.vec4("Offset", vec4(0))
```
### parameter.color(name, initial, callback)
```lua
parameter.color(name, initial, callback)
```
Adds a color picker. Pass a color object, rather than separate red, green, blue, or alpha arguments.
adds a color picker
#### 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.
#### Example
```lua
parameter.color("Tint", color(255, 100, 50, 255))
```
### parameter.text(name, initial, callback, multiline)
```lua
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.
adds a text field
#### 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.
#### Example
```lua
parameter.text("Notes", "", function(value)
-- Notes is also updated automatically
end, true)
```
### parameter.option(name, choices, initial, callback)
```lua
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:
adds a dropdown of string labels
#### 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.
#### Example
```lua
parameter.option(name, choices)
parameter.option(name, choices, initial)
parameter.option(name, choices, callback)
parameter.option(name, choices, initial, callback)
```
#### Example
```lua
local modes = {"Slow", "Normal", "Fast"}
parameter.option("Mode", modes, 2, function(index)
print(modes[index])
end)
```
### parameter.action(name, callback)
```lua
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.
adds a button that calls callback() when pressed
#### Parameters
- **name** (string): Button label.
- **callback** (function): Function to run when pressed.
#### Example
```lua
parameter.action("Clear Output", function()
output.clear()
end)
```
### parameter.watch(expression)
```lua
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.
displays the current result of a lua expression
#### Parameters
- **expression** (string): Lua expression to evaluate repeatedly.
#### Example
```lua
parameter.watch("Radius * 2")
parameter.watch("WIDTH")
```
### parameter.doc(content)
```lua
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.
adds live markdown to the parameter list
#### Parameters
- **content** (string or function): Markdown template or function returning Markdown.
#### Example
```lua
parameter.doc("## Settings\nCurrent speed: **@Speed**")
parameter.doc(function()
return string.format("Double speed: %.2f", Speed * 2)
end)
```
### parameter.custom(object)
```lua
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.
adds a custom drawn control backed by a lua table
#### Parameters
- **object** (table): Table implementing the custom control methods.
#### Example
```lua
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()
```lua
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.
removes all parameters, including actions, watches, markdown, and custom controls
#### Example
```lua
parameter.clear()
Speed = 2
parameter.number("Speed", 0, 10, Speed)
```