houdini

Automate Houdini procedural workflows with VEX, the hou Python API, PDG/TOPs, and Solaris/Karma rendering.

SKILL.md

GitHub

SideFX Houdini AI Skill Guide (Claude)

Overview & Engine Architecture

SideFX Houdini is the industry-standard procedural VFX, procedural modeling, dynamic simulation, and USD-native pipeline tool. Claude operates as a Senior Houdini TD (Technical Director), specializing in VEX syntax and vector math, Python hou scripting via hython, Solaris USD / Karma XPU rendering, PDG/TOPs task-graph automation, and headless CLI simulation baking.

Houdini Context Architecture & Execution Pipeline

┌─────────────────────────────────────────────────────────────┐
│                 Houdini Context Architecture                │
│                                                             │
│  Context Domains                                            │
│  ├── SOPs (Surface Operators - Geometry & Modeling)         │
│  ├── DOPs (Dynamic Operators - FLIP, Pyro, Vellum, RBD)     │
│  ├── LOPs / Solaris (USD Scene Composition & Lighting)      │
│  ├── TOPs / PDG (Procedural Dependency Graph & Wedging)     │
│  └── Karma XPU (Hydra Delegate CPU/GPU Renderer)            │
│                                                             │
│  Programming & Scripting Interfaces                         │
│  ├── VEX (High-Performance SIMD Vector Expression Language) │
│  ├── `hou` (Python 3.11 Houdini Object Model API)           │
│  └── Hython / HBatch (Headless Batch Execution Interpreters)│
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

  1. VEX Code Generation & Optimization: Write vectorized, thread-safe VEX snippets for Attribute Wranglers, Volume Wranglers, and Point Deformation routines using @P, @v, @orient, and @pscale.
  2. Headless Python Automation (hython): Script standalone pipeline tools using hou to inspect scenes, dirty/cook TOP networks, parameterize HDAs, and trigger ROP nodes.
  3. Simulation Solver Tuning: Troubleshoot substepping, collision margins, pressure projection convergence, and spatial oversampling in Vellum, FLIP, and RBD solvers.
  4. Solaris & MaterialX USD Pipeline: Construct USD primitive hierarchies, configure Karma XPU shaders using MaterialX (mtlxstandard_surface), and set up AOV cryptomatte passes.

Production Python Automation: Headless Simulation Baker (hython)

Save this script as bake_simulation.py and run via hython to cook and cache heavy simulations to disk without opening the GUI:

"""
Headless Houdini Simulation & ROP Baker
Run via: hython bake_simulation.py <hip_file> <rop_node_path> [start_frame] [end_frame]
"""

import sys
import os
import hou

def bake_rop_node(hip_path: str, rop_path: str, start_frame: int = None, end_frame: int = None):
    if not os.path.exists(hip_path):
        print(f"Error: HIP file not found: {hip_path}")
        sys.exit(1)

    print(f"Loading scene: {hip_path}...")
    hou.hipFile.load(hip_path, suppress_save_prompt=True, ignore_load_warnings=True)

    target_node = hou.node(rop_path)
    if not target_node:
        print(f"Error: Node '{rop_path}' does not exist in scene.")
        sys.exit(1)

    # Set frame range override if specified
    if start_frame is not None and end_frame is not None:
        target_node.parm("trange").set(1) # Specific frame range
        target_node.parm("f1").set(start_frame)
        target_node.parm("f2").set(end_frame)
        target_node.parm("f3").set(1)

    print(f"Cooking node: {target_node.path()} from frame {target_node.evalParm('f1')} to {target_node.evalParm('f2')}...")
    
    try:
        # Execute ROP cook
        target_node.render(verbose=True, output_progress=True)
        print("Baking completed successfully.")
    except hou.Error as e:
        print(f"Cook failed: {e}")
        sys.exit(1)

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage: hython bake_simulation.py <scene.hip> <rop_path> [start] [end]")
        sys.exit(1)
        
    start = int(sys.argv[3]) if len(sys.argv) > 3 else None
    end = int(sys.argv[4]) if len(sys.argv) > 4 else None
    bake_rop_node(sys.argv[1], sys.argv[2], start, end)

Production VEX Snippet: Quaternion Point Rotation & Noise Advection

Use this snippet in a Point Wrangle SOP to orient instanced particles along a curl noise velocity vector:

// Calculate 3D Curl Noise Velocity Field
vector freq = chv("frequency");
vector offset = chv("offset") + @P * freq;
vector noise_v = curlnoise(offset);

// Blend existing velocity with noise
float blend = chf("noise_blend");
@v = lerp(@v, noise_v * chf("speed"), blend);

// Update Point Orientation Quaternion (@orient) to face velocity
vector up = {0, 1, 0};
if (length(@v) > 0.001) {
    matrix3 m = maketransform(normalize(@v), up);
    @orient = quaternion(m);
}

// Age-based scale falloff
float life_ratio = @age / @life;
@pscale = chf("base_scale") * (1.0 - smooth(0.7, 1.0, life_ratio));

Technical Troubleshooting Matrix

Issue & Failure Signature Root Cause Analysis Diagnostic & Resolution Pathway
FLIP Fluid Explosion at Frame 1 Particle separation too coarse relative to narrow collision geometry, or initial velocity creates divergence spikes. 1. Decrease Particle Separation on FLIP Object.<br>2. In FLIP Solver $\rightarrow$ Volume Motion, set Min Substeps to 2-4.<br>3. Enable Collision Separation on static collision objects.
Vellum Cloth Collision Penetration / Sticking Insufficient substeps or collision thickness is greater than distance between overlapping folds. 1. Increase Substeps on Vellum Solver (default is 10; increase to 25-40 for fine cloth).<br>2. Reduce thickness attribute on Vellum Cloth constraints.<br>3. Enable Layer Shock Absorber for multi-layered garments.
Karma XPU Shader Falling Back to CPU MaterialX network contains VEX-only VOP nodes unsupported on GPU hardware acceleration. 1. Replace classic VOP nodes with native MaterialX standard nodes (mtlxstandard_surface).<br>2. Check Houdini Console for XPU_WARNING_UNSUPPORTED_NODE.<br>3. Ensure GPU drivers match NVIDIA Studio / CUDA 12 requirements.
PDG / TOPs Work Items Hanging / Deadlock Work item output files were not written to the path expected by downstream dependency nodes. 1. Open PDG Service Monitor.<br>2. Inspect work item log: verify token $HIP or $PDG_DIR expansion matches output directory.<br>3. Select TOP node $\rightarrow$ Right-Click $\rightarrow$ Dirty and Cook Selected Node.

Command Line Syntax & Batch Processing

# Windows CLI: Headless Python Script Execution
"C:\Program Files\Side Effects Software\Houdini 20.5.278\bin\hython.exe" "C:\Pipeline\bake_pyro.py"

# Linux CLI: Render Solaris LOP USD Stage via Karma
hython -c "import hou; hou.hipFile.load('scene.hip'); hou.node('/stage/karma1').render()"

# Run HScript Command Line Engine
hbatch -c "render -Va /out/geometry_cache" "C:\Projects\destruction.hip"

Environment Configuration & Package Locations

  • Windows Environment: %USERPROFILE%\Documents\houdini20.5\houdini.env
  • Windows JSON Packages: %USERPROFILE%\Documents\houdini20.5\packages\*.json
  • Linux Environment: $HOME/houdini20.5/houdini.env
  • Critical Environment Variables:
  • HOUDINI_PATH: Custom tools, HDAs, and plugin search paths
  • HOUDINI_DSO_ERROR=1: Displays verbose C++ plugin/DSO load errors
  • OCIO: Path to custom ACES OpenColorIO configuration file

Agent Operational Directive

MANDATORY: For high-performance geometry deformation and point manipulation, write vectorized VEX wranglers rather than Python SOPs. When scripting headless batch pipelines, use hython and handle exceptions with explicit error logging.