Mecha Blender Plugin

The Mecha Blender Plugin is a production-ready add-on for Blender 3.6 LTS and 4.x that assembles humanoid mecha with interchangeable components. It creates clean armatures with deterministic naming, mirrors attachments across limbs, previews component variants before import, and integrates external generation providers such as Meshy via an extensible API.

Features

• Humanoid rig generator – produces either a Rigify-ready metarig or a clean basic armature with .L/.R naming and correct bone rolls.
• Attachment sockets – adds named empties aligned to standard hardpoints (shoulder, forearm, backpack) with consistent axes.
• Modular component library – ships with swappable heads, torsos, arms, legs, shoulder weapons, hand weapons, backpacks, and wings.
• Preview workflow – the in-viewport Mecha N-panel exposes Base, Components, Preview, API, Mirror, and Utilities tabs for browsing variants and running operators.
• Provider interface – supports a local cache-backed provider and a Meshy HTTP provider for remote asset generation with job polling and downloads.
• Caching and logging – configurable cache directories, thumbnail paths, and log verbosity from the add-on preferences.
• Automated tests – pytest suite covers the importer, aligners, mirroring logic, and Meshy provider stubs without requiring Blender at runtime.

Repository Layout

mecha_blender_plugin/
  __init__.py            # Blender add-on entry point and registration
  addon_prefs.py         # Persistent add-on preferences (API keys, defaults, directories)
  apis/                  # Provider protocol, Meshy implementation, registry, local provider
  core/                  # Rig generation, components, attach points, alignment, caching, logging
  ui/                    # N-panel tabs and preview operators
  assets/
    cache/               # Cached downloads (configurable)
    thumbs/              # Generated previews
    templates/           # Geometry node groups / templates (placeholder directory)
CHANGELOG.md
LICENSE
README.md
requirements-dev.txt
tests/
  test_aligners.py
  test_api_meshy.py
  test_importer.py
  test_mirroring.py

Installation

1. Zip the mecha_blender_plugin folder or install the repository directory directly inside Blender via Edit ▸ Preferences ▸ Add-ons ▸ Install….
2. Enable Mecha Blender Plugin from the list of add-ons.
3. Configure preferences (Meshy API key/endpoint, default rig type, cache & thumbnail directories, mirroring options) in Edit ▸ Preferences ▸ Add-ons ▸ Mecha Blender Plugin.
4. Open the Mecha tab in the 3D Viewport sidebar to generate a base rig, add attachment points, preview components, and trigger imports.

External Providers

The provider registry registers a cache-backed Local provider by default. Supplying a Meshy API key activates the Meshy provider, which:

• Submits prompts to the configured Meshy endpoint.
• Polls job status until an asset URL is available.
• Downloads the generated GLB/FBX/OBJ into the configured cache directory.

Custom providers can implement the AssetProvider protocol and register with providers_registry.get_registry().register(...).

Development

pip install -r requirements-dev.txt  # optional helper for pytest
pytest

Tests run outside Blender thanks to conditional imports and stubs. Keep logic pure-Python where possible and gate Blender-only calls behind try/except ImportError guards.

Logging & Cache

Logging defaults to INFO level; enable debug output from the preferences. Cache files are written as JSON blobs into the configured directory (default assets/cache). Thumbnail renders should be stored under assets/thumbs.

Contributing

• Maintain deterministic bone and component naming (.L/.R).
• Keep operations non-destructive and mirror-safe.
• Extend the pytest suite when adding new systems or providers.
• Update the changelog alongside README when shipping new features.