spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/playtest/report.py

@@ -0,0 +1,148 @@
+"""Aggregates bot telemetry into per-profile metrics, a Markdown report and a death heatmap."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+
+@dataclass
+class ProfileStats:
+    profile: str
+    runs: int
+    wins: int
+    mean_time: float
+    deaths: int
+    causes: dict[str, int]
+    falls_after_jump: int
+    jumps_intended: int
+    jumps_missed: int
+    pickup_rate: float
+    stuck: int
+
+    @property
+    def win_rate(self) -> float:
+        return self.wins / self.runs if self.runs else 0.0
+
+    @property
+    def missed_rate(self) -> float:
+        return self.jumps_missed / self.jumps_intended if self.jumps_intended else 0.0
+
+    def to_dict(self) -> dict:
+        d = dict(self.__dict__)
+        d.update(win_rate=round(self.win_rate, 3), missed_rate=round(self.missed_rate, 3))
+        return d
+
+
+@dataclass
+class Report:
+    profiles: dict[str, ProfileStats]
+    runs: list[dict]
+    level_issues: list[str] = field(default_factory=list)
+
+    def get(self, profile: str) -> ProfileStats | None:
+        return self.profiles.get(profile)
+
+    def to_dict(self) -> dict:
+        return {"profiles": {k: v.to_dict() for k, v in self.profiles.items()},
+                "level_issues": self.level_issues, "runs": self.runs}
+
+
+def aggregate(runs: list[dict], goal_entities: set[str] | None = None) -> Report:
+    """`goal_entities`: entity types the player must reach (pickups, exits); an unreachable one
+    is a level problem. Enemies the bot could not path to are not."""
+    by: dict[str, list[dict]] = {}
+    for r in runs:
+        by.setdefault(r["profile"], []).append(r)
+    stats = {}
+    for prof, rs in by.items():
+        deaths = [d for r in rs for d in r["deaths"]]
+        won = [r for r in rs if r["outcome"] == "won"]
+        total = sum(r["pickups"]["total"] for r in rs)
+        stats[prof] = ProfileStats(
+            profile=prof, runs=len(rs), wins=len(won),
+            mean_time=round(sum(r["time"] for r in won) / len(won), 2) if won else 0.0,
+            deaths=len(deaths), causes=dict(Counter(d["cause"] for d in deaths).most_common()),
+            falls_after_jump=sum(1 for d in deaths if d["cause"] == "fall" and d.get("after_jump")),
+            jumps_intended=sum(r["jumps"]["intended"] for r in rs),
+            jumps_missed=sum(len(r["jumps"]["missed"]) for r in rs),
+            pickup_rate=round(sum(r["pickups"]["collected"] for r in rs) / total, 3) if total else 1.0,
+            stuck=sum(len(r["stuck"]) for r in rs),
+        )
+    return Report(stats, runs, _level_issues(runs, stats, goal_entities))
+
+
+def _level_issues(runs: list[dict], stats: dict[str, ProfileStats], goal_entities: set[str] | None) -> list[str]:
+    issues = []
+    no_path = Counter((u["entity"], u["x"], u["y"]) for r in runs for u in r.get("unreachable", [])
+                      if u.get("reason") == "no_path" and (goal_entities is None or u["entity"] in goal_entities))
+    for (entity, x, y), n in sorted(no_path.items()):
+        if n == len(runs):  # no bot ever found a way: a level problem, not a skill problem
+            issues.append(f"{entity} at ({x},{y}) has no path from the player")
+    expert = stats.get("expert")
+    if expert and expert.wins == 0:
+        issues.append("even the expert bot never won — the goal may be impossible or the time too short")
+    return issues
+
+
+def markdown(rep: Report, title: str, changes: list[str] | None = None) -> str:
+    lines = [f"# Playtest — {title}", "", "| profile | wins | mean win time | deaths | top causes | missed jumps | pickups | stuck |",
+             "|---|---|---|---|---|---|---|---|"]
+    for s in rep.profiles.values():
+        causes = ", ".join(f"{k} {v}" for k, v in list(s.causes.items())[:3]) or "—"
+        lines.append(f"| {s.profile} | {s.wins}/{s.runs} | {s.mean_time or '—'}s | {s.deaths} | {causes} | "
+                     f"{s.jumps_missed}/{s.jumps_intended} | {s.pickup_rate:.0%} | {s.stuck} |")
+    if rep.level_issues:
+        lines += ["", "## Level issues", *[f"- {i}" for i in rep.level_issues]]
+    if changes:
+        lines += ["", "## Tuning applied", *[f"- {c}" for c in changes]]
+    return "\n".join(lines) + "\n"
+
+
+CAUSE_COLORS = [(255, 0, 77), (255, 163, 0), (41, 173, 255), (0, 228, 54), (255, 119, 168), (131, 118, 156)]
+
+
+def heatmap(plan: dict, runs: list[dict], out: Path, cell: int = 12) -> Path:
+    """Level drawn from the build plan; deaths as dots colored by cause, stuck spots as rings."""
+    w, h = plan["map"]["width"], plan["map"]["height"]
+    legend_h = 18
+    img = Image.new("RGB", (w * cell, h * cell + legend_h), (29, 33, 46))
+    d = ImageDraw.Draw(img, "RGBA")
+    for x, y, kind in plan["map"]["cells"]:
+        box = (x * cell, y * cell, x * cell + cell - 1, y * cell + cell - 1)
+        if kind == "solid":
+            d.rectangle(box, fill=(95, 87, 79))
+        else:
+            d.rectangle((box[0], box[1], box[2], box[1] + 2), fill=(171, 82, 54))
+    ts = plan["tile_size"]
+    for p in plan["placements"]:
+        if p["entity"] == "Player":
+            cx, cy = p["x"] / ts * cell, p["y"] / ts * cell
+            d.ellipse((cx - 4, cy - 4, cx + 4, cy + 4), outline=(0, 228, 54), width=2)
+    causes = sorted({dd["cause"] for r in runs for dd in r["deaths"]})
+    colors = {c: CAUSE_COLORS[i % len(CAUSE_COLORS)] for i, c in enumerate(causes)}
+    for r in runs:
+        for s in r["stuck"]:
+            cx, cy = (s["x"] + 0.5) * cell, (s["y"] + 0.5) * cell
+            d.ellipse((cx - 6, cy - 6, cx + 6, cy + 6), outline=(255, 236, 39, 200), width=1)
+        for u in r.get("unreachable", []):
+            cx, cy = (u["x"] + 0.5) * cell, (u["y"] + 0.5) * cell
+            d.line((cx - 4, cy - 4, cx + 4, cy + 4), fill=(255, 255, 255, 200), width=2)
+            d.line((cx - 4, cy + 4, cx + 4, cy - 4), fill=(255, 255, 255, 200), width=2)
+        for dd in r["deaths"]:
+            # Falls happen below the map: pin them to the bottom row so they stay visible.
+            cx, cy = (min(max(dd["x"], 0), w - 1) + 0.5) * cell, (min(max(dd["y"], 0), h - 1) + 0.5) * cell
+            c = colors[dd["cause"]]
+            d.ellipse((cx - 4, cy - 4, cx + 4, cy + 4), fill=(*c, 150))
+    x = 4
+    for cause, c in colors.items():
+        d.ellipse((x, h * cell + 5, x + 8, h * cell + 13), fill=c)
+        d.text((x + 11, h * cell + 3), cause, fill=(255, 241, 232))
+        x += 16 + len(cause) * 7
+    d.text((x + 8, h * cell + 3), "o stuck   x bots gave up", fill=(255, 236, 39))
+    out.parent.mkdir(parents=True, exist_ok=True)
+    img.save(out)
+    return out

spawnpoint/playtest/runner.py

@@ -0,0 +1,51 @@
+"""Runs the Godot playtest bots on a built project and returns their telemetry."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+from pathlib import Path
+
+from .. import godot
+from ..manifest import ADDON_DIR
+
+PLAYTEST_SCENE = "res://addons/spawn_point/tools/playtest.tscn"
+PROFILES = ("novice", "average", "expert")
+
+
+def sync_addon(project: Path) -> None:
+    """Brings the project's copy of the library up to date (older builds lack telemetry hooks)."""
+    shutil.copytree(ADDON_DIR, project / "addons" / "spawn_point", dirs_exist_ok=True,
+                    ignore=shutil.ignore_patterns("*.import", "*.uid", "__pycache__"))
+
+
+def time_limit(graph: dict, brief: dict | None = None) -> float:
+    """Seconds a run may take: generous for slow players, scaled to the level size and goal."""
+    rows = graph["level"]["map"]
+    width_px = max(len(r) for r in rows) * graph.get("settings", {}).get("tile_size", 32)
+    player = graph["entities"].get("Player", {}).get("components", {})
+    speed = (player.get("PlatformerMovement") or player.get("TopDownMovement") or {}).get("max_speed", 230)
+    limit = width_px / (float(speed) * 0.25) + 30 if graph["genre"] == "platformer" else 90.0
+    if brief and brief.get("goal") == "survive":
+        limit = max(limit, brief.get("survive_seconds", 60) + 15)
+    return float(min(max(limit, 45.0), 240.0))
+
+
+def run(project: Path, *, profiles: tuple[str, ...] = PROFILES, runs: int = 3, seed: int = 1,
+        limit_s: float = 90.0, sync: bool = True) -> list[dict]:
+    if sync:
+        sync_addon(project)
+        godot.import_project(project)
+    with tempfile.TemporaryDirectory() as tmp:
+        out = Path(tmp) / "playtest.json"
+        game_seconds = limit_s * runs * len(profiles)
+        # Bots run far faster than real time; a script error makes Godot hang, so keep a cap.
+        res = godot.run_scene(project, PLAYTEST_SCENE, [str(out), ",".join(profiles), str(runs), str(seed),
+                                                        str(limit_s)],
+                              fixed_fps=60, check=False, timeout=60 + game_seconds / 5)
+        if not out.exists():
+            raise godot.GodotError("playtest produced no report", res.output)
+        if res.script_errors:
+            raise godot.GodotError("playtest hit script errors: " + "; ".join(res.script_errors[:3]), res.output)
+        return json.loads(out.read_text())["runs"]

spawnpoint/playtest/tuner.py

@@ -0,0 +1,151 @@
+"""Deterministic tuning rules: telemetry symptoms -> bounded parameter changes (a set_params patch).
+
+Every change is bounded relative to the *original* graph (before any tuning), so repeated rounds can
+never drift into absurd values, and every change carries a human-readable reason.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..manifest import Manifest
+from .report import Report
+
+MOVEMENT = ("PlatformerMovement", "TopDownMovement")
+
+
+def targets(difficulty: int) -> dict[str, float]:
+    """Win-rate targets per profile; novices are allowed to struggle more on harder games."""
+    d = min(max(difficulty, 1), 5)
+    return {"novice": round(0.8 - (d - 1) * 0.125, 3), "average": 0.8, "expert": 0.95}
+
+
+def score(rep: Report, difficulty: int) -> float:
+    """Distance from the targets (lower is better). Too easy only counts on hard games."""
+    t = targets(difficulty)
+    total = 0.0
+    for prof, goal in t.items():
+        s = rep.get(prof)
+        if s is None:
+            continue
+        total += max(0.0, goal - s.win_rate) * (2.0 if prof == "expert" else 1.0)
+        if difficulty >= 3 and prof == "novice" and s.win_rate > goal + 0.35:
+            total += s.win_rate - goal - 0.35
+    return round(total, 4)
+
+
+@dataclass
+class Change:
+    entity: str
+    component: str
+    param: str
+    value: float | int
+    reason: str
+
+    def to_patch(self) -> dict:
+        return {"entity": self.entity, "component": self.component, "param": self.param, "value": self.value}
+
+    def __str__(self) -> str:
+        return f"{self.entity}.{self.component}.{self.param} = {self.value:g} — {self.reason}"
+
+
+class _Params:
+    """Reads current and original parameter values (graph value or manifest default)."""
+
+    def __init__(self, graph: dict, original: dict, manifest: Manifest):
+        self.g, self.o, self.m = graph, original, manifest
+
+    def _get(self, graph: dict, entity: str, comp: str, param: str):
+        value = graph["entities"].get(entity, {}).get("components", {}).get(comp, {}).get(param)
+        if value is None:
+            spec = self.m.get(comp)
+            value = spec.params[param].default if spec and param in spec.params else None
+        return value
+
+    def now(self, entity: str, comp: str, param: str):
+        return self._get(self.g, entity, comp, param)
+
+    def base(self, entity: str, comp: str, param: str):
+        return self._get(self.o, entity, comp, param)
+
+
+def propose(rep: Report, graph: dict, original: dict, manifest: Manifest, difficulty: int = 2) -> list[Change]:
+    t = targets(difficulty)
+    p = _Params(graph, original, manifest)
+    ents = graph["entities"]
+    player = ents.get("Player", {}).get("components", {})
+    novice, average = rep.get("novice"), rep.get("average")
+    too_hard = bool((novice and novice.win_rate < t["novice"] - 0.1) or (average and average.win_rate < t["average"] - 0.1))
+    changes: list[Change] = []
+
+    def bump(entity, comp, param, factor=None, add=None, lo=None, hi=None, reason="", integer=False):
+        cur = p.now(entity, comp, param)
+        base = p.base(entity, comp, param)
+        if cur is None or base is None:
+            return
+        new = cur * factor if factor is not None else cur + add
+        if lo is not None:
+            new = max(new, lo(base))
+        if hi is not None:
+            new = min(new, hi(base))
+        new = int(round(new)) if integer else round(float(new), 3)
+        if new != cur:
+            changes.append(Change(entity, comp, param, new, reason))
+
+    deaths = [s for s in (novice, average) if s]
+    all_causes: dict[str, int] = {}
+    for s in deaths:
+        for k, v in s.causes.items():
+            all_causes[k] = all_causes.get(k, 0) + v
+    n_deaths = sum(all_causes.values())
+
+    # 1. Missed jumps: the player pressed jump a moment too late.
+    missed = max((s.missed_rate for s in deaths), default=0.0)
+    if "PlatformerMovement" in player and missed > 0.15:
+        why = f"{missed:.0%} of jumps were pressed too late"
+        bump("Player", "PlatformerMovement", "coyote_time", add=0.04, hi=lambda b: max(0.2, b), reason=why)
+        bump("Player", "PlatformerMovement", "jump_buffer", add=0.04, hi=lambda b: max(0.2, b), reason=why)
+
+    if too_hard and n_deaths:
+        top, top_n = max(all_causes.items(), key=lambda kv: kv[1])
+        share = top_n / n_deaths
+        falls = sum(s.falls_after_jump for s in deaths)
+        # 2. Falling into pits after jumping: more air control, slightly higher jump.
+        if "PlatformerMovement" in player and falls / n_deaths >= 0.3:
+            why = f"{falls}/{n_deaths} deaths were falls right after a jump"
+            bump("Player", "PlatformerMovement", "air_acceleration", factor=1.2, hi=lambda b: b * 2.0, reason=why)
+            bump("Player", "PlatformerMovement", "jump_velocity", factor=1.05, hi=lambda b: b * 1.15, reason=why)
+        ent = ents.get(top, {})
+        comps = ent.get("components", {})
+        mv = next((m for m in MOVEMENT if m in comps), None)
+        if share >= 0.4 and top != "fall":
+            why = f"{top} caused {top_n}/{n_deaths} deaths"
+            if mv:  # 3. A moving enemy dominates: slow it down.
+                bump(top, mv, "max_speed", factor=0.85, lo=lambda b: b * 0.5, reason=why)
+            elif "Projectile" in comps:  # 4. Bullets: the shooters fire less often.
+                for name, e in ents.items():
+                    if e.get("components", {}).get("Weapon", {}).get("projectile") == top:
+                        bump(name, "Weapon", "fire_rate", factor=0.85, lo=lambda b: b * 0.5, reason=why)
+            elif "Hitbox" in comps and "Hurtbox" in player:  # 5. Static hazards: a more forgiving hurtbox.
+                bump("Player", "Hurtbox", "size_scale", add=-0.1, lo=lambda b: min(0.6, b), reason=why)
+        # 6. Still far too hard: more health and longer invincibility.
+        if novice and novice.win_rate < t["novice"] - 0.25 and "Health" in player:
+            why = f"novice bots won only {novice.wins}/{novice.runs}"
+            bump("Player", "Health", "max_health", add=1, hi=lambda b: max(6, b), reason=why, integer=True)
+            bump("Player", "Health", "invincibility_time", add=0.2, hi=lambda b: max(1.5, b), reason=why)
+    # 7. Too easy on a game meant to be hard: enemies get faster.
+    if difficulty >= 3 and novice and novice.win_rate > t["novice"] + 0.35 and novice.deaths == 0:
+        for name, e in ents.items():
+            comps = e.get("components", {})
+            mv = next((m for m in MOVEMENT if m in comps), None)
+            if mv and name != "Player" and any(k in comps for k in ("PatrolAI", "ChaseAI")):
+                bump(name, mv, "max_speed", factor=1.1, hi=lambda b: b * 1.5,
+                     reason=f"too easy for difficulty {difficulty}: novices won {novice.wins}/{novice.runs} without dying")
+    # Deduplicate (first reason wins).
+    seen, out = set(), []
+    for c in changes:
+        key = (c.entity, c.component, c.param)
+        if key not in seen:
+            seen.add(key)
+            out.append(c)
+    return out

spawnpoint/project.py

@@ -0,0 +1,94 @@
+"""Writing the generated Godot project to disk (everything except the scenes, which Godot writes)."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from pathlib import Path
+
+from .manifest import ADDON_DIR
+
+AUTOLOADS = {
+    "GameState": "res://addons/spawn_point/runtime/game_state.gd",
+    "World": "res://addons/spawn_point/runtime/world.gd",
+    "FX": "res://addons/spawn_point/runtime/fx.gd",
+    "Sfx": "res://addons/spawn_point/runtime/sfx.gd",
+    "Cockpit": "res://addons/spawn_point/runtime/cockpit.gd",
+}
+LAYER_NAMES = ["world", "player", "enemy", "player_hurtbox", "enemy_hurtbox", "pickup"]
+GENERATED_DIRS = ("entities", "levels", "rules", "sprites")
+
+
+def slugify(name: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+    return s or "game"
+
+
+def _color(hex_color: str) -> str:
+    h = hex_color.lstrip("#")
+    r, g, b = (int(h[i : i + 2], 16) / 255 for i in (0, 2, 4))
+    return f"Color({r:.4f}, {g:.4f}, {b:.4f}, 1)"
+
+
+def project_godot(plan: dict, godot_feature: str = "4.6") -> str:
+    vw, vh = plan["viewport"]
+    lines = [
+        "; Generated by Spawn Point. Safe to edit; rebuilding rewrites this file.",
+        "config_version=5",
+        "",
+        "[application]",
+        "",
+        f"config/name={json.dumps(plan['name'])}",
+        'run/main_scene="res://levels/main.tscn"',
+        f'config/features=PackedStringArray("{godot_feature}")',
+        "",
+        "[autoload]",
+        "",
+        *[f'{k}="*{v}"' for k, v in AUTOLOADS.items()],
+        "",
+        "[display]",
+        "",
+        f"window/size/viewport_width={vw}",
+        f"window/size/viewport_height={vh}",
+        'window/stretch/mode="canvas_items"',
+        'window/stretch/aspect="expand"',
+        "",
+        "[layer_names]",
+        "",
+        *[f'2d_physics/layer_{i + 1}="{n}"' for i, n in enumerate(LAYER_NAMES)],
+        "",
+        "[physics]",
+        "",
+        f"2d/default_gravity={float(plan['gravity'])}",
+        "",
+        "[rendering]",
+        "",
+        'renderer/rendering_method="gl_compatibility"',
+        'renderer/rendering_method.mobile="gl_compatibility"',
+        f"environment/defaults/default_clear_color={_color(plan['background'])}",
+        "textures/canvas_textures/default_texture_filter=0",  # nearest: crisp pixel art
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def write(out: Path, graph_data: dict, plan: dict, rules_source: str, godot_feature: str = "4.6",
+          sprites: dict | None = None, tiles_image=None) -> None:
+    out.mkdir(parents=True, exist_ok=True)
+    for d in GENERATED_DIRS:
+        shutil.rmtree(out / d, ignore_errors=True)
+        (out / d).mkdir()
+    shutil.copytree(ADDON_DIR, out / "addons" / "spawn_point", dirs_exist_ok=True,
+                    ignore=shutil.ignore_patterns("*.import", "*.uid", "__pycache__"))
+    (out / "project.godot").write_text(project_godot(plan, godot_feature))
+    (out / "build_plan.json").write_text(json.dumps(plan, indent=1))
+    (out / "rules" / "main_rules.gd").write_text(rules_source)
+    for entity, sprite in (sprites or {}).items():
+        sprite.sheet.save(out / "sprites" / f"{entity}.png")
+    if tiles_image is not None:
+        tiles_image.save(out / "sprites" / "tiles.png")
+    (out / "spawnpoint.json").write_text(json.dumps(graph_data, indent=2, ensure_ascii=False) + "\n")
+    gi = out / ".gitignore"
+    if not gi.exists():
+        gi.write_text(".godot/\n")