spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/cockpit/static/app.js

@@ -0,0 +1,327 @@
+// Spawn Point Studio — cockpit page. Plain JS, no build step.
+"use strict";
+
+const state = { projects: [], current: null, detail: null, status: null, selected: null, running: 0 };
+const $ = (sel) => document.querySelector(sel);
+
+// Builds DOM without innerHTML (names and text may come from an LLM).
+function h(tag, attrs = {}, ...children) {
+  const el = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === null || v === undefined || v === false) continue;
+    if (k === "class") el.className = v;
+    else if (k.startsWith("on")) el.addEventListener(k.slice(2), v);
+    else if (k === "text") el.textContent = v;
+    else el.setAttribute(k, v === true ? "" : v);
+  }
+  for (const c of children.flat()) {
+    if (c === null || c === undefined || c === false) continue;
+    el.append(c instanceof Node ? c : document.createTextNode(String(c)));
+  }
+  return el;
+}
+
+async function api(path, body) {
+  const opts = body === undefined ? {} : { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) };
+  const res = await fetch(path, opts);
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || res.statusText);
+  return data;
+}
+
+function log(text, cls = "") {
+  const box = $("#log");
+  box.append(h("div", { class: cls, text: `${new Date().toLocaleTimeString()}  ${text}` }));
+  while (box.childElementCount > 400) box.firstChild.remove();
+  box.scrollTop = box.scrollHeight;
+}
+
+async function submitJob(promise, label) {
+  try {
+    const job = await promise;
+    log(`#${job.id} ${label} — queued`, "start");
+  } catch (e) {
+    log(`${label}: ${e.message}`, "error");
+  }
+}
+
+// --- status ---------------------------------------------------------------------------------
+
+async function refreshStatus() {
+  try {
+    state.status = await api("/api/status");
+  } catch { return; }
+  const s = state.status;
+  const llm = $("#pill-llm");
+  llm.textContent = s.llm ? `LLM ${s.model || ""}` : "LLM offline";
+  llm.className = `pill ${s.llm ? "ok" : "down"}`;
+  llm.title = s.llm ? s.base_url : `No LLM at ${s.base_url}. Start one with scripts/llm-up.sh — parameter edits and playtests still work.`;
+  const gd = $("#pill-godot");
+  gd.textContent = s.godot ? "Godot ready" : "Godot missing";
+  gd.className = `pill ${s.godot ? "ok" : "down"}`;
+  document.querySelectorAll("button.llm").forEach((b) => { b.disabled = !s.llm; b.title = s.llm ? "" : llm.title; });
+}
+
+function setBusy(delta) {
+  state.running = Math.max(0, state.running + delta);
+  const p = $("#pill-job");
+  p.textContent = state.running ? `working… (${state.running})` : "idle";
+  p.className = `pill ${state.running ? "busy" : "idle"}`;
+}
+
+// --- projects -------------------------------------------------------------------------------
+
+async function loadProjects() {
+  state.projects = await api("/api/projects");
+  const ul = $("#project-list");
+  ul.replaceChildren(...state.projects.map((p) =>
+    h("li", { class: p.name === state.current ? "active" : "", onclick: () => openProject(p.name), "data-name": p.name },
+      h("span", { text: p.title }),
+      h("span", { class: "badge", text: `${p.genre}${p.studio ? "" : " · graph"}` }))));
+  if (!state.projects.length) ul.append(h("li", { class: "muted", text: "No games yet." }));
+}
+
+async function openProject(name, { keepGame = false } = {}) {
+  const changed = state.current !== name;
+  state.current = name;
+  document.querySelectorAll("#project-list li").forEach((li) => li.classList.toggle("active", li.dataset.name === name));
+  state.detail = await api(`/api/projects/${encodeURIComponent(name)}`);
+  const d = state.detail;
+  $("#stage-empty").hidden = true;
+  $("#stage-noweb").hidden = d.web;
+  const frame = $("#game");
+  if (d.web && (changed || !keepGame || !frame.src)) frame.src = `/game/${encodeURIComponent(name)}/`;
+  if (!d.web) frame.removeAttribute("src");
+  if (changed) clearSelection();
+  renderDesks();
+}
+
+// --- desks ----------------------------------------------------------------------------------
+
+function renderDesks() {
+  renderDesigner();
+  renderArtist();
+  renderDeveloper();
+  renderQA();
+  if (state.selected) renderSelection();
+}
+
+function chips(items) {
+  return h("div", { class: "chips" }, items.map((t) => h("span", { class: "chip", text: t })));
+}
+
+function renderDesigner() {
+  const d = state.detail;
+  const box = $("#tab-designer");
+  if (!d) return box.replaceChildren();
+  const rows = [];
+  const kv = (k, v) => rows.push(h("dt", { text: k }), h("dd", {}, v));
+  if (d.brief) {
+    const b = d.brief;
+    kv("Title", b.title);
+    kv("Genre", `${b.genre} · ${b.palette} palette`);
+    kv("Goal", b.goal + (b.goal === "score_target" ? ` (${b.score_target})` : b.goal === "survive" ? ` (${b.survive_seconds}s)` : ""));
+    kv("Player", chips([b.player.character, ...b.player.abilities, `jump ${b.player.jump_tiles} tiles`, `${b.player.speed}`, `${b.player.health} hp`]));
+    kv("Enemies", chips(b.enemies.map((e) => `${e.count}× ${e.name} (${e.archetype})`)));
+    kv("Pickups", `${b.collectible.count}× ${b.collectible.name}` + (b.health_pickups ? ` · ${b.health_pickups} hearts` : ""));
+    kv("Level", `${b.length} · difficulty ${b.difficulty} · ${b.hazards.join(", ") || "no hazards"}`);
+    kv("Feel", `${b.feel} · juice ${b.juice}`);
+    kv("Intro", b.intro);
+  } else {
+    kv("Title", d.title);
+    kv("Genre", d.genre);
+    kv("Entities", chips(Object.keys(d.entities)));
+  }
+  const parts = [h("dl", { class: "kv" }, rows), h("h2", { text: "Rules" }),
+    h("ul", { class: "changes" }, d.rules.map((r) => h("li", { text: `on ${r.on}${r.if ? ` if ${r.if}` : ""} → ${[].concat(r.do).join(", ")}` })))];
+  if (d.history.length) parts.push(h("h2", { text: "Tweaks" }), h("ul", { class: "changes" }, d.history.map((x) => h("li", {}, h("b", { text: x.request }), h("div", { class: "muted", text: x.changes.join(" · ") || "no change" })))));
+  if (d.overrides.length) parts.push(h("h2", { text: `Studio edits (${d.overrides.length})` }), h("ul", { class: "changes" }, d.overrides.map((o) => h("li", { class: "muted", text: describePatch(o) }))));
+  if (d.tuning.length) parts.push(h("h2", { text: "Playtest tuning" }), h("ul", { class: "changes" }, d.tuning.map((t) => h("li", { class: "muted", text: `${t.entity}.${t.component}.${t.param} = ${t.value}` }))));
+  box.replaceChildren(...parts);
+}
+
+function describePatch(p) {
+  const out = [];
+  (p.set_params || []).forEach((s) => out.push(`${s.entity}.${s.component}.${s.param} = ${s.value}`));
+  (p.add_components || []).forEach((a) => out.push(`+${a.component} on ${a.entity}`));
+  Object.keys(p.add_entities || {}).forEach((n) => out.push(`+entity ${n}`));
+  (p.add_rules || []).forEach((r) => out.push(`+rule on ${r.on}`));
+  return out.join(" · ");
+}
+
+function renderArtist() {
+  const d = state.detail;
+  const box = $("#tab-artist");
+  if (!d) return box.replaceChildren();
+  const cards = Object.entries(d.entities).map(([name, e]) =>
+    h("div", { class: "sprite-card", onclick: () => select(name) },
+      h("div", { class: "thumb" }, e.sprite
+        ? h("img", { src: `/files/${encodeURIComponent(d.name)}/sprites/${encodeURIComponent(name)}.png?t=${Date.now()}`, alt: name })
+        : h("span", { class: "muted", text: "shape" })),
+      h("div", { text: name })));
+  box.replaceChildren(h("p", { class: "muted", text: "Sprite sheets, one row per animation. Click one to select the entity." }), h("div", { class: "gallery" }, cards));
+}
+
+function paramInput(entity, comp, p) {
+  const send = (value) => submitJob(api(`/api/projects/${encodeURIComponent(state.current)}/params`, { entity, component: comp, param: p.name, value }), `${entity}.${comp}.${p.name} = ${value}`);
+  let input;
+  if (p.type === "bool") {
+    input = h("input", { type: "checkbox", onchange: (e) => send(e.target.checked) });
+    input.checked = !!p.value;
+  } else if (p.choices) {
+    input = h("select", { onchange: (e) => send(e.target.value) }, p.choices.map((c) => h("option", { value: c, text: c, selected: c === p.value })));
+  } else if (p.type === "int" || p.type === "float") {
+    const step = p.type === "int" ? 1 : (Math.abs(p.max ?? 1) > 50 ? 1 : 0.01);
+    input = h("input", { type: "number", value: p.value, min: p.min ?? null, max: p.max ?? null, step,
+      onchange: (e) => { const v = p.type === "int" ? parseInt(e.target.value, 10) : parseFloat(e.target.value); if (!Number.isNaN(v)) send(v); } });
+  } else {
+    input = h("input", { type: "text", value: p.value ?? "", onchange: (e) => send(e.target.value) });
+  }
+  return h("div", { class: `param ${p.set ? "set" : ""}`, title: p.doc || "" }, h("label", { text: p.name }), input);
+}
+
+function renderDeveloper() {
+  const d = state.detail;
+  const box = $("#tab-developer");
+  if (!d) return box.replaceChildren();
+  const items = Object.entries(d.entities).map(([name, e]) => {
+    const det = h("details", { class: `entity ${state.selected === name ? "selected" : ""}`, "data-entity": name, open: state.selected === name },
+      h("summary", {}, h("span", { text: name }), h("span", { class: "badge", text: `${e.body}${e.team ? " · " + e.team : ""}` })),
+      Object.entries(e.components).map(([cname, c]) => h("div", { class: "component" },
+        h("h4", { text: cname, title: c.doc }),
+        c.params.length ? c.params.map((p) => paramInput(name, cname, p)) : h("div", { class: "muted", text: "no parameters" }))));
+    return det;
+  });
+  box.replaceChildren(h("p", { class: "muted", text: "Edit any parameter: the game rebuilds and reloads (no LLM needed). Bold = set by the game, grey = default." }), ...items);
+}
+
+function renderQA() {
+  const d = state.detail;
+  const box = $("#tab-qa");
+  if (!d) return box.replaceChildren();
+  const run = (tune) => submitJob(api(`/api/projects/${encodeURIComponent(d.name)}/playtest`, { tune }), tune ? "playtest + tune" : "playtest");
+  const parts = [h("div", { class: "row" },
+    h("button", { onclick: () => run(false), text: "Run playtest" }),
+    h("button", { class: "primary", onclick: () => run(true), text: "Run + tune" }))];
+  const pt = d.playtest;
+  if (!pt) {
+    parts.push(h("p", { class: "muted", text: "Bots (novice / average / expert) play the game headless, report where and why they die, and can tune parameters within safe bounds." }));
+  } else {
+    const prof = pt.final.profiles;
+    parts.push(h("table", { class: "stats" },
+      h("tr", {}, ["profile", "won", "deaths", "top causes", "pickups"].map((t) => h("th", { text: t }))),
+      Object.values(prof).map((p) => h("tr", {},
+        h("td", { text: p.profile }), h("td", { text: `${p.wins}/${p.runs}` }), h("td", { text: p.deaths }),
+        h("td", { text: Object.entries(p.causes).slice(0, 3).map(([k, v]) => `${k} ${v}`).join(", ") || "—" }),
+        h("td", { text: `${Math.round(p.pickup_rate * 100)}%` })))));
+    parts.push(h("p", { class: "muted", text: `score ${pt.score.baseline} → ${pt.score.final} (lower is better) · difficulty ${pt.difficulty} · targets ${JSON.stringify(pt.targets)}` }));
+    if (pt.changes.length) parts.push(h("h2", { text: "Tuning applied" }), h("ul", { class: "changes" }, pt.changes.map((c) => h("li", {}, h("b", { text: `${c.entity}.${c.component}.${c.param} = ${c.value}` }), h("div", { class: "muted", text: c.reason })))));
+    if (pt.final.level_issues.length) parts.push(h("h2", { text: "Level issues" }), h("ul", { class: "issues" }, pt.final.level_issues.map((i) => h("li", { text: i }))));
+    parts.push(h("img", { class: "heatmap", src: `/files/${encodeURIComponent(d.name)}/playtest/heatmap.png?t=${Date.now()}`, alt: "death heatmap" }));
+  }
+  box.replaceChildren(...parts);
+}
+
+// --- selection (click-to-edit) --------------------------------------------------------------
+
+function select(entity) {
+  if (!state.detail || !state.detail.entities[entity]) return;
+  state.selected = entity;
+  renderSelection();
+  renderDeveloper();
+  showTab("developer");
+  const el = document.querySelector(`details[data-entity="${CSS.escape(entity)}"]`);
+  if (el) el.scrollIntoView({ block: "nearest", behavior: "smooth" });
+  $("#ask-input").focus();
+}
+
+function renderSelection() {
+  const e = state.detail && state.detail.entities[state.selected];
+  if (!e) return clearSelection();
+  $("#selection").hidden = false;
+  $("#sel-name").textContent = state.selected;
+  $("#sel-summary").textContent = Object.keys(e.components).join(" · ") || "no components";
+}
+
+function clearSelection() {
+  state.selected = null;
+  $("#selection").hidden = true;
+}
+
+window.addEventListener("message", (ev) => {
+  const data = ev.data;
+  if (data && data.spawnpoint === "select" && typeof data.entity === "string") {
+    log(`selected ${data.entity} (${data.node}) in the game`);
+    select(data.entity);
+  }
+});
+
+// --- tabs & forms ---------------------------------------------------------------------------
+
+function showTab(name) {
+  document.querySelectorAll(".tab").forEach((t) => t.classList.toggle("active", t.dataset.tab === name));
+  document.querySelectorAll(".desk").forEach((d) => { d.hidden = d.id !== `tab-${name}`; });
+}
+document.querySelectorAll(".tab").forEach((t) => t.addEventListener("click", () => showTab(t.dataset.tab)));
+
+$("#new-game").addEventListener("submit", (ev) => {
+  ev.preventDefault();
+  const prompt = $("#prompt").value.trim();
+  if (!prompt) return;
+  submitJob(api("/api/create", { prompt, playtest: $("#opt-playtest").checked, creative: $("#opt-creative").checked }), `create “${prompt}”`);
+});
+
+$("#tweak").addEventListener("submit", (ev) => {
+  ev.preventDefault();
+  const request = $("#tweak-input").value.trim();
+  if (!request || !state.current) return;
+  submitJob(api(`/api/projects/${encodeURIComponent(state.current)}/tweak`, { request }), `tweak “${request}”`);
+  $("#tweak-input").value = "";
+});
+
+$("#ask").addEventListener("submit", (ev) => {
+  ev.preventDefault();
+  const request = $("#ask-input").value.trim();
+  if (!request || !state.current || !state.selected) return;
+  submitJob(api(`/api/projects/${encodeURIComponent(state.current)}/entity`, { entity: state.selected, request }), `${state.selected}: “${request}”`);
+  $("#ask-input").value = "";
+});
+
+$("#sel-close").addEventListener("click", () => { clearSelection(); renderDeveloper(); });
+$("#btn-export").addEventListener("click", () => state.current && submitJob(api(`/api/projects/${encodeURIComponent(state.current)}/export`, {}), "web build"));
+
+// --- live events ----------------------------------------------------------------------------
+
+function connectEvents() {
+  const es = new EventSource("/api/events");
+  es.onmessage = async (msg) => {
+    const ev = JSON.parse(msg.data);
+    const job = ev.job;
+    switch (ev.type) {
+      case "started": setBusy(+1); log(`#${job.id} ${job.kind}${job.project ? " " + job.project : ""} — running`, "start"); break;
+      case "log": log(`#${ev.job}  ${ev.message}`); break;
+      case "reload":
+        await loadProjects();
+        if (!state.current) await openProject(ev.project);
+        else if (ev.project === state.current) await openProject(ev.project, { keepGame: true });
+        break;
+      case "done":
+        setBusy(-1);
+        log(`#${job.id} ${job.kind} — done`, "done");
+        await loadProjects();
+        if (job.kind === "create" && job.result && job.result.project) await openProject(job.result.project);
+        else if (job.project && job.project === state.current) await openProject(job.project, { keepGame: true });
+        break;
+      case "error": setBusy(-1); log(`#${job.id} ${job.kind} — failed: ${job.error}`, "error"); break;
+    }
+  };
+  es.onerror = () => { /* EventSource reconnects by itself */ };
+}
+
+(async function main() {
+  connectEvents();
+  await refreshStatus();
+  setInterval(refreshStatus, 30000);
+  await loadProjects();
+  if (state.projects.length) await openProject(state.projects[0].name);
+})();

spawnpoint/cockpit/static/index.html

@@ -0,0 +1,79 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Spawn Point Studio</title>
+  <link rel="stylesheet" href="/static/app.css">
+</head>
+<body>
+  <header class="topbar">
+    <div class="brand"><span class="logo">▲</span> Spawn Point <b>Studio</b></div>
+    <div class="pills">
+      <span id="pill-llm" class="pill">LLM …</span>
+      <span id="pill-godot" class="pill">Godot …</span>
+      <span id="pill-job" class="pill idle">idle</span>
+    </div>
+  </header>
+
+  <main class="floor">
+    <aside class="panel" id="projects">
+      <form id="new-game" class="card">
+        <label for="prompt">New game</label>
+        <textarea id="prompt" rows="3" placeholder="a ninja platformer where you collect stars…"></textarea>
+        <div class="row">
+          <label class="check"><input type="checkbox" id="opt-playtest"> playtest &amp; tune</label>
+          <label class="check"><input type="checkbox" id="opt-creative"> creative pass</label>
+        </div>
+        <button type="submit" class="primary llm">Create</button>
+      </form>
+      <h2>Games</h2>
+      <ul id="project-list" class="list"></ul>
+    </aside>
+
+    <section class="panel" id="arcade">
+      <div class="stage">
+        <iframe id="game" title="game" allow="autoplay; fullscreen"></iframe>
+        <div id="stage-empty" class="stage-empty">
+          <p>Pick a game on the left, or describe a new one.</p>
+        </div>
+        <div id="stage-noweb" class="stage-empty" hidden>
+          <p>This game has no web build yet.</p>
+          <button id="btn-export" class="primary">Build web version</button>
+        </div>
+      </div>
+      <p class="hint">Click the game to play · <b>right-click</b> an enemy or item to select it · R restarts</p>
+      <form id="tweak" class="bar">
+        <input id="tweak-input" placeholder="Change the game: “jump 20% higher, add a dash, night colors”" autocomplete="off">
+        <button type="submit" class="primary llm">Tweak</button>
+      </form>
+      <div id="log" class="log" aria-live="polite"></div>
+    </section>
+
+    <aside class="panel" id="desks">
+      <section id="selection" class="card selection" hidden>
+        <div class="row between">
+          <h3>Selected: <span id="sel-name"></span></h3>
+          <button id="sel-close" class="ghost" title="clear selection">✕</button>
+        </div>
+        <p id="sel-summary" class="muted"></p>
+        <form id="ask" class="bar">
+          <input id="ask-input" placeholder="“double its health and make it shoot fireballs”" autocomplete="off">
+          <button type="submit" class="primary llm">Ask</button>
+        </form>
+      </section>
+      <nav class="tabs" role="tablist">
+        <button class="tab active" data-tab="designer">Designer</button>
+        <button class="tab" data-tab="artist">Artist</button>
+        <button class="tab" data-tab="developer">Developer</button>
+        <button class="tab" data-tab="qa">QA</button>
+      </nav>
+      <div class="desk" id="tab-designer"></div>
+      <div class="desk" id="tab-artist" hidden></div>
+      <div class="desk" id="tab-developer" hidden></div>
+      <div class="desk" id="tab-qa" hidden></div>
+    </aside>
+  </main>
+  <script src="/static/app.js"></script>
+</body>
+</html>

spawnpoint/diagnostics.py

@@ -0,0 +1,91 @@
+"""Structured diagnostics — the feedback channel for humans and for the LLM orchestrator."""
+
+from __future__ import annotations
+
+import difflib
+from dataclasses import asdict, dataclass, field
+from typing import Iterable, Literal
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    severity: Severity
+    code: str
+    path: str
+    message: str
+    hint: str | None = None
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        if d["hint"] is None:
+            del d["hint"]
+        return d
+
+    def __str__(self) -> str:
+        s = f"{self.severity}[{self.code}] {self.path}: {self.message}"
+        if self.hint:
+            s += f" (hint: {self.hint})"
+        return s
+
+
+@dataclass
+class Diagnostics:
+    items: list[Diagnostic] = field(default_factory=list)
+
+    def error(self, code: str, path: str, message: str, hint: str | None = None) -> None:
+        self.items.append(Diagnostic("error", code, path, message, hint))
+
+    def warning(self, code: str, path: str, message: str, hint: str | None = None) -> None:
+        self.items.append(Diagnostic("warning", code, path, message, hint))
+
+    def extend(self, other: Iterable[Diagnostic]) -> None:
+        self.items.extend(other)
+
+    @property
+    def errors(self) -> list[Diagnostic]:
+        return [d for d in self.items if d.severity == "error"]
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        return [d for d in self.items if d.severity == "warning"]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+
+def did_you_mean(word: str, options: Iterable[str]) -> str | None:
+    """Return a 'Did you mean ...?' hint, or a list of valid options when nothing is close."""
+    opts = sorted(set(options))
+    if not opts:
+        return None
+    close = difflib.get_close_matches(word, opts, n=1, cutoff=0.6)
+    if not close:
+        lowered = {o.lower(): o for o in opts}
+        if word.lower() in lowered:
+            close = [lowered[word.lower()]]
+    if close:
+        return f"Did you mean '{close[0]}'?"
+    if len(opts) <= 24:
+        return "Valid options: " + ", ".join(opts)
+    return None
+
+
+def join_path(*parts: object) -> str:
+    out = ""
+    for p in parts:
+        if isinstance(p, int):
+            out += f"[{p}]"
+        elif out:
+            out += f".{p}"
+        else:
+            out = str(p)
+    return out