Godot and Blender through MCP

# AGENTS.md: Godot 4 and Blender through MCP

The agent drives two tools: Godot (MCP server `godot`: launch the editor, run the project, read debug output, create
scenes and nodes) and Blender (MCP server `blender`: inspect and change the open scene, run Python in safe mode, look at
the viewport). Assets move from Blender to Godot as glTF.

## Godot
- Run the project through the `godot` server after every gameplay change and read the debug output. Errors or warnings
  you caused are failures.
- Prefer editing `.gd` scripts and creating scenes through the server's scene tools. Hand-edit `.tscn` only for small,
  obvious changes; keep `uid://` references intact.
- Typed GDScript (`var speed: float = 200.0`), signals for decoupling, one responsibility per scene.
- If the server cannot find Godot, ask the human to set `GODOT_PATH` to the Godot executable in the MCP config.

## Blender
- The human saves the `.blend` before you start. You never save over it without asking; save variants as `<name>-v<n>.blend`.
- Safe mode stays on (`BLENDER_MCP_SAFE_MODE=1`): scripts that touch files, the network or other programs are blocked.
  Do not ask to turn it off. If a blocked script is needed, explain why and let the human decide.
- After every change, use the viewport look tool to check the result before continuing.
- Match the style in `art/reference/` (images the human provides): palette, proportions, polygon budget. Look at them first.
- Keep models game-ready: applied transforms, origin at the base, real-world scale (1 unit = 1 m), named objects and
  materials, modest polygon counts.
- Imported third-party assets keep their licence and credit. Record source and licence in `art/CREDITS.md`.

## Blender → Godot
Use the `blender-to-godot` skill for every asset that moves between the two.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `blender-to-godot`. Use them when their description matches the task.
- MCP servers for this project are in `.mcp.json`. If a server is not connected, tell the human rather than working around it.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Godot and Blender through MCP" v1.0.0 — https://loadout.jnw-it.com/loadouts/godot-blender-mcp/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `blender-to-godot`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Godot and Blender through MCP" v1.0.0 — https://loadout.jnw-it.com/loadouts/godot-blender-mcp/ -->

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@coding-solo/godot-mcp@0.1.1"]
    },
    "blender": {
      "command": "uvx",
      "args": ["mcp-for-blender==2.1.9"],
      "env": {
        "BLENDER_MCP_SAFE_MODE": "1",
        "DISABLE_TELEMETRY": "true"
      }
    }
  }
}

---
name: blender-to-godot
description: Model or adjust an asset in Blender through MCP, export it as glTF and bring it into a Godot 4 scene, then check it in the running game. Use when creating or updating a 3D asset for the Godot project.
---

# Blender to Godot

1. **Brief.** Restate the asset: purpose, size in metres, polygon budget, style references from `art/reference/`.
2. **Build in Blender** with the `blender` tools: block out, refine, materials. Look at the viewport from several angles
   after each step. Keep to `references/asset-checklist.md`.
3. **Prepare for export**: apply transforms, set the origin, name the object and its materials, remove unused data.
4. **Export** glTF binary to `assets/models/<name>.glb` inside the Godot project, selected objects only, +Y up.
   Use a short Blender script through the MCP tool if needed; safe mode allows normal export.
5. **Import in Godot.** Godot imports `.glb` on focus or project run. Instance it in the target scene with the `godot`
   scene tools (or a small `.tscn` edit), set collision if gameplay needs it.
6. **Run** the project through the `godot` server, read the debug output, and fix import or script errors.
7. **Report**: file paths, polygon count, any licence credits added to `art/CREDITS.md`, and what the human should look at.

# Game-ready asset checklist

- [ ] Scale: 1 Blender unit = 1 metre; a door is about 2 m tall
- [ ] Transforms applied (location, rotation, scale); origin at the base or the pivot gameplay needs
- [ ] Object, mesh and material names are meaningful (`crate_wood`, not `Cube.004`)
- [ ] Polygon count within the brief's budget; no hidden or duplicate geometry
- [ ] Normals face outwards; smooth/flat shading chosen on purpose
- [ ] Materials use Principled BSDF with image textures (these export cleanly to glTF)
- [ ] Textures packed or saved next to the `.glb`, power-of-two sizes
- [ ] Exported as `.glb`, selected objects only, +Y up
- [ ] Third-party assets: source and licence recorded in `art/CREDITS.md`