Dialog Script Overview

The dialog script is a simple text-based language that describes a parameter interface. It is used to define parameter interfaces for HDA operators as well as custom parameter layouts with spare parameters for individual node instances.

Its basic syntax looks like:

{
    # Operator properties
    name        foo
    label       Foo
    help {
        "Some help text for the node type."
    }
    # [additional operator properties]
    # Top level parameter
    parm {
        name    "parm1"
        label   "Parameter 1"
        type    string
        default { "" }
        # [additional parameter properties]
    }
    # Parameters nested in two top level tab folders.
    group {
        name    "folder1_1"
        label   "Folder 1"
        # [additional group properties]
        parm {
            name    "nested_parm1"
            label   "Nested Parm 1"
            type    toggle
            default { "0" }
        }
        parm {
            name    "nested_parm2"
            label   "Nested Parm 2"
            type    vector
            size    3
            default { "0" "0" "1" }
            range   { 0 1 }
        }
    }
    group {
        name    "folder1_2"
        label   "Folder 2"
        # [additional group properties]
        parm {
            name    "nested_parm3"
            label   "Nested Parm 3"
            type    ordinal
            default { "foo" }
            menu {
                "foo"   "Foo"
                "bar"   "Bar"
            }
        }
    }
}

Folders can be nested arbitrarily and there are many more folder types, parameter types and properties than illustrated in the above example.

Operator Properties

Operator properties generally precede any parameters defined in the dialog script, though that is not required by the language. Many are only used in specific situations where the dialog script itself registers an operator.

Note: These properties are typically not included as part of the dialog script snippet for generating the parameter interface for an HDK operator.

Operator Property	Example	Notes
name	name "foo"	The internal name of the operator. Used only when a dialog script registers an operator.
label	label "Foo"	The full name of the operator as it appears in the UI. Used only when a dialog script registers an operator.
help	help { "Help Line 1" "Help Line 2" "Help Line 3" }	The help card for the operator. Used only when a dialog script registers an operator.
inputlabel	inputlabel 1 "Input 1"	Input label to use for a particular input number.
bindhandle	bindhandle tx sphere "Transformer" tx ""	There is one bindhandle property for each parameter component bound to a handle. The usage is `bindhandle <node parameter component> <handle type> <handle label> <handle parameter> <default_settings_string>`. Only the default settings string from the first bindhandle property for a given handle is used.

Groups

In the dialog script language, folders are defined by nesting parameters inside group objects.

The token used to declare the group determines the folder type.

Group Token	Folder Type
group	Tab. Adjacent groups append folders to the same switcher by default.
groupradio	Radio. Adjacent groups append folders to the same switcher by default.
groupcollapsible	Collapsible. Adjacent groups are unrelated.
groupsimple	Simple outline. Adjacent groups are unrelated.

Group Properties

Group Property	Example	Notes
name	name "folder1"	The internal name of the switcher parameter. Where a switcher consists of multiple groups, only the name on the first group matters.
label	label "Attributes"	The folder label.
tabbreak	tabbreak	Used to end merging of adjacent tab or radio groups into the same switcher.
disablewhen	disablewhen "{ enable_switcher == 0 }"	Used to control disabling of all folders in a switcher.
disablewhentab	disablewhentab "{ enable_folder == 0 }"	Used to control disabling of a single folder.
hidewhen	hidewhen "{ hide_switcher == 0 }"	Used to control visibility of all folders in a switcher.
hidewhentab	hidewhentab "{ hide_folder == 0 }"	Used to control visibility of a single folder.
parmtag	parmtag { "group_default" "1" }	General purpose switcher level tag. Syntax is `parmtag { <name> <string_value> }`
grouptag	grouptag { "sidefx::look" "blank" }	General purpose folder level tag. Syntax is `grouptag { <name> <string_value> }`

Parameters

The type of a parameter is set by the type property in the parm block. See Houdini docs for parm types for more details.

Type	Type Label on Edit Type Properties Dialog
angle	Angle
button	Button
buttonstrip	Button Strip
color	Color
color4	Color and Alpha
data	Data
direction	Direction Vector
directory	File - Directory
file	File
float	Float
float_minmax	Min/max Float
geometry	File - Geometry
geometrydata	Geometry Data
huecircle	Hue Circle
iconstrip	Icon Strip
image	File - Image
int	Integer
integer	Integer
intlog	Logarithmic Integer
int_minmax	Min/max Integer
intvector	Integer Vector 3
intvector2	Integer Vector 2
intvector3	Integer Vector 3
intvector4	Integer Vector 4
keyvaluedict	Key-Value Dictionary
label	Label
log	Logarithmic Float
oplist	Operator List
oppath	Operator Path
ordinal	Ordered Menu
ramp_flt	Ramp (Float)
ramp_rgb	Ramp (Color)
rgb	Color
rgba	Color and Alpha
rgbamask	RGBA Mask
separator	Separator
string	String
toggle	Toggle
uv	UV
uvw	UVW
vector	Float Vector 3
vector2	Float Vector 2
vector3	Float Vector 3
vector4	Float Vector 4

Several of the parameter types that appear in the Type Properties dialog are variations of a base type that are achieved by setting additional properties.

Variation	Key Properties
Label - Heading	type label parmtag { "sidefx::look", "heading" }
Label - Message	type label parmtag { "sidefx::look", "block" }
Spacer	type separator parmtag { "sidefx::look", "blank" } parmtag { "sidefx::layout_height", "small" }

Parameter Properties

Parm Property	Examples	Notes
name	name "attribmask"	The internal name of the parameter from which channel names are derived.
label	label "Attribute Mask"	The label displayed in the parameter dialog.
type	type float	The type of the parameter. See the previous section for allowed types.
baseparm	baseparm	Used in custom parameter layouts to differentiate base parameters from spare parameters. Base parameters are part of the operator definition and the changes that can be applied to them by a custom layout are limited.
callback	callback "hou.phm().callback(kwargs)"	Sets the callback script. Equivalent to using parmtag to set "script_callback", which should be preferred to using this property.
cppname	cppname "AttribMask"	This name is used in place of an automatically capitalized version of name during proto generation from embedded dialog scripts.
default	default { "0" "0" "1" } default { [ "3*ch(\"otherparm\")" hscript-expr ] }	The default value(s) for the parameter. The second form, which uses `[ "value" meaning ]` instead of `"value"` can be used to set a default expression. Supported meanings are literal, hscript-expr, python, and default-lang.
defaults	defaults { "0" "0" "1" }	See default.
disablewhen	disablewhen "{ enable_switcher == 0 }"	Used to control disabling of the parameter.
export	export none	Used to control export to additional dialogs. A value of 0 or none means the parameter is only available in the main parameter dialog. A value of 1 or dialog means the parameter is available in the main parameter dialog and the viewer state dialog. A value of 2 or all means that the parameter is availble in the main parameter dialog, viewer state dialog, and the viewer toolbox.
hidewhen	hidewhen "{ hide_switcher == 0 }"	Used to control visibility of the parameter.
invisible	invisible	Used to flag a parameter as invisible. Invisible parameters do not appear in the dialog, but can still be queried or set by scripts.
joinnext	joinnext	Put the next parameter on the same line as this parameter. Most commonly used with toggles.
menu	menu { "tokenA" "Label A" "tokenB "Label B" } menu { [ "items = [\"tokenA\" \"Label A\" \"tokenB\" \"Label B\"]" ] [ "return items" ] language python }	Turns the parameter into a menu. Menu items are specified, either as a hard-coded list or a script that returns them. Script lines are enclosed in []. Most commonly used with 'ordinal' or 'string' type parameters.
menujoin	menujoin { "tokenA" "Label A" "tokenB "Label B" }	Turns the parameter into a menu and joins it horizontally with the next parameter. Houdini uses this style for menus that modify the operation of the following parameter. A script can be used, as with menu.
menumini	menumini { "tokenA" "Label A" "tokenB "Label B" }	Displays the parameter as "mini" pop-up menu. This only shows a small button to open the menu, instead of showing the current value. Usually joined to the previous parameter (see joinnext) and combined with a callback script to execute actions on item selection. A script can be used, as with menu.
menureplace	menureplace { "tokenA" "Label A" "tokenB "Label B" }	Displays the parameter as a regular field, with a mini pop-up menu at the end from which they can choose items. Choosing an item replaces the contents of the field. A script can be used, as with menu.
menutoggle	menutoggle { "tokenA" "Label A" "tokenB "Label B" }	Displays the parameter as a regular field, treated ass a space-separated lisst of keywords, with a mini pop-up menu at the end from which they can choose items. Choosing an item adds its token to the list or removes it if it is already there. A script can be used, as with menu.
nolabel	nolabel	Hides the parameter label in the dialog. Most commonly used when joining parameters on the same line.
parmtag	xi parmtag { "script_callback" "hou.phm().callback(kwargs)" } parmtag { "script_callback_language" "python" }	General purpose tag. Syntax is `parmtag { <name> <string_value> }`
proto_includeraw	proto_includeraw	Tells the proto generation to create a raw string field instead of a normal string field during proto generation. This will create raw_ prefixed accessors that can be used to get the raw string from OP_Utils::evalOpParmRaw().
range	range { 0 1 } range { 1! 10 }	Specifies the range for numeric parameters. If the minimum or maximum value ends with an ! character, then the parameter interface will prevent the user from manually entering values lower and/or higher than that bound.
size	size 3	Tuple size.

MultiParms

In the dialog script language, multiparms are defined by nesting "instance" parameters inside multiparm objects. Instance parameter names should contain a # character for each level of nesting inside a multiparm, which will be replaced by the index inside the multiparm as these are instanced.

The token used to declare the multiparm determines the multiparm type.

Multiparm Token	Multiparm Type
multiparm	List style multiparm that adds the instanced parameters as part of the normal parameter layout.
multiscroll	Scrolling style multiparm that adds the instanced parameters inside a scrolling region so that the dialog itself doesn't grow in height.
multiswitcher	Tab style multiparm that puts set of instance parameters into a separate tab.

Multiparm Properties

Multiparm Property	Example	Notes
name	name "numattribs"	The internal name of the multiparm.
label	label "Number of Attributes"	The label for the multiparm.
baseparm	baseparm	Used in custom parameter layouts to differentiate base parameters from spare parameters. Base parameters are part of the operator definition and the changes that can be applied to them by a custom layout are limited.
default	default 5 default { 5 }	Default value for the multiparm. Unlike regular parameters, multiparms are never tuples, and so the enclosing {} are optional.
disablewhen	disablewhen "{ enable_multiparm == 0 }"	Used to control disabling of the multiparm.
hidewhen	hidewhen "{ hide_multiparm == 0 }"	Used to control visibility of the multiparm.
parmtag	parmtag { "multistartoffset" "1" }	General purpose tag. Syntax is `parmtag { <name> <string_value> }`

Example Cookbook

This section provides dialog script examples for common parameter interfaces.

Ordinal Menu

Value is an integer, but is saved to hip files as the entry token, allowing menu order to be safely changed.

parm {
    name    "grouptype"
    label   "Group Type"
    type    ordinal
    default { "points" }
    menu {
        "vertices"  "Vertices"
        "edges"     "Edges"
        "points",   "Points"
        "prims",    "Primitives"
    }
}

Ordinal Menu Using Python Script

Menu script returns a flat list of strings, where the even items are tokens and the odd items are labels.

parm {
    name    "grouptype"
    label   "Group Type"
    type    ordinal
    default { "points" }
    menu {
        [ "items = [" ]
        [ " \"vertices\", \"Vertices\"," ]
        [ " \"edges\", \"Edges\"," ]
        [ " \"points\", \"Points\"" ]
        [ " \"prims\", \"Primitives\"" ]
        [ "]" ]
        [ "return items" ]
        language python
    }
}

Toggle

A basic toggle parameter.

parm {
    name   "removeunused"
    label  "Remove Unused Points"
    type    toggle
    default { "0" }
}

Toggle Joined to String Field

A toggle parameter joined to a string field that also controls whether the string field is enabled.

parm {
    name   "usecustomattrib"
    label  "Use Custom Attribute"
    type    toggle
    default { "0" }
    nolabel
    joinnext
}
parm {
    name    "customattrib"
    label   "Custom Attribute"
    type    string
    default { "N" }
    disablewhen "{ usecustomattrib == 0 }"
}

Float Field

A basic float parameter with a single field.

parm {
    name    "dist"
    label   "Distance"
    type    float
    default { "1" }
    range   { -5 5 }
}

Float Field Joined to Menu Exposing Additional Controls

A float parameter with a single field whose value can be optionally scaled by an attribute.

parm {
    name    "mask"
    label   "Mask"
    type    float
    joinnext
    default { "1" }
    range   { 0 1 }
}
parm {
    name    "enablemaskattrib"
    label   "Enable Mask Attribute"
    type    ordinal
    nolabel
    default { "0" }
    menu {
        "noscaling"   "No Scaling"
        "byattrib"    "Scale by Attribute"
    }
}
parm {
    name    "maskattrib"
    label   "Mask Attribute"
    type    string
    default { "mask" }
    hidewhen "{ enablemaskattrib == noscaling }"
    menureplace {
        [ "kwargs['node'].generateInputAttribMenu(0, hou.attribType.Point, hou.attribData.Float, max_size=1, array_type=False)" ]
        language python
    }
}

Float Tuple

A basic float parameter with two fields.

parm {
    name    "urange"
    label   "U Range"
    type    float
    size    2
    default { "0" "1" }
}

Float Vector

A basic float vector parameter with three fields. Chief difference from a float tuple is the channel name suffixes are x,y,z instead of 1,2,3.

parm {
    name    "origin"
    label   "Origin"
    type    vector
    size    3
    default { "0" "0" "0" }
}

Float Vector with Auto Scope

The "autoscope" tag value is a bit field specifying which components automatically get scoped in the channel editor when a node is selected.

parm {
    name    "t"
    label   "Translate"
    type     vector
    size     3
    default  { "0" "0" "0" }
    parmtag> { "autoscope" "1111111111111111111111111111111" }
}

Direction

In old versions of Houdini this had a different UI than a plani vector parameter, but that is no longer the case.

parm {
    name    "dir"
    label   "Direction"
    type    direction
    size    3
    default { "1" "0" "0" }
}

Callback Button (Python)

Script arguments are passed via the kwargs dictionary. The arguments are the same as for hscript with additional HOM objects for the node and parm.

parm {
    name    "callback"
    label   "Callback"
    type    button
    parmtag { "script_callback" "hou.ui.displayMessage(repr(kwargs))" }
    parmtag { "script_callback_language" "python" }
}

Callback Button (HScript)

Script arguments are available as local variables.

parm {
    name    "callback"
    label   "Callback"
    type    button
    parmtag { "script_callback" "message `run(\"set\")`" }
    parmtag { "script_callback_language" "hscript" }
}

Toggle Button Strip

Buttons in a toggle button strip are defined by a menutoggle property. For a regular button strip, only the menu item labels are used.

parm {
    name    "buttons"
    label   "Buttons"
    type    buttonstrip
    default { "0" }
    menutoggle {
        "move",   "Move"
        "rotate", "Rotate"
    }
}

Radio Button Strip

Buttons in a radio button strip are defined by a menu property. For a regular button strip, only the menu item labels are used.

parm {
    name    "buttons"
    label   "Buttons"
    type    buttonstrip
    default { "0" }
    menu {
        "move",   "Move"
        "rotate", "Rotate"
    }
}

Toggle Icon Strip

Buttons in a toggle icon strip are defined by a menutoggle property. The menu item tokens specify the icons while the labels will be used as tooltips.

parm {
    name    "buttons"
    label   "Buttons"
    type    iconstrip
    default { "0" }
    menutoggle {
        "TOOLS_move",   "Move"
        "TOOLS_rotate", "Rotate"
    }
}

Radio Icon Strip

Buttons in a radio icon strip are defined by a menu property. The menu item tokens specify the icons while the labels will be used as tooltips.

parm {
    name    "buttons"
    label   "Buttons"
    type    iconstrip
    default { "0" }
    menu {
        "TOOLS_move",   "Move"
        "TOOLS_rotate", "Rotate"
    }
}

Collapsible Folder

Collapsible folders are closed by default. A parmtag can be used to control this default state.

groupcollapsible {
    name    "parmgroup_pivotxform"
    label   "Pivot Transform"
    parmtag { "group_default" "1" }
    parm {
        name    "p"
        label   "Pivot Translate"
        type    vector
        size    3
        default { "0" "0" "0" }
        range   { -1 1 }
    }
    parm {
        name    "pr"
        label   "Pivot Rotate"
        type    vector
        size    3
        default { "0" "0" "0" }
        range   { 0 360 }
    }
}

Group and Group Type Parameters with Reselect Action Button

These are very common parameters on SOP operators.

parm {
    name    "group"
    label   "Group"
    type    string
    default { "" }
    parmtag { "script_action" "import soputils\nkwargs['geometrytype'] = kwargs['node'].parmTuple('grouptype')\nkwargs['inputindex'] = 0\nsoputils.selectGroupParm(kwargs)" }
    parmtag { "script_action_help" "Select geometry from an available viewport.\nShift-click to turn on Select Groups." }
    parmtag { "script_action_icon" "BUTTONS_reselect" }
}
parm {
    name    "grouptype"
    label   "Group Type"
    type    ordinal
    default { "guess" }
    menu {
        "guess"     "Guess from Group"
        "vertices"  "Vertices"
        "edges"     "Edges"
        "points",   "Points"
        "prims",    "Primitives"
    }
}

String with Toggle Menu of Input Attributes

A string parameter with a mini toggle menu populated with input attributes.

parm {
    name    "pointattriblist"
    label   "Point Attributes"
    type    string
    default { "" }
    menutoggle {
        [ "kwargs['node'].generateInputAttribMenu(0, hou.attribType.Point, hou.attribData.Float, max_size=-1, array_type=False)" ]
        language python
    }
}

String with Replace Menu of Input Attributes and Paint Action Button

A string parameter with a mini menu for setting the value to an input attribute.

parm {
    name    "maskattrib"
    label   "Mask Attribute"
    type    string
    default { "mask" }
    menureplace {
        [ "kwargs['node'].generateInputAttribMenu(0, hou.attribType.Point, hou.attribData.Float, max_size=1, array_type=False)" ]
        language python
    }
    parmtag { "script_action" "import soptoolutils as su\nnode = kwargs['node']\nsu.paintNodeInput(kwargs, node, 0, node.parm('maskattrib').eval(), { 'attribdef': 0 })" }
    parmtag { "script_action_help" "Paint mask attribute on the input." }
    parmtag { "script_action_icon" "SOP_attribpaint" }
}

Color Ramp with Default Values

A color ramp parameter configured with a default ramp.

parm {
    name    "colorramp"
    label   "Color Mapping"
    type    ramp_rgb
    default { "3" }
    range   { 2! 10 }
    parmtag { "rampcolordefault" "1pos ( 0 ) 1c ( 0 0 1 ) 1interp  ( linear ) 2pos ( 0.5 ) 2c ( 1 1 1 ) 2interp  ( linear ) 3pos ( 1.0 ) 3c ( 1 0 0 ) 3interp  ( linear )" }
    parmtag { "rampshowcontrolsdefault" "0" }
}

Float Ramp with Default Values

A float ramp parameter configured with a default ramp.

parm {
    name    "densityramp"
    label   "Density Ramp"
    type    ramp_flt
    default { "2" }
    range   { 2! 10 }
    parmtag { "rampfloatdefault" "1pos ( 0 ) 1value ( 0.5 ) 1interp ( catmull-rom ) 2pos ( 1 ) 2value ( 0.5 ) 2interp ( catmull-rom )" }
    parmtag { "rampshowcontrolsdefault" "0" }
}

Multiparm

Unlike for normal parms, the default value does not have to be enclosed in {}, though it can be if so desired.

multiparm {
    name    "numgroups"
    label   "Number of Groups"
    default 1
    parmtag { "multistartoffset" "1" }
    parm {
        name    "group#"
        label   "Group"
        type    string
        default { "" }
    }
    parm {
        name    "groupname#"
        label   "Group Name"
        type    string
        default { "" }
    }
}