# VibeInc AI Art Team

An open-source, AI-first Blender toolkit: an "art team" of roles that agents (Claude Code, through MCP) and
people (through a Blender panel) can drive. Every action runs in headless Blender too, returns machine-readable
JSON, and measures its own output.

Made by [VibeInc](#studio-and-privacy), an AI-first game studio. The core tool is free and always will be.

![Concept to game-ready mesh](evidence/radio_eevee.png)

*GPT concept, then TRELLIS.2 on the local GPU, then Blender cleanup to 12k triangles, 35 cm tall, pivot at the base.
Rendered with `render_still`.*

## How it works

You, or Claude, ask for something in plain words. The request becomes one of 28 tools, and Blender does the work in
the background. Each tool returns what it made, along with its own checks: triangle count, scale, pivot,
clearance from walls, and whether anything is cropped. When a check fails, the agent can fix the problem before you
ever see it.

![Draft vs best quality](evidence/radio_draft_vs_hq.png)

*The same concept at TRELLIS.2 draft quality (left) and best quality (right), after Blender cleanup.*

## Why it makes the work easier

- **Idea to game-ready prop in about 5 minutes:** 45 s of concept art, about 3 min of 3D on a free 16 GB GPU, then
  seconds of cleanup.
- **The boring part is automatic:** scale, pivots, UVs, triangle budgets and GLB/FBX exports.
- **Blockouts and camera passes in seconds:** the same seed gives the same level, and walkthroughs never clip
  through walls.
- **No new subscriptions:** it uses your ChatGPT plan, your GPU and free Blender.
- **Agents can run it unattended:** results are plain JSON with pass/fail checks, so Claude knows whether each step
  worked.

## What works today (v0.1.0)

| Role | Engine | Status | Tool(s) |
|---|---|---|---|
| Concept artist | GPT image generation through your ChatGPT plan (Codex app); or the OpenAI API with your key | Works (API path untested: no key here) | `concept` |
| 3D artist | TRELLIS.2 on your GPU, then Blender cleanup | Works | `image_to_mesh`, `cleanup_mesh` |
| Surfacing | Script-built PBR presets, bake to maps, photo to PBR | Works | `assign_material`, `photo_to_pbr`, `list_material_presets` |
| Layout | Seeded or spec-driven greybox levels | Works | `greybox` |
| Camera | Orbit, greybox flythrough, explicit paths | Works | `camera_path` |
| Render | Workbench (viewport look), EEVEE, Cycles on CPU; studio lighting; image sequences for turntables and flythroughs | Works | `render_still`, `studio_setup`, `render_frames` |
| Animator | BVH import (100STYLE, CC BY 4.0) | BVH import works. **Auto-rig is a stub.** Kimodo is blocked until a Hugging Face login. | `import_motion`, `list_motion_styles`, `autorig` |
| Sound | Search your own library | Search works. **Generation is a stub.** | `sound_search`, `sound_generate` |
| One shot | Concept → mesh → cleanup → render | Works | `make_prop` |

Plus: `status`, `list_providers`, `connect_provider`, `package_asset`, `verify_package`, `about`,
`usage_stats`, `live_blender`, `job_status`, `import_asset`, `scene_report`.

## Quick start

Requirements: Blender 4.2 or newer (tested on 5.2.2) and Python 3.10 or newer. The toolkit uses only the standard
library, so there is nothing to `pip install`.

1. **Machine settings.** Copy `vibeart.local.example.json` to `vibeart.local.json` and set the paths: Blender,
   your TRELLIS.2 folder, GPU lock files to respect, and your BVH and sound libraries.
2. **Check it.**
   ```bash
   python -m vibeart.cli status '{}'
   ```
3. **Use it from Claude Code.** Copy `.mcp.example.json` to `.mcp.json` and fix the path, or add the server by hand:
   ```bash
   claude mcp add vibeinc-art-team -- python <path-to>/ai-art-team/vibeart/mcp_server.py
   ```
4. **Use it in Blender.** Build the extension with `python tools/build_addon.py`, then in Blender go to
   Edit > Preferences > Get Extensions > Install from Disk and pick `dist/vibeinc_art_team-0.1.0.zip`.
   The panel is at View3D > Sidebar > **VibeInc**.

## For agents

- Read [AGENTS.md](AGENTS.md). It covers the contract, the rules and the typical flows.
- **Result envelope.** Every tool returns `vibeart.result/1`. The `status` field is one of
  `ok | ok_with_failed_checks | blocked | stub | error`. The envelope also carries `outputs` (file paths),
  `metrics`, `checks` (`name, passed, value, expected`), `warnings` and `provenance`.
  `render_still`, `cleanup_mesh` and `image_to_mesh` also return the image itself through MCP, so you can look at it.
- **Scenes chain.** Scene tools take `scene` (a `.blend` path). Each step loads it and saves it back.
- **Long jobs.** `concept`, `image_to_mesh` and `make_prop` accept `background: true`, which returns a `job_id` for
  `job_status`.
- **Live mode.** With the add-on's "Allow live control" preference on, `live_blender` runs the same actions in the
  user's open Blender. It listens on localhost only, needs a token, and only runs whitelisted actions.

### CLI examples

```bash
python -m vibeart.cli greybox '{"scene": "runs/level/level.blend", "preset": "rooms", "seed": 3, "rooms": 5}'
```

```bash
python -m vibeart.cli camera_path '{"scene": "runs/level/level.blend", "mode": "flythrough"}'
```

```bash
python -m vibeart.cli render_still '{"scene": "runs/level/level.blend", "engine": "eevee", "camera": "auto"}'
```

```bash
python -m vibeart.cli make_prop '{"prompt": "a battered field radio", "quality": "draft", "target_height_m": 0.35}'
```

## Determinism and self-measurement

- **Greybox.** A seed or spec always gives the same layout. It reports `layout_signature`, connectivity, grid
  snapping and blocks on floor.
- **Mesh cleanup.** Reports triangles against the budget, UVs in 0–1, UV area (overlap), texel density, pivot at the
  base centre, transforms applied, height, open edges, export files and a thumbnail.
- **Camera.** Reports path length, speed, minimum clearance to geometry and whether the target stays in frame.
- **Render.** Reports exposure, clipping, subject coverage and render time.
- **Photo to PBR.** Reports seam ratio before and after, normal validity and height detail.
- **Generators.** TRELLIS and GPT take seeds or prompts, but their output is not bit-identical between runs.
  Every run folder keeps `provenance.json`.

## GPU courtesy

`image_to_mesh` checks the lock files listed in `gpu_lock_files` and the GPU load first. If another app owns the GPU,
it refuses with `blocked`. The exception is `quality: "draft"` with `allow_busy_gpu: true`, which runs a short job of
about 3 minutes using about 4 GB. It never kills other processes.

## Money: how VibeInc earns without charging for the tool

1. **Referral links.** Users connect their own accounts. A connector can carry a VibeInc referral link, which is shown
   only with this disclosure: *"Referral link: VibeInc may earn a referral fee if you subscribe. Your price is the
   same."* Users can switch referral links off. Referral fees never change the ordering or the defaults.
   See [docs/providers.md](docs/providers.md) and [docs/affiliate-programmes.md](docs/affiliate-programmes.md).
2. **Marketplace (designed, not launched).** `.vibepack` packages carry licence, provenance, AI disclosure and file
   hashes. See [docs/marketplace.md](docs/marketplace.md).
3. **Studio funnel.** "Made with VibeInc" appears in the panel, in glTF `extras.generator` and in PNG metadata.
   A visible render badge is opt-in. The panel also links to the studio and to the opt-in community.
   Links stay hidden until URLs are set in `vibeart/data/branding.json`.

## Studio and privacy

There is no telemetry unless the user opts in (`usage_stats`). If they do, the toolkit keeps per-tool counts only, on
the user's machine, and has no upload endpoint. Opting out deletes the counts. VibeInc never sells data, never uses the
user's machine for background compute, and never trains on users' creations without explicit consent.
See [docs/privacy.md](docs/privacy.md).

## Licences

See [LICENSES.md](LICENSES.md).
- **TRELLIS output is not cleared for commercial use.** Its GLB export uses NVIDIA nvdiffrast, which is licensed for
  non-commercial use only. The toolkit records this in provenance, and `package_asset` refuses paid listings for it.
- 100STYLE motion needs a credit line (CC BY 4.0).

## Tests

```bash
cd tests && python -m unittest
```

- There are 33 tests, covering every role plus MCP, the add-on install, the live bridge, providers, the
  marketplace and privacy. The run takes about 2 minutes with headless Blender.
- Live engine tests are opt-in: `VIBEART_LIVE_GPT=1` and `VIBEART_LIVE_TRELLIS=1`. Results of the live runs made
  during development are in [evidence/README.md](evidence/README.md).

## Layout

```
vibeart/                 host package (stdlib only): roles, tools registry, MCP server, CLI, providers,
                         marketplace, branding, telemetry, jobs, live client
blender_addon/vibeinc_art_team/   Blender extension: ops_core (all bpy actions), headless runner, panel, live bridge
tests/                   unittest suite + Blender fixture builder
tools/                   build_addon.py, try_action.py, when_gpu_free.py, showcase/ (renders + composes the demo videos)
docs/                    providers, affiliate research, marketplace design, privacy
evidence/                live run outputs (GPT concept, TRELLIS mesh, renders)
```

## Inspiration

Scenario's Blender plugin (announced by @emmanuel_2m on X, 14 Oct 2026) showed eight AI roles exposed through MCP. This project
has no Scenario code and does not use Scenario's service. It follows the same idea, but with engines you run yourself
or connect with your own accounts.