spriteforge 0.1.1__py3-none-any.whl

spriteforge/game/record.py

@@ -0,0 +1,138 @@
+"""Serve a build locally and record its autoplay: fixed-step frames, encoded with ffmpeg."""
+
+import base64
+import json
+import shutil
+import subprocess
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from threading import Thread
+
+from playwright.sync_api import Error as PlaywrightError
+from playwright.sync_api import sync_playwright
+
+READY = "window.sf && window.sf.ready === true"
+
+
+class QuietHandler(SimpleHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+
+@contextmanager
+def serve(directory: Path):
+    """Serve one build folder on 127.0.0.1 (random port) for the headless browser."""
+    server = ThreadingHTTPServer(("127.0.0.1", 0), partial(QuietHandler, directory=str(directory)))
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_port}"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+def wait_until(page, expression: str, timeout: float = 30) -> bool:
+    """Poll `expression` with `page.evaluate` until it is true; False after `timeout` seconds.
+
+    Not `page.wait_for_function`: when the expression is not true at its first check, it
+    polls by compiling the string in the page, which a build's CSP (no 'unsafe-eval') blocks
+    with an EvalError. Slow-loading builds then looked like they never booted (L2.2 live run:
+    a build with 24 entities was reported "no-boot" while it ran fine in a browser)."""
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            if page.evaluate(expression):
+                return True
+        except PlaywrightError:  # the page is still navigating: not ready yet
+            pass
+        if time.monotonic() >= deadline:
+            return False
+        page.wait_for_timeout(50)
+
+
+def encode(frames_dir: Path, fps: int, scale: int, out: Path) -> Path | None:
+    """PNG frames -> H.264 mp4 scaled with nearest neighbour; None when ffmpeg is missing."""
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        return None
+    cmd = [
+        ffmpeg,
+        "-y",
+        "-loglevel",
+        "error",
+        "-framerate",
+        str(fps),
+        "-i",
+        str(frames_dir / "%05d.png"),
+        "-vf",
+        f"scale=iw*{scale}:ih*{scale}:flags=neighbor,format=yuv420p",
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-crf",
+        "16",
+        "-movflags",
+        "+faststart",
+        str(out),
+    ]
+    subprocess.run(cmd, check=True)
+    return out
+
+
+@dataclass
+class Recording:
+    video: Path | None
+    poster: Path
+    summary: dict
+
+
+def record_game(
+    build_dir: Path, out_dir: Path, *, seconds: float = 20, fps: int = 30, scale: int = 2
+) -> Recording:
+    """Play the build's own autoplay for `seconds` (?demo=1&capture=1) and save demo.mp4 and
+    poster.png. Frames are stepped by the SDK, so the same build always gives the same video."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    total = int(seconds * fps)
+    with TemporaryDirectory() as tmp, serve(Path(build_dir)) as url:
+        frames_dir = Path(tmp)
+        with sync_playwright() as pw:
+            browser = pw.chromium.launch(headless=True)
+            try:
+                page = browser.new_page(viewport={"width": 320, "height": 180})
+                errors: list[str] = []
+                page.on("pageerror", lambda e: errors.append(str(e)))
+                page.goto(f"{url}/index.html?demo=1&capture=1")
+                if not wait_until(page, READY):
+                    raise RuntimeError("the game never finished booting (sf.ready stayed false)")
+                n = 0
+                while n < total:
+                    batch = page.evaluate(f"window.sfCapture({min(fps, total - n)}, {fps})")
+                    for data_url in batch:
+                        png = base64.b64decode(data_url.split(",", 1)[1])
+                        (frames_dir / f"{n:05d}.png").write_bytes(png)
+                        n += 1
+                counts = page.evaluate("window.sf.counts")
+                errors += page.evaluate("window.sf.errors")
+            finally:
+                browser.close()
+        poster = out_dir / "poster.png"
+        shutil.copy(frames_dir / f"{min(total - 1, int(fps * 2.5)):05d}.png", poster)
+        video = encode(frames_dir, fps, scale, out_dir / "demo.mp4")
+    summary = {
+        "seconds": seconds,
+        "fps": fps,
+        "frames": total,
+        "video": video.name if video else None,
+        "events": {name: c["count"] for name, c in counts.items()},
+        "errors": errors[:20],
+    }
+    (out_dir / "recording.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
+    return Recording(video, poster, summary)

spriteforge/game/research.py

@@ -0,0 +1,262 @@
+"""Research: how good games of this kind work, studied with live web search before designing.
+
+The Game Designer (Muse Spark with `web_search`, Responses API) names 3-6 reference games
+with a page about each, the patterns that make the genre's levels interesting, the feel
+numbers players expect (in tiles and seconds), and common pitfalls. References teach
+patterns: the design is original and never copies a game's levels, characters, story or art.
+
+Code checks what the model cannot be trusted with: a reference's URL counts as verified only
+when one of the searches returned that page (the JSON answer may name a URL no search
+found); URLs that are not http(s) are dropped; lists are bounded. Offline (mock runs, or the
+human said no research at G1) a stand-in is read from the genre notes, with no references.
+"""
+
+import re
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, Field
+
+from spriteforge.agents.models import Contract
+from spriteforge.providers.base import SearchResult, WebSource
+
+MAX_REFERENCES, MAX_PATTERNS, MAX_FEEL, MAX_PITFALLS = 6, 8, 10, 8
+PATTERN_KINDS = ("teaching a mechanic safely", "gating", "combining abilities",
+                 "risk and reward", "pacing")  # fmt: skip
+
+
+class Reference(Contract):
+    title: str = Field(description="a published game of this genre")
+    url: str = Field(description="a page about it that one of your searches returned")
+    learn: str = Field(
+        description="the pattern to learn from it, concretely; never its levels, characters, "
+        "story or art to copy"
+    )
+
+
+class Pattern(Contract):
+    name: str = Field(description="e.g. " + ", ".join(PATTERN_KINDS))
+    how: str = Field(description="how good games of the genre do it, concretely")
+    use: str = Field(description="how this game could use it")
+
+
+class FeelNumber(Contract):
+    name: str = Field(description="e.g. jump height, air time, move speed, dash length, coyote time")
+    value: str = Field(description="the number players expect, in tiles and seconds")
+    why: str
+
+
+class Research(Contract):
+    references: list[Reference] = Field(description="3 to 6 reference games")
+    patterns: list[Pattern]
+    feel: list[FeelNumber]
+    pitfalls: list[str] = Field(description="common mistakes in games of this kind")
+
+
+class ResearchRecord(BaseModel):
+    """What the run keeps (`game/research.json`): the answer and how it was checked."""
+
+    research: Research
+    verified: list[bool]  # per reference: a search returned its URL
+    sources: list[WebSource] = Field(default_factory=list)  # every page the searches returned
+    queries: list[str] = Field(default_factory=list)
+    searches: int = 0
+    by: str = ""
+    notes: list[str] = Field(default_factory=list)
+
+    @property
+    def references(self) -> list[tuple[Reference, bool]]:
+        return list(zip(self.research.references, self.verified, strict=True))
+
+
+def research_prompt(request: str, genre: str) -> str:
+    return f"""Before we design this game, study how good published games of its kind work.
+Use web search. Find 3 to 6 well-regarded games of this genre and, for each, a page about it
+that a search returned (url) and what to learn from it. Then:
+* patterns: what makes this genre's levels interesting, concretely: {", ".join(PATTERN_KINDS)};
+  for each, how good games do it and how this game could use it;
+* feel: the numbers players expect, in tiles (16 px) and seconds: move speed, jump height and
+  air time, dash length and cooldown, coyote time, or what fits this genre;
+* pitfalls: common mistakes in games of this kind.
+References teach patterns only. Our game is original: never copy a specific game's levels,
+characters, story or art. Short, concrete sentences.
+
+Genre: {genre}
+
+The human's request:
+{request.strip()}"""
+
+
+def level_research_prompt(design_text: str, levels: str) -> str:
+    return f"""Before laying out this platformer's levels, study the level design of well-regarded
+published platformers like it. Use web search. Find 3 to 6 games and, for each, a page about
+it that a search returned (url) and the level-design lesson to learn from it. Then:
+* patterns: how good levels use height and depth (upper routes, drops, more than one way),
+  puzzles (levers or switches and the doors they open, keys, coming back the way you came),
+  teaching a new idea safely, pacing and checkpoints, secrets and optional paths, and how
+  long a level runs; for each, how good games do it and how these levels could use it;
+* feel: the level numbers players expect: screens per level, seconds per level, checkpoints
+  per level, how much of a level is climbing or falling;
+* pitfalls: common level-design mistakes.
+References teach patterns only. Our levels are original: never copy a game's levels.
+Short, concrete sentences.
+
+The game:
+{design_text.strip()}
+
+The planned levels:
+{levels.strip()}"""
+
+
+def fallback_level_research() -> Research:
+    """Offline stand-in: level-design patterns without references (nothing was searched)."""
+    p = lambda name, how, use: Pattern(name=name, how=how, use=use)
+    return Research(
+        references=[],
+        patterns=[
+            p("height and depth", "levels climb to upper ledges and drop into lower rooms; the "
+              "way on is seldom one flat line", "give each level an upper and a lower stretch"),
+            p("lever puzzles", "a lever off the main path opens a gate on it; the player goes "
+              "up or down to pull it and comes back", "where a level teaches looking around"),
+            p("pacing", "a hard stretch, then a calm one with a checkpoint", "a checkpoint "
+              "after every challenge"),
+        ],
+        feel=[FeelNumber(name="level length", value="3 to 6 screens (60 to 120 tiles)",
+                         why="long enough to build an idea, short enough to retry")],
+        pitfalls=["one long flat corridor", "a gate whose lever cannot be found"],
+    )
+
+
+def structure_prompt(text: str, sources: list[WebSource]) -> str:
+    """The second call when the searched answer did not fit the schema: structure it."""
+    pages = "\n".join(f"- {s.url}" + (f" ({s.title})" if s.title else "") for s in sources[:40])
+    return f"""Put these research notes into the schema. Use only these pages as reference
+URLs (leave url '' when none fits); keep every number and pattern the notes give.
+
+Pages the searches returned:
+{pages or "- (none)"}
+
+Notes:
+{text.strip()[:12000]}"""
+
+
+def section(body: str, heading: str) -> str:
+    part = body.split("# " + heading + "\n", 1)
+    return part[1].split("\n# ", 1)[0].strip() if len(part) == 2 else ""
+
+
+def fallback_research(genre_body: str, side_view: bool) -> Research:
+    """Offline stand-in from the genre notes: no references (nothing was searched)."""
+    loop = section(genre_body, "Core mechanics template") or "the genre's core loop"
+    pitfalls = [re.sub(r"^[*-]\s*", "", line).strip()
+                for line in section(genre_body, "Common pitfalls").splitlines() if line.strip()]  # fmt: skip
+    feel = [
+        FeelNumber(name="move speed", value="6 tiles per second", why="crosses a screen in 3 s"),
+    ]
+    if side_view:
+        feel += [
+            FeelNumber(name="jump height", value="3 tiles", why="clears enemies and low walls"),
+            FeelNumber(name="air time", value="0.7 s", why="time to steer without floating"),
+            FeelNumber(name="coyote time", value="0.1 s", why="forgives a late jump at a ledge"),
+        ]
+    patterns = [
+        Pattern(name="teaching a mechanic safely", how="show a new idea where failing costs "
+                "nothing, then test it with a hazard", use=f"each level introduces one idea of {loop}"),
+        Pattern(name="pacing", how="alternate tense stretches with calm ones and checkpoints",
+                use="a checkpoint after every hard challenge"),
+    ]  # fmt: skip
+    return Research(references=[], patterns=patterns, feel=feel,
+                    pitfalls=pitfalls[:MAX_PITFALLS] or ["difficulty spikes with no warning"])  # fmt: skip
+
+
+def norm_url(url: str) -> str:
+    """Comparable form of a URL: no scheme, no www., no fragment, no trailing slash."""
+    try:
+        parts = urlsplit(url.strip())
+    except ValueError:
+        return ""
+    host = (parts.hostname or "").lower().removeprefix("www.")
+    path = parts.path.rstrip("/")
+    return host + path + (f"?{parts.query}" if parts.query else "")
+
+
+def web_url(url: str) -> bool:
+    try:
+        parts = urlsplit(url.strip())
+    except ValueError:
+        return False
+    return parts.scheme in {"http", "https"} and bool(parts.hostname)
+
+
+def fit_research(research: Research, found: SearchResult | None, by: str) -> ResearchRecord:
+    """The research as code allows it: bounded lists, unique references, http(s) URLs only,
+    and each reference marked verified only when a search returned its page."""
+    notes = []
+    seen, refs = set(), []
+    for r in research.references:
+        key = r.title.strip().casefold()
+        if not key or key in seen:
+            continue
+        seen.add(key)
+        if r.url and not web_url(r.url):
+            notes.append(f"{r.title}: {r.url!r} is not a web page; dropped")
+            r = r.model_copy(update={"url": ""})
+        refs.append(r)
+    if len(refs) > MAX_REFERENCES:
+        notes.append(f"{len(refs)} references; kept the first {MAX_REFERENCES}")
+        refs = refs[:MAX_REFERENCES]
+    pages = {norm_url(s.url) for s in (found.sources if found else [])} - {""}
+    verified = [bool(r.url) and norm_url(r.url) in pages for r in refs]
+    for r, ok in zip(refs, verified, strict=True):
+        if r.url and not ok:
+            notes.append(f"{r.title}: {r.url} was not among the pages the searches returned")
+    clean = lambda items, n: [re.sub(r"\s+", " ", i).strip() for i in items if i.strip()][:n]
+    fitted = research.model_copy(update={
+        "references": refs,
+        "patterns": research.patterns[:MAX_PATTERNS],
+        "feel": research.feel[:MAX_FEEL],
+        "pitfalls": clean(research.pitfalls, MAX_PITFALLS),
+    })  # fmt: skip
+    return ResearchRecord(
+        research=fitted,
+        verified=verified,
+        sources=[s for s in (found.sources if found else []) if web_url(s.url)],
+        queries=found.queries if found else [],
+        searches=found.searches if found else 0,
+        by=by,
+        notes=notes,
+    )
+
+
+def research_brief(record: ResearchRecord) -> str:
+    """The research as the plan prompt reads it (no source lists)."""
+    r = record.research
+    refs = "\n".join(f"- {ref.title}: {ref.learn}" for ref in r.references)
+    pats = "\n".join(f"- {p.name}: {p.how} For this game: {p.use}" for p in r.patterns)
+    feel = "\n".join(f"- {f.name}: {f.value} ({f.why})" for f in r.feel)
+    return (
+        f"Reference games (patterns only, never copy):\n{refs or '- (none)'}\n"
+        f"Patterns:\n{pats or '- (none)'}\nFeel numbers players expect:\n{feel or '- (none)'}\n"
+        f"Pitfalls:\n" + ("\n".join(f"- {p}" for p in r.pitfalls) or "- (none)")
+    )
+
+
+def research_markdown(record: ResearchRecord) -> str:
+    r = record.research
+    refs = "\n".join(
+        f"* **{ref.title}**: {ref.learn}"
+        + (f" [{ref.url}]({ref.url})" if ref.url else "")
+        + ("" if ok or not ref.url else " _(not among the pages the searches returned)_")
+        for ref, ok in record.references
+    )
+    pats = "\n".join(f"* **{p.name}**: {p.how} _For this game:_ {p.use}" for p in r.patterns)
+    feel = "\n".join(f"| {f.name} | {f.value} | {f.why} |" for f in r.feel)
+    sources = "\n".join(f"* {s.url}" for s in record.sources[:30])
+    return (
+        f"# Research\n\n_{record.by}; {record.searches} search call(s)._\n\n"
+        f"## Reference games (patterns only)\n{refs or '- (none)'}\n\n## Patterns\n{pats}\n\n"
+        f"## Feel numbers\n| what | value | why |\n|---|---|---|\n{feel}\n\n"
+        "## Pitfalls\n" + ("\n".join(f"* {p}" for p in r.pitfalls) or "- (none)")
+        + ("\n\n## Searched for\n" + "\n".join(f"* {q}" for q in record.queries) if record.queries else "")
+        + (f"\n\n## Sources the searches returned\n{sources}" if sources else "")
+        + "".join(f"\n> {n}" for n in record.notes) + "\n"
+    )  # fmt: skip

spriteforge/game/revision.py

@@ -0,0 +1,225 @@
+"""Reviewer feedback on a playable build -> what to redo (Director, Muse Spark).
+
+Only the parts the feedback is about are redone: the design (a new design version), the art
+of named entities (Muse edits of the previous image; everything else stays locked), and the
+code (the Programmer edits the working game). Untouched parts are reused as they are.
+"""
+
+import re
+
+from pydantic import Field, model_validator
+
+from spriteforge.agents.models import Contract
+
+from .design import GameDesign
+
+
+class ArtChange(Contract):
+    entity: str = Field(description="entity id whose look should change")
+    prompt: str = Field(description="the new look for Muse Image: subject, colours, materials")
+
+
+class LevelChange(Contract):
+    level: int = Field(description="the level number the feedback is about")
+    change: str = Field(description="what to change in that level, in the human's words")
+
+
+class Revision(Contract):
+    design_changes: str = Field(
+        description="rule, entity, progression or difficulty changes for the design doc; ''"
+    )
+    art_changes: list[ArtChange] = Field(description="entities to redraw; [] if none")
+    code_instructions: str = Field(
+        description="behaviour, controls, feel or UI changes for the programmer; ''"
+    )
+    drop_qa_tests: list[str] = Field(
+        description="names of QA tests the human wants dropped ('ignore the restart test'); []"
+    )
+    story_changes: str = Field(
+        description="only when the human asks for a story or changes to it (named characters, "
+        "plot, lore): what they want; ''"
+    )
+    level_changes: list[LevelChange] = Field(
+        description="changes to one level's layout (gaps, platforms, enemies, crates, length, "
+        "difficulty of that level); [] if none"
+    )
+    menu_changes: str = Field(
+        description="changes to the menus or the title screen (labels, colours, the title "
+        "picture, screens): what they want, in their words; ''"
+    )
+    sound_changes: str = Field(
+        description="changes to the sound effects (a sound too loud, wrong, missing or unwanted; "
+        "a new sound for something): what they want, in their words; ''"
+    )
+    add_qa_checks: list[str] = Field(
+        description="checks the human wants the QA Playtester to add to every build, each in "
+        "their words ('check that the bat cannot fly through walls'); [] if none"
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def older(cls, data):
+        """Revisions saved before QA tests, stories, levels, menus, sounds or suggested checks
+        existed lack those fields."""
+        if isinstance(data, dict):
+            data = {"drop_qa_tests": [], "story_changes": "", "level_changes": [],
+                    "menu_changes": "", "sound_changes": "", "add_qa_checks": [],
+                    **data}  # fmt: skip
+        return data
+
+    @property
+    def story_only(self) -> bool:
+        """Only the story changes: nothing to rebuild."""
+        return bool(self.story_changes.strip()) and not (
+            self.design_changes.strip()
+            or self.art_changes
+            or self.code_instructions.strip()
+            or self.drop_qa_tests
+            or self.add_qa_checks
+            or self.level_changes
+            or self.menu_changes.strip()
+            or self.sound_changes.strip()
+        )
+
+    @property
+    def sound_only(self) -> bool:
+        """Only the sounds change: they are data, swapped in the same build (no rebuild)."""
+        return bool(self.sound_changes.strip()) and not (
+            self.design_changes.strip()
+            or self.art_changes
+            or self.code_instructions.strip()
+            or self.drop_qa_tests
+            or self.add_qa_checks
+            or self.level_changes
+            or self.menu_changes.strip()
+            or self.story_changes.strip()
+        )
+
+
+def merge(a: Revision, b: Revision) -> Revision:
+    """Both revisions' changes: texts joined, lists concatenated (an entity or level named in
+    both keeps `b`'s change)."""
+
+    def text(x: str, y: str) -> str:
+        return "\n".join(p.strip() for p in (x, y) if p.strip())
+
+    art = {c.entity: c for c in [*a.art_changes, *b.art_changes]}
+    levels = {c.level: c for c in [*a.level_changes, *b.level_changes]}
+    return Revision(
+        design_changes=text(a.design_changes, b.design_changes),
+        art_changes=list(art.values()),
+        code_instructions=text(a.code_instructions, b.code_instructions),
+        drop_qa_tests=list(dict.fromkeys([*a.drop_qa_tests, *b.drop_qa_tests])),
+        story_changes=text(a.story_changes, b.story_changes),
+        level_changes=list(levels.values()),
+        menu_changes=text(a.menu_changes, b.menu_changes),
+        sound_changes=text(a.sound_changes, b.sound_changes),
+        add_qa_checks=list(dict.fromkeys([*a.add_qa_checks, *b.add_qa_checks])),
+    )
+
+
+def revision_prompt(
+    design: GameDesign, art: dict[str, str], feedback: str, qa: dict[str, bool] | None = None
+) -> str:
+    """`qa`: the build's QA tests by name -> passed."""
+    sources = "\n".join(f"* {eid}: {src}" for eid, src in art.items())
+    tests = "\n".join(
+        f"* {name}: {'passed' if ok else 'FAILED'}" for name, ok in (qa or {}).items()
+    )
+    return (
+        "A human played this build and wrote the feedback below. Split it into what must be "
+        "redone: design_changes (new or changed rules, entities, upgrades, difficulty), "
+        "art_changes (only entities whose look they want different, with the new look), "
+        "code_instructions (how the game should behave or feel), drop_qa_tests (exact names "
+        "of QA tests they want ignored or dropped, e.g. a test they judge wrong), "
+        "story_changes (only when they ask for a story, named characters, a plot or lore, or "
+        "for changes to the story: their words), and level_changes (feedback about one level's "
+        "layout: its gaps, platforms, enemies, crates, length or difficulty, with the level "
+        "number), and menu_changes (the title screen, menus, pause or game-over screens: "
+        "labels, colours, the title picture; the SDK draws them from data, so they are not "
+        "code), and sound_changes (sound effects: a sound too loud, quiet, wrong, unwanted or "
+        "missing; the SDK synthesises them from data, so they are not code), and add_qa_checks "
+        "(a 'check that ...' the human wants tested in every build: their words). Leave a part "
+        "empty when the feedback does not touch it; do not invent changes.\n\n"
+        f"Feedback:\n{feedback.strip()}\n\nDesign:\n{design.model_dump_json()}\n\n"
+        f"Current art sources:\n{sources}"
+        + (f"\n\nQA tests of this build:\n{tests}" if tests else "")
+    )
+
+
+DROP_VERBS = {"ignore", "drop", "remove", "skip", "delete", "disable"}
+FILLER = {"the", "a", "an", "this", "that", "those", "these", "qa", "failing", "broken", "wrong",
+          "bad", "please", "also", "too", "it", "one", "you", "can", "we", "just", "flaky"}  # fmt: skip
+
+
+def dropped_tests(feedback: str, names: list[str]) -> list[str]:
+    """QA tests the feedback asks to drop: "ignore the restart test" drops the tests whose name
+    has every word said before "test" ("restarts after losing"). Only a part with a drop verb
+    counts, or one that carries it on with "and" ("remove the idle test and the restart test");
+    "the restart test is fine, drop the menu test" drops only the menu test."""
+    out, carried = [], False
+    for clause in re.split(r"[,;.!?]", feedback.lower()):
+        parts = re.split(r"\band\b", clause)
+        if not re.match(r"\s*(and|also)\b", clause):
+            carried = False
+        for part in parts:
+            carried = carried or any(re.search(rf"\b{v}\b", part) for v in DROP_VERBS)
+            match = re.search(r"([a-z0-9 -]*?)\btests?\b", part) if carried else None
+            if not match:
+                continue
+            said = [w for w in re.findall(r"[a-z0-9]+", match.group(1))
+                    if w not in FILLER | DROP_VERBS]  # fmt: skip
+            for name in names:
+                words = set(re.findall(r"[a-z0-9]+", name.lower()))
+                stems = {w.rstrip("s") for w in words} | {w[:-2] for w in words if w.endswith("ed")}
+                if said and all(w in words or w.rstrip("s") in stems for w in said):
+                    out.append(name)
+    return list(dict.fromkeys(out))
+
+
+def fallback_revision(design: GameDesign, feedback: str, qa_names: list[str] = ()) -> Revision:
+    """Offline Director: entities named in the feedback are redrawn with it appended to their
+    look; QA tests it asks to ignore are dropped; a request for a story goes to the story;
+    everything else goes to the programmer."""
+    text = feedback.lower()
+    if STORY_ASK.search(text):
+        return Revision(design_changes="", art_changes=[], code_instructions="",
+                        drop_qa_tests=[], story_changes=feedback.strip(), level_changes=[],
+                        menu_changes="")  # fmt: skip
+    if SOUND_ASK.search(text):
+        return Revision(design_changes="", art_changes=[], code_instructions="", drop_qa_tests=[],
+                        story_changes="", level_changes=[], menu_changes="",
+                        sound_changes=feedback.strip())  # fmt: skip
+    if MENU_ASK.search(text):
+        return Revision(design_changes="", art_changes=[], code_instructions="", drop_qa_tests=[],
+                        story_changes="", level_changes=[], menu_changes=feedback.strip())  # fmt: skip
+    if levels := sorted({int(n) for n in LEVEL_ASK.findall(text)}):
+        return Revision(design_changes="", art_changes=[], code_instructions="", drop_qa_tests=[],
+                        story_changes="", level_changes=[LevelChange(level=n, change=feedback.strip())
+                                                         for n in levels], menu_changes="")  # fmt: skip
+    changes = [
+        ArtChange(entity=e.id, prompt=f"{e.look}; {feedback.strip()}")
+        for e in design.entities
+        if re.search(rf"\b{re.escape(e.id.replace('_', ' '))}s?\b", text.replace("_", " "))
+    ]
+    drops = dropped_tests(feedback, list(qa_names))
+    return Revision(
+        design_changes="",
+        art_changes=changes,
+        code_instructions="" if changes or drops else feedback.strip(),
+        drop_qa_tests=drops,
+        story_changes="",
+        level_changes=[],
+        menu_changes="",
+    )
+
+
+# "add a story", "give it a plot", "the story should ...": the offline Director's story cue.
+STORY_ASK = re.compile(r"\b(stor(y|ies|yline)|plot|lore|backstor(y|ies)|narrative)\b")
+# "the menus should be red", "a darker title screen": the offline Director's menu cue.
+MENU_ASK = re.compile(r"\b(menus?|title screen|title art|pause screen|game over screen|emblem)\b")
+# "the jump sound is too loud", "no menu beeps": the offline Director's sound cue.
+SOUND_ASK = re.compile(r"\b(sounds?|sfx|audio|noises?|beeps?|volume|loud(er)?|quiet(er)?|mute|"
+                       r"splash(es)?|bleeps?)\b")
+# "level 2 is too long", "make level 3 harder": the offline Director's level cue.
+LEVEL_ASK = re.compile(r"\blevel\s+(\d)\b")