Parameter Design
Designparameter-designParameter Design is an Agent Skill for design published in the dylanroscover/Embody repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
MUST READ before creating or designing custom parameters on any COMP: pages, styles, ranges, help text, naming, ParGroup gotchas.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/dylanroscover/Embody/blob/HEAD/.claude/skills/parameter-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/parameter-design, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Parameter Design
Help Text
Every custom parameter MUST have help text set via par.help = "...". Help text appears as a tooltip when users hover the parameter name in the dialog. Describe what the parameter controls and what its values mean.
- Good:
"Maximum number of rows displayed in the manager list. Set to 0 for unlimited." - Bad:
"Max rows"(just restates the label) - Unacceptable: no help text at all
In TDN files, include "help": "..." in the parameter definition. Embody exports and imports help text automatically.
Section Breaks
Use par.startSection = True on the first parameter of each logical group. This draws a horizontal separator line above the parameter, visually grouping related controls.
In TDN: "startSection": true in the parameter definition.
Parameter Ordering
Parameters appear in the order they are appended. Keep related parameters together and maintain a logical flow within each page:
- Primary controls first (what users interact with most)
- Secondary/advanced settings after
- Read-only status/info parameters last
If reordering after creation, use par.order (accepts float values like 11.5 to insert between existing positions).
Page Organization
Group parameters into pages by function. Use comp.appendCustomPage('PageName') -- pages appear in creation order.
Common patterns:
| Page | Purpose |
|---|---|
| Main / Settings | Primary configuration |
| Tags | Externalization tags, strategies |
| UI | Visual and display options |
| About | Version, build, author (read-only) |
Naming
- First letter MUST be uppercase, rest lowercase letters and numbers only
- No underscores, spaces, or special characters
- Examples:
Speed,Maxrows,Autosave,Envoyenable
Style Selection
| Use case | Style | Notes |
|---|---|---|
| On/off toggle | Toggle | Values are 0/1 |
| Fire-once action | Pulse | No persistent value |
| Enumerated choices | Menu | Set menuNames and menuLabels separately |
| Editable dropdown | StrMenu | Free-text input with suggestions |
| Numeric value | Float or Int | Set range properties (see below) |
| Text input | Str | Free-form string |
| File/folder path | File / Folder | Opens system dialog |
| Operator reference | OP, COMP, TOP, CHOP, SOP, DAT, MAT | Filtered by family |
| Section header | Header | Visual label only, no value |
Numeric Ranges
For Float and Int parameters, configure the range:
| Property | Purpose |
|---|---|
min / max | Minimum and maximum values |
clampMin / clampMax | Whether to enforce min/max as hard limits (True) or allow values outside (False) |
normMin / normMax | Slider range in the UI (what the slider covers visually) |
Example:
p = page.appendFloat('Speed', label='Speed')[0]
p.default = 1.0
p.min = 0.0
p.max = 10.0
p.clampMin = True
p.clampMax = False # Allow values above 10 via manual entry
p.normMin = 0.0
p.normMax = 5.0 # Slider covers 0-5, but values up to 10+ accepted
p.help = "Playback speed multiplier. 1.0 = normal speed."
Read-Only Parameters
Use par.readOnly = True for status and informational parameters that users should see but not edit (version, build number, connection status).
Defaults
Always set par.default = value. This enables "Revert to Default" in the TD parameter dialog and ensures TDN round-trips produce consistent results.
Creating Custom Parameters
All page.append*() methods return a ParGroup (tuple-like), not a single Par. Index with [0] to get the Par object:
page = comp.appendCustomPage('Settings')
pg = page.appendFloat('Speed', label='Speed') # Returns ParGroup
p = pg[0] # Get the Par
p.default = 1.0
p.help = "Playback speed multiplier."
p.startSection = True