git clone https://git.lucas.co/hou-control.git
AGENTS.md (2.9K)
1 # Repository Guidelines
2
3 ## Project Structure & Module Organization
4
5 `hou-control` is a SideFX Houdini package, not a standalone app. Core Python code lives in `python3.11libs/hc/`, where wrapper classes such as `HCSession`, `HCPane`, and `HCNetworkEditor` extend Houdini behavior without subclassing `hou.*` types. Houdini startup hooks live in `python3.11libs/uiready.py` and `python3.11libs/nodegraphhooks.py`. Session scripts are in `scripts/` (`123.py`, `456.py`, `OnCreated.py`). UI and package assets are organized under `config/`, `desktop/`, `radialmenu/`, `toolbar/`, `presets/`, `viewer_states/`, `vex/`, `help/`, and `otls/`.
6
7 ## Build, Test, and Development Commands
8
9 There is no build system for this repository; Houdini loads it at runtime through `houdini-studio-utils.json`.
10
11 - `python mcpserver/houdini_mcp.py`: starts the local MCP bridge for driving a running Houdini session.
12 - `python -m py_compile python3.11libs/hc/*.py python3.11libs/*.py scripts/*.py`: quick syntax check outside Houdini.
13 - In Houdini, use the `hc` menu actions `Reload Hotkeys`, `Reload Colors`, and `Reload Keycam` to validate targeted changes.
14 - For full reloads in Houdini, use `hou.ui.reloadPackage(...)` via `HCSession.reloadHC()`.
15
16 ## Coding Style & Naming Conventions
17
18 Follow the existing Python style: 4-space indentation, `snake_case` for functions/methods, `CapWords` for wrapper classes, and concise docstrings only where behavior is not obvious. Keep filesystem paths dynamic by reading `hou.getenv("HC_PATH")`; do not hardcode machine-specific paths. New commands should be implemented on the appropriate wrapper in `python3.11libs/hc/` and then registered in `hcmaps.py` if they must appear in the HC panel.
19
20 ## Testing Guidelines
21
22 There is no committed automated test suite yet. Validate changes by reloading the affected subsystem inside Houdini and exercising the relevant pane, viewer state, menu, or hotkey. For hotkey work, update `hc_hotkeys.json` and confirm conflict handling through `HCBindings`. If you add nontrivial Python logic, run the `py_compile` check before manual Houdini verification.
23
24 ## Commit & Pull Request Guidelines
25
26 Recent history favors short, scoped subjects such as `hc: fix phantom zoom when pressing Ctrl in Network Editor` or `UI: make locked camera pill and mask colors paler`. Use a lowercase area prefix when possible (`hc:`, `keycam:`, `UI:`) followed by an imperative summary. PRs should explain user-visible behavior, list the Houdini contexts exercised, and include screenshots or short clips for UI, node graph, or viewer-state changes.
27
28 ## Configuration & Runtime Notes
29
30 This package runs inside Houdini's embedded Python 3.11. Many features depend on Houdini filename conventions and package loading, so preserve names such as `uiready.py`, `123.py`, and `456.py`. Treat `otls/` and Houdini config files as runtime assets and verify them in an actual Houdini session before merging.