Skip to content

shelf

shelf

MCP tools for Houdini's shelf tools.

Some setups are authored by a shelf tool rather than by node creation -- the ocean procedural's internals come from dopparticlefluidtoolutils.largeOcean -- so build_network structurally cannot produce them, and reading SideFX's own recipe is often more valuable than running it.

Functions:

Name Description
get_shelf_tool_script

Read the script a shelf tool runs, plus its help and imports.
list_shelf_tools

Find shelf tools by name, label or keyword.
run_shelf_tool

Run a shelf tool and report the nodes it created.

Functions:

get_shelf_tool_script async 

get_shelf_tool_script(ctx: Context, tool_name: str) -> dict

Read the script a shelf tool runs, plus its help and imports.

This is how you learn SideFX's own recipe instead of reinventing it. Most scripts are two or three lines calling a worker in a toolutils module, and the reported imports name exactly what to read next.

Parameters:

Name Type Description Default
tool_name
str

Internal tool name, from list_shelf_tools.

 required

list_shelf_tools async 

list_shelf_tools(
    ctx: Context, filter: str | None = None, limit: int = 60
) -> dict

Find shelf tools by name, label or keyword.

Use this when a setup exists as a shelf tool rather than as a node: oceans, quick sims, rigging setups. A full install ships around 8,000 of them, so always filter.

Parameters:

Name Type Description Default
filter
str | None

Substring matched against name, label and keywords.

 None
limit
int

Maximum tools to return.

 60

run_shelf_tool async 

run_shelf_tool(
    ctx: Context,
    tool_name: str,
    kwargs: dict[str, Any] | None = None,
    parent_path: str | None = None,
    selection: list[str] | None = None,
    dop_network: str | None = None,
) -> dict

Run a shelf tool and report the nodes it created.

A tool that asks for objects takes selection, or the objects already selected, as in Houdini. A tool that asks for anything else is retried once as a Ctrl+click, Houdini's "place immediately" (ran_as_ctrl_click): the Crowds Simulate tool then builds its whole default crowd. A tool that still asks (the FLIP ocean layer, collide-with) is refused, since through the bridge it would block Houdini until someone clicks: read the recipe with get_shelf_tool_script and build the nodes with build_network.

Nodes the tool added inside networks that already existed (a FLIP tool into the current POP network) are listed in created_in_existing; current_dop_network says where DOP tools put theirs, before and after. A tool that creates a DOP network (model_popnet) does not make it the current one, so the next DOP tool would build into the previous network: pass that network as dop_network.

A tool whose script fails has what it built removed, and the error names it. A dialog tool refused for its question names, when there is one, a tool that builds the same branch without asking.

Parameters:

Name Type Description Default
tool_name
str

Internal tool name, from list_shelf_tools.

 required
kwargs
dict[str, Any] | None

Overrides merged into the synthetic kwargs the script reads.

 None
parent_path
str | None

An extra network to watch for new nodes. /obj, /stage, /out, /mat and /img are always watched, because a shelf tool is free to build in more than one of them: largeOcean creates both a geo in /obj and a LOP in /stage. A SOP network given here is also where a SOP tool places its nodes (placed_in).

 None
selection
list[str] | None

Object paths the tool takes as its object selection. The scene's selection is left as it was, whatever the tool selects.

 None
dop_network
str | None

DOP network to make current before the run (hou.setCurrentDopNet), where DOP tools build. It stays current afterwards, as when an artist picks it.

 None