loom-godot 0.3.0

AI-friendly authoring layer for Godot 4.5: author scenes in token-efficient YAML, emit real Godot .tscn/.gd you ship.

Loom

An AI-friendly authoring layer for Godot 4.5. You author scenes in a small, declarative YAML markup; Loom emits real .tscn and .gd files you open in Godot and ship. The point is the AI loop: dense source an agent can write fast, structured errors with hints when it gets something wrong, and a skill layer Claude Code reads at session start so it already knows how your project is laid out and how Godot 4.5 works.

Loom installs into your Godot project. loom init drops an addon and a couple of root files; the scenes Loom generates live beside your hand-written ones, namespaced with a loom_ prefix. Remove Loom and your project is exactly as it was.

pip install loom-godot

Requires Python 3.11+ and Godot 4.5+.

What Loom is — and isn't

• Loom is not a game engine. Godot 4.5+ is. Loom is the substrate between an AI agent and Godot: it lowers a token-efficient markup into the real Godot files Godot runs.
• Loom is not a no-code GUI. You (or an agent on your behalf) author text; Loom compiles it. A visual editor for people who don't want to touch files is a separate, future product — it is not part of this release. Don't come here expecting "build a game without typing anything."

What you do get today: a markup that's ~3–4× denser than the equivalent hand-written Godot, every translator error returned as a structured value (code / message / location / hint / context) an AI can act on without re-reading your code, and four genre packs that supply ready-made archetypes plus per-pack skill files.

First five minutes

This walkthrough goes from an empty Godot project to a verified, playable Loom scene. Every command here was run end-to-end on Windows 11 before this README shipped.

Windows note. pip install may not put the loom script on your PATH. If loom isn't found, use py -m loom <command> instead — it reaches the exact same CLI. (On macOS/Linux, loom <command> works directly.) The commands below were verified via py -m loom.

1. Install, inside an existing Godot 4.5+ project (the directory with project.godot):

pip install loom-godot
loom init

loom init reports what it created and lists the available packs:

Loom 0.3.0 initialized.

Created:
  addons/loom/             (Loom addon - runtime libraries and packs)
  LOOM.md                  (Claude Code reads this at session start)
  loom.yaml                (project config - edit to opt into genre packs)
  loom_scenes/             (author markup here)

Available packs (edit loom.yaml to opt in):
  - iso-rpg          isometric / top-down RPG primitives
  - narrative-vn     visual novel / dialogue chains
  - quest-core       quest state tracking
  - save-core        save / load substrate

2. Opt into a pack. Edit loom.yaml — set the starting scene's name and list the pack you want. A fresh loom.yaml ships with packs: []; change two lines:

project:
  starting_scene: "intro"   # was "main" — match a scene you author below

packs:
  - narrative-vn            # was: packs: []

3. Write a scene at loom_scenes/intro.loom.yaml. About ten lines:

# requires: narrative-vn
scene:
  name: "intro"
  pack: narrative-vn

entities:
  narrator:
    archetype: Speaker
    position: [120, 64]
    character: { name: "Narrator", default_emotion: "neutral" }
  box:
    archetype: DialogueBox
    position: [0, 240]

dialogue:
  - { speaker: "Narrator", body: "Hello from Loom." }
  - { speaker: "Narrator", body: "You wrote this scene in YAML." }
  - { speaker: "Narrator", body: "Now it's a real Godot scene." }

4. Translate the markup into Godot files:

loom translate

This writes scenes/loom_intro.tscn, scripts/loom_intro_behavior.gd, and scripts/loom_event_bus.gd into your project, and adds Loom-managed autoload entries to project.godot (inside delimited marker comments — everything else in the file is byte-preserved).

5. Verify it imports and runs headlessly:

loom verify

loom verify: [PASS] <your-project>
============================================================
  Scene smoke: 1/1 pass
    [ok] loom_intro

loom verify runs loom translate, then headless Godot: it imports the project and smoke-runs each scene for a few frames. It resolves Godot from LOOM_GODOT_PATH or your PATH. That's the loop — author markup, translate, verify, repeat. Then open project.godot in Godot and hit Play.

The lifecycle commands

Four commands cover the whole lifecycle. Each is intentionally shallow here — the real reference is LOOM.md, which loom init writes into your project and Claude Code reads at session start.

• loom init — run at a Godot 4.5+ project root. Drops addons/loom/ (the packs + runtime), writes LOOM.md and loom.yaml, creates an empty loom_scenes/. --force reinstalls the addon and templates without touching your authored markup.
• loom translate — reads loom.yaml and loom_scenes/*.loom.yaml, emits scenes/loom_*.tscn + scripts/loom_*.gd into your project, and updates Loom's marker sections in project.godot. Deterministic: same markup in, byte-identical Godot out. loom translate --check (alias loom validate) validates without writing anything.
• loom verify — translates, then runs headless Godot to import the project and smoke-run each scene. --import-only skips the smoke pass for a faster static check; --json emits a structured result for CI.
• loom uninstall — removes Loom's scaffolding (the addon, LOOM.md, loom.yaml, the manifest, the project.godot markers) and, by default, keeps both your authored loom_scenes/ markup and the compiled loom_* files. --remove-output and --remove-markup are explicit opt-outs.

The genre packs

The universal core pack is always loaded (it ships the LoomEntity, Toast, Music, and event-bus plumbing every other pack builds on). Opt into the genre packs you need in loom.yaml:

• iso-rpg — isometric / top-down RPG primitives: hero, NPCs, enemies, doors, save points, items, an attack system, a HUD bar.
• narrative-vn — visual novel / dialogue chains: speakers, dialogue boxes, choice forks, a Story autoload managing chains and flags.
• quest-core — quest state tracking: a quest archetype with a quest component, no runtime.
• save-core — save / load substrate: a save-point archetype and an autosave autoload with atomic write semantics.

Each pack carries a skill.md — the authoritative, AI-facing description of what it provides and how to author against it.

A real example

games/example-project/ is the canonical on-disk demonstration: a small coffee-shop / back-garden game across four scenes (two narrative-vn, two iso-rpg), composing both packs with cross-scene transitions. It ships 3.93× leverage (markup vs. emitted .tscn + .gd) and zero script: blocks — every behavior is expressed in the markup, not a GDScript escape hatch. Read it as the live shape of a working Loom project.

Where Loom is

Loom is alpha, and this is its first release on PyPI. Expect rough edges; read the docs honestly rather than the marketing.

What works today is the substrate. Phase 3 brought Loom from a separate translator into something that lives inside your Godot project:

• Single-project coexistence. Generated loom_* scenes sit beside your hand-written ones; Loom only writes inside delimited marker sections of project.godot; loom uninstall mechanically reverses everything.
• A universal Godot 4.5 skill layer. The LOOM.md that loom init installs distils Godot 4.5 patterns, gotchas, and idioms — so Claude Code is more effective in any Godot project, even with no genre packs loaded.

And it's been driven by real content: Loom's translator was validated in Phase 2 by porting a full game end-to-end (Salt Tide — ~30 scenes, four packs composed, ~2.58× project-wide leverage), and the in-repo example project above is the current canonical demo.

It is not finished. The GUI editor described above doesn't exist yet, and the markup has known gaps (logged in TODO.md). The honest field notes from building the example project — what worked, what was friction — are in docs/phase3/REAL_WORLD_VALIDATION.md.

Development

git clone https://github.com/crunchynacho/Loom
cd Loom
pip install -e ".[dev]"
pytest

See SETUP.md for the Godot install and the headless verify-pipeline setup. The AI-first design principles that govern the substrate are in PRINCIPLES.md.

License

MIT. See LICENSE.