M3D-core — Modular Agentic 3D/Game Development System (v0.2)

Reference implementation of the core contracts from the M3D Architecture Blueprint: a system where humans and agents co-develop games and 3D experiences by composing independently-runnable MCP modules into shareable, content-addressed DAG workflows.

Principles implemented here: every module works in isolation and over real MCP (stdio); every GLB artifact is content-addressed with an append-only provenance sidecar (.asset.json); human-gate nodes pause pipelines for manual/editor edits; license graphs are declared in every module manifest and validated at composition time.

Layout

m3d/
  module.py               # M3DModule SDK: manifest + MCP server (v2), in-process + stdio
  store.py                # content-addressed store: cas://<sha256[:12]>/<name>
  runner.py               # DAG runner: typed edges, human-gates, conditioned edges, provenance
  modules/gltf_mcp.py     # std/gltf-mcp: validate/inspect/rig_check/stats/optimize
  modules/mock_gen.py     # std/mock-generate: DAG test module
  modules/trellis_gen.py  # std/trellis-generate: REAL image->GLB via trellis-community/TRELLIS Space
                          #   (gradio_client; self-healing fallback_fn when the Space is degraded)
  modules/triposr_gen.py  # std/triposr-generate: REAL GPU generate module that RUNS AS AN HF JOB
                          #   (stabilityai/TripoSR, MIT; owns its runtime — no third-party availability risk)
  modules/mock_edit.py    # std/mock-texture + std/mock-sfx: edit-class stand-ins (same io kinds as real editors)
  modules/intent_planner.py  # std/intent-planner: agent-class L5 module — intent + .asset.json
                             #   -> executable edit DAG (human-gates included); pluggable LLM (llm(ctx)->plan)
scripts/proof_triposr.py  # GPU-proof script: bucket CAS + gltf-mcp validation (runs inside the TripoSR job)
workflows/sample_character.json
tests/                    # 10 passing tests incl. real MCP stdio round-trip

What v0.2 proves

1. Remote-Space modules + self-healing — std/trellis-generate calls trellis-community/TRELLIS (the MCP-enabled community fork; signature matched via view_api()) with std/mock-generate as declared fallback: degraded Space -> fallback runs, result marked "degraded": true (test: test_trellis_self_healing_fallback). Live note (2026-09-08): that Space currently fails its own app with AppError: FileNotFoundError on any client call (2 attempts, authenticated) — the fallback path is exactly what covers this.
2. HF Job as module runtime — std/triposr-generate generates a real GLB on GPU (a10g-small job m3d-triposr-gpu-proof), writes it into an HF Bucket CAS (jkorstad/m3d-artifacts, volume-mounted) and validates it with gltf-mcp.
3. Intent-driven editing (L5) — std/intent-planner reads .asset.json, maps an intent to per-modality edit nodes (module edits + Blender human-gates), and the emitted DAG runs through the same runner, approvals included (test_intent_plan_and_execute). Swap rule_based_planner for any open LLM: llm(ctx) -> plan is the whole interface.
4. Hosted MCP module — the Space adapter lives at jkorstad/m3d-gltf-mcp: 4 MCP tools (validate/inspect/rig_check/stats) auto-generated from typed functions, live at /gradio_api/mcp/ on a Gradio 6 Space.

Quickstart

pip install -r requirements.txt   # mcp==2.2.0, trimesh==5.1.0, pygltflib==1.16.5, numpy==2.5.3,
                                  # gradio_client==2.6.1, pillow==12.3.0
python -m pytest tests/ -q        # offline suite
python -m m3d.modules.gltf_mcp    # serve gltf-mcp over MCP stdio for any agent harness
M3D_LIVE=1 python -m pytest tests/test_trellis_live.py::test_trellis_live_generate -q
                                  # live TRELLIS call (GPU queue on the Space, minutes)

Contracts

• Module manifest — every module declares id, version, class (generate|edit|inspect|convert|agent|human-gate|engine), runtime type (hf-space | hf-job | docker | local-process), io kinds, license (code + model_licenses + usage_profiles), and health.fallbacks.
• Asset manifest — every GLB written through the runner gets <name>.asset.json with an append-only provenance chain (module@version per step). Partial regeneration = swapping one part URI; history travels with the asset.
• Workflow DAG — workflows/*.json: nodes reference modules (std/gltf-mcp@^0.1), edges are typed artifact kinds, "review[approve]->post" conditional gates.
• Self-healing ladder — retry -> fallback module (manifest-declared) -> degraded mode (marked in the result report) -> human-gate escape. Modules implement steps 2–3; std/trellis-generate demonstrates them in code and tests.

Test status (2026-09-08, Python 3.12)

Offline suite: 10 passed — module isolation, skinned-GLB rig detection, optimize-refuses-rigged, full DAG with human gate + provenance, MCP stdio validate round-trip, intent plan -> gated execution, TRELLIS fallback degradation, TripoSR fail-fast contract.

License

MIT for all code in this repo. Models referenced: TRELLIS-image-large (MIT), TripoSR (MIT). See the blueprint for the full license-compliance policy (non-commercial weights like FLUX.1-dev / Stable Audio are excluded from defaults by design).