spriteforge 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (218) hide show
  1. spriteforge/__init__.py +1 -0
  2. spriteforge/__main__.py +3 -0
  3. spriteforge/agents/__init__.py +0 -0
  4. spriteforge/agents/assets.py +109 -0
  5. spriteforge/agents/cancellation.py +12 -0
  6. spriteforge/agents/director.py +50 -0
  7. spriteforge/agents/models.py +63 -0
  8. spriteforge/agents/roles/art-director.md +15 -0
  9. spriteforge/agents/roles/art-reviewer.md +14 -0
  10. spriteforge/agents/roles/director.md +14 -0
  11. spriteforge/agents/roles/game-designer.md +15 -0
  12. spriteforge/agents/roles/level-tile-designer.md +16 -0
  13. spriteforge/agents/roles/librarian.md +13 -0
  14. spriteforge/agents/roles/menu-designer.md +15 -0
  15. spriteforge/agents/roles/pixel-artist.md +14 -0
  16. spriteforge/agents/roles/programmer.md +14 -0
  17. spriteforge/agents/roles/qa-playtester.md +13 -0
  18. spriteforge/agents/roles/sound-director.md +14 -0
  19. spriteforge/agents/roles.py +39 -0
  20. spriteforge/agents/router.py +233 -0
  21. spriteforge/agents/router_eval.py +145 -0
  22. spriteforge/agents/routing_state.py +133 -0
  23. spriteforge/agents/runtime.py +430 -0
  24. spriteforge/agents/workflow.py +389 -0
  25. spriteforge/app/__init__.py +0 -0
  26. spriteforge/app/agents_view.py +248 -0
  27. spriteforge/app/chat.py +114 -0
  28. spriteforge/app/extensions.py +115 -0
  29. spriteforge/app/index.html +279 -0
  30. spriteforge/app/local_only.py +49 -0
  31. spriteforge/app/server.py +358 -0
  32. spriteforge/app/static/assets/index-L2s1wlcp.css +1 -0
  33. spriteforge/app/static/assets/index-aBfzgLQl.js +71 -0
  34. spriteforge/app/static/assets/press-start-2p-latin-400-normal-BKfmdmKK.woff +0 -0
  35. spriteforge/app/static/assets/press-start-2p-latin-400-normal-xj9lRvVs.woff2 +0 -0
  36. spriteforge/app/static/index.html +13 -0
  37. spriteforge/app/static/press-start-2p-LICENSE.txt +93 -0
  38. spriteforge/app/studio.py +278 -0
  39. spriteforge/app/workers.py +73 -0
  40. spriteforge/cli.py +241 -0
  41. spriteforge/config.py +193 -0
  42. spriteforge/config.yaml +157 -0
  43. spriteforge/core/__init__.py +0 -0
  44. spriteforge/core/acting.py +16 -0
  45. spriteforge/core/cost.py +236 -0
  46. spriteforge/core/credentials.py +24 -0
  47. spriteforge/core/demo.py +79 -0
  48. spriteforge/core/forms.py +20 -0
  49. spriteforge/core/gates.py +175 -0
  50. spriteforge/core/security.py +42 -0
  51. spriteforge/core/state.py +222 -0
  52. spriteforge/core/team.py +15 -0
  53. spriteforge/core/usage.py +68 -0
  54. spriteforge/game/__init__.py +0 -0
  55. spriteforge/game/actors.py +377 -0
  56. spriteforge/game/agent_tools.py +178 -0
  57. spriteforge/game/art.py +2097 -0
  58. spriteforge/game/art_checks.py +190 -0
  59. spriteforge/game/art_review.py +518 -0
  60. spriteforge/game/build.py +134 -0
  61. spriteforge/game/bundle.py +1178 -0
  62. spriteforge/game/cli.py +119 -0
  63. spriteforge/game/codegen.py +433 -0
  64. spriteforge/game/codeinfo.py +154 -0
  65. spriteforge/game/dbsource.py +137 -0
  66. spriteforge/game/design.py +342 -0
  67. spriteforge/game/export.py +62 -0
  68. spriteforge/game/gamedb.py +191 -0
  69. spriteforge/game/image_cache.py +61 -0
  70. spriteforge/game/lessons.py +259 -0
  71. spriteforge/game/level_gen.py +118 -0
  72. spriteforge/game/level_preview.py +97 -0
  73. spriteforge/game/levels.py +934 -0
  74. spriteforge/game/loops.py +38 -0
  75. spriteforge/game/menus.py +712 -0
  76. spriteforge/game/mock_game.js +109 -0
  77. spriteforge/game/mock_platformer.js +58 -0
  78. spriteforge/game/motion.py +881 -0
  79. spriteforge/game/pipeline.py +1768 -0
  80. spriteforge/game/plan.py +502 -0
  81. spriteforge/game/playtest.py +318 -0
  82. spriteforge/game/qa.py +664 -0
  83. spriteforge/game/qa_checks.py +223 -0
  84. spriteforge/game/qa_runtime.py +565 -0
  85. spriteforge/game/reach.py +807 -0
  86. spriteforge/game/record.py +138 -0
  87. spriteforge/game/research.py +262 -0
  88. spriteforge/game/revision.py +225 -0
  89. spriteforge/game/sdk/API.md +104 -0
  90. spriteforge/game/sdk/FLOW.md +19 -0
  91. spriteforge/game/sdk/LEVELS.md +65 -0
  92. spriteforge/game/sdk/sf.js +418 -0
  93. spriteforge/game/sdk/sfflow.js +442 -0
  94. spriteforge/game/sdk/sflevel.js +683 -0
  95. spriteforge/game/sdk/sfsound-editor.js +225 -0
  96. spriteforge/game/sdk/sfsound.js +260 -0
  97. spriteforge/game/sdk/sounds.html +67 -0
  98. spriteforge/game/sounds.py +793 -0
  99. spriteforge/game/story.py +188 -0
  100. spriteforge/game/structure.py +98 -0
  101. spriteforge/game/team_reports.py +394 -0
  102. spriteforge/game/tilesets.py +70 -0
  103. spriteforge/game/title_art.py +186 -0
  104. spriteforge/genres/__init__.py +0 -0
  105. spriteforge/library/__init__.py +15 -0
  106. spriteforge/library/cli.py +126 -0
  107. spriteforge/library/describe.py +242 -0
  108. spriteforge/library/looks.py +154 -0
  109. spriteforge/library/models.py +79 -0
  110. spriteforge/library/store.py +422 -0
  111. spriteforge/library/tilesets/README.md +32 -0
  112. spriteforge/library/tilesets/gandalf-seasons.json +111 -0
  113. spriteforge/library/tilesets/pixel-crawler-dungeon.json +66 -0
  114. spriteforge/mcp/__init__.py +0 -0
  115. spriteforge/mcp/cli.py +58 -0
  116. spriteforge/mcp/client.py +57 -0
  117. spriteforge/mcp/filesystem_read.py +32 -0
  118. spriteforge/mcp/gamedb.py +56 -0
  119. spriteforge/mcp/library.py +179 -0
  120. spriteforge/mcp/memory.py +37 -0
  121. spriteforge/mcp/pixel_tools.py +145 -0
  122. spriteforge/mcp/registry.py +145 -0
  123. spriteforge/mcp/service.py +224 -0
  124. spriteforge/mcp/templates/context7.json +6 -0
  125. spriteforge/mcp/templates/fetch.json +6 -0
  126. spriteforge/mcp/templates/filesystem-read.json +6 -0
  127. spriteforge/mcp/templates/pixel-tools.json +6 -0
  128. spriteforge/memory/README.md +10 -0
  129. spriteforge/memory/__init__.py +0 -0
  130. spriteforge/memory/cli.py +131 -0
  131. spriteforge/memory/okf/__init__.py +1 -0
  132. spriteforge/memory/okf/catalog.py +331 -0
  133. spriteforge/memory/okf/codec.py +63 -0
  134. spriteforge/memory/okf/git.py +104 -0
  135. spriteforge/memory/okf/indexes.py +50 -0
  136. spriteforge/memory/okf/models.py +114 -0
  137. spriteforge/memory/okf/search.py +53 -0
  138. spriteforge/memory/okf/seed.py +81 -0
  139. spriteforge/memory/okf/seeds/genres.yaml +121 -0
  140. spriteforge/memory/okf/seeds/other.yaml +150 -0
  141. spriteforge/memory/okf/store.py +402 -0
  142. spriteforge/memory/okf/validate.py +115 -0
  143. spriteforge/pixel/__init__.py +17 -0
  144. spriteforge/pixel/atlas.py +110 -0
  145. spriteforge/pixel/grid.py +174 -0
  146. spriteforge/pixel/palette.py +156 -0
  147. spriteforge/pixel/palettes/dungeon.json +9 -0
  148. spriteforge/pixel/postprocess.py +170 -0
  149. spriteforge/pixel/preview.py +40 -0
  150. spriteforge/pixel/schemas.py +139 -0
  151. spriteforge/pixel/source.py +237 -0
  152. spriteforge/pixel/terrain.py +48 -0
  153. spriteforge/pixel/validate.py +138 -0
  154. spriteforge/prompts/anim_frame.txt +1 -0
  155. spriteforge/prompts/character.txt +1 -0
  156. spriteforge/prompts/item.txt +1 -0
  157. spriteforge/prompts/tile.txt +1 -0
  158. spriteforge/prompts/ui.txt +1 -0
  159. spriteforge/providers/__init__.py +0 -0
  160. spriteforge/providers/base.py +97 -0
  161. spriteforge/providers/http.py +38 -0
  162. spriteforge/providers/mock.py +111 -0
  163. spriteforge/providers/muse_image.py +60 -0
  164. spriteforge/providers/muse_search.py +91 -0
  165. spriteforge/providers/muse_spark.py +66 -0
  166. spriteforge/skills/__init__.py +0 -0
  167. spriteforge/skills/builtin/LICENSE-awesome-gamedev-agent-skills.txt +201 -0
  168. spriteforge/skills/builtin/NOTICE-awesome-gamedev-agent-skills.txt +15 -0
  169. spriteforge/skills/builtin/THIRD_PARTY.md +21 -0
  170. spriteforge/skills/builtin/audio-design/SKILL.md +190 -0
  171. spriteforge/skills/builtin/game-feel/SKILL.md +174 -0
  172. spriteforge/skills/builtin/game-ui-ux/SKILL.md +167 -0
  173. spriteforge/skills/builtin/level-design/SKILL.md +169 -0
  174. spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md +17 -0
  175. spriteforge/skills/builtin/physics-tuning/SKILL.md +164 -0
  176. spriteforge/skills/builtin/pixel-art-prompting/SKILL.md +12 -0
  177. spriteforge/skills/builtin/platformer/SKILL.md +153 -0
  178. spriteforge/skills/builtin/puzzle/SKILL.md +143 -0
  179. spriteforge/skills/builtin/sprite-animation-frames/SKILL.md +11 -0
  180. spriteforge/skills/builtin/tileset-design/SKILL.md +10 -0
  181. spriteforge/skills/catalog.py +200 -0
  182. spriteforge/skills/cli.py +41 -0
  183. spriteforge/stages/__init__.py +0 -0
  184. spriteforge/stages/asset_context.py +301 -0
  185. spriteforge/stages/asset_models.py +192 -0
  186. spriteforge/stages/asset_render.py +366 -0
  187. spriteforge/stages/asset_review.py +140 -0
  188. spriteforge/stages/asset_store.py +94 -0
  189. spriteforge/stages/chat_changes.py +236 -0
  190. spriteforge/stages/concept.py +42 -0
  191. spriteforge/stages/game.py +1699 -0
  192. spriteforge/stages/game_confirm.py +112 -0
  193. spriteforge/stages/game_final.py +220 -0
  194. spriteforge/stages/game_record.py +246 -0
  195. spriteforge/stages/gameplay.py +218 -0
  196. spriteforge/stages/intake.py +372 -0
  197. spriteforge/stages/preview_assets.py +212 -0
  198. spriteforge/stages/preview_models.py +167 -0
  199. spriteforge/stages/preview_render.py +169 -0
  200. spriteforge/stages/preview_repair.py +61 -0
  201. spriteforge/stages/preview_review.py +169 -0
  202. spriteforge/stages/production.py +170 -0
  203. spriteforge/stages/references.py +105 -0
  204. spriteforge/stages/rewind.py +128 -0
  205. spriteforge/stages/workflow.py +440 -0
  206. spriteforge/templates/phaser/audit.js +45 -0
  207. spriteforge/templates/phaser/font.png +0 -0
  208. spriteforge/templates/phaser/font.xml +1 -0
  209. spriteforge/templates/phaser/preview.html +9 -0
  210. spriteforge/templates/phaser/room.js +49 -0
  211. spriteforge/templates/phaser/vendor/LICENSE.md +20 -0
  212. spriteforge/templates/phaser/vendor/phaser.min.js +1 -0
  213. spriteforge-0.1.1.dist-info/METADATA +364 -0
  214. spriteforge-0.1.1.dist-info/RECORD +218 -0
  215. spriteforge-0.1.1.dist-info/WHEEL +5 -0
  216. spriteforge-0.1.1.dist-info/entry_points.txt +2 -0
  217. spriteforge-0.1.1.dist-info/licenses/LICENSE +27 -0
  218. spriteforge-0.1.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,318 @@
1
+ """Deterministic playtest: run the whole session headless with the game's own bot and check
2
+ the design's events.
3
+
4
+ The page is loaded with `?autoplay=1&headless=1&god=1`: logic-only steps (Phaser's
5
+ headlessStep, no drawing, so a 10 minute session takes seconds), the game's autoplay policy
6
+ instead of the keyboard, and god mode (the bot may be hurt but not killed) so it reaches the
7
+ end of the session. The SDK steps fixed frames, so the same build always gives the same report.
8
+
9
+ `capture_at` (game seconds) adds screenshots for the art review: at each time one frame is
10
+ drawn (`sfShot`; the game logic is the same as in a logic-only step), so sprites appear on the
11
+ real floor at game scale with the HUD and crowds. A session that ends before a capture time
12
+ gets one last shot when it ends.
13
+ """
14
+
15
+ import base64
16
+ from pathlib import Path
17
+
18
+ from playwright.sync_api import Error as PlaywrightError
19
+ from playwright.sync_api import sync_playwright
20
+
21
+ from .design import Check
22
+ from .record import READY, serve, wait_until
23
+
24
+ CHUNK_SECONDS = 30 # game seconds per browser call (keeps each evaluate short)
25
+ GRACE_SECONDS = 30 # the session may end a little after its nominal length
26
+ HUD_AT = 3.0 # game seconds: the first look at the HUD (then after every browser call)
27
+
28
+
29
+ def look_at_hud(page, seen: dict[str, str]) -> None:
30
+ """Add what the SDK's HUD check finds now (texts over each other or off the screen) to
31
+ `seen`, by place, so a counter that changes is one problem. A build made before the check
32
+ has no `sf.hudProblems` and is not looked at."""
33
+ try:
34
+ found = page.evaluate("window.sf && window.sf.hudProblems ? window.sf.hudProblems() : []")
35
+ except PlaywrightError:
36
+ return
37
+ for f in found or []:
38
+ seen.setdefault(f["key"], f["message"])
39
+
40
+
41
+ def evaluate_checks(checks: list[Check], counts: dict) -> list[dict]:
42
+ results = []
43
+ for c in checks:
44
+ info = counts.get(c.event) or {}
45
+ if c.by_second: # half a second of slack for frame-stepped timers
46
+ got = sum(1 for t in info.get("times", []) if t <= c.by_second + 0.5)
47
+ else:
48
+ got = info.get("count", 0)
49
+ results.append(
50
+ {
51
+ "id": c.id,
52
+ "event": c.event,
53
+ "description": c.description,
54
+ "min_count": c.min_count,
55
+ "by_second": c.by_second,
56
+ "count": got,
57
+ "first_at": info.get("first"),
58
+ "ok": got >= c.min_count,
59
+ }
60
+ )
61
+ return results
62
+
63
+
64
+ def review_times(session_seconds: float) -> list[float]:
65
+ """Early, middle and late in the session: when the art review's screenshots are taken."""
66
+ return [round(session_seconds * f, 1) for f in (0.15, 0.5, 0.85)]
67
+
68
+
69
+ def playtest(
70
+ build_dir: Path,
71
+ checks: list[Check],
72
+ session_seconds: int,
73
+ *,
74
+ fps: int = 30,
75
+ capture_at: list[float] = (),
76
+ hud: bool = True,
77
+ ) -> dict:
78
+ """Run the build and return the report (also the repair input for the Programmer). With
79
+ `capture_at`, the report has "screenshots": [{"t", "png" (bytes)}]; pop them before saving
80
+ it as JSON."""
81
+ errors: list[str] = []
82
+ hud_seen: dict[str, str] = {}
83
+ ended, t, counts, state, sounds = "timeout", 0.0, {}, {}, {}
84
+ limit = session_seconds + GRACE_SECONDS
85
+ pending, shots = sorted(capture_at), []
86
+ with serve(Path(build_dir)) as url, sync_playwright() as pw:
87
+ browser = pw.chromium.launch(headless=True)
88
+ try:
89
+ page = browser.new_page(viewport={"width": 320, "height": 180})
90
+ page.on("pageerror", lambda e: errors.append(str(e)))
91
+ page.goto(f"{url}/index.html?autoplay=1&headless=1&god=1")
92
+ if not wait_until(page, READY):
93
+ ended = "no-boot"
94
+
95
+ def shot() -> None:
96
+ url = page.evaluate(f"window.sfShot({fps})")
97
+ shots.append({"t": round(t, 1), "png": base64.b64decode(url.split(",", 1)[1])})
98
+
99
+ while ended != "no-boot" and t < limit:
100
+ before = t
101
+ chunk = min(CHUNK_SECONDS, limit - t)
102
+ if pending:
103
+ chunk = min(chunk, max(pending[0] - t, 1 / fps))
104
+ if hud and t < HUD_AT - 0.5 / fps:
105
+ chunk = min(chunk, HUD_AT - t)
106
+ try:
107
+ result = page.evaluate(f"window.sfRun({chunk}, {fps})")
108
+ except PlaywrightError as exc: # e.g. sfRun missing because sf.js broke
109
+ errors.append(str(exc).splitlines()[0])
110
+ ended = "error"
111
+ break
112
+ t = float(result["t"])
113
+ if hud:
114
+ look_at_hud(page, hud_seen)
115
+ if pending and t >= pending[0] - 0.5 / fps:
116
+ pending.pop(0)
117
+ shot()
118
+ counts = page.evaluate("window.sf.counts")
119
+ if "win" in counts or "lose" in counts:
120
+ ended = "win" if "win" in counts else "lose"
121
+ break
122
+ if result["errors"]:
123
+ ended = "error"
124
+ break
125
+ if t <= before: # the game loop is not advancing
126
+ ended = "stalled"
127
+ break
128
+ if ended != "no-boot":
129
+ if pending and ended != "error": # ended before a capture time: its last frame
130
+ shot()
131
+ counts = page.evaluate("window.sf.counts")
132
+ state = page.evaluate("window.sf.state")
133
+ sounds = page.evaluate("window.sf.soundCount || {}")
134
+ errors += page.evaluate("window.sf ? window.sf.errors : []")
135
+ finally:
136
+ browser.close()
137
+ results = evaluate_checks(checks, counts)
138
+ unique_errors = list(dict.fromkeys(errors))[:20]
139
+ return {
140
+ "passed": not unique_errors
141
+ and not hud_seen
142
+ and ended not in {"no-boot", "stalled"}
143
+ and all(r["ok"] for r in results),
144
+ "ended": ended,
145
+ "game_seconds": round(t, 1),
146
+ "session_seconds": session_seconds,
147
+ "errors": unique_errors,
148
+ "hud": list(hud_seen.values()),
149
+ "checks": results,
150
+ "events": {name: c["count"] for name, c in sorted(counts.items())},
151
+ "state": state,
152
+ "sounds": sounds, # how often each sound played (sfsound.js counts them, silently)
153
+ **({"screenshots": shots} if capture_at else {}),
154
+ }
155
+
156
+
157
+ LEVEL_SECONDS = 20 # game seconds per level, plus STEP_SECONDS per step of the bot's route
158
+ STEP_SECONDS = 6
159
+
160
+
161
+ def merge_counts(per_level: list[dict]) -> dict:
162
+ """Event counts of every level's run together (times stay per level)."""
163
+ out: dict[str, dict] = {}
164
+ for counts in per_level:
165
+ for name, c in counts.items():
166
+ m = out.setdefault(name, {"count": 0, "first": c["first"], "last": c["last"], "times": []})
167
+ m["count"] += c["count"]
168
+ m["first"], m["last"] = min(m["first"], c["first"]), max(m["last"], c["last"])
169
+ m["times"] = (m["times"] + c.get("times", []))[:300]
170
+ return out
171
+
172
+
173
+ def playtest_levels(build_dir: Path, checks: list[Check], levels: list[dict], *, fps: int = 30,
174
+ capture: bool = False, hud: bool = True) -> dict: # fmt: skip
175
+ """Play each level on its own (`?level=n&only=1`) with the SDK's route bot in god mode and
176
+ check the design's events over all levels. `levels`: [{"n", "name", "events", "steps"}]
177
+ (the events each level makes happen). With `capture`, one drawn screenshot per level a few
178
+ seconds in (for the art review)."""
179
+ errors: list[str] = []
180
+ hud_seen: dict[str, str] = {}
181
+ results, shots, counts_by_level, state, sounds = [], [], [], {}, {}
182
+ with serve(Path(build_dir)) as url, sync_playwright() as pw:
183
+ browser = pw.chromium.launch(headless=True)
184
+ try:
185
+ for lv in levels:
186
+ page = browser.new_page(viewport={"width": 320, "height": 180})
187
+ mine: list[str] = []
188
+ page.on("pageerror", lambda e, mine=mine: mine.append(str(e)))
189
+ page.goto(f"{url}/index.html?autoplay=1&headless=1&god=1&only=1&level={lv['n']}")
190
+ ended, t, counts, bot = "timeout", 0.0, {}, {}
191
+ limit = LEVEL_SECONDS + STEP_SECONDS * lv.get("steps", 10)
192
+ if not wait_until(page, READY):
193
+ ended = "no-boot"
194
+ shot_at = 4.0 if capture else None
195
+ while ended != "no-boot" and t < limit:
196
+ before = t
197
+ chunk = min(CHUNK_SECONDS, limit - t)
198
+ if shot_at is not None:
199
+ chunk = min(chunk, max(shot_at - t, 1 / fps))
200
+ if hud and t < HUD_AT - 0.5 / fps:
201
+ chunk = min(chunk, HUD_AT - t)
202
+ try:
203
+ result = page.evaluate(f"window.sfRun({chunk}, {fps})")
204
+ except PlaywrightError as exc:
205
+ mine.append(str(exc).splitlines()[0])
206
+ ended = "error"
207
+ break
208
+ t = float(result["t"])
209
+ if hud:
210
+ look_at_hud(page, hud_seen)
211
+ if shot_at is not None and t >= shot_at - 0.5 / fps:
212
+ shot_at = None
213
+ data = page.evaluate(f"window.sfShot({fps})")
214
+ shots.append({"t": round(t, 1), "level": lv["n"],
215
+ "png": base64.b64decode(data.split(",", 1)[1])}) # fmt: skip
216
+ counts = page.evaluate("window.sf.counts")
217
+ bot = page.evaluate("window.sf.bot") or {}
218
+ if "level_complete" in counts or "win" in counts:
219
+ ended = "cleared"
220
+ break
221
+ if result["errors"]:
222
+ ended = "error"
223
+ break
224
+ if bot.get("status") == "stuck":
225
+ ended = "stuck"
226
+ break
227
+ if t <= before:
228
+ ended = "stalled"
229
+ break
230
+ if ended != "no-boot":
231
+ counts = page.evaluate("window.sf.counts")
232
+ state = page.evaluate("window.sf.state")
233
+ bot = page.evaluate("window.sf.bot") or bot
234
+ for name, k in (page.evaluate("window.sf.soundCount || {}") or {}).items():
235
+ sounds[name] = sounds.get(name, 0) + k
236
+ mine += page.evaluate("window.sf ? window.sf.errors : []")
237
+ page.close()
238
+ mine = list(dict.fromkeys(mine))[:10]
239
+ errors += [f"level {lv['n']}: {e}" for e in mine]
240
+ events = {name: c["count"] for name, c in sorted(counts.items())}
241
+ missing = [e for e in lv.get("events", []) if e not in counts]
242
+ counts_by_level.append(counts)
243
+ results.append({"n": lv["n"], "name": lv.get("name", ""), "cleared": ended == "cleared",
244
+ "ended": ended, "game_seconds": round(t, 1), "bot": bot,
245
+ "events": events, "expected": lv.get("events", []),
246
+ "missing": missing, "errors": mine,
247
+ "ok": ended == "cleared" and not missing and not mine}) # fmt: skip
248
+ finally:
249
+ browser.close()
250
+ merged = merge_counts(counts_by_level)
251
+ checked = evaluate_checks(checks, merged)
252
+ unique_errors = list(dict.fromkeys(errors))[:20]
253
+ ok = (all(r["ok"] for r in results) and all(c["ok"] for c in checked) and not unique_errors
254
+ and not hud_seen) # fmt: skip
255
+ worst = next((r["ended"] for r in results if not r["cleared"]), "cleared")
256
+ return {
257
+ "passed": ok and bool(results),
258
+ "ended": worst if results else "no-boot",
259
+ "game_seconds": round(sum(r["game_seconds"] for r in results), 1),
260
+ "session_seconds": sum(LEVEL_SECONDS + STEP_SECONDS * lv.get("steps", 10) for lv in levels),
261
+ "errors": unique_errors,
262
+ "hud": list(hud_seen.values()),
263
+ "checks": checked,
264
+ "events": {name: c["count"] for name, c in sorted(merged.items())},
265
+ "state": state,
266
+ "sounds": sounds,
267
+ "levels": results,
268
+ **({"screenshots": shots} if capture else {}),
269
+ }
270
+
271
+
272
+ def level_failures(report: dict) -> list[str]:
273
+ lines = []
274
+ for r in report.get("levels", []):
275
+ bot = r.get("bot") or {}
276
+ if not r["cleared"]:
277
+ why = {"stuck": f"the bot got stuck: {bot.get('detail') or '?'}",
278
+ "timeout": f"time ran out at step {bot.get('step', '?')} of {bot.get('steps', '?')}",
279
+ "no-boot": "the level never finished booting", "error": "a runtime error stopped it",
280
+ "stalled": "the game loop stopped advancing"}.get(r["ended"], r["ended"]) # fmt: skip
281
+ lines.append(f"Level {r['n']} ({r['name']}) was not cleared: {why}. Events seen: {r['events']}.")
282
+ if r.get("missing"):
283
+ lines.append(f"Level {r['n']} never emitted {', '.join(r['missing'])} (the level makes "
284
+ "these happen on the bot's way to the exit: check the touch hook and the "
285
+ "sf.event calls).") # fmt: skip
286
+ return lines
287
+
288
+
289
+ def failure_summary(report: dict) -> str:
290
+ """Plain-text failures for the Programmer's repair prompt."""
291
+ lines = level_failures(report)
292
+ if report["ended"] == "no-boot":
293
+ lines.append("The game never finished booting (sf.ready stayed false within 30 s).")
294
+ if report["ended"] == "stalled":
295
+ lines.append("The game loop stopped advancing.")
296
+ lines += [f"Runtime error: {e}" for e in report["errors"]]
297
+ if report.get("hud"):
298
+ lines += report["hud"][:8]
299
+ if len(report["hud"]) > 8:
300
+ lines.append(f"... and {len(report['hud']) - 8} more HUD problems of the same kind.")
301
+ lines.append(
302
+ "Fix the HUD: sf.text's x and y are screen pixels, but its size is in design pixels "
303
+ "(the SDK multiplies it by sf.assets.scale, so size 8 is 48 pixels tall on a "
304
+ "1920x1080 screen). Use size 8-12, put each line at least size * sf.assets.scale * "
305
+ "1.3 pixels below the one above, and keep every line inside the screen."
306
+ )
307
+ for r in report["checks"]:
308
+ if not r["ok"]:
309
+ when = f" by {r['by_second']:g} s" if r["by_second"] else ""
310
+ lines.append(
311
+ f"Check '{r['id']}' failed: event '{r['event']}' happened {r['count']} times"
312
+ f"{when}, needed {r['min_count']} ({r['description']})."
313
+ )
314
+ lines.append(
315
+ f"The bot (god mode) played {report['game_seconds']} of {report['session_seconds']} "
316
+ f"game seconds; ended: {report['ended']}; events seen: {report['events']}."
317
+ )
318
+ return "\n".join(lines)