spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/studio/brief.py

@@ -0,0 +1,197 @@
+"""GameBrief: the small, enumerated design an LLM fills in, plus normalization of weak-model output."""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Genre = Literal["platformer", "topdown"]
+Palette = Literal["night", "forest", "desert", "neon", "candy", "ocean", "lava", "snow"]
+Ability = Literal["double_jump", "dash", "stomp", "shoot"]
+Archetype = Literal["walker", "hopper", "chaser", "shooter", "turret"]
+Speed = Literal["slow", "normal", "fast"]
+Goal = Literal["reach_exit", "collect_all", "collect_all_then_exit", "defeat_all", "score_target", "survive"]
+Hazard = Literal["spikes", "pits"]
+
+ARCHETYPES_BY_GENRE: dict[str, tuple[str, ...]] = {
+    "platformer": ("walker", "hopper", "chaser", "shooter", "turret"),
+    "topdown": ("chaser", "shooter", "turret"),
+}
+# What an archetype becomes when it does not exist in the genre.
+ARCHETYPE_FALLBACK = {"topdown": {"walker": "chaser", "hopper": "chaser"}}
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class PlayerBrief(_Model):
+    character: str = Field(default="Hero", max_length=24, description="what the player is, e.g. Ninja, Fox, Robot")
+    shape: Literal["capsule", "circle", "rect"] = "capsule"
+    abilities: list[Ability] = Field(default_factory=list, max_length=4)
+    jump_tiles: float = Field(default=3.5, ge=1.5, le=8.0, description="jump height in tiles (platformer)")
+    speed: Speed = "normal"
+    health: int = Field(default=3, ge=1, le=10)
+
+
+class EnemyBrief(_Model):
+    name: str = Field(max_length=24)
+    archetype: Archetype
+    count: int = Field(default=3, ge=0, le=20)
+    health: int = Field(default=1, ge=1, le=20)
+    speed: Speed = "normal"
+
+
+class CollectibleBrief(_Model):
+    name: str = Field(default="Coin", max_length=24)
+    count: int = Field(default=10, ge=0, le=60)
+
+
+class GameBrief(_Model):
+    title: str = Field(max_length=40)
+    genre: Genre
+    palette: Palette = "night"
+    player: PlayerBrief = Field(default_factory=PlayerBrief)
+    enemies: list[EnemyBrief] = Field(default_factory=list, max_length=4)
+    collectible: CollectibleBrief = Field(default_factory=CollectibleBrief)
+    health_pickups: int = Field(default=1, ge=0, le=10)
+    goal: Goal = "collect_all_then_exit"
+    score_target: int = Field(default=100, ge=10, le=10000)
+    survive_seconds: int = Field(default=60, ge=10, le=600)
+    hazards: list[Hazard] = Field(default_factory=list, max_length=2)
+    length: Literal["short", "medium", "long"] = "medium"
+    difficulty: int = Field(default=2, ge=1, le=5)
+    feel: Literal["snappy", "floaty", "heavy"] = "snappy"
+    juice: Literal["subtle", "normal", "wild"] = "normal"
+    intro: str = Field(default="", max_length=80)
+
+
+def json_schema() -> dict:
+    """JSON schema for guided decoding (vLLM / OpenAI structured outputs)."""
+    return GameBrief.model_json_schema()
+
+
+# --- normalization ----------------------------------------------------------------------------
+
+RESERVED_NAMES = {
+    "Player", "Bullet", "EnemyBullet", "Exit", "Door", "HealthPack", "Spikes", "Portal",
+    "GameState", "Game", "World", "FX", "Sfx", "SP", "Entity", "Visual", "Shape", "Main", "Tiles",
+    "Entities", "Rules", "HUD", "Camera",
+}
+COMPONENT_NAMES = {
+    "Health", "Hitbox", "Hurtbox", "Weapon", "Projectile", "Collectible", "TriggerZone", "Spawner",
+    "Gate", "PlayerInput", "PatrolAI", "ChaseAI", "PlatformerMovement", "TopDownMovement", "Aim",
+    "Juice", "Stomp",
+}
+_IRREGULAR = {"enemies": "enemy", "bodies": "body", "ponies": "pony", "berries": "berry", "cherries": "cherry",
+              "flies": "fly", "mice": "mouse", "geese": "goose", "children": "child", "leaves": "leaf",
+              "knives": "knife", "wolves": "wolf", "elves": "elf", "zombies": "zombie", "lives": "life"}
+_KEEP_S = ("ss", "us", "is", "os")
+
+
+def pascal_singular(raw: str, fallback: str) -> str:
+    words = re.findall(r"[A-Za-z][A-Za-z0-9]*", raw or "")
+    if not words:
+        return fallback
+    last = words[-1].lower()
+    if last in _IRREGULAR:
+        words[-1] = _IRREGULAR[last]
+    elif last.endswith("ies") and len(last) > 4:
+        words[-1] = words[-1][:-3] + "y"
+    elif last.endswith("s") and not last.endswith(_KEEP_S) and len(last) > 3:
+        words[-1] = words[-1][:-1]
+    name = "".join(w[:1].upper() + w[1:] for w in words)[:24]
+    return name if name[:1].isalpha() else fallback
+
+
+def normalize(brief: GameBrief) -> tuple[GameBrief, list[str]]:
+    """Repair typical weak-model mistakes. Returns a new brief and human-readable notes."""
+    b = brief.model_copy(deep=True)
+    notes: list[str] = []
+    taken = set(RESERVED_NAMES) | set(COMPONENT_NAMES)
+
+    def unique(name: str, fallback: str, what: str) -> str:
+        fixed = pascal_singular(name, fallback)
+        if fixed in taken:
+            fixed = fixed + ("Foe" if what == "enemy" else "Item")
+        base, i = fixed, 2
+        while fixed in taken:
+            fixed, i = f"{base}{i}", i + 1
+        if fixed != name:
+            notes.append(f"renamed {what} '{name}' -> '{fixed}'")
+        taken.add(fixed)
+        return fixed
+
+    b.collectible.name = unique(b.collectible.name, "Coin", "collectible")
+    b.player.character = pascal_singular(b.player.character, "Hero")
+
+    allowed = ARCHETYPES_BY_GENRE[b.genre]
+    enemies = []
+    seen_names: set[str] = set()
+    for e in b.enemies:
+        if e.count == 0:
+            notes.append(f"dropped enemy '{e.name}' with count 0")
+            continue
+        if e.archetype not in allowed:
+            new = ARCHETYPE_FALLBACK.get(b.genre, {}).get(e.archetype, allowed[0])
+            notes.append(f"{e.name}: archetype '{e.archetype}' does not exist in {b.genre}; using '{new}'")
+            e.archetype = new
+        if pascal_singular(e.name, "Enemy").lower() in seen_names:
+            notes.append(f"merged duplicate enemy '{e.name}'")
+            continue
+        seen_names.add(pascal_singular(e.name, "Enemy").lower())
+        e.name = unique(e.name, "Enemy", "enemy")
+        enemies.append(e)
+    b.enemies = enemies
+
+    b.player.abilities = list(dict.fromkeys(b.player.abilities))
+    if b.genre == "topdown":
+        dropped = [a for a in b.player.abilities if a in ("double_jump", "stomp")]
+        if dropped:
+            notes.append(f"top-down has no jumping; ignored {', '.join(dropped)}")
+            b.player.abilities = [a for a in b.player.abilities if a not in dropped]
+        if "pits" in b.hazards:
+            b.hazards = [h for h in b.hazards if h != "pits"]
+            notes.append("top-down has no pits; ignored")
+        if not b.enemies and "shoot" not in b.player.abilities and b.goal in ("defeat_all",):
+            pass
+    b.hazards = list(dict.fromkeys(b.hazards))
+
+    total_enemies = sum(e.count for e in b.enemies)
+    if b.goal in ("collect_all", "collect_all_then_exit") and b.collectible.count == 0:
+        b.collectible.count = 8
+        notes.append(f"goal '{b.goal}' needs pickups; added 8 {b.collectible.name}s")
+    if b.goal == "defeat_all":
+        if total_enemies == 0:
+            b.goal = "reach_exit" if b.genre == "platformer" else "collect_all"
+            notes.append(f"goal 'defeat_all' without enemies; using '{b.goal}'")
+        elif b.genre == "topdown" and "shoot" not in b.player.abilities:
+            b.player.abilities.append("shoot")
+            notes.append("defeating enemies in top-down needs shooting; gave the player 'shoot'")
+        elif b.genre == "platformer" and not {"stomp", "shoot"} & set(b.player.abilities):
+            b.player.abilities.append("stomp")
+            notes.append("defeating enemies needs an attack; gave the player 'stomp'")
+    if b.goal == "collect_all" and b.genre == "topdown" and b.collectible.count == 0:
+        b.collectible.count = 10
+    if b.goal == "score_target":
+        reachable = b.collectible.count + total_enemies * 10
+        if reachable < b.score_target and b.genre == "platformer":
+            b.score_target = max(10, reachable - reachable % 5)
+            notes.append(f"score_target lowered to {b.score_target} (the level holds only that many points)")
+    if not b.intro:
+        b.intro = _default_intro(b)
+    return b, notes
+
+
+def _default_intro(b: GameBrief) -> str:
+    c = b.collectible.name
+    return {
+        "reach_exit": "Reach the exit!",
+        "collect_all": f"Collect every {c}!",
+        "collect_all_then_exit": f"Collect every {c} to open the door!",
+        "defeat_all": "Defeat every enemy!",
+        "score_target": f"Score {b.score_target} points!",
+        "survive": f"Survive {b.survive_seconds} seconds!",
+    }[b.goal]

spawnpoint/studio/creative.py

@@ -0,0 +1,124 @@
+"""Creative pass: the LLM proposes a small graph patch; the compiler is the judge.
+
+The patch is applied to a copy of the graph and analyzed. Diagnostics go back to the LLM for up to
+`max_repairs` rounds. If it still does not compile, the patch is dropped — the working build is kept.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from dataclasses import dataclass, field
+
+from ..analyze import analyze
+from ..manifest import Manifest
+from .llm import ChatModel, LLMError
+from .prompts import creative_messages, repair_message
+
+PATCH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "set_params": {
+            "type": "array", "maxItems": 4,
+            "items": {
+                "type": "object",
+                "properties": {
+                    "entity": {"type": "string"}, "component": {"type": "string"}, "param": {"type": "string"},
+                    "value": {"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "boolean"}]},
+                },
+                "required": ["entity", "component", "param", "value"], "additionalProperties": False,
+            },
+        },
+        "add_rules": {
+            "type": "array", "maxItems": 3,
+            "items": {
+                "type": "object",
+                "properties": {"on": {"type": "string"}, "if": {"type": "string"},
+                               "do": {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 4}},
+                "required": ["on", "if", "do"], "additionalProperties": False,
+            },
+        },
+    },
+    "required": ["set_params", "add_rules"], "additionalProperties": False,
+}
+
+
+@dataclass
+class CreativeResult:
+    graph: dict
+    applied: bool
+    patch: dict | None = None
+    rounds: int = 0
+    errors: list[str] = field(default_factory=list)
+    history: list[dict] = field(default_factory=list)  # per round: {"patch", "errors"}
+
+
+def apply_patch(graph: dict, patch: dict) -> dict:
+    """Applies a graph patch: add_entities, add_components, set_params, add_rules (in that order)."""
+    g = copy.deepcopy(graph)
+    for name, ent in (patch.get("add_entities") or {}).items():
+        g["entities"].setdefault(name, copy.deepcopy(ent))
+    for ac in patch.get("add_components", []):
+        ent = g["entities"].setdefault(ac["entity"], {"components": {}})
+        ent.setdefault("components", {}).setdefault(ac["component"], {}).update(ac.get("params") or {})
+    for sp in patch.get("set_params", []):
+        ent = g["entities"].get(sp["entity"])
+        if ent is None:
+            # Unknown entity: create the reference so the compiler reports it with a hint.
+            g["entities"].setdefault(sp["entity"], {"components": {}})
+            ent = g["entities"][sp["entity"]]
+        ent.setdefault("components", {}).setdefault(sp["component"], {})[sp["param"]] = sp["value"]
+    for r in patch.get("add_rules", []):
+        rule = {"on": r["on"], "do": r["do"]}
+        if r.get("if", "").strip():
+            rule["if"] = r["if"]
+        g.setdefault("rules", []).append(rule)
+    return g
+
+
+def summarize_graph(graph: dict) -> str:
+    lines = [f"genre: {graph['genre']}", "entities:"]
+    for name, ent in graph["entities"].items():
+        comps = ", ".join(f"{c}{params if params else ''}" for c, params in ent.get("components", {}).items())
+        lines.append(f"  {name}: {comps}")
+    lines.append("rules:")
+    for r in graph.get("rules", []):
+        cond = f" if {r['if']}" if r.get("if") else ""
+        lines.append(f"  on {r['on']}{cond} do {r['do']}")
+    return "\n".join(lines)
+
+
+def reference(graph: dict, manifest: Manifest) -> str:
+    """Only the components the game uses, to keep the prompt small."""
+    used = {c for ent in graph["entities"].values() for c in ent.get("components", {})}
+    lines = []
+    for name in sorted(used):
+        comp = manifest.get(name)
+        if comp is None:
+            continue
+        params = "; ".join(p.describe() for p in comp.params.values())
+        sigs = ", ".join(f"{s.name}({', '.join(a.name for a in s.args)})" for s in comp.signals.values())
+        methods = ", ".join(f"{m.name}({', '.join(a.name for a in m.args)})" for m in comp.methods.values())
+        lines.append(f"{name}: params {params}" + (f" | signals {sigs}" if sigs else "")
+                     + (f" | methods {methods}" if methods else ""))
+    return "\n".join(lines)
+
+
+def creative_pass(graph: dict, prompt: str, llm: ChatModel, manifest: Manifest, max_repairs: int = 2) -> CreativeResult:
+    messages = creative_messages(prompt, summarize_graph(graph), reference(graph, manifest))
+    errors: list[str] = []
+    history: list[dict] = []
+    for round_no in range(1 + max_repairs):
+        try:
+            patch = llm.chat_json(messages, PATCH_SCHEMA, "GraphPatch", temperature=0.5, max_tokens=800)
+        except LLMError as e:
+            return CreativeResult(graph, False, None, round_no, [str(e)], history)
+        candidate = apply_patch(graph, patch)
+        analysis = analyze(candidate, manifest)
+        errors = [str(d) for d in analysis.diagnostics.errors]
+        errors += [str(d) for d in analysis.diagnostics.warnings if d.code == "W_UNREACHABLE"]
+        history.append({"patch": patch, "errors": errors})
+        if not errors:
+            return CreativeResult(candidate, True, patch, round_no + 1, [], history)
+        messages = messages + [{"role": "assistant", "content": json.dumps(patch)}, repair_message(errors)]
+    return CreativeResult(graph, False, None, 1 + max_repairs, errors, history)

spawnpoint/studio/dataset.py

@@ -0,0 +1,136 @@
+"""Opt-in, local-only recording of LLM calls as fine-tuning data (sub-project 7).
+
+Each LLM call becomes one JSONL record: the exact messages, the model's raw output, and a
+`target` — the corrected answer the pipeline actually used (the normalized brief, or the patch the
+compiler accepted). Training on `messages -> target` teaches a model to stop making the mistakes the
+normalizer and the compiler had to catch. Nothing leaves the machine.
+
+Enable with `--record` or SPAWNPOINT_RECORD=1; location: SPAWNPOINT_DATASET_DIR
+(default ~/.local/share/spawnpoint/dataset).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .llm import ChatModel, Usage
+
+TASKS = {"Translation": "translate", "GameBrief": "brief", "BriefUpdate": "tweak", "GraphPatch": "creative"}
+
+
+def enabled_by_env() -> bool:
+    return os.environ.get("SPAWNPOINT_RECORD", "").lower() in ("1", "true", "yes", "on")
+
+
+def default_dir() -> Path:
+    env = os.environ.get("SPAWNPOINT_DATASET_DIR")
+    return Path(env) if env else Path.home() / ".local" / "share" / "spawnpoint" / "dataset"
+
+
+@dataclass
+class Record:
+    task: str
+    messages: list[dict]
+    schema_name: str
+    raw: Any
+    model: str
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    time: str = field(default_factory=lambda: time.strftime("%Y-%m-%dT%H:%M:%S"))
+    target: Any = None
+    notes: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    accepted: bool | None = None
+    corrected: bool | None = None  # the pipeline had to fix the model's answer
+    meta: dict = field(default_factory=dict)
+
+
+class Recorder:
+    """Collects records for one studio operation, then appends them to the day's JSONL file."""
+
+    def __init__(self, directory: Path | None = None):
+        self.directory = directory or default_dir()
+        self.pending: list[Record] = []
+
+    def wrap(self, llm: ChatModel) -> "RecordingModel":
+        return RecordingModel(llm, self)
+
+    def last(self, task: str) -> Record | None:
+        for r in reversed(self.pending):
+            if r.task == task:
+                return r
+        return None
+
+    def all(self, task: str) -> list[Record]:
+        return [r for r in self.pending if r.task == task]
+
+    def flush(self, accepted: bool, meta: dict | None = None) -> Path | None:
+        if not self.pending:
+            return None
+        self.directory.mkdir(parents=True, exist_ok=True)
+        path = self.directory / f"{time.strftime('%Y-%m-%d')}.jsonl"
+        with path.open("a", encoding="utf-8") as f:
+            for r in self.pending:
+                if r.accepted is None:
+                    r.accepted = accepted
+                r.meta = {**(meta or {}), **r.meta}
+                f.write(json.dumps(r.__dict__, ensure_ascii=False) + "\n")
+        self.pending = []
+        return path
+
+
+@dataclass
+class RecordingModel:
+    """ChatModel proxy that records every call into a Recorder."""
+
+    inner: ChatModel
+    recorder: Recorder
+
+    @property
+    def name(self) -> str:
+        return self.inner.name
+
+    @property
+    def usage(self) -> Usage:
+        return self.inner.usage
+
+    def chat_json(self, messages: list[dict], schema: dict, schema_name: str, **kw) -> dict:
+        raw = self.inner.chat_json(messages, schema, schema_name, **kw)
+        self.recorder.pending.append(Record(
+            task=TASKS.get(schema_name, schema_name), messages=messages, schema_name=schema_name,
+            raw=raw, model=self.inner.name))
+        return raw
+
+
+def iter_records(directory: Path | None = None):
+    d = directory or default_dir()
+    for path in sorted(d.glob("*.jsonl")):
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if line.strip():
+                yield json.loads(line)
+
+
+def stats(directory: Path | None = None) -> dict:
+    by_task: Counter = Counter()
+    accepted: Counter = Counter()
+    corrected: Counter = Counter()
+    models: Counter = Counter()
+    for r in iter_records(directory):
+        t = r["task"]
+        by_task[t] += 1
+        models[r.get("model", "?")] += 1
+        if r.get("accepted"):
+            accepted[t] += 1
+        if r.get("corrected"):
+            corrected[t] += 1
+    return {
+        "records": sum(by_task.values()),
+        "models": dict(models),
+        "tasks": {t: {"count": n, "accepted": accepted[t], "corrected": corrected[t]} for t, n in sorted(by_task.items())},
+    }

spawnpoint/studio/edits.py

@@ -0,0 +1,206 @@
+"""Edits of a built game from the cockpit: direct parameter changes and LLM edits scoped to one entity.
+
+Every edit is a graph patch (add_entities / add_components / set_params / add_rules). Studio games keep
+it as an override in studio.json (re-applied after every assemble); hand-written graphs are patched in
+place. The compiler judges every patch before anything is built.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+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, assemble
+from .brief import GameBrief
+from .creative import apply_patch
+from .llm import ChatModel, LLMError
+from .orchestrator import SESSION_FILE, _save_session, finalize_graph, load_session
+from .prompts import needs_translation, repair_message, translate_messages, TRANSLATE_SCHEMA
+
+VALUE = {"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "boolean"}]}
+ENTITY_PATCH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "set_params": {"type": "array", "maxItems": 6, "items": {
+            "type": "object", "additionalProperties": False, "required": ["component", "param", "value"],
+            "properties": {"component": {"type": "string"}, "param": {"type": "string"}, "value": VALUE}}},
+        "add_components": {"type": "array", "maxItems": 3, "items": {
+            "type": "object", "additionalProperties": False, "required": ["component", "params"],
+            "properties": {"component": {"type": "string"}, "params": {"type": "array", "maxItems": 6, "items": {
+                "type": "object", "additionalProperties": False, "required": ["param", "value"],
+                "properties": {"param": {"type": "string"}, "value": VALUE}}}}}},
+        "add_rules": {"type": "array", "maxItems": 2, "items": {
+            "type": "object", "additionalProperties": False, "required": ["on", "if", "do"],
+            "properties": {"on": {"type": "string"}, "if": {"type": "string"},
+                           "do": {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 3}}}},
+    },
+    "required": ["set_params", "add_components", "add_rules"],
+    "additionalProperties": False,
+}
+
+ADDABLE = ("Health", "Hurtbox", "Hitbox", "Weapon", "ChaseAI", "PatrolAI", "Spawner", "Stomp",
+           "PlatformerMovement", "TopDownMovement", "Collectible", "Gate")
+
+ENTITY_SYSTEM = """You edit ONE entity of a 2D game built from components. Return a small patch for it.
+- set_params: change parameters of components the entity already has (use the exact names below, stay in range).
+- add_components: give it a new component (only from the list of addable components).
+- add_rules: optional extra rules, e.g. {"on": "Slime.died", "if": "", "do": ["shake(0.6)"]}.
+Common requests:
+- "more health" / "x2 health" -> Health.max_health. "faster" -> the movement component's max_speed.
+- "make it shoot" -> add Weapon with projectile "EnemyBullet" (it will be created) and auto_fire true,
+  or with ChaseAI so it aims at the player. "fire bullets" -> projectile "Fireball".
+- "jump higher" -> PlatformerMovement.jump_velocity. "hits harder" -> Hitbox.damage.
+Keep it minimal: change only what is asked."""
+
+
+@dataclass
+class EditResult:
+    ok: bool
+    patch: dict | None = None
+    build: BuildResult | None = None
+    errors: list[str] = field(default_factory=list)
+    rounds: int = 0
+    english: str = ""
+
+
+def current_graph(project: Path) -> dict:
+    return json.loads((project / "spawnpoint.json").read_text())
+
+
+def _entity_view(graph: dict, entity: str, manifest: Manifest) -> str:
+    ent = graph["entities"][entity]
+    lines = [f"Entity {entity}: body {ent.get('body', 'character')}, team {ent.get('team', 'auto')}"]
+    for cname, params in ent.get("components", {}).items():
+        comp = manifest.get(cname)
+        if comp is None:
+            continue
+        values = {p.name: params.get(p.name, p.default) for p in comp.params.values()}
+        ranges = "; ".join(p.describe() for p in comp.params.values())
+        lines.append(f"- {cname} current {json.dumps(values)} | params: {ranges}")
+    addable = [c for c in ADDABLE if c not in ent.get("components", {}) and manifest.get(c)]
+    lines.append("Addable components:")
+    for cname in addable:
+        comp = manifest.get(cname)
+        lines.append(f"- {cname}: {comp.doc.splitlines()[0] if comp.doc else ''} params: "
+                     + "; ".join(p.describe() for p in comp.params.values()))
+    lines.append("Other entities: " + ", ".join(n for n in graph["entities"] if n != entity))
+    return "\n".join(lines)
+
+
+def scope_patch(entity: str, raw: dict) -> dict:
+    """LLM output (entity-relative) -> generic graph patch."""
+    return {
+        "set_params": [dict(sp, entity=entity) for sp in raw.get("set_params", [])],
+        "add_components": [{"entity": entity, "component": ac["component"],
+                            "params": {p["param"]: p["value"] for p in ac.get("params", [])}}
+                           for ac in raw.get("add_components", [])],
+        "add_rules": [{k: v for k, v in r.items() if not (k == "if" and not str(v).strip())}
+                      for r in raw.get("add_rules", [])],
+    }
+
+
+def add_missing_projectiles(graph: dict, patch: dict) -> dict:
+    """A new Weapon may name a projectile that does not exist yet: create a sensible one."""
+    patched = apply_patch(graph, patch)
+    extra = dict(patch.get("add_entities") or {})
+    for name, ent in patched["entities"].items():
+        weapon = ent.get("components", {}).get("Weapon")
+        if weapon is None:
+            continue
+        proj = weapon.get("projectile", "Bullet")
+        if proj in patched["entities"] or proj in extra:
+            continue
+        fiery = any(w in proj.lower() for w in ("fire", "flame", "lava", "magma"))
+        team = ent.get("team") or ("player" if "PlayerInput" in ent.get("components", {}) else "enemy")
+        extra[proj] = {
+            "body": "area", "team": team,
+            "sprite": {"generate": {"kind": "bullet", "color": "#ff6c11" if fiery else "#ff77a8"}},
+            "components": {"Projectile": {"speed": 320.0 if team == "enemy" else 700.0, "lifetime": 2.5},
+                           "Hitbox": {"damage": 1, "knockback": 220.0}},
+        }
+    if extra:
+        patch = dict(patch, add_entities=extra)
+    return patch
+
+
+def ask_entity(project: Path, entity: str, request: str, llm: ChatModel, manifest: Manifest | None = None,
+               max_repairs: int = 2) -> tuple[dict | None, list[str], int, str]:
+    """LLM -> validated patch for one entity. Returns (patch or None, last errors, rounds, english)."""
+    manifest = manifest or manifest_mod.load()
+    graph = current_graph(project)
+    if entity not in graph["entities"]:
+        return None, [f"unknown entity '{entity}'"], 0, request
+    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
+    messages = [{"role": "system", "content": ENTITY_SYSTEM},
+                {"role": "user", "content": f"{_entity_view(graph, entity, manifest)}\n\nRequest: {english}"}]
+    errors: list[str] = []
+    for round_no in range(1 + max_repairs):
+        raw = llm.chat_json(messages, ENTITY_PATCH_SCHEMA, "EntityPatch", temperature=0.2, max_tokens=700)
+        patch = add_missing_projectiles(graph, scope_patch(entity, raw))
+        if not any(patch.get(k) for k in ("set_params", "add_components", "add_rules")):
+            errors = ["the patch is empty"]
+        else:
+            analysis = analyze(apply_patch(graph, patch), manifest, base_dir=project)
+            errors = [str(d) for d in analysis.diagnostics.errors]
+            if not errors:
+                return patch, [], round_no + 1, english
+        messages = messages + [{"role": "assistant", "content": json.dumps(raw)}, repair_message(errors)]
+    return None, errors, 1 + max_repairs, english
+
+
+def apply_override(project: Path, patch: dict, *, manifest: Manifest | None = None, web_export: bool = True,
+                   smoke: bool = True) -> EditResult:
+    """Validates, persists and builds a patch. Studio games keep it in studio.json overrides."""
+    manifest = manifest or manifest_mod.load()
+    studio = (project / SESSION_FILE).exists()
+    if studio:
+        session = load_session(project)
+        brief = GameBrief.model_validate(session["brief"])
+        trial = dict(session, overrides=(session.get("overrides") or []) + [patch])
+        base = assemble(brief, LAYERS[-1], session["seed"], session.get("chunks"), ai_art=bool(session.get("ai_art")))
+        graph = finalize_graph(base, trial, manifest)
+        # finalize_graph silently skips patches that no longer fit; this one must fit now.
+        check = analyze(apply_patch(finalize_graph(base, session, manifest), patch), manifest)
+    else:
+        graph = apply_patch(current_graph(project), patch)
+        check = analyze(graph, manifest, base_dir=project)
+    errors = [str(d) for d in check.diagnostics.errors]
+    if errors:
+        return EditResult(False, patch, errors=errors)
+    res = build(graph, project, manifest=manifest, smoke=smoke)
+    if not res.ok:
+        return EditResult(False, patch, res, [str(d) for d in res.diagnostics.errors])
+    if studio:
+        session["overrides"] = trial["overrides"]
+        _save_session(project, session)
+    if web_export and (project / web.WEB_DIR / "index.html").exists():
+        web.export(project)
+    return EditResult(True, patch, res)
+
+
+def set_param_patch(entity: str, component: str, param: str, value) -> dict:
+    return {"set_params": [{"entity": entity, "component": component, "param": param, "value": value}]}
+
+
+def edit_entity(project: Path, entity: str, request: str, llm: ChatModel, *, manifest: Manifest | None = None,
+                web_export: bool = True) -> EditResult:
+    manifest = manifest or manifest_mod.load()
+    try:
+        patch, errors, rounds, english = ask_entity(project, entity, request, llm, manifest)
+    except LLMError as e:
+        return EditResult(False, None, errors=[str(e)])
+    if patch is None:
+        return EditResult(False, None, errors=errors, rounds=rounds, english=english)
+    res = apply_override(project, copy.deepcopy(patch), manifest=manifest, web_export=web_export)
+    res.rounds, res.english = rounds, english
+    return res