Development

Contributions are welcome! Please create an issue to discuss significant work before starting. Open all PRs to the dev branch.

Pull Request Process

1. Fork the repository and create a branch matching the issue name.
2. Add the feature/fix with accompanying unit tests.
3. Run tests and ensure all pass.
4. Submit PR to dev with updated documentation.

Note

New features require accompanying unit tests to be approved.

Prerequisites

• VS Code (recommended for pre-configured profiles)
• Python 3.11
• uv (Python package manager)
• Git with Git LFS
• Blender 4.5+

Setup

Using UV (Recommended)

# pip install uv (if not installed) however system wide install is more ideal. (See instal link above)
pip install uv

# Create venv and install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

Using VS Code

1. Open the workspace - VS Code will prompt to install recommended extensions from .vscode/extensions.json
2. Copy .env.example to .env
3. Restart VS Code
4. Run > Python: Select Interpreter and choose .venv/Scripts/python.exe

Build Tasks

Launch Blender/Unreal through VS Code build tasks (CTRL+SHIFT+B) to enable dev dependencies and debugging.

Note

Selecting "debug" will hang the app until you attach via debugpy in VS Code.

Note

Override executable paths via .env: UNREAL_EXE_PATH, UNREAL_PROJECT, BLENDER_EXE_PATH

Launch Actions

Use Python Debugger: Attach to connect to Blender after launching from build tasks.

Reloading Addon Code

Blender (when launched from VS Code):

from poly_hammer_utils.helpers import reload_addon_source_code
reload_addon_source_code(['meta_human_dna'])

Code Quality

All code is checked via pre-commit hooks and CI:

• Ruff: Linting and formatting (configured in pyproject.toml)
• CSpell: Spell checking (configured in cspell.json)
• Pyright: Type checking (configured in pyproject.toml)

Run checks manually:

uv run pre-commit run --all-files
uv run ruff check .
uv run ruff format --check .

Type Stubs (Optional)

For better IDE autocomplete with bpy, install type stubs into a separate virtual environment:

uv venv .stubs-venv
uv pip install --python .stubs-venv/Scripts/python.exe -e ".[stubs]"

Warning

Do not install stubs into the main .venv—they conflict with the real bpy package.