Metadata-Version: 2.4
Name: loom-godot
Version: 0.3.0
Summary: AI-friendly authoring layer for Godot 4.5: author scenes in token-efficient YAML, emit real Godot .tscn/.gd you ship.
Author: Loom contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/crunchynacho/Loom
Project-URL: Repository, https://github.com/crunchynacho/Loom
Project-URL: Issues, https://github.com/crunchynacho/Loom/issues
Keywords: godot,game-development,ai,claude,markup,translator
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.21
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# 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:

```yaml
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:

```yaml
# 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/`](https://github.com/crunchynacho/Loom/tree/main/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`](https://github.com/crunchynacho/Loom/blob/main/TODO.md)). The
honest field notes from building the example project — what worked, what was
friction — are in
[`docs/phase3/REAL_WORLD_VALIDATION.md`](https://github.com/crunchynacho/Loom/blob/main/docs/phase3/REAL_WORLD_VALIDATION.md).

## Development

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

See [`SETUP.md`](https://github.com/crunchynacho/Loom/blob/main/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`](https://github.com/crunchynacho/Loom/blob/main/PRINCIPLES.md).

## License

MIT. See [`LICENSE`](https://github.com/crunchynacho/Loom/blob/main/LICENSE).
