spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/level.py

@@ -0,0 +1,157 @@
+"""ASCII level parsing, checks, and a platformer reachability estimate."""
+
+from __future__ import annotations
+
+import math
+from collections import deque
+from dataclasses import dataclass, field
+
+from .diagnostics import Diagnostics, did_you_mean, join_path
+from .graph import Level
+
+TILE_KINDS = ("solid", "oneway")
+EMPTY = {".", " "}
+MAX_W, MAX_H = 512, 256
+
+
+@dataclass
+class Placement:
+    entity: str
+    x: int
+    y: int
+
+
+@dataclass
+class LevelData:
+    width: int
+    height: int
+    tiles: dict[tuple[int, int], str] = field(default_factory=dict)  # (x, y) -> solid | oneway
+    placements: list[Placement] = field(default_factory=list)
+
+    def is_solid(self, x: int, y: int) -> bool:
+        return self.tiles.get((x, y)) == "solid"
+
+    def is_floor(self, x: int, y: int) -> bool:
+        return (x, y) in self.tiles
+
+
+def parse_level(level: Level, entity_names: set[str], diags: Diagnostics) -> LevelData | None:
+    path = "level"
+    ok = True
+    legend: dict[str, str] = {}
+    for ch, value in level.legend.items():
+        p = join_path(path, "legend", ch)
+        if len(ch) != 1:
+            diags.error("E_LEGEND_KEY", p, f"legend keys must be single characters, got '{ch}'")
+            ok = False
+            continue
+        if ch in EMPTY:
+            diags.error("E_LEGEND_KEY", p, f"'{ch}' is reserved for empty space")
+            ok = False
+            continue
+        if value not in TILE_KINDS and value not in entity_names:
+            diags.error("E_LEGEND_VALUE", p, f"'{value}' is neither a tile kind nor an entity",
+                        did_you_mean(value, [*TILE_KINDS, *entity_names]))
+            ok = False
+            continue
+        legend[ch] = value
+
+    rows = level.map
+    if not rows or not any(r.strip(". ") for r in rows):
+        diags.error("E_MAP_EMPTY", join_path(path, "map"), "the map is empty")
+        return None
+    width = max(len(r) for r in rows)
+    height = len(rows)
+    if width > MAX_W or height > MAX_H:
+        diags.error("E_MAP_SIZE", join_path(path, "map"), f"map is {width}x{height}; maximum is {MAX_W}x{MAX_H}")
+        return None
+
+    data = LevelData(width, height)
+    unknown: dict[str, list[tuple[int, int]]] = {}
+    for y, row in enumerate(rows):
+        for x, ch in enumerate(row):
+            if ch in EMPTY:
+                continue
+            if ch not in legend:
+                unknown.setdefault(ch, []).append((x, y))
+                continue
+            value = legend[ch]
+            if value in TILE_KINDS:
+                data.tiles[(x, y)] = value
+            else:
+                data.placements.append(Placement(value, x, y))
+    for ch, cells in unknown.items():
+        if ch in level.legend:
+            continue  # already reported as a bad legend entry
+        where = ", ".join(f"({x},{y})" for x, y in cells[:4]) + (" ..." if len(cells) > 4 else "")
+        diags.error("E_MAP_CHAR", join_path(path, "map"), f"character '{ch}' at {where} is not in the legend",
+                    f'Add "{ch}": "<tile kind or entity>" to level.legend, or use "." for empty')
+        ok = False
+    return data if ok else None
+
+
+@dataclass
+class JumpModel:
+    """How far the player can travel, in tiles (rough estimate for warnings)."""
+
+    up: int
+    across: int
+    height_tiles: int
+
+
+def jump_model(jump_velocity: float, gravity: float, fall_mult: float, max_speed: float,
+               tile: int, player_h: float, air_jumps: int = 0) -> JumpModel:
+    if gravity <= 0:
+        return JumpModel(99, 99, 1)
+    jumps = 1 + max(0, air_jumps)
+    h = jump_velocity**2 / (2 * gravity) * jumps
+    t_up = jump_velocity / gravity * jumps
+    t_down = math.sqrt(2 * h / (gravity * fall_mult))
+    return JumpModel(int(h // tile), max(1, int(max_speed * (t_up + t_down) // tile)),
+                     max(1, math.ceil(player_h / tile)))
+
+
+def unreachable(data: LevelData, start: tuple[int, int], targets: list[Placement], jm: JumpModel) -> list[Placement]:
+    """Targets the player probably cannot reach (platformer heuristic: jumps, walks and falls)."""
+
+    def free(x: int, y: int) -> bool:
+        return 0 <= x < data.width and y < data.height and not data.is_solid(x, y)
+
+    def standable(x: int, y: int) -> bool:
+        if not (0 <= x < data.width and 0 <= y < data.height - 1):
+            return False
+        if not data.is_floor(x, y + 1):
+            return False
+        return all(free(x, y - k) for k in range(jm.height_tiles))
+
+    # Drop the player onto the floor below its start cell.
+    sx, sy = start
+    while sy < data.height - 1 and not standable(sx, sy):
+        sy += 1
+    if not standable(sx, sy):
+        return []  # Reported separately as W_NO_GROUND.
+    stands = [(x, y) for x in range(data.width) for y in range(data.height) if standable(x, y)]
+    if len(stands) > 4000:
+        return []  # Too big for this quadratic heuristic; skip the warning.
+    seen = {(sx, sy)}
+    queue = deque([(sx, sy)])
+    while queue:
+        x, y = queue.popleft()
+        for nx, ny in stands:
+            if (nx, ny) in seen:
+                continue
+            dy = ny - y  # positive = lower
+            reach = jm.across + max(0, dy)
+            if abs(nx - x) <= reach and dy >= -jm.up:
+                seen.add((nx, ny))
+                queue.append((nx, ny))
+    missing = []
+    for t in targets:
+        ok = any(abs(t.x - x) <= jm.across and y - jm.up - jm.height_tiles < t.y <= y + 1 for x, y in seen)
+        if not ok:
+            missing.append(t)
+    return missing
+
+
+def has_ground_below(data: LevelData, x: int, y: int) -> bool:
+    return any(data.is_floor(x, yy) for yy in range(y + 1, data.height))

spawnpoint/llm_server.py

@@ -0,0 +1,77 @@
+"""`spawnpoint llm up|down|status`: run SpawnPoint-Coder-7B locally in the vLLM Docker image."""
+
+from __future__ import annotations
+
+import getpass
+import os
+import shutil
+import subprocess
+import time
+import urllib.request
+from pathlib import Path
+
+NAME = os.environ.get("SPAWNPOINT_LLM_CONTAINER", "spawnpoint-llm")
+IMAGE = os.environ.get("VLLM_IMAGE", "vllm/vllm-openai:v0.10.2")  # CUDA 12.8: NVIDIA driver >= 570
+MODEL = os.environ.get("SPAWNPOINT_MODEL", "smoky1496/SpawnPoint-Coder-7B-AWQ")
+SERVED = "SpawnPoint-Coder-7B"
+
+
+def _docker(*args: str, check: bool = True, capture: bool = True) -> subprocess.CompletedProcess:
+    if shutil.which("docker") is None:
+        raise RuntimeError("Docker is required (with the NVIDIA container toolkit) to run the local model")
+    return subprocess.run(["docker", *args], check=check, capture_output=capture, text=True)
+
+
+def _exists() -> bool:
+    return bool(_docker("ps", "-a", "--filter", f"name=^{NAME}$", "--format", "{{.Names}}").stdout.strip())
+
+
+def _running() -> bool:
+    out = _docker("inspect", "-f", "{{.State.Running}}", NAME, check=False)
+    return out.returncode == 0 and out.stdout.strip() == "true"
+
+
+def ready(port: int = 8000) -> bool:
+    try:
+        urllib.request.urlopen(f"http://localhost:{port}/v1/models", timeout=2)
+        return True
+    except Exception:
+        return False
+
+
+def up(port: int = 8000, max_len: int = 16384, say=print) -> int:
+    if _exists():
+        _docker("start", NAME)
+    else:
+        hf = Path.home() / ".cache" / "huggingface"
+        hf.mkdir(parents=True, exist_ok=True)
+        user = getpass.getuser()
+        # Run as the current user so downloaded weights are not root-owned; that UID does not exist in
+        # the image, so USER/LOGNAME are set for torch's getpass.getuser().
+        _docker("run", "-d", "--name", NAME, "--gpus", "all", "-p", f"{port}:8000", "--ipc=host",
+                "-u", f"{os.getuid()}:{os.getgid()}", "-e", f"USER={user}", "-e", f"LOGNAME={user}",
+                "-e", "HOME=/tmp", "-e", "HF_HOME=/hf", "-v", f"{hf}:/hf", IMAGE, "--model", MODEL,
+                "--served-model-name", SERVED, "--max-model-len", str(max_len), "--gpu-memory-utilization", "0.85")
+    say(f"Starting {SERVED} on :{port} (first start downloads ~5.6 GB) ...")
+    while not ready(port):
+        if not _running():
+            say(_docker("logs", "--tail", "30", NAME, check=False).stdout)
+            return 1
+        time.sleep(2)
+    say(f"Ready: http://localhost:{port}/v1 — stop with `spawnpoint llm down`.")
+    return 0
+
+
+def down(say=print) -> int:
+    if _exists():
+        _docker("stop", NAME)
+        say("Stopped.")
+    else:
+        say("Not running.")
+    return 0
+
+
+def status(port: int = 8000, say=print) -> int:
+    say(f"container {NAME}: {'running' if _exists() and _running() else 'stopped'}; "
+        f"API on :{port}: {'ready' if ready(port) else 'not responding'}")
+    return 0

spawnpoint/manifest.py

@@ -0,0 +1,222 @@
+"""Component manifest: what the Godot library offers, generated from the scripts themselves.
+
+`generate()` runs Godot headless to introspect every component script (exports, ranges, signals,
+methods, metadata constants) and merges the `##` doc comments parsed from source. `load()` reads
+the resulting manifest.json. Nobody edits the manifest by hand.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import godot
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PACKAGE_DATA = Path(__file__).resolve().parent / "_data"  # filled when building a wheel (see setup.py)
+
+
+def _library_project() -> Path:
+    """The Godot project holding the addon: $SPAWNPOINT_LIBRARY, the repository (development), or
+    the copy bundled in the installed package."""
+    env = os.environ.get("SPAWNPOINT_LIBRARY")
+    if env:
+        return Path(env)
+    repo = REPO_ROOT / "godot"
+    if (repo / "addons" / "spawn_point" / "manifest.json").exists():
+        return repo
+    return PACKAGE_DATA / "godot"
+
+
+LIBRARY_PROJECT = _library_project()
+ADDON_DIR = LIBRARY_PROJECT / "addons" / "spawn_point"
+MANIFEST_PATH = ADDON_DIR / "manifest.json"
+EXAMPLES_DIR = REPO_ROOT / "examples" if (REPO_ROOT / "examples").is_dir() else PACKAGE_DATA / "examples"
+
+BODY_CLASSES = {"character": "CharacterBody2D", "static": "StaticBody2D", "area": "Area2D"}
+
+
+@dataclass(frozen=True)
+class Param:
+    name: str
+    type: str  # Godot type name: bool, int, float, String, Vector2, Color
+    default: Any
+    doc: str = ""
+    min: float | None = None
+    max: float | None = None
+    choices: tuple[str, ...] | None = None
+
+    def describe(self) -> str:
+        s = f"{self.name}: {self.type} = {json.dumps(self.default)}"
+        if self.min is not None:
+            s += f" [{self.min:g}..{self.max:g}]"
+        if self.choices:
+            s += " one of " + "|".join(self.choices)
+        return s
+
+
+@dataclass(frozen=True)
+class Arg:
+    name: str
+    type: str
+
+
+@dataclass(frozen=True)
+class Signal:
+    name: str
+    args: tuple[Arg, ...]
+    doc: str = ""
+
+
+@dataclass(frozen=True)
+class Method:
+    name: str
+    args: tuple[Arg, ...]
+    default_count: int
+    doc: str = ""
+
+    @property
+    def min_args(self) -> int:
+        return len(self.args) - self.default_count
+
+
+@dataclass
+class Component:
+    name: str
+    class_name: str
+    script: str
+    base: str
+    hosts: list[str]
+    requires: list[str]
+    category: str
+    entity_params: list[str]
+    doc: str
+    params: dict[str, Param] = field(default_factory=dict)
+    state: dict[str, str] = field(default_factory=dict)
+    signals: dict[str, Signal] = field(default_factory=dict)
+    methods: dict[str, Method] = field(default_factory=dict)
+
+    @property
+    def is_area(self) -> bool:
+        return self.base == "Area2D"
+
+
+@dataclass
+class Manifest:
+    godot_version: str
+    components: dict[str, Component]
+
+    def get(self, name: str) -> Component | None:
+        return self.components.get(name)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self.components
+
+
+# ---------------------------------------------------------------------------------------------
+# Loading
+
+
+def load(path: Path | None = None) -> Manifest:
+    data = json.loads(Path(path or MANIFEST_PATH).read_text())
+    return from_dict(data)
+
+
+def from_dict(data: dict) -> Manifest:
+    comps: dict[str, Component] = {}
+    for c in data["components"]:
+        comp = Component(
+            name=c["name"],
+            class_name=c["class"],
+            script=c["script"],
+            base=c["base"],
+            hosts=list(c["hosts"]),
+            requires=list(c["requires"]),
+            category=c["category"],
+            entity_params=list(c.get("entity_params", [])),
+            doc=c.get("doc", ""),
+            state={s["name"]: s["type"] for s in c.get("state", [])},
+        )
+        for p in c["params"]:
+            comp.params[p["name"]] = _param(p)
+        for s in c["signals"]:
+            comp.signals[s["name"]] = Signal(s["name"], tuple(Arg(a["name"], a["type"]) for a in s["args"]), s.get("doc", ""))
+        for m in c["methods"]:
+            comp.methods[m["name"]] = Method(
+                m["name"], tuple(Arg(a["name"], a["type"]) for a in m["args"]), m["default_count"], m.get("doc", "")
+            )
+        comps[comp.name] = comp
+    return Manifest(data.get("godot", ""), comps)
+
+
+def _param(p: dict) -> Param:
+    lo = hi = None
+    choices = None
+    if p.get("hint") == "range":
+        parts = [x.strip() for x in p["hint_string"].split(",")]
+        lo, hi = float(parts[0]), float(parts[1])
+    elif p.get("hint") == "enum":
+        choices = tuple(x.split(":")[0] for x in p["hint_string"].split(","))
+    return Param(p["name"], p["type"], p.get("default"), p.get("doc", ""), lo, hi, choices)
+
+
+# ---------------------------------------------------------------------------------------------
+# Generation
+
+
+def generate(project: Path = LIBRARY_PROJECT, out: Path | None = None) -> dict:
+    """Introspect the library in Godot and write manifest.json. Returns the manifest dict."""
+    with tempfile.TemporaryDirectory() as tmp:
+        raw_path = Path(tmp) / "raw.json"
+        godot.run_scene(project, "res://addons/spawn_point/tools/dump_manifest.tscn", [str(raw_path)], import_first=True)
+        raw = json.loads(raw_path.read_text())
+    for comp in raw["components"]:
+        docs = parse_docs((project / comp["script"].removeprefix("res://")).read_text())
+        comp["doc"] = docs.get("@class", "")
+        for group in ("params", "signals", "methods"):
+            for item in comp[group]:
+                item["doc"] = docs.get(item["name"], "")
+    data = {"godot": raw["godot"], "components": raw["components"]}
+    target = out or (project / "addons" / "spawn_point" / "manifest.json")
+    target.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    return data
+
+
+_DECL = re.compile(r"^(?:@export\w*(?:\([^)]*\))?\s+)?(?:var|signal|func|static func)\s+(\w+)")
+
+
+def parse_docs(source: str) -> dict[str, str]:
+    """Map declared names to their `##` doc comments. The class doc is stored under '@class'."""
+    docs: dict[str, str] = {}
+    pending: list[str] = []
+    class_doc: list[str] = []
+    seen_decl = False
+    for raw in source.splitlines():
+        line = raw.strip()
+        if line.startswith("##"):
+            pending.append(line[2:].strip())
+            continue
+        if not line:
+            if pending and not seen_decl and not class_doc:
+                class_doc, pending = pending, []
+            continue
+        if line.startswith(("class_name", "extends")):
+            if pending:
+                class_doc += pending
+                pending = []
+            continue
+        m = _DECL.match(line)
+        if m:
+            seen_decl = True
+            if pending:
+                docs[m.group(1)] = " ".join(p for p in pending if p).strip()
+        elif not seen_decl and pending and line.startswith("const") and not class_doc:
+            class_doc, pending = pending, []
+        pending = []
+    docs["@class"] = " ".join(p if p else "\n" for p in class_doc).replace(" \n ", "\n").strip()
+    return docs

spawnpoint/playtest/__init__.py

@@ -0,0 +1,104 @@
+"""Sub-project 5: bots play the game, telemetry is aggregated, parameters are tuned within bounds."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from .. import manifest as manifest_mod
+from ..build import build
+from ..manifest import Manifest
+from ..studio.creative import apply_patch
+from . import report as report_mod, runner, tuner
+from .report import Report
+from .tuner import Change
+
+OUT_DIR = "playtest"
+
+
+@dataclass
+class PlaytestResult:
+    baseline: Report
+    final: Report
+    changes: list[Change] = field(default_factory=list)
+    rounds: list[dict] = field(default_factory=list)
+    files: dict[str, Path] = field(default_factory=dict)
+    seconds: float = 0.0
+    difficulty: int = 2
+
+
+def goal_entities(graph: dict) -> set[str]:
+    return {n for n, e in graph["entities"].items()
+            if any(c in e.get("components", {}) for c in ("Collectible", "TriggerZone"))}
+
+
+def merge_tuning(old: list[dict], changes: list[Change]) -> list[dict]:
+    merged = {(t["entity"], t["component"], t["param"]): t for t in old}
+    for c in changes:
+        merged[(c.entity, c.component, c.param)] = c.to_patch()
+    return list(merged.values())
+
+
+def playtest(project: Path, *, runs: int = 3, profiles: tuple[str, ...] = runner.PROFILES, tune: bool = False,
+             rounds: int = 2, seed: int = 1, manifest: Manifest | None = None, original: dict | None = None,
+             difficulty: int = 2, brief: dict | None = None,
+             on_progress: Callable[[str], None] | None = None) -> PlaytestResult:
+    """Plays `project` with bots; with `tune`, proposes bounded changes and keeps them only if the
+    score improves. `original` is the untuned graph used for the bounds (default: current graph)."""
+    t0 = time.perf_counter()
+    manifest = manifest or manifest_mod.load()
+    say = on_progress or (lambda _m: None)
+    graph = json.loads((project / "spawnpoint.json").read_text())
+    original = original or graph
+    goals = goal_entities(graph)
+    limit = runner.time_limit(graph, brief)
+
+    say(f"playing {len(profiles)} profiles x {runs} runs (≤ {limit:.0f}s each)")
+    baseline = report_mod.aggregate(runner.run(project, profiles=profiles, runs=runs, seed=seed, limit_s=limit), goals)
+    best_graph, best = graph, baseline
+    result = PlaytestResult(baseline, baseline, difficulty=difficulty)
+    built_graph = graph
+    if tune:
+        for i in range(rounds):
+            changes = tuner.propose(best, best_graph, original, manifest, difficulty)
+            if not changes:
+                break
+            say(f"round {i + 1}: trying {len(changes)} change(s)")
+            candidate = apply_patch(best_graph, {"set_params": [c.to_patch() for c in changes], "add_rules": []})
+            built = build(candidate, project, manifest=manifest, smoke=True)
+            built_graph = candidate
+            if not built.ok:
+                result.rounds.append({"round": i + 1, "changes": [str(c) for c in changes], "accepted": False,
+                                      "error": [str(d) for d in built.diagnostics.errors]})
+                break
+            rep = report_mod.aggregate(runner.run(project, profiles=profiles, runs=runs, seed=seed, limit_s=limit,
+                                                  sync=False), goals)
+            before, after = tuner.score(best, difficulty), tuner.score(rep, difficulty)
+            accepted = after < before
+            result.rounds.append({"round": i + 1, "changes": [str(c) for c in changes], "score_before": before,
+                                  "score_after": after, "accepted": accepted})
+            say(f"round {i + 1}: score {before} -> {after} ({'kept' if accepted else 'reverted'})")
+            if not accepted:
+                break
+            best_graph, best = candidate, rep
+            result.changes.extend(changes)
+        if built_graph is not best_graph:  # the last candidate was rejected: rebuild the best one
+            build(best_graph, project, manifest=manifest, smoke=False)
+    result.final = best
+    out = project / OUT_DIR
+    out.mkdir(exist_ok=True)
+    payload = {"difficulty": difficulty, "targets": tuner.targets(difficulty),
+               "score": {"baseline": tuner.score(baseline, difficulty), "final": tuner.score(best, difficulty)},
+               "baseline": baseline.to_dict(), "final": best.to_dict(), "rounds": result.rounds,
+               "changes": [c.to_patch() | {"reason": c.reason} for c in result.changes]}
+    (out / "report.json").write_text(json.dumps(payload, indent=1, ensure_ascii=False))
+    (out / "report.md").write_text(report_mod.markdown(best, best_graph.get("name", project.name),
+                                                       [str(c) for c in result.changes]))
+    plan = json.loads((project / "build_plan.json").read_text())
+    report_mod.heatmap(plan, best.runs, out / "heatmap.png")
+    result.files = {"json": out / "report.json", "md": out / "report.md", "heatmap": out / "heatmap.png"}
+    result.seconds = time.perf_counter() - t0
+    return result