spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/build.py

@@ -0,0 +1,146 @@
+"""The full pipeline: validate -> write project -> Godot builds scenes -> smoke run."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import godot, manifest as manifest_mod, project, sfx
+from .analyze import Analysis, analyze
+from .diagnostics import Diagnostics
+from .manifest import Manifest
+
+BUILD_SCENE = "res://addons/spawn_point/tools/build.tscn"
+SMOKE_SCENE = "res://addons/spawn_point/tools/smoke.tscn"
+
+
+@dataclass
+class BuildResult:
+    out_dir: Path | None
+    diagnostics: Diagnostics
+    timings: dict[str, float] = field(default_factory=dict)
+    smoke: dict[str, Any] | None = None
+    log: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.diagnostics.ok and self.out_dir is not None
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "out_dir": str(self.out_dir) if self.out_dir else None,
+            "diagnostics": [d.to_dict() for d in self.diagnostics],
+            "timings": {k: round(v, 3) for k, v in self.timings.items()},
+            "smoke": self.smoke,
+        }
+
+
+def load_graph(path: Path) -> Any:
+    return json.loads(Path(path).read_text())
+
+
+def validate(data: Any, manifest: Manifest | None = None, base_dir: Path | None = None) -> Analysis:
+    return analyze(data, manifest or manifest_mod.load(), base_dir)
+
+
+def build(data: Any, out_dir: Path, *, manifest: Manifest | None = None, smoke: bool = True,
+          base_dir: Path | None = None) -> BuildResult:
+    """`base_dir` is the graph file's folder (for relative sprite paths)."""
+    timings: dict[str, float] = {}
+    t0 = time.perf_counter()
+    if base_dir is not None:
+        data = absolutize_sprites(data, base_dir)  # the project's spawnpoint.json must stand alone
+    analysis = validate(data, manifest, base_dir)
+    timings["validate"] = time.perf_counter() - t0
+    if not analysis.ok:
+        return BuildResult(None, analysis.diagnostics, timings)
+    diags = analysis.diagnostics
+    plan = analysis.plan
+    assert plan is not None and analysis.rules_source is not None
+
+    t = time.perf_counter()
+    feature = _godot_feature()
+    project.write(out_dir, data, plan, analysis.rules_source, feature, analysis.sprites, analysis.tiles_image)
+    sfx.write_all(out_dir / "sfx", seed=analysis.graph.settings.seed)
+    timings["write"] = time.perf_counter() - t
+
+    log: list[str] = []
+    t = time.perf_counter()
+    imp = godot.import_project(out_dir)
+    log.append(imp.output)
+    timings["godot_import"] = time.perf_counter() - t
+
+    t = time.perf_counter()
+    res = godot.run_scene(out_dir, BUILD_SCENE, check=False)
+    log.append(res.output)
+    timings["godot_build"] = time.perf_counter() - t
+    errors = res.script_errors + [ln for ln in res.output.splitlines() if "SPAWNPOINT_BUILD_ERROR" in ln]
+    if res.returncode != 0 or "SPAWNPOINT_BUILD_OK" not in res.output or errors:
+        for e in errors or [f"Godot build exited with code {res.returncode}"]:
+            diags.error("E_GODOT_BUILD", "(build)", e)
+        return BuildResult(out_dir, diags, timings, log="\n".join(log))
+
+    report = None
+    if smoke:
+        t = time.perf_counter()
+        res = godot.run_scene(out_dir, SMOKE_SCENE, fixed_fps=60, check=False, timeout=120)
+        log.append(res.output)
+        timings["smoke"] = time.perf_counter() - t
+        report = _smoke_report(res.output)
+        for e in res.script_errors:
+            diags.error("E_RUNTIME", "(smoke)", e)
+        if report is None:
+            diags.error("E_RUNTIME", "(smoke)", "smoke run produced no report (crash?)")
+        else:
+            _judge_smoke(report, plan, diags)
+    timings["total"] = time.perf_counter() - t0
+    return BuildResult(out_dir, diags, timings, report, "\n".join(log))
+
+
+def absolutize_sprites(data: Any, base_dir: Path) -> Any:
+    if not isinstance(data, dict) or not isinstance(data.get("entities"), dict):
+        return data
+    out = json.loads(json.dumps(data))
+    for ent in out["entities"].values():
+        ref = ent.get("sprite") if isinstance(ent, dict) else None
+        if isinstance(ref, str) and not Path(ref).is_absolute():
+            ent["sprite"] = str((base_dir / ref).resolve())
+    return out
+
+
+def _godot_feature() -> str:
+    try:
+        m = re.match(r"(\d+)\.(\d+)", godot.version())
+        if m:
+            return f"{m.group(1)}.{m.group(2)}"
+    except Exception:
+        pass
+    return "4.6"
+
+
+def _smoke_report(output: str) -> dict | None:
+    for line in output.splitlines():
+        if line.startswith("SPAWNPOINT_SMOKE "):
+            try:
+                return json.loads(line.removeprefix("SPAWNPOINT_SMOKE "))
+            except json.JSONDecodeError:
+                return None
+    return None
+
+
+def _judge_smoke(report: dict, plan: dict, diags: Diagnostics) -> None:
+    if report.get("error"):
+        diags.error("E_RUNTIME", "(smoke)", report["error"])
+        return
+    if not report.get("player_found"):
+        diags.error("E_RUNTIME", "(smoke)", "the player entity was not found when the level ran")
+        return
+    if plan["genre"] == "platformer" and not report.get("on_floor_after_1s"):
+        diags.warning("W_SMOKE_FLOOR", "(smoke)", "the player is not standing on a floor after 1 second")
+    if report.get("moved_px", 0) < 4:
+        diags.warning("W_SMOKE_STUCK", "(smoke)", "the player did not move under scripted input (stuck?)")

spawnpoint/cli.py

@@ -0,0 +1,290 @@
+"""Command line: spawnpoint validate | build | run | components | manifest."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__, godot, manifest as manifest_mod
+from .build import build, load_graph, validate
+from .project import slugify
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="spawnpoint", description="Compile JSON game graphs into Godot 4 projects.")
+    ap.add_argument("--version", action="version", version=f"spawnpoint {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    v = sub.add_parser("validate", help="check a game graph without building")
+    v.add_argument("graph", type=Path)
+    v.add_argument("--json", action="store_true", help="print diagnostics as JSON")
+
+    b = sub.add_parser("build", help="build a playable Godot project")
+    b.add_argument("graph", type=Path)
+    b.add_argument("-o", "--out", type=Path, help="output directory (default: out/<game-name>)")
+    b.add_argument("--no-smoke", action="store_true", help="skip the headless smoke run")
+    b.add_argument("--json", action="store_true", help="print the result as JSON")
+    b.add_argument("--run", action="store_true", help="open the game window after a successful build")
+
+    r = sub.add_parser("run", help="play a built project")
+    r.add_argument("project", type=Path)
+
+    c = sub.add_parser("components", help="list available components")
+    c.add_argument("--json", action="store_true")
+
+    sub.add_parser("manifest", help="regenerate the component manifest from the Godot library")
+
+    cr = sub.add_parser("create", help="design and build a game from a text prompt (uses the LLM)")
+    cr.add_argument("prompt")
+    cr.add_argument("-o", "--out", type=Path, help="output directory (default: out/<title>)")
+    cr.add_argument("--seed", type=int, help="level seed (default: derived from the prompt)")
+    cr.add_argument("--brief", type=Path, help="skip the LLM and use this GameBrief JSON")
+    cr.add_argument("--creative", action="store_true", help="let the LLM add a validated creative patch")
+    cr.add_argument("--no-web", action="store_true", help="skip the web export (play with `spawnpoint run`)")
+    cr.add_argument("--no-open", action="store_true", help="do not open the browser")
+    cr.add_argument("--no-serve", action="store_true", help="exit after building instead of serving")
+    cr.add_argument("--port", type=int, default=8060)
+    cr.add_argument("--record", action="store_true", help="save LLM calls as local fine-tuning data")
+    cr.add_argument("--playtest", action="store_true", help="after layer 2, let bots play and tune the game")
+    cr.add_argument("--ai-art", action="store_true",
+                    help="layer 2 sprites from an image model (SPAWNPOINT_IMAGE_PROVIDER), generated ones as fallback")
+
+    st = sub.add_parser("studio", help="open the web cockpit (create, tweak, click-to-edit, playtest)")
+    st.add_argument("--workspace", type=Path, default=Path("out"), help="folder holding the games (default: out)")
+    st.add_argument("--port", type=int, default=8070)
+    st.add_argument("--no-open", action="store_true")
+
+    pt = sub.add_parser("playtest", help="bots play a built game: report, death heatmap, optional tuning")
+    pt.add_argument("project", type=Path)
+    pt.add_argument("--runs", type=int, default=3, help="runs per profile")
+    pt.add_argument("--profiles", default="novice,average,expert")
+    pt.add_argument("--tune", action="store_true", help="adjust parameters within bounds and re-test")
+    pt.add_argument("--rounds", type=int, default=2)
+    pt.add_argument("--seed", type=int, default=1)
+    pt.add_argument("--difficulty", type=int, help="target difficulty 1-5 (default: the brief's, else 2)")
+    pt.add_argument("--json", action="store_true")
+
+    tw = sub.add_parser("tweak", help="change a created game with a text request (uses the LLM)")
+    tw.add_argument("project", type=Path)
+    tw.add_argument("request")
+    tw.add_argument("--no-web", action="store_true")
+    tw.add_argument("--record", action="store_true", help="save LLM calls as local fine-tuning data")
+
+    lm = sub.add_parser("llm", help="run SpawnPoint-Coder-7B locally (Docker + NVIDIA GPU)")
+    lm.add_argument("action", choices=["up", "down", "status"])
+    lm.add_argument("--port", type=int, default=8000)
+
+    ex = sub.add_parser("examples", help="list the example graphs, or copy one here")
+    ex.add_argument("action", nargs="?", choices=["list", "copy"], default="list")
+    ex.add_argument("name", nargs="?")
+
+    gf = sub.add_parser("gif", help="record a gameplay GIF of a built project (autopilot; needs a display)")
+    gf.add_argument("project", type=Path)
+    gf.add_argument("-o", "--out", type=Path, help="output file (default: <project>/demo.gif)")
+    gf.add_argument("--seconds", type=float, default=8.0)
+    gf.add_argument("--fps", type=int, default=20)
+    gf.add_argument("--width", type=int, default=640)
+
+    sp = sub.add_parser("sprites", help="import, generate or preview sprites")
+    sps = sp.add_subparsers(dest="sprites_cmd", required=True)
+    si = sps.add_parser("import", help="turn a sprite sheet or a folder of frames into a SpriteSet")
+    si.add_argument("source", type=Path, help="PNG sheet or folder of PNG frames")
+    si.add_argument("--name", help="sprite name (default: from the file name)")
+    si.add_argument("--grid", help="cell size WxH, e.g. 32x32 (default: auto-detect from transparent gutters)")
+    si.add_argument("--spacing", type=int, default=0)
+    si.add_argument("--margin", type=int, default=0)
+    si.add_argument("--anim", action="append", default=[], metavar="NAME=FRAMES",
+                    help="e.g. idle=0-3 (repeatable; frame indices in reading order)")
+    si.add_argument("--rows", help="comma-separated animation names, one per row, e.g. idle,run,jump")
+    si.add_argument("--fps", action="append", default=[], metavar="NAME=FPS")
+    si.add_argument("--scale", type=int, default=2)
+    si.add_argument("--anchor", choices=["bottom", "center"], default="bottom")
+    si.add_argument("-o", "--out", type=Path, default=Path("assets/sprites"))
+    sg = sps.add_parser("generate", help="draw a procedural pixel-art SpriteSet")
+    sg.add_argument("kind")
+    sg.add_argument("--name", required=True)
+    sg.add_argument("--color", default="#29adff")
+    sg.add_argument("--features", help="comma-separated, e.g. mask,tail (default: from the name)")
+    sg.add_argument("--seed", type=int, default=0)
+    sg.add_argument("-o", "--out", type=Path, default=Path("assets/sprites"))
+    sv2 = sps.add_parser("preview", help="render a contact sheet PNG of a SpriteSet with its collision outline")
+    sv2.add_argument("sprite", type=Path)
+    sv2.add_argument("-o", "--out", type=Path)
+    sps.add_parser("kinds", help="list the procedural sprite kinds")
+
+    ds = sub.add_parser("dataset", help="recorded fine-tuning data")
+    ds.add_argument("action", choices=["stats", "path"])
+    ds.add_argument("--json", action="store_true")
+
+    sv = sub.add_parser("serve", help="serve a project's web build with live reload")
+    sv.add_argument("project", type=Path)
+    sv.add_argument("--port", type=int, default=8060)
+    sv.add_argument("--no-open", action="store_true")
+
+    args = ap.parse_args(argv)
+    try:
+        from . import studio_cli
+        return {"validate": _validate, "build": _build, "run": _run, "components": _components,
+                "manifest": _manifest, "create": studio_cli.create, "tweak": studio_cli.tweak,
+                "serve": studio_cli.serve, "dataset": studio_cli.dataset, "playtest": studio_cli.playtest, "studio": studio_cli.studio,
+                "sprites": _sprites, "gif": _gif, "llm": _llm, "examples": _examples}[args.cmd](args)
+    except godot.GodotError as e:
+        print(f"error: {e}", file=sys.stderr)
+        if e.output:
+            print(e.output[-3000:], file=sys.stderr)
+        return 2
+
+
+def _print_diags(diags) -> None:
+    for d in diags:
+        print(("  ✗ " if d.severity == "error" else "  ! ") + str(d))
+
+
+def _validate(args) -> int:
+    analysis = validate(load_graph(args.graph), base_dir=args.graph.resolve().parent)
+    if args.json:
+        print(json.dumps([d.to_dict() for d in analysis.diagnostics], indent=2))
+    else:
+        _print_diags(analysis.diagnostics)
+        n_err, n_warn = len(analysis.diagnostics.errors), len(analysis.diagnostics.warnings)
+        print(f"{'OK' if analysis.ok else 'INVALID'}: {n_err} error(s), {n_warn} warning(s)")
+    return 0 if analysis.ok else 1
+
+
+def _build(args) -> int:
+    data = load_graph(args.graph)
+    name = data.get("name", args.graph.stem) if isinstance(data, dict) else args.graph.stem
+    out = args.out or Path("out") / slugify(str(name))
+    result = build(data, out.resolve(), smoke=not args.no_smoke, base_dir=args.graph.resolve().parent)
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        _print_diags(result.diagnostics)
+        if result.ok:
+            t = result.timings
+            print(f"Built {out} in {t.get('total', sum(t.values())):.1f}s "
+                  f"(validate {t.get('validate', 0) * 1000:.0f}ms, godot {t.get('godot_import', 0) + t.get('godot_build', 0):.1f}s"
+                  + (f", smoke {t['smoke']:.1f}s" if "smoke" in t else "") + ")")
+            if result.smoke:
+                print("Smoke:", json.dumps(result.smoke))
+            print(f"Play it: spawnpoint run {out}   (or open {out}/project.godot in Godot)")
+        else:
+            print("BUILD FAILED")
+            if result.log:
+                tail = "\n".join(result.log.splitlines()[-30:])
+                print(tail, file=sys.stderr)
+    if result.ok and args.run:
+        return _run(argparse.Namespace(project=out))
+    return 0 if result.ok else 1
+
+
+def _run(args) -> int:
+    return subprocess.call([godot.find_binary(), "--path", str(args.project)])
+
+
+def _components(args) -> int:
+    m = manifest_mod.load()
+    if args.json:
+        print(manifest_mod.MANIFEST_PATH.read_text())
+        return 0
+    for c in sorted(m.components.values(), key=lambda c: (c.category, c.name)):
+        hosts = f" (body: {', '.join(c.hosts)})" if c.hosts else ""
+        print(f"\n{c.name} [{c.category}]{hosts}")
+        print("  " + c.doc.split("\n")[0])
+        for p in c.params.values():
+            print(f"    {p.describe()}")
+        for s in c.signals.values():
+            print(f"    signal {s.name}({', '.join(a.name for a in s.args)})")
+        for mt in c.methods.values():
+            print(f"    {mt.name}({', '.join(a.name for a in mt.args)})")
+    return 0
+
+
+def _llm(args) -> int:
+    from . import llm_server
+
+    try:
+        return {"up": lambda: llm_server.up(args.port), "down": llm_server.down,
+                "status": lambda: llm_server.status(args.port)}[args.action]()
+    except (RuntimeError, subprocess.CalledProcessError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+def _examples(args) -> int:
+    import shutil
+
+    files = sorted(manifest_mod.EXAMPLES_DIR.glob("*.json"))
+    if args.action == "list" or not args.name:
+        for f in files:
+            data = json.loads(f.read_text())
+            print(f"{f.stem:<14} {data.get('genre', ''):<11} {data.get('name', '')}")
+        print("Copy one: spawnpoint examples copy pixel_hopper   then: spawnpoint build pixel_hopper.json --run")
+        return 0
+    src = manifest_mod.EXAMPLES_DIR / f"{args.name.removesuffix('.json')}.json"
+    if not src.exists():
+        print(f"error: no example '{args.name}'", file=sys.stderr)
+        return 1
+    shutil.copy2(src, Path.cwd() / src.name)
+    print(f"Wrote {src.name}")
+    return 0
+
+
+def _gif(args) -> int:
+    from .gif import record_gif
+
+    out = args.out or args.project / "demo.gif"
+    path = record_gif(args.project.resolve(), out.resolve(), args.seconds, args.fps, args.width)
+    print(f"Wrote {out} ({path.stat().st_size / 1e6:.1f} MB)")
+    return 0
+
+
+def _sprites(args) -> int:
+    from .sprites import generate as gen, importer
+    from .sprites.spriteset import SpriteError, load
+
+    try:
+        if args.sprites_cmd == "kinds":
+            for k, spec in gen.KINDS.items():
+                print(f"{k:<8} {spec.size[0]}x{spec.size[1]} px  animations: {', '.join(spec.anims)}")
+            return 0
+        if args.sprites_cmd == "preview":
+            s = load(args.sprite)
+            out = args.out or args.sprite.with_suffix("").with_suffix(".preview.png")
+            importer.preview(s).save(out)
+            print(f"Wrote {out}")
+            return 0
+        if args.sprites_cmd == "generate":
+            feats = [f.strip() for f in args.features.split(",")] if args.features else None
+            s = gen.generate(args.name, args.kind, args.color, feats, args.seed)
+        else:
+            fps = {k: float(v) for k, v in (x.split("=", 1) for x in args.fps)}
+            if args.source.is_dir():
+                s = importer.import_folder(args.source, args.name, fps=fps, scale=args.scale, anchor=args.anchor)
+            else:
+                grid = tuple(int(v) for v in args.grid.lower().split("x")) if args.grid else None
+                anims = {k: importer.parse_ranges(v) for k, v in (x.split("=", 1) for x in args.anim)} or None
+                rows = [r.strip() for r in args.rows.split(",")] if args.rows else None
+                s = importer.import_sheet(args.source, args.name, grid=grid, spacing=args.spacing, margin=args.margin,
+                                          anims=anims, row_names=rows, fps=fps, scale=args.scale, anchor=args.anchor)
+    except (SpriteError, ValueError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    path = s.save(args.out)
+    anims = ", ".join(f"{k} ({len(a.frames)})" for k, a in s.animations.items())
+    print(f"Wrote {path}: {s.frame_size[0]}x{s.frame_size[1]} frames, {anims}; outline {len(s.polygon)} points")
+    print(f'Use it in a graph: "sprite": "{path}"')
+    return 0
+
+
+def _manifest(args) -> int:
+    data = manifest_mod.generate()
+    print(f"Wrote {manifest_mod.MANIFEST_PATH} ({len(data['components'])} components)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())