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.
`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.

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

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.

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 ¶

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 ¶

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` ¶

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` ¶