git clone https://git.lucas.co/hou-control.git
GEMINI.md (2.3K)
1 # Project Overview: hou-control
2
3 `hou-control` is a specialized Houdini environment and toolset designed to enhance the user interface, automate session management, and provide custom modeling and simulation operators. It bridges Houdini with external AI agents via a Model Context Protocol (MCP) server.
4
5 ## Architecture & Technology Stack
6
7 - **Houdini Python API (hou):** Core integration for UI manipulation and node graph control.
8 - **PySide6:** Used for custom Qt-based UI elements (HC Status, Floating Layouts).
9 - **RPyC:** Enables remote procedure calls between the external MCP server and the internal Houdini session.
10 - **FastMCP:** Powers the Model Context Protocol server for AI-driven interaction.
11 - **Operator Sets:**
12 - **GEM (General Export Methods):** Manufacturing and export-focused HDAs.
13 - **Developer (Shapeshifter):** Simulation and surface development tools.
14
15 ## Key Components
16
17 - **`python3.11libs/hc/`**: Core logic for session management, hotkey binding, and UI overlays.
18 - **`mcpserver/`**: Contains the `houdini_mcp.py` server which allows external agents to evaluate code in Houdini.
19 - **`viewer_states/keycam.py`**: A custom viewer state for keyboard-driven camera navigation using the official `PluginHotkeyDefinitions` system.
20 - **`config/`**: Contains UI theme files, custom cursors, and node shape definitions.
21
22 ## Building and Running
23
24 Houdini automatically loads the package if the directory is added to the `HOUDINI_PATH`.
25
26 - **Start Houdini with HC:** Ensure `uiready.py` is in your Houdini search path; it initializes the session and starts the RPyC server.
27 - **Start MCP Server:**
28 ```bash
29 source mcpserver/.venv/bin/activate
30 python mcpserver/houdini_mcp.py
31 ```
32 - **Tests:** Currently, verification is performed manually within the Houdini session or via RPyC evaluation.
33
34 ## Development Conventions
35
36 - **Surgical Updates:** (MANDATORY) Never remove or refactor unrelated code. Maintain all existing parameters, menu items, and logic.
37 - **Hotkey Management:** Use the official `hou.PluginHotkeyDefinitions` for viewer states to ensure proper context scoping.
38 - **Node Tagging:** Use `hc_custom_color: "1"` user data to identify nodes that should be affected by global style updates.
39 - **Communication:** Use the RPyC server (port 18811) for speculative research and debugging within the live environment.