spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/expr.py

@@ -0,0 +1,219 @@
+"""Rule expressions: a whitelisted subset of Python syntax translated to GDScript.
+
+Supported: numbers, strings, true/false, `score`, `lives`, `time`, `vars.<name>`,
+`event.<arg>`, `self`, `self.<Component>.<property>`, functions count("Entity"), randf(),
+min, max, abs, str; operators + - * / %, comparisons (chainable), and/or/not.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import re
+from dataclasses import dataclass, field
+
+from .diagnostics import Diagnostics, did_you_mean
+from .manifest import Manifest
+
+FUNCS = {"count": (1, 1), "randf": (0, 0), "min": (2, 2), "max": (2, 2), "abs": (1, 1), "str": (1, 1)}
+GLOBALS = {"score": "GameState.score", "lives": "GameState.lives", "time": "GameState.time"}
+CONSTS = {"true": "true", "false": "false", "True": "true", "False": "false", "null": "null", "None": "null"}
+
+_BIN = {ast.Add: "+", ast.Sub: "-", ast.Mult: "*"}
+_CMP = {ast.Eq: "==", ast.NotEq: "!=", ast.Lt: "<", ast.LtE: "<=", ast.Gt: ">", ast.GtE: ">="}
+
+
+class ExprError(Exception):
+    def __init__(self, message: str, hint: str | None = None):
+        super().__init__(message)
+        self.hint = hint
+
+
+@dataclass
+class Scope:
+    """What an expression may reference."""
+
+    manifest: Manifest
+    entities: dict[str, list[str]]  # entity name -> component names
+    event_args: dict[str, str] = field(default_factory=dict)  # arg name -> GDScript param name
+    self_entity: str | None = None  # entity type of `self`, None if no source entity
+    used: set[str] = field(default_factory=set)  # param names referenced (for unused-arg naming)
+
+
+_STRING = re.compile(r"(\"(?:\\.|[^\"\\])*\"|'(?:\\.|[^'\\])*')")
+
+
+def normalize(src: str) -> str:
+    """Accept common C-style operators from LLM output (outside string literals)."""
+    parts = _STRING.split(src)
+    for i in range(0, len(parts), 2):
+        s = parts[i].replace("&&", " and ").replace("||", " or ")
+        parts[i] = re.sub(r"!(?!=)", " not ", s)
+    return "".join(parts)
+
+
+def parse(src: str) -> ast.expr:
+    try:
+        return ast.parse(normalize(src).strip(), mode="eval").body
+    except SyntaxError as e:
+        raise ExprError(f"syntax error in '{src}': {e.msg}") from e
+
+
+def translate(src: str, scope: Scope) -> str:
+    return _Translator(scope).visit(parse(src))
+
+
+def check(src: str, scope: Scope, diags: Diagnostics, path: str) -> str | None:
+    try:
+        return translate(src, scope)
+    except ExprError as e:
+        diags.error("E_EXPR", path, str(e), e.hint)
+        return None
+
+
+def gd_string(s: str) -> str:
+    return json.dumps(s, ensure_ascii=False)
+
+
+class _Translator:
+    def __init__(self, scope: Scope):
+        self.s = scope
+
+    def visit(self, node: ast.AST) -> str:
+        method = getattr(self, "v_" + type(node).__name__, None)
+        if method is None:
+            raise ExprError(f"'{ast.unparse(node)}' is not allowed in rule expressions")
+        return method(node)
+
+    def v_Constant(self, n: ast.Constant) -> str:
+        v = n.value
+        if isinstance(v, bool):
+            return "true" if v else "false"
+        if v is None:
+            return "null"
+        if isinstance(v, (int, float)):
+            return repr(v)
+        if isinstance(v, str):
+            return gd_string(v)
+        raise ExprError(f"unsupported literal {v!r}")
+
+    def v_Name(self, n: ast.Name) -> str:
+        if n.id in CONSTS:
+            return CONSTS[n.id]
+        if n.id in GLOBALS:
+            return GLOBALS[n.id]
+        if n.id == "self":
+            if self.s.self_entity is None:
+                raise ExprError("'self' is not available for this event (no emitting entity)")
+            self.s.used.add("source")
+            return "source"
+        if n.id in self.s.entities:
+            raise ExprError(f"'{n.id}' is an entity type, not a value", f'Use count("{n.id}") for how many exist')
+        if n.id in ("event", "vars"):
+            raise ExprError(f"'{n.id}' needs a field, e.g. {n.id}.something")
+        raise ExprError(f"unknown name '{n.id}'", did_you_mean(n.id, [*GLOBALS, "self", "event", "vars"]))
+
+    def v_Attribute(self, n: ast.Attribute) -> str:
+        chain = _attr_chain(n)
+        if chain is None:
+            raise ExprError(f"'{ast.unparse(n)}' is not allowed")
+        head, *rest = chain
+        if head == "vars" and len(rest) == 1:
+            return f"GameState.get_var({gd_string(rest[0])})"
+        if head == "event" and len(rest) == 1:
+            arg = rest[0]
+            if arg not in self.s.event_args:
+                opts = list(self.s.event_args)
+                raise ExprError(f"event has no argument '{arg}'",
+                                did_you_mean(arg, opts) if opts else "This event has no arguments")
+            gd = self.s.event_args[arg]
+            self.s.used.add(gd)
+            return gd
+        if head == "self" and len(rest) == 2:
+            if self.s.self_entity is None:
+                raise ExprError("'self' is not available for this event (no emitting entity)")
+            comp_name, prop = rest
+            comps = self.s.entities.get(self.s.self_entity, [])
+            if comp_name not in comps:
+                raise ExprError(f"{self.s.self_entity} has no component '{comp_name}'", did_you_mean(comp_name, comps))
+            comp = self.s.manifest.get(comp_name)
+            props = [*comp.params, *comp.state] if comp else []
+            if prop not in props:
+                raise ExprError(f"{comp_name} has no property '{prop}'", did_you_mean(prop, props))
+            self.s.used.add("source")
+            return f'SP.component(source, &"{comp_name}").{prop}'
+        raise ExprError(f"'{ast.unparse(n)}' is not allowed",
+                        "Use vars.<name>, event.<arg> or self.<Component>.<property>")
+
+    def v_Call(self, n: ast.Call) -> str:
+        if not isinstance(n.func, ast.Name) or n.func.id not in FUNCS:
+            name = ast.unparse(n.func)
+            raise ExprError(f"function '{name}' is not allowed in expressions", did_you_mean(name, FUNCS))
+        if n.keywords:
+            raise ExprError("keyword arguments are not supported")
+        lo, hi = FUNCS[n.func.id]
+        if not lo <= len(n.args) <= hi:
+            raise ExprError(f"{n.func.id}() takes {lo if lo == hi else f'{lo}-{hi}'} argument(s), got {len(n.args)}")
+        if n.func.id == "count":
+            name = entity_literal(n.args[0], self.s.entities)
+            return f'World.count(&"{name}")'
+        args = ", ".join(self.visit(a) for a in n.args)
+        return f"{n.func.id}({args})"
+
+    def v_BinOp(self, n: ast.BinOp) -> str:
+        a, b = self.visit(n.left), self.visit(n.right)
+        if isinstance(n.op, ast.Div):
+            return f"(float({a}) / {b})"
+        if isinstance(n.op, ast.Mod):
+            return f"fposmod({a}, {b})"
+        op = _BIN.get(type(n.op))
+        if op is None:
+            raise ExprError(f"operator in '{ast.unparse(n)}' is not supported")
+        return f"({a} {op} {b})"
+
+    def v_UnaryOp(self, n: ast.UnaryOp) -> str:
+        v = self.visit(n.operand)
+        if isinstance(n.op, ast.Not):
+            return f"(not {v})"
+        if isinstance(n.op, ast.USub):
+            return f"(-{v})"
+        if isinstance(n.op, ast.UAdd):
+            return v
+        raise ExprError(f"operator in '{ast.unparse(n)}' is not supported")
+
+    def v_BoolOp(self, n: ast.BoolOp) -> str:
+        op = " and " if isinstance(n.op, ast.And) else " or "
+        return "(" + op.join(self.visit(v) for v in n.values) + ")"
+
+    def v_Compare(self, n: ast.Compare) -> str:
+        parts = []
+        left = n.left
+        for op, right in zip(n.ops, n.comparators):
+            sym = _CMP.get(type(op))
+            if sym is None:
+                raise ExprError(f"comparison in '{ast.unparse(n)}' is not supported")
+            parts.append(f"{self.visit(left)} {sym} {self.visit(right)}")
+            left = right
+        return "(" + " and ".join(parts) + ")"
+
+
+def _attr_chain(n: ast.AST) -> list[str] | None:
+    out: list[str] = []
+    while isinstance(n, ast.Attribute):
+        out.append(n.attr)
+        n = n.value
+    if not isinstance(n, ast.Name):
+        return None
+    out.append(n.id)
+    return out[::-1]
+
+
+def entity_literal(node: ast.AST, entities: dict[str, list[str]]) -> str:
+    """An argument that must be a string literal naming an entity type."""
+    if isinstance(node, ast.Name) and node.id in entities:
+        return node.id  # be lenient: count(Slime) == count("Slime")
+    if not (isinstance(node, ast.Constant) and isinstance(node.value, str)):
+        raise ExprError(f"expected an entity name in quotes, got '{ast.unparse(node)}'")
+    if node.value not in entities:
+        raise ExprError(f"unknown entity '{node.value}'", did_you_mean(node.value, entities))
+    return node.value

spawnpoint/gif.py

@@ -0,0 +1,58 @@
+"""Record a gameplay GIF of a built project (autopilot + screenshots -> optimized GIF).
+
+Needs a display (the game renders in a real window for a few seconds).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from PIL import Image
+
+from . import godot
+from .manifest import ADDON_DIR
+
+RECORD_SCENE = "res://addons/spawn_point/tools/record.tscn"
+
+
+def record_frames(project: Path, out_dir: Path, seconds: float, fps: int) -> list[Path]:
+    # Projects built before the recorder existed get the current tool copied in.
+    tools = project / "addons" / "spawn_point" / "tools"
+    for name in ("record.gd", "record.tscn"):
+        shutil.copy2(ADDON_DIR / "tools" / name, tools / name)
+    step = max(1, round(60 / fps))
+    total = int(seconds * 60)
+    cmd = [godot.find_binary(), "--path", str(project), "--fixed-fps", "60", RECORD_SCENE,
+           "--", str(out_dir), str(total), str(step)]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=seconds * 20 + 60)
+    frames = sorted(out_dir.glob("frame_*.png"))
+    if not frames:
+        raise godot.GodotError("recording produced no frames (is a display available?)", proc.stdout + proc.stderr)
+    return frames
+
+
+def make_gif(frames: list[Path], out: Path, fps: int, width: int, colors: int = 128) -> Path:
+    images = [Image.open(f).convert("RGB") for f in frames]
+    w, h = images[0].size
+    size = (width, round(h * width / w))
+    resample = Image.NEAREST if w % width == 0 else Image.LANCZOS  # exact halves keep pixel art crisp
+    images = [im.resize(size, resample) for im in images]
+    # One shared palette (sampled across the clip) so colors don't flicker between frames.
+    sample = Image.new("RGB", (size[0], size[1] * min(6, len(images))))
+    for i, im in enumerate(images[:: max(1, len(images) // 6)][:6]):
+        sample.paste(im, (0, i * size[1]))
+    palette = sample.quantize(colors=colors, method=Image.Quantize.MEDIANCUT)
+    quantized = [im.quantize(palette=palette, dither=Image.Dither.NONE) for im in images]
+    out.parent.mkdir(parents=True, exist_ok=True)
+    quantized[0].save(out, save_all=True, append_images=quantized[1:], duration=round(1000 / fps), loop=0,
+                      optimize=True, disposal=1)
+    return out
+
+
+def record_gif(project: Path, out: Path, seconds: float = 8.0, fps: int = 20, width: int = 640) -> Path:
+    with tempfile.TemporaryDirectory() as tmp:
+        frames = record_frames(project, Path(tmp), seconds, fps)
+        return make_gif(frames, out, fps, width)

spawnpoint/godot.py

@@ -0,0 +1,107 @@
+"""Locating and running the Godot binary headless."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+CANDIDATES = ("godot4", "godot", "Godot", "godot-4")
+
+# Lines Godot prints at exit in headless mode that are not problems of the game.
+_NOISE = (
+    "RID allocations of type",
+    "were leaked at exit",
+    "ObjectDB instances leaked at exit",
+    "resources still in use at exit",
+    "at: cleanup",
+    "at: clear",
+    "at: finalize",
+)
+
+
+class GodotError(RuntimeError):
+    def __init__(self, message: str, output: str = ""):
+        super().__init__(message)
+        self.output = output
+
+
+@dataclass
+class RunResult:
+    returncode: int
+    output: str
+
+    @property
+    def script_errors(self) -> list[str]:
+        return find_errors(self.output)
+
+
+def find_binary() -> str:
+    env = os.environ.get("GODOT_BIN") or os.environ.get("GODOT")
+    if env:
+        return env
+    for c in CANDIDATES:
+        path = shutil.which(c)
+        if path:
+            return path
+    raise GodotError("Godot 4 not found. Install it or set GODOT_BIN=/path/to/godot.")
+
+
+def available() -> bool:
+    try:
+        find_binary()
+        return True
+    except GodotError:
+        return False
+
+
+def version() -> str:
+    out = subprocess.run([find_binary(), "--version"], capture_output=True, text=True, timeout=30)
+    return out.stdout.strip()
+
+
+def run(project: Path, args: list[str], timeout: float = 180) -> RunResult:
+    cmd = [find_binary(), "--headless", "--path", str(project), *args]
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired as e:
+        out = (e.stdout or b"").decode() if isinstance(e.stdout, bytes) else (e.stdout or "")
+        raise GodotError(f"Godot timed out after {timeout}s: {' '.join(cmd)}", out) from e
+    return RunResult(p.returncode, (p.stdout or "") + (p.stderr or ""))
+
+
+def import_project(project: Path) -> RunResult:
+    """Imports resources and refreshes the global class cache (required before running scripts)."""
+    return run(project, ["--import"], timeout=300)
+
+
+def run_scene(project: Path, scene: str, user_args: list[str] | None = None, *, import_first: bool = False,
+              fixed_fps: int | None = None, timeout: float = 180, check: bool = True) -> RunResult:
+    if import_first:
+        import_project(project)
+    args: list[str] = []
+    if fixed_fps:
+        args += ["--fixed-fps", str(fixed_fps)]
+    args.append(scene)
+    if user_args:
+        args += ["--", *user_args]
+    result = run(project, args, timeout=timeout)
+    if check and (result.returncode != 0 or result.script_errors):
+        raise GodotError(f"Godot failed running {scene} (exit {result.returncode})", result.output)
+    return result
+
+
+_ERR = re.compile(r"^(SCRIPT ERROR|ERROR|USER ERROR|Parse Error|Compile Error)\b.*", re.MULTILINE)
+
+
+def find_errors(output: str) -> list[str]:
+    errors = []
+    for m in _ERR.finditer(output):
+        line = m.group(0)
+        if any(n in line for n in _NOISE):
+            continue
+        errors.append(line.strip())
+    return errors

spawnpoint/graph.py

@@ -0,0 +1,175 @@
+"""Game graph schema (v1). Structural validation only; semantics live in analyze.py."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+from .diagnostics import Diagnostics, did_you_mean, join_path
+
+HEX_COLOR = re.compile(r"^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$")
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+def _check_color(v: str | None) -> str | None:
+    if v is not None and not HEX_COLOR.match(v):
+        raise ValueError(f"'{v}' is not a hex color like '#29adff'")
+    return v
+
+
+class Shape(_Model):
+    type: Literal["rect", "circle", "capsule", "triangle", "spikes", "none"] = "rect"
+    size: tuple[float, float] = (28.0, 28.0)
+    color: str | None = None
+
+    _color = field_validator("color")(_check_color)
+
+    @field_validator("size")
+    @classmethod
+    def _positive(cls, v: tuple[float, float]) -> tuple[float, float]:
+        if v[0] <= 0 or v[1] <= 0 or v[0] > 1024 or v[1] > 1024:
+            raise ValueError("size must be within 1..1024 px")
+        return v
+
+
+class SpriteGenerate(_Model):
+    kind: str
+    color: str | None = None
+    features: list[str] | None = None
+    seed: int = 0
+
+    _color = field_validator("color")(_check_color)
+
+
+class SpriteAI(_Model):
+    prompt: str = Field(min_length=1, max_length=200)
+    kind: str  # also the pixel size, animations and the fallback when no image provider is available
+    color: str | None = None
+    seed: int = 0
+
+    _color = field_validator("color")(_check_color)
+
+
+class SpriteRef(_Model):
+    generate: SpriteGenerate | None = None
+    ai: SpriteAI | None = None
+
+    @model_validator(mode="after")
+    def _one(self) -> "SpriteRef":
+        if (self.generate is None) == (self.ai is None):
+            raise ValueError('use exactly one of "generate" or "ai"')
+        return self
+
+
+class Entity(_Model):
+    body: Literal["character", "static", "area"] = "character"
+    team: Literal["player", "enemy", "neutral"] | None = None
+    shape: Shape = Field(default_factory=Shape)
+    # Path to a .sprite.json (relative to the graph file) or {"generate": {...}}.
+    sprite: Union[str, SpriteRef, None] = None
+    components: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    juice: Union[Literal["none"], dict[str, Any], None] = None
+
+
+class Level(_Model):
+    map: list[str]
+    legend: dict[str, str]
+
+
+class Rule(_Model):
+    on: str
+    if_: str | None = Field(default=None, alias="if")
+    do: list[str] | str
+
+    @property
+    def actions(self) -> list[str]:
+        return [self.do] if isinstance(self.do, str) else list(self.do)
+
+
+class TileStyle(_Model):
+    color: str | None = None
+    top: str | None = None
+    _color = field_validator("color", "top")(_check_color)
+
+
+class Settings(_Model):
+    tile_size: int = Field(default=32, ge=8, le=128)
+    viewport: tuple[int, int] = (960, 540)
+    lives: int = Field(default=3, ge=1, le=99)
+    juice: Literal["default", "none"] = "default"
+    background: str | None = None
+    gravity: float | None = Field(default=None, ge=0, le=10000)
+    seed: int = 0
+    tiles: dict[Literal["solid", "oneway"], TileStyle] = Field(default_factory=dict)
+    tile_style: Literal["pixel", "flat"] = "pixel"
+    zoom: float = Field(default=1.0, ge=0.5, le=4.0)
+
+    _bg = field_validator("background")(_check_color)
+
+
+class Graph(_Model):
+    spawnpoint: Literal[1] = 1
+    name: str = Field(min_length=1, max_length=80)
+    genre: Literal["platformer", "topdown"]
+    settings: Settings = Field(default_factory=Settings)
+    entities: dict[str, Entity]
+    level: Level
+    rules: list[Rule] = Field(default_factory=list)
+
+
+def parse(data: Any) -> tuple[Graph | None, Diagnostics]:
+    """Parse raw JSON data into a Graph, converting pydantic errors into diagnostics."""
+    diags = Diagnostics()
+    try:
+        return Graph.model_validate(data), diags
+    except ValidationError as e:
+        found = []
+        for err in e.errors():
+            # Drop pydantic's union-branch tags ("str", "SpriteRef", "literal['none']", ...).
+            loc = [p for p in err["loc"] if not (isinstance(p, str) and ("[" in p or "-" in p or p in _TYPE_TAGS))]
+            path = join_path(*loc) if loc else "(root)"
+            msg = err["msg"]
+            hint = None
+            if err["type"] == "extra_forbidden":
+                field = str(loc[-1])
+                hint = did_you_mean(field, _allowed_fields(loc[:-1]))
+                msg = f"unknown field '{field}'"
+            elif err["type"] == "missing":
+                msg = f"missing required field '{loc[-1]}'"
+            found.append((path, msg, hint))
+        # A union reports one error per branch; keep only the most specific ones.
+        paths = {p for p, _, _ in found}
+        for path, msg, hint in dict.fromkeys(found):
+            if not any(o != path and o.startswith(path + ".") for o in paths):
+                diags.error("E_SCHEMA", path, msg, hint)
+        return None, diags
+
+
+_TYPE_TAGS = {"str", "int", "float", "bool", "SpriteRef", "SpriteGenerate", "SpriteAI", "Shape", "Entity"}
+
+
+# Which model lives under a field name (dict/list containers skip their key/index).
+_CHILD = {"settings": (Settings, 1), "shape": (Shape, 1), "level": (Level, 1), "generate": (SpriteGenerate, 1),
+          "ai": (SpriteAI, 1),
+          "sprite": (SpriteRef, 1),
+          "entities": (Entity, 2), "rules": (Rule, 2)}
+
+
+def _allowed_fields(parent_loc: list) -> list[str]:
+    """Valid field names at a location (for typo hints)."""
+    model: type[BaseModel] | None = Graph
+    i = 0
+    while model is not None and i < len(parent_loc):
+        child = _CHILD.get(str(parent_loc[i]))
+        if child is None:
+            return []
+        model, step = child
+        i += step
+    if model is None:
+        return []
+    return [f.alias or name for name, f in model.model_fields.items()]