parameters

parameters ¶

MCP tools for Houdini parameter operations.

Exposes 14 tools covering parameter get/set, expressions, channel references, locking, schema inspection, and spare parameter creation.

Functions:

Name	Description
`create_spare_parameter`	Add a spare parameter to a node.
`create_spare_parameters`	Batch-create multiple spare parameters in one call, optionally in a folder tab.
`get_expression`	Get the expression on a parameter.
`get_parameter`	Get the value and metadata of a parameter.
`get_parameter_schema`	Get the template schema for parameter(s) on a node.
`get_parameters`	Read many parameter values at once, matched by name or label substring.
`get_parm_references`	Who references a parameter, and what it references — in one call.
`get_parm_template_tree`	The whole parameter interface as a tree, the way Type Properties shows
`link_parameters`	Create a channel reference from one parameter to another.
`lock_parameter`	Lock or unlock a parameter.
`promote_vop_parameters`	Promote VOP inputs to parameters, as the network editor's Promote Parameter does.
`revert_parameter`	Revert a parameter to its default value.
`set_expression`	Set an expression on a parameter.
`set_parameter`	Set a parameter value.
`set_parameters`	Batch-set multiple parameters on a node, in the order given.

Functions:¶

create_spare_parameter `async` ¶

create_spare_parameter(
    ctx: Context,
    node_path: str,
    parm_name: str,
    parm_type: str,
    label: str,
    default_value: Value | None = None,
    min_val: float | None = None,
    max_val: float | None = None,
    menu_items: list[str | list[str]] | None = None,
) -> dict

Add a spare parameter to a node.

A menu needs its items: a menu without any is refused, not created with Houdini's "none" placeholder. The reply reads the menu back from the node (menu_items as [value, label] pairs, default_value as a value).

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str`	Internal parameter name.	required
`parm_type` ¶	`str`	"float", "int", "string", "toggle", or "menu".	required
`label` ¶	`str`	UI label.	required
`default_value` ¶	`Value \| None`	Default value. For a menu, the default item by value or index.	`None`
`min_val` ¶	`float \| None`	Minimum value (float/int only).	`None`
`max_val` ¶	`float \| None`	Maximum value (float/int only).	`None`
`menu_items` ¶	`list[str \| list[str]] \| None`	A menu's items, as set_hda_interface takes them: plain strings, or [value, label] pairs such as [["0", "Uniform"], ["1", "By Attribute"]].	`None`

create_spare_parameters `async` ¶

create_spare_parameters(
    ctx: Context,
    node_path: str,
    parameters: list[dict[str, Any]],
    folder_name: str | None = None,
    folder_type: str = "Tabs",
) -> dict

Batch-create multiple spare parameters in one call, optionally in a folder tab.

A name that already exists as a spare parameter is updated in place (label, default, range); its current value and keyframes are kept. A type change on an existing parameter is refused.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parameters` ¶	`list[dict[str, Any]]`	List of parameter specs. Each dict has keys: parm_name (str), parm_type (str: "float"/"int"/"string"/"toggle"/"menu"), label (str), default_value (optional), min_val (optional), max_val (optional), menu_items (a menu's items: strings or [value, label] pairs, as in create_spare_parameter; default_value then picks one).	required
`folder_name` ¶	`str \| None`	If provided, wraps all parameters in a named folder tab.	`None`
`folder_type` ¶	`str`	Folder style: "Tabs", "Collapsible", or "Simple".	`'Tabs'`

get_expression `async` ¶

get_expression(ctx: Context, node_path: str, parm_name: str) -> dict

Get the expression on a parameter.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str`	Parameter name.	required

get_parameter `async` ¶

get_parameter(ctx: Context, node_path: str, parm_name: str) -> dict

Get the value and metadata of a parameter.

A ramp reads as {"type": "Ramp", "basis", "keys", "values", "is_color"}, which set_parameters and build_network take back as it is.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str`	Parameter name.	required

get_parameter_schema `async` ¶

get_parameter_schema(
    ctx: Context,
    node_path: str,
    parm_name: str | None = None,
    filter: str | None = None,
) -> dict

Get the template schema for parameter(s) on a node.

Most nodes have dozens of parameters; many have 100+. Always use parm_name or filter unless you genuinely need the full list.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str \| None`	Exact parameter name for a single-parameter lookup.	`None`
`filter` ¶	`str \| None`	Substring to match against parameter name or label (case-insensitive). Use instead of dumping all params.	`None`

get_parameters `async` ¶

get_parameters(
    ctx: Context,
    node_path: str | None = None,
    patterns: list[str] | None = None,
    include_defaults: bool = False,
    inside: str | None = None,
    recursive: bool = False,
    node_type: str | None = None,
    include_locked_assets: bool = False,
    value_contains: str | None = None,
    non_default_only: bool = False,
) -> dict

Read many parameter values at once, matched by name or label substring.

The batch counterpart of set_parameters. Several unrelated groups of settings ("flame", "wind", "buoy") come back in one call instead of one call each, and unlike get_node_card these are the live values on this node rather than the defaults for its type.

Pass inside instead of node_path to read the same patterns across a whole network in one call: "every file parm of this material library, unexpanded" comes back as rows of {node, parm, value, raw_value}, up to 2000 rows. raw_value is the unexpanded text ($JOB/...), shown when it differs from the value, exactly as for a single node.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str \| None`	Node to read.	`None`
`patterns` ¶	`list[str] \| None`	Substrings matched against parameter name and label. Omit for everything, up to the cap. Required with `inside`, unless non_default_only or value_contains.	`None`
`include_defaults` ¶	`bool`	Also report whether each value is still the default, and, where it differs, the default (`default`, `default_expression`).	`False`
`inside` ¶	`str \| None`	Network to read instead of a single node.	`None`
`recursive` ¶	`bool`	With `inside`, include every descendant, not only children. Nodes inside locked HDAs (a solver's own internals) are skipped and counted in `skipped_inside_locked_assets`.	`False`
`node_type` ¶	`str \| None`	With `inside`, only nodes of this type (e.g. "mtlximage").	`None`
`include_locked_assets` ¶	`bool`	With `recursive`, read inside locked HDAs too.	`False`
`value_contains` ¶	`str \| None`	Only parameters whose raw text or expression holds this substring (case-insensitive), e.g. inside="/", recursive=True, value_contains="/obj/X": every parameter that still names that node by its absolute path, a deleted one included. A relative "../X" is not "/obj/X": search "X" to catch those. No patterns needed.	`None`
`non_default_only` ¶	`bool`	Only parameters changed from their defaults, each with its default: "what was changed on every node of this network" in one call (with `inside`, no patterns needed). A changed ramp is one entry holding all its keys; its key parms (`ramp2pos`...) are listed only when a pattern names them and not the ramp.	`False`

get_parm_references `async` ¶

get_parm_references(
    ctx: Context,
    node_path: str,
    parm_name: str | None = None,
    direction: str = "both",
    limit: int = 200,
    include_node_level: bool | None = None,
) -> dict

Who references a parameter, and what it references — in one call.

incoming: for each parameter of the node (or just parm_name), the parameters elsewhere whose expressions read it — what breaks if this control is renamed. outgoing: what this node's expressions and backtick strings read, resolved to parameter paths (pure ch() links and richer expressions alike; unresolved names a written target that no longer exists). node_dependents / node_references give the node-level view for this node only; include_node_level in the reply says whether they were included.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node to inspect.	required
`parm_name` ¶	`str \| None`	One parameter instead of all of them.	`None`
`direction` ¶	`str`	"both", "incoming" or "outgoing".	`'both'`
`limit` ¶	`int`	Cap on reported entries.	`200`
`include_node_level` ¶	`bool \| None`	Include node_dependents / node_references. Default: on for a whole-node query, off when parm_name names one parameter; on an asset with hundreds of children those lists run to about 100 KB and answer a question about the node, not the parameter.	`None`

get_parm_template_tree `async` ¶

get_parm_template_tree(
    ctx: Context,
    node_path: str | None = None,
    type_name: str | None = None,
    context: str = "Sop",
    folder: str | list[str] | None = None,
    max_entries: int = 150,
    include_tags: bool = False,
) -> dict

The whole parameter interface as a tree, the way Type Properties shows it: folders (with folder_type — tabs, collapsible, multiparm), every parameter in order with defaults, default expressions, ranges, menu items, Hide/Disable When conditionals, callbacks, naming scheme; a multiparm's default_instances. Each entry uses get_parameter_schema's keys (default_value, is_hidden, menu_items...).

get_hda_info shows only the top folders and get_parameter_schema flattens the structure away; read this before editing an interface. Give node_path for a node (its instance interface, spares included) or type_name + context for a type.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str \| None`	Node whose interface to read.	`None`
`type_name` ¶	`str \| None`	Node type instead (with context).	`None`
`context` ¶	`str`	Category of type_name — "Sop", "Object", "Lop", ...	`'Sop'`
`folder` ¶	`str \| list[str] \| None`	Narrow to one folder by label, or a list of nested labels.	`None`
`max_entries` ¶	`int`	Cap on entries (depth-first); the reply says when it cut.	`150`
`include_tags` ¶	`bool`	Also return each template's tags (needed to preserve them when editing an interface; about a quarter of the size).	`False`

link_parameters `async` ¶

link_parameters(
    ctx: Context,
    source_path: str,
    source_parm: str,
    dest_path: str,
    dest_parm: str,
    replace_existing: bool = False,
) -> dict

Create a channel reference from one parameter to another.

The destination gets an HScript expression that reads the source as its own type: chs() for a String parameter, ch() for numbers, toggles and menus. The path is relative to the destination node (chs("../CTRL/mat")), so the link survives moving the pair, collapsing into a subnet or instancing an HDA. The reply carries the expression, the function used and the destination's evaluated value.

Two ramps (or two multiparms) are linked entry by entry as well, now and whenever the source gains or loses keys: the opmultiparm links Promote Parameter makes. The reply lists multiparm_links and follows_source. Inside an asset, update_hda afterwards to keep the link in its contents.

Parameters:

Name	Type	Description	Default
`source_path` ¶	`str`	Source node path.	required
`source_parm` ¶	`str`	Source parameter name.	required
`dest_path` ¶	`str`	Destination node path.	required
`dest_parm` ¶	`str`	Destination parameter name.	required
`replace_existing` ¶	`bool`	Overwrite a destination that already has keyframes or an expression. Refused otherwise, so animation is never lost by accident. A link whose source already reads the destination through ch() is refused as a cycle in every case.	`False`

lock_parameter `async` ¶

lock_parameter(
    ctx: Context, node_path: str, parm_name: str, locked: bool
) -> dict

Lock or unlock a parameter.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str`	Parameter name.	required
`locked` ¶	`bool`	True to lock, False to unlock.	required

promote_vop_parameters `async` ¶

promote_vop_parameters(ctx: Context, promotions: list[dict[str, Any]]) -> dict

Promote VOP inputs to parameters, as the network editor's Promote Parameter does.

Each input gets a Parameter VOP wired in, and its parm appears on the VOP network that owns it (POP VOP, Attribute VOP, ...): the owner is compiled once for the whole batch, and the reply names, per input, the parm and the node it landed on, with its value. Nothing is promoted if any item is wrong; an input that is already wired is refused, not rewired.

Parameters:

Name	Type	Description	Default
`promotions` ¶	`list[dict[str, Any]]`	One dict per input: node_path (the VOP node), input (its input name, e.g. "input2", "destmin"), and optionally name (the parm name; default the input's), label, kind ("parameter", "constant" or "subnet_input"; default "parameter") and use_input_value (start from the input's current value; default True).	required

revert_parameter `async` ¶

revert_parameter(ctx: Context, node_path: str, parm_name: str) -> dict

Revert a parameter to its default value.

A default that is itself an expression comes back, named in default_expression with its default_expression_language; expression_error says when it does not evaluate.

A locked parameter cannot be reverted; the error names what sets the lock.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str`	Parameter name.	required

set_expression `async` ¶

set_expression(
    ctx: Context,
    node_path: str,
    parm_name: str,
    expression: str,
    language: str = "hscript",
) -> dict

Set an expression on a parameter.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str`	Parameter name.	required
`expression` ¶	`str`	Expression string.	required
`language` ¶	`str`	"hscript" (default) or "python".	`'hscript'`

set_parameter `async` ¶

set_parameter(
    ctx: Context,
    node_path: str,
    parm_name: str,
    value: Value,
    override_expression: bool = False,
    run_callbacks: bool = False,
) -> dict

Set a parameter value.

A parameter that holds an expression does NOT take a literal: Houdini writes the value into a slot the expression keeps overriding. The reply then carries expression_kept: true with the surviving expression and what you requested (plus same_as_evaluated when the expression happens to evaluate to that value right now) — read those before calling the write done. Pass override_expression=True to clear the expression first.

A parameter holding a BARE ch() reference is the opposite trap: Houdini writes THROUGH it into the parameter it reads, so the value lands on another node. The reply names that parameter in written_through.

Inside a DOP network a write does not reset frames already simulated: simulation_cache names the network to pass to reset_simulation.

A String parameter echoes raw_value (the unexpanded text, $JOB/...) next to the expanded new_value.

A list with {"expr": ...} components ("t": [{"expr": "$F"}, 0, 0]) and a whole ramp ({"keys", "values", "basis"}) go through set_parameters: this tool's value takes plain values only.

A LOCKED parameter (karmarendersettings resolutiony under res_mode autoheight) takes nothing at all; the error names the menu whose callback sets the lock. Houdini runs such callbacks only from the UI: set that menu with run_callbacks=True first, then the locked parameter.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`parm_name` ¶	`str`	Parameter name.	required
`value` ¶	`Value`	New value (int, float, string, bool, or list).	required
`override_expression` ¶	`bool`	Remove an expression standing in the way, instead of reporting that the write did not take.	`False`
`run_callbacks` ¶	`bool`	Run the parameter's callback script after the write, as editing it in the UI does (`callback_run` in the reply, and `callback_error` when the callback raised).	`False`

set_parameters `async` ¶

set_parameters(
    ctx: Context,
    node_path: str,
    params: dict[str, Any],
    override_expression: bool = False,
    run_callbacks: bool = False,
) -> dict

Batch-set multiple parameters on a node, in the order given.

Expressions go in the same call: {"tx": {"expr": "ch('../size')"}} sets an expression, so no set_expression per parameter is needed.

Inside a DOP network a write does not reset frames already simulated: simulation_cache names the network to pass to reset_simulation.

Parameters that held an expression and therefore ignored the literal are listed in expressions_kept, with a top-level warning: a batch whose errors is empty can still contain a write that did not take. Values that landed on ANOTHER node, because the parameter is a bare ch() reference Houdini writes through, are in written_through. Each entry in set carries the same keys as set_parameter's reply. Pass override_expression=True to clear those expressions and links instead.

Locked parameters are in errors with locked: true and listed in locked_parms; the error names the menu whose callback sets the lock. With run_callbacks=True each parameter's callback runs after its write, so {"res_mode": "manual", "resolutiony": 1080} unlocks and then writes; a callback that raised is listed in callbacks_not_run.

Parameters:

Name	Type	Description	Default
`node_path` ¶	`str`	Node path.	required
`params` ¶	`dict[str, Any]`	Mapping of parameter names to values, written in this order. A value written {"expr": "...", "language": "hscript" \| "python"} is set as an expression, as in build_network, also as one component of a list ("t": [{"expr": "$F"}, 0, 0]). A ramp takes the whole ramp at once: {"keys": [0, 1], "values": [[1, 0, 0], [0, 0, 1]], "basis": "linear"} (one basis or one per key; a float ramp takes numbers), the shape get_parameter reads it in. A ramp's `new_value` is what it holds once the whole call is through, so a key added by count and then set reads as set.	required
`override_expression` ¶	`bool`	Remove expressions standing in the way.	`False`
`run_callbacks` ¶	`bool`	Run each parameter's callback script after its write, as the UI does.	`False`

parameters

parameters ¶

Functions:¶

create_spare_parameter async ¶

node_path ¶

parm_name ¶

parm_type ¶

label ¶

default_value ¶

min_val ¶

max_val ¶

menu_items ¶

create_spare_parameters async ¶

node_path ¶

parameters ¶

folder_name ¶

folder_type ¶

get_expression async ¶

node_path ¶

parm_name ¶

get_parameter async ¶

node_path ¶

parm_name ¶

get_parameter_schema async ¶

node_path ¶

parm_name ¶

filter ¶

get_parameters async ¶

node_path ¶

patterns ¶

include_defaults ¶

inside ¶

recursive ¶

node_type ¶

include_locked_assets ¶

value_contains ¶

non_default_only ¶

get_parm_references async ¶

node_path ¶

parm_name ¶

direction ¶

limit ¶

include_node_level ¶

get_parm_template_tree async ¶

node_path ¶

type_name ¶

context ¶

folder ¶

max_entries ¶

include_tags ¶

link_parameters async ¶

source_path ¶

source_parm ¶

dest_path ¶

dest_parm ¶

replace_existing ¶

lock_parameter async ¶

node_path ¶

parm_name ¶

locked ¶

promote_vop_parameters async ¶

promotions ¶

revert_parameter async ¶

node_path ¶

parm_name ¶

set_expression async ¶

node_path ¶

parm_name ¶

expression ¶

language ¶

set_parameter async ¶

node_path ¶

parm_name ¶

value ¶

override_expression ¶

run_callbacks ¶

set_parameters async ¶

node_path ¶

params ¶

override_expression ¶

create_spare_parameter `async` ¶

`node_path` ¶

`parm_name` ¶

`parm_type` ¶

`label` ¶

`default_value` ¶

`min_val` ¶

`max_val` ¶

`menu_items` ¶

create_spare_parameters `async` ¶

`node_path` ¶

`parameters` ¶

`folder_name` ¶

`folder_type` ¶

get_expression `async` ¶

`node_path` ¶

`parm_name` ¶

get_parameter `async` ¶

`node_path` ¶

`parm_name` ¶

get_parameter_schema `async` ¶

`node_path` ¶

`parm_name` ¶

`filter` ¶

get_parameters `async` ¶

`node_path` ¶

`patterns` ¶

`include_defaults` ¶

`inside` ¶

`recursive` ¶

`node_type` ¶

`include_locked_assets` ¶

`value_contains` ¶

`non_default_only` ¶

get_parm_references `async` ¶

`node_path` ¶

`parm_name` ¶

`direction` ¶

`limit` ¶

`include_node_level` ¶

get_parm_template_tree `async` ¶

`node_path` ¶

`type_name` ¶

`context` ¶

`folder` ¶

`max_entries` ¶

`include_tags` ¶

link_parameters `async` ¶

`source_path` ¶

`source_parm` ¶

`dest_path` ¶

`dest_parm` ¶

`replace_existing` ¶

lock_parameter `async` ¶

`node_path` ¶

`parm_name` ¶

`locked` ¶

promote_vop_parameters `async` ¶

`promotions` ¶

revert_parameter `async` ¶

`node_path` ¶

`parm_name` ¶

set_expression `async` ¶

`node_path` ¶

`parm_name` ¶

`expression` ¶

`language` ¶

set_parameter `async` ¶

`node_path` ¶

`parm_name` ¶

`value` ¶

`override_expression` ¶

`run_callbacks` ¶

set_parameters `async` ¶

`node_path` ¶

`params` ¶

`override_expression` ¶

`run_callbacks` ¶