spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/studio/orchestrator.py

@@ -0,0 +1,341 @@
+"""Studio orchestrator: prompt -> brief -> layered builds -> web; and tweaks of an existing game."""
+
+from __future__ import annotations
+
+import json
+import time
+import zlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from .. import manifest as manifest_mod
+from ..analyze import analyze
+from ..build import BuildResult, build
+from ..manifest import Manifest
+from . import web
+from .assemble import LAYERS, ai_art_from_env, assemble, chunks_fit, plan_chunks
+from .brief import GameBrief, json_schema, normalize
+from .creative import CreativeResult, creative_pass
+from .dataset import Recorder
+from .llm import ChatModel, LLMError, Usage
+from .prompts import (TRANSLATE_SCHEMA, brief_messages, needs_translation, translate_messages,
+                      tweak_messages)
+
+SESSION_FILE = "studio.json"
+SEED_ATTEMPTS = 8
+
+TWEAK_SCHEMA_NAME = "BriefUpdate"
+
+
+class StudioError(RuntimeError):
+    pass
+
+
+@dataclass
+class LayerReport:
+    layer: int
+    build: BuildResult
+    web_seconds: float | None = None
+
+
+@dataclass
+class StudioResult:
+    out_dir: Path
+    brief: GameBrief
+    notes: list[str]
+    seed: int
+    layers: list[LayerReport] = field(default_factory=list)
+    creative: CreativeResult | None = None
+    changes: list[str] = field(default_factory=list)
+    usage: Usage = field(default_factory=Usage)
+    timings: dict[str, float] = field(default_factory=dict)
+    playtest: object | None = None  # playtest.PlaytestResult when --playtest ran
+
+    @property
+    def ok(self) -> bool:
+        return bool(self.layers) and all(r.build.ok for r in self.layers)
+
+
+LayerCallback = Callable[[LayerReport], None]
+
+
+# --- brief ------------------------------------------------------------------------------------
+
+
+def design_brief(prompt: str, llm: ChatModel) -> tuple[GameBrief, list[str], str]:
+    """Returns (normalized brief, notes, the English prompt actually used)."""
+    english = prompt
+    if needs_translation(prompt):
+        english = llm.chat_json(translate_messages(prompt), TRANSLATE_SCHEMA, "Translation",
+                                temperature=0.1, max_tokens=300).get("english") or prompt
+    raw = llm.chat_json(brief_messages(english), json_schema(), "GameBrief", temperature=0.4)
+    try:
+        brief = GameBrief.model_validate(raw)
+    except Exception as e:  # guided decoding makes this rare; retry once with the error
+        raise StudioError(f"the LLM produced an invalid brief: {e}") from e
+    brief, notes = normalize(brief)
+    return brief, notes, english
+
+
+def _playable(brief: GameBrief, seed: int, chunks: list[str] | None, manifest: Manifest) -> bool:
+    analysis = analyze(assemble(brief, LAYERS[-1], seed, chunks), manifest)
+    return analysis.ok and not any(d.code == "W_UNREACHABLE" for d in analysis.diagnostics)
+
+
+def choose_seed(brief: GameBrief, seed: int, manifest: Manifest) -> tuple[int, list[str] | None]:
+    """First seed (from `seed`) whose full game has no reachability warnings, and its chunk plan."""
+    for s in range(seed, seed + SEED_ATTEMPTS):
+        chunks = plan_chunks(brief, s)
+        if _playable(brief, s, chunks, manifest):
+            return s, chunks
+    return seed, plan_chunks(brief, seed)
+
+
+def default_seed(prompt: str) -> int:
+    return zlib.crc32(prompt.encode()) % 100_000
+
+
+# --- create -----------------------------------------------------------------------------------
+
+
+def create(prompt: str, out_dir: Path | Callable[[GameBrief], Path], llm: ChatModel, *, seed: int | None = None, creative: bool = False,
+           brief: GameBrief | None = None, web_export: bool = True,
+           on_layer: LayerCallback | None = None, on_brief: Callable[[GameBrief, list[str]], None] | None = None,
+           manifest: Manifest | None = None, recorder: Recorder | None = None, playtest: bool = False,
+           on_progress: Callable[[str], None] | None = None) -> StudioResult:
+    result = None
+    try:
+        result = _create(prompt, out_dir, recorder.wrap(llm) if recorder else llm, seed, creative, brief, web_export,
+                         on_layer, on_brief, manifest, recorder)
+        if playtest and result.ok:
+            result.playtest = studio_playtest(result.out_dir, tune=True, web_export=web_export, manifest=manifest,
+                                              on_progress=on_progress)
+        return result
+    finally:
+        if recorder:
+            recorder.flush(accepted=bool(result and result.ok),
+                           meta={"op": "create", "prompt": prompt, "seed": result.seed if result else None})
+
+
+def _create(prompt, out_dir, llm, seed, creative, brief, web_export, on_layer, on_brief, manifest,
+            recorder: Recorder | None) -> StudioResult:
+    manifest = manifest or manifest_mod.load()
+    t0 = time.perf_counter()
+    timings: dict[str, float] = {}
+    english = prompt
+    if brief is None:
+        brief, notes, english = design_brief(prompt, llm)
+        if recorder:
+            _annotate_design(recorder, brief, notes)
+    else:
+        brief, notes = normalize(brief)
+    timings["design"] = time.perf_counter() - t0
+    if on_brief:
+        on_brief(brief, notes)
+    if callable(out_dir):  # e.g. a folder named after the designed title
+        out_dir = out_dir(brief)
+
+    seed, chunks = choose_seed(brief, default_seed(prompt) if seed is None else seed, manifest)
+    ai_art = ai_art_from_env()
+    result = StudioResult(out_dir, brief, notes, seed, usage=llm.usage)
+    creative_result = None
+    for layer in LAYERS:
+        graph = assemble(brief, layer, seed, chunks, ai_art=ai_art)
+        if layer == LAYERS[-1] and creative:
+            t = time.perf_counter()
+            creative_result = creative_pass(graph, english, llm, manifest)
+            timings["creative"] = time.perf_counter() - t
+            graph = creative_result.graph
+            if recorder:
+                for rec, h in zip(recorder.all("creative"), creative_result.history):
+                    rec.errors = h["errors"]
+                    rec.accepted = not h["errors"]
+                    rec.target = h["patch"] if not h["errors"] else None
+                    rec.corrected = bool(h["errors"])
+        report = _build_layer(layer, graph, out_dir, manifest, web_export)
+        result.layers.append(report)
+        if on_layer:
+            on_layer(report)
+        if not report.build.ok:
+            break
+    result.creative = creative_result
+    timings["total"] = time.perf_counter() - t0
+    result.timings = timings
+    _save_session(out_dir, {"prompt": prompt, "english": english, "brief": brief.model_dump(), "seed": seed,
+                            "chunks": chunks, "ai_art": ai_art,
+                            "creative_patch": creative_result.patch if creative_result else None,
+                            "model": llm.name, "history": []})
+    return result
+
+
+def _annotate_design(recorder: Recorder, brief: GameBrief, notes: list[str]) -> None:
+    tr = recorder.last("translate")
+    if tr:
+        tr.target, tr.corrected = tr.raw, False
+    rec = recorder.last("brief")
+    if rec:
+        rec.target = brief.model_dump()  # the normalized brief is the answer the model should have given
+        rec.notes = notes
+        rec.corrected = rec.target != GameBrief.model_validate(rec.raw).model_dump()
+
+
+def finalize_graph(graph: dict, session: dict, manifest: Manifest, tuning: bool = True) -> dict:
+    """Re-applies the session's creative patch, playtest tuning and cockpit overrides (in that order,
+    so a person's edit always wins over the tuner) to a freshly assembled graph. Each is kept only
+    while it still fits the game (a tweak may have removed an entity)."""
+    from ..analyze import analyze
+    from .creative import apply_patch
+
+    def try_apply(g: dict, patch: dict) -> dict:
+        candidate = apply_patch(g, patch)
+        return candidate if analyze(candidate, manifest).ok else g
+
+    if session.get("creative_patch"):
+        graph = try_apply(graph, session["creative_patch"])
+    entries = [t for t in (session.get("tuning") or []) if tuning
+               and t["component"] in graph["entities"].get(t["entity"], {}).get("components", {})]
+    if entries:
+        graph = try_apply(graph, {"set_params": entries, "add_rules": []})
+    for override in session.get("overrides") or []:  # cockpit edits, oldest first
+        graph = try_apply(graph, override)
+    return graph
+
+
+def studio_playtest(out_dir: Path, *, runs: int = 3, tune: bool = True, rounds: int = 2, web_export: bool = True,
+                    manifest: Manifest | None = None, on_progress: Callable[[str], None] | None = None):
+    """Playtests a studio game; accepted tuning is stored in the session so tweaks keep it."""
+    from .. import playtest as pt
+
+    manifest = manifest or manifest_mod.load()
+    session = load_session(out_dir)
+    brief = GameBrief.model_validate(session["brief"])
+    original = finalize_graph(assemble(brief, LAYERS[-1], session["seed"], session.get("chunks"),
+                                       ai_art=bool(session.get("ai_art"))), session,
+                              manifest, tuning=False)
+    res = pt.playtest(out_dir, runs=runs, tune=tune, rounds=rounds, manifest=manifest, original=original,
+                      difficulty=brief.difficulty, brief=session["brief"], on_progress=on_progress)
+    if res.changes:
+        session["tuning"] = pt.merge_tuning(session.get("tuning") or [], res.changes)
+        _save_session(out_dir, session)
+    if web_export and (out_dir / web.WEB_DIR / "index.html").exists():
+        web.export(out_dir)
+    return res
+
+
+def _build_layer(layer: int, graph: dict, out_dir: Path, manifest: Manifest, web_export: bool) -> LayerReport:
+    res = build(graph, out_dir, manifest=manifest, smoke=True)
+    report = LayerReport(layer, res)
+    if res.ok and web_export:
+        report.web_seconds = web.export(out_dir)
+    return report
+
+
+# --- tweak ------------------------------------------------------------------------------------
+
+
+def tweak_schema() -> dict:
+    schema = json_schema()
+    defs = schema.pop("$defs", {})
+    return {"type": "object", "$defs": defs,
+            "properties": {"brief": schema, "new_level": {"type": "boolean"}},
+            "required": ["brief", "new_level"], "additionalProperties": False}
+
+
+def tweak(out_dir: Path, request: str, llm: ChatModel, *, web_export: bool = True,
+          on_layer: LayerCallback | None = None, manifest: Manifest | None = None,
+          recorder: Recorder | None = None) -> StudioResult:
+    if recorder is None:
+        return _tweak(out_dir, request, llm, web_export, on_layer, manifest, None)
+    result = None
+    try:
+        result = _tweak(out_dir, request, recorder.wrap(llm), web_export, on_layer, manifest, recorder)
+        return result
+    finally:
+        recorder.flush(accepted=bool(result and result.ok),
+                       meta={"op": "tweak", "request": request, "changes": result.changes if result else None})
+
+
+def _tweak(out_dir, request, llm, web_export, on_layer, manifest, recorder: Recorder | None) -> StudioResult:
+    manifest = manifest or manifest_mod.load()
+    session = load_session(out_dir)
+    old = GameBrief.model_validate(session["brief"])
+    t0 = time.perf_counter()
+    english = request
+    if needs_translation(request):
+        english = llm.chat_json(translate_messages(request), TRANSLATE_SCHEMA, "Translation",
+                                temperature=0.1, max_tokens=300).get("english") or request
+    raw = llm.chat_json(tweak_messages(old.model_dump(), english), tweak_schema(), TWEAK_SCHEMA_NAME,
+                        temperature=0.1)
+    try:
+        new = GameBrief.model_validate(raw["brief"])
+    except Exception as e:
+        raise StudioError(f"the LLM produced an invalid brief update: {e}") from e
+    new, notes = normalize(new)
+    if recorder:
+        tr = recorder.last("translate")
+        if tr:
+            tr.target, tr.corrected = tr.raw, False
+        rec = recorder.last("tweak")
+        if rec:
+            rec.target = {"brief": new.model_dump(), "new_level": bool(raw.get("new_level"))}
+            rec.notes = notes
+            rec.corrected = rec.target["brief"] != GameBrief.model_validate(raw["brief"]).model_dump()
+    seed, chunks = session["seed"], session.get("chunks")
+    if raw.get("new_level"):
+        seed, chunks = choose_seed(new, seed + 1000, manifest)
+    elif new.genre != "platformer":
+        if new.genre != old.genre or not _playable(new, seed, None, manifest):
+            seed, chunks = choose_seed(new, seed, manifest)
+    elif not (chunks_fit(new, chunks) and _playable(new, seed, chunks, manifest)):
+        # The kept layout no longer works for the changed player (e.g. lower jump): re-plan.
+        seed, chunks = choose_seed(new, seed, manifest)
+    changes = diff_briefs(old.model_dump(), new.model_dump())
+    if raw.get("new_level"):
+        changes.append("new level layout")
+    timings = {"design": time.perf_counter() - t0}
+
+    result = StudioResult(out_dir, new, notes, seed, changes=changes, usage=llm.usage)
+    graph = finalize_graph(assemble(new, LAYERS[-1], seed, chunks, ai_art=bool(session.get("ai_art"))), session,
+                           manifest)
+    report = _build_layer(LAYERS[-1], graph, out_dir, manifest, web_export)
+    result.layers.append(report)
+    if on_layer:
+        on_layer(report)
+    timings["total"] = time.perf_counter() - t0
+    result.timings = timings
+    if report.build.ok:
+        session["history"].append({"request": request, "english": english, "changes": changes})
+        session.update(brief=new.model_dump(), seed=seed, chunks=chunks)
+        _save_session(out_dir, session)
+    return result
+
+
+def diff_briefs(old: dict, new: dict, prefix: str = "") -> list[str]:
+    out = []
+    for key in sorted(set(old) | set(new)):
+        a, b = old.get(key), new.get(key)
+        path = f"{prefix}{key}"
+        if isinstance(a, dict) and isinstance(b, dict):
+            out += diff_briefs(a, b, path + ".")
+        elif a != b:
+            out.append(f"{path}: {json.dumps(a, ensure_ascii=False)} -> {json.dumps(b, ensure_ascii=False)}")
+    return out
+
+
+# --- session ----------------------------------------------------------------------------------
+
+
+def load_session(out_dir: Path) -> dict:
+    path = out_dir / SESSION_FILE
+    if not path.exists():
+        raise StudioError(f"{out_dir} was not created by `spawnpoint create` (no {SESSION_FILE})")
+    return json.loads(path.read_text())
+
+
+def _save_session(out_dir: Path, data: dict) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    (out_dir / SESSION_FILE).write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+__all__ = ["create", "tweak", "design_brief", "StudioError", "StudioResult", "LLMError"]

spawnpoint/studio/prompts.py

@@ -0,0 +1,122 @@
+"""Prompts. Written for small local models: explicit rules, one worked example, common mistakes named."""
+
+from __future__ import annotations
+
+import json
+
+BRIEF_SYSTEM = """You are the lead designer of a tiny 2D game studio. Turn the user's game idea into a GameBrief JSON.
+
+Fields:
+- title: short catchy game title.
+- genre: "platformer" (side view, gravity, jumping between platforms) or "topdown" (seen from above, moves in 8 directions, usually shooting).
+- palette: night | forest | desert | neon | candy | ocean | lava | snow. Pick the one matching the theme.
+- player.character: what the player is, one word in PascalCase (e.g. "Ninja", "Fox", "Astronaut").
+- player.abilities: any of double_jump, dash, stomp (jump on enemies to defeat them), shoot. Top-down games usually have shoot and dash.
+- player.jump_tiles: jump height in tiles, 3-4 is normal. player.speed: slow | normal | fast. player.health: 3 is normal.
+- enemies: 1 to 3 enemy types. Each has
+    name: one singular noun in PascalCase, e.g. "Slime", "FireBat", "Robot".
+    archetype: walker (patrols back and forth; platformer), hopper (bounces around; platformer),
+               chaser (runs at the player), shooter (keeps distance and shoots), turret (stands still and shoots).
+    count: how many (2-6 each), health: 1-3, speed: slow | normal | fast.
+- collectible: the item the player picks up. name: singular noun in PascalCase (e.g. "Star"); count: 5-20.
+- health_pickups: 0-3 hearts that heal.
+- goal: reach_exit | collect_all | collect_all_then_exit | defeat_all | score_target | survive.
+  score_target and survive_seconds are only used by those goals.
+- hazards: any of spikes, pits (platformer only).
+- length: short | medium | long. difficulty: 1-5 (2 is normal).
+- feel: snappy (tight, default) | floaty (moon-like, slow falls) | heavy (weighty).
+- juice: subtle | normal | wild (how strong screen shake and impacts are).
+- intro: one short sentence shown when the game starts, telling the player the goal.
+
+Common mistakes to avoid:
+- The player is never an enemy or a collectible.
+- Platforms, walls, floors and the level itself are NOT enemies or collectibles; the level is generated automatically.
+- Names are singular ("Star", not "Stars").
+- Only use the archetypes listed above."""
+
+BRIEF_EXAMPLE_USER = "a space game where I blast alien bugs in an arena"
+BRIEF_EXAMPLE = {
+    "title": "Bug Blaster", "genre": "topdown", "palette": "neon",
+    "player": {"character": "Astronaut", "shape": "circle", "abilities": ["shoot", "dash"], "jump_tiles": 3.5, "speed": "normal", "health": 5},
+    "enemies": [{"name": "Beetle", "archetype": "chaser", "count": 5, "health": 2, "speed": "normal"},
+                {"name": "Spitter", "archetype": "shooter", "count": 2, "health": 3, "speed": "slow"}],
+    "collectible": {"name": "Crystal", "count": 8}, "health_pickups": 2, "goal": "score_target",
+    "score_target": 150, "survive_seconds": 60, "hazards": [], "length": "medium", "difficulty": 2,
+    "feel": "snappy", "juice": "wild", "intro": "Blast 150 points of bugs!",
+}
+
+
+def brief_messages(prompt: str) -> list[dict]:
+    return [
+        {"role": "system", "content": BRIEF_SYSTEM},
+        {"role": "user", "content": BRIEF_EXAMPLE_USER},
+        {"role": "assistant", "content": json.dumps(BRIEF_EXAMPLE)},
+        {"role": "user", "content": prompt},
+    ]
+
+
+TWEAK_SYSTEM = """You edit GameBrief JSON for a tiny 2D game studio.
+You get the current brief and a change request from the player. Return the updated brief.
+
+Rules:
+- Change ONLY the fields the request is about. Copy every other field exactly as it is.
+- Percentages scale numbers: "jump 20% higher" with jump_tiles 3.5 -> 4.2. "a bit" means about 15%.
+- "more enemies" increases counts; "harder" raises difficulty by 1; "add dash" adds "dash" to player.abilities.
+- Allowed values are the same as in the brief: archetypes walker, hopper, chaser, shooter, turret; abilities
+  double_jump, dash, stomp, shoot; palettes night, forest, desert, neon, candy, ocean, lava, snow.
+- Set new_level to true only if the player asks for a different level, map or layout."""
+
+
+def tweak_messages(brief: dict, request: str) -> list[dict]:
+    return [
+        {"role": "system", "content": TWEAK_SYSTEM},
+        {"role": "user", "content": f"Current brief:\n{json.dumps(brief)}\n\nChange request: {request}"},
+    ]
+
+
+CREATIVE_SYSTEM = """You are a game designer polishing a 2D game made of components.
+Propose a small patch that makes the game more fun and closer to the player's idea:
+- set_params: change component parameters of existing entities (only parameters listed in the reference, within range).
+- add_rules: new rules {"on": event, "if": condition or "", "do": [actions]}.
+Keep it small: at most 4 set_params and 3 add_rules. Do not repeat existing rules.
+
+Rule syntax:
+- events: Entity.signal (e.g. "Slime.died", "Star.collected"), "GameState.score_changed", "GameState.second_passed", "Game.ready".
+- conditions: Python-like expressions using score, lives, time, vars.NAME, event.ARG, count("Entity").
+- actions: add_score(n), set_var("name", v), add_var("name", d), win(), lose(), spawn("Entity") (at the emitting entity),
+  spawn_at("Entity", tile_x, tile_y), destroy(self), shake(0..1), freeze(seconds), sound("coin"), message("text"),
+  Entity.method(args) using methods from the reference (e.g. Door.open())."""
+
+
+def creative_messages(prompt: str, graph_summary: str, reference: str) -> list[dict]:
+    return [
+        {"role": "system", "content": CREATIVE_SYSTEM},
+        {"role": "user", "content": f"Player's idea: {prompt}\n\nGame:\n{graph_summary}\n\nComponent reference:\n{reference}"},
+    ]
+
+
+def repair_message(errors: list[str]) -> dict:
+    return {"role": "user", "content": "The compiler rejected the patch:\n- " + "\n- ".join(errors)
+            + "\nReturn a corrected patch (drop anything you cannot fix)."}
+
+
+TRANSLATE_SYSTEM = """Translate the user's game idea into clear English for a game designer.
+Keep every detail: characters, enemies, items, goals, numbers. Output JSON.
+Vietnamese game terms: "sao"/"ngôi sao" = star, "ăn"/"nhặt" an item = collect it, "qua màn" = finish the level,
+"quái"/"quái vật" = enemies/monsters, "né" = avoid/dodge, "bắn" = shoot, "nhảy" = jump, "bục" = platform,
+"sống sót" = survive, "tiêu diệt hết" = defeat all, "cửa" = door/exit, "gai" = spikes, "hố" = pits."""
+
+TRANSLATE_SCHEMA = {
+    "type": "object",
+    "properties": {"english": {"type": "string"}},
+    "required": ["english"],
+    "additionalProperties": False,
+}
+
+
+def translate_messages(prompt: str) -> list[dict]:
+    return [{"role": "system", "content": TRANSLATE_SYSTEM}, {"role": "user", "content": prompt}]
+
+
+def needs_translation(prompt: str) -> bool:
+    return any(ord(ch) > 127 for ch in prompt)

spawnpoint/studio/web.py

@@ -0,0 +1,123 @@
+"""Web export of a built project and a tiny live-reloading static server."""
+
+from __future__ import annotations
+
+import functools
+import json
+import socket
+import threading
+import time
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from .. import godot
+
+WEB_DIR = "web"
+VERSION_FILE = "version.json"
+
+# Polls version.json and reloads the page when a new build lands.
+LIVE_RELOAD = (
+    "<script>(function(){var v=null;setInterval(function(){"
+    "fetch('version.json?'+Date.now(),{cache:'no-store'}).then(function(r){return r.ok?r.json():null})"
+    ".then(function(j){if(!j)return;if(v!==null&&j.version!==v)location.reload();v=j.version;})"
+    ".catch(function(){});},1000);})();</script>"
+)
+
+
+def export_preset(head_include: str = LIVE_RELOAD) -> str:
+    return "\n".join([
+        "[preset.0]",
+        "",
+        'name="Web"',
+        'platform="Web"',
+        "runnable=true",
+        "dedicated_server=false",
+        'custom_features=""',
+        'export_filter="all_resources"',
+        'include_filter=""',
+        'exclude_filter="build_plan.json,spawnpoint.json,studio.json"',
+        f'export_path="{WEB_DIR}/index.html"',
+        "",
+        "[preset.0.options]",
+        "",
+        'custom_template/debug=""',
+        'custom_template/release=""',
+        "variant/extensions_support=false",
+        # Single-threaded build: plays from any static server, no COOP/COEP headers needed.
+        "variant/thread_support=false",
+        "vram_texture_compression/for_desktop=true",
+        "vram_texture_compression/for_mobile=false",
+        "html/export_icon=true",
+        'html/custom_html_shell=""',
+        f"html/head_include={json.dumps(head_include)}",
+        "html/canvas_resize_policy=2",
+        "html/focus_canvas_on_start=true",
+        "html/experimental_virtual_keyboard=false",
+        "progressive_web_app/enabled=false",
+        "",
+    ])
+
+
+def export(project: Path) -> float:
+    """Exports the project to <project>/web and bumps the live-reload version. Returns seconds."""
+    t0 = time.perf_counter()
+    web = project / WEB_DIR
+    web.mkdir(exist_ok=True)
+    (web / ".gdignore").write_text("")  # keep Godot from importing the build output
+    (project / "export_presets.cfg").write_text(export_preset())
+    result = godot.run(project, ["--export-release", "Web", f"{WEB_DIR}/index.html"], timeout=300)
+    if result.returncode != 0 or not (web / "index.html").exists():
+        raise godot.GodotError("web export failed (are the Godot web export templates installed?)", result.output)
+    bump_version(project)
+    return time.perf_counter() - t0
+
+
+def bump_version(project: Path) -> int:
+    path = project / WEB_DIR / VERSION_FILE
+    try:
+        version = json.loads(path.read_text())["version"] + 1
+    except (OSError, ValueError, KeyError):
+        version = 1
+    path.write_text(json.dumps({"version": version}))
+    return version
+
+
+class _Handler(SimpleHTTPRequestHandler):
+    extensions_map = {**SimpleHTTPRequestHandler.extensions_map, ".wasm": "application/wasm",
+                      ".pck": "application/octet-stream", ".js": "text/javascript"}
+
+    def end_headers(self) -> None:
+        self.send_header("Cache-Control", "no-store")
+        super().end_headers()
+
+    def log_message(self, format: str, *args) -> None:  # quiet
+        pass
+
+
+def free_port(start: int) -> int:
+    for port in range(start, start + 50):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            if s.connect_ex(("127.0.0.1", port)) != 0:
+                return port
+    raise OSError(f"no free port in {start}..{start + 49}")
+
+
+class Server:
+    """Serves <project>/web on localhost in a background thread."""
+
+    def __init__(self, project: Path, port: int = 8060):
+        self.port = free_port(port)
+        handler = functools.partial(_Handler, directory=str(project / WEB_DIR))
+        self.httpd = ThreadingHTTPServer(("127.0.0.1", self.port), handler)
+        self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+
+    @property
+    def url(self) -> str:
+        return f"http://localhost:{self.port}/"
+
+    def start(self) -> "Server":
+        self.thread.start()
+        return self
+
+    def stop(self) -> None:
+        self.httpd.shutdown()