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,1178 @@
1
+ """The concepts of a game's OKF bundle, written by code from a `GameRecord` (no model call).
2
+
3
+ `bundle(record)` returns every concept and file; `gamedb.sync` writes them. See gamedb for
4
+ the layout.
5
+ """
6
+
7
+ import hashlib
8
+ import io
9
+ import re
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+
13
+ from PIL import Image
14
+
15
+ from spriteforge.core.security import redact
16
+ from spriteforge.library.looks import measure
17
+ from spriteforge.memory.okf.codec import UnsafeKnowledge, ensure_no_secrets
18
+ from spriteforge.memory.okf.models import Entry, Metadata, Source
19
+
20
+ from .art import Filled
21
+ from .art_review import sheet_image, thumb
22
+ from .codegen import GameCode
23
+ from .codeinfo import Module, read_code
24
+ from .design import GameDesign
25
+ from .levels import LevelRecord
26
+ from .menus import ACTIONS, MenuRecord, menus_markdown
27
+ from .motion import MotionRecord, motion_markdown
28
+ from .plan import PlanRecord
29
+ from .qa import SDK_EVENTS, STATE_KEYS, QASuite, Step
30
+ from .qa_runtime import describe_step
31
+ from .research import ResearchRecord
32
+ from .story import StoryBible
33
+ from .structure import GameStructure, structure_markdown
34
+
35
+ WITHHELD = "withheld from the record: it looked like a credential"
36
+
37
+
38
+ # --- what a game is made of ------------------------------------------------------------------
39
+
40
+
41
+ @dataclass
42
+ class ArtInfo:
43
+ """One entity's locked art."""
44
+
45
+ source: str # "muse", "library <id>", "muse (locked, from v1)" ...
46
+ version: int # the build that made it
47
+ sheet: bytes # the sprite sheet / image the game loads (PNG)
48
+ portrait: bytes # its first frame at 4x (PNG)
49
+ look: str # measured colours, brightness, detail
50
+ prompt: str = "" # the Muse prompt, '' for library art
51
+
52
+ @property
53
+ def digest(self) -> str:
54
+ return hashlib.sha256(self.sheet).hexdigest()[:12]
55
+
56
+
57
+ def art_info(filled: dict[str, Filled], version: int) -> dict[str, ArtInfo]:
58
+ """The locked art of a build, by entity id."""
59
+ out = {}
60
+ for eid, f in filled.items():
61
+ made = int(f.record.get("version") or f.record.get("reused_from") or version)
62
+ prompt = f.record.get("muse_prompt") or f.record.get("prompt") or ""
63
+ out[eid] = ArtInfo(f.source, made, f.png, thumb(f), measure(sheet_image(f)).text,
64
+ str(prompt)) # fmt: skip
65
+ return out
66
+
67
+
68
+ @dataclass
69
+ class Build:
70
+ version: int
71
+ source: str # the report's artifact or file name
72
+ report: dict # report.json
73
+
74
+
75
+ @dataclass
76
+ class Decision:
77
+ """The human at a gate: what they said and what it changed."""
78
+
79
+ gate: str # "G2 design v1", "G4 playtest v2"
80
+ outcome: str # "approved" | "changes requested" | "story added"
81
+ words: str # their feedback (redacted), '' for a plain approval
82
+ changed: str # what it changed
83
+ build: int | None = None # the build it is about, or the build that answered it
84
+ asked_build: bool = False # it asked for that build (approving a design, changes at G4)
85
+
86
+
87
+ @dataclass
88
+ class GameRecord:
89
+ design: GameDesign
90
+ design_source: str
91
+ story: StoryBible | None = None
92
+ story_source: str = ""
93
+ builds: list[Build] = field(default_factory=list)
94
+ art: dict[str, ArtInfo] = field(default_factory=dict) # the latest build's
95
+ screen: tuple[int, int] = (320, 180)
96
+ scale: int = 1
97
+ credits: list[str] = field(default_factory=list)
98
+ code: GameCode | None = None # the latest build's
99
+ qa: QASuite | None = None # the latest build's suite
100
+ qa_export: bytes | None = None # test_game_qa.py
101
+ decisions: list[Decision] = field(default_factory=list)
102
+ play: str | None = None
103
+ research: ResearchRecord | None = None # L2.2: similar games studied with web search
104
+ research_source: str = ""
105
+ plan: PlanRecord | None = None # L2.2: the game plan of the current design
106
+ plan_source: str = ""
107
+ levels: list[LevelRecord] = field(default_factory=list) # L2.3: the levels as data
108
+ levels_source: str = ""
109
+ level_files: dict[int, bytes] = field(default_factory=dict) # what the SDK loads, per level
110
+ level_previews: dict[int, bytes] = field(default_factory=dict) # map previews (PNG)
111
+ level_play: dict[int, dict] = field(default_factory=dict) # the latest build's playtest
112
+ motion: MotionRecord | None = None # L2.4: the motion design of the current design
113
+ motion_source: str = ""
114
+ motion_gif: bytes | None = None # the latest build's rows playing
115
+ structure: GameStructure | None = None # L2.5: levels in order, carries, saved, win
116
+ structure_source: str = ""
117
+ menus: MenuRecord | None = None # L2.5: the menus as data (the latest build's version)
118
+ menus_source: str = ""
119
+ menus_file: bytes | None = None # menus.json as the SDK loads it (theme in the art's colours)
120
+ menu_shots: dict[str, bytes] = field(default_factory=dict) # screen id -> PNG
121
+ title_art: dict[str, bytes] = field(default_factory=dict) # "title-art", "emblem" -> PNG
122
+
123
+ @property
124
+ def latest(self) -> Build | None:
125
+ return self.builds[-1] if self.builds else None
126
+
127
+
128
+ # --- concepts --------------------------------------------------------------------------------
129
+
130
+
131
+ def make_entry(ident: str, type_: str, title: str, description: str, tags, body: str,
132
+ sources: list[str], resource: str | None = None,
133
+ status: str = "stable") -> Entry: # fmt: skip
134
+ fields = {
135
+ "type": type_,
136
+ "title": title,
137
+ "description": re.sub(r"\s+", " ", description).strip()[:300],
138
+ "tags": sorted({str(t).lower() for t in tags if str(t).strip()}),
139
+ "sources": [Source(resource="spriteforge game", id=s) for s in sources if s],
140
+ "status": status,
141
+ }
142
+ if resource:
143
+ fields["resource"] = resource
144
+ return Entry(id=ident, metadata=Metadata(**fields), body=body.strip() + "\n")
145
+
146
+
147
+ def bullets(items, empty: str = "- (none)") -> str:
148
+ return "\n".join(f"- {i}" for i in items) or empty
149
+
150
+
151
+ def slug(text: str) -> str:
152
+ return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:60] or "x"
153
+
154
+
155
+ def safe_text(text: str) -> str:
156
+ """Text the human or a model wrote, as it may go into the record."""
157
+ text = redact(text)
158
+ try:
159
+ ensure_no_secrets(text)
160
+ except UnsafeKnowledge:
161
+ return f"({WITHHELD})"
162
+ return text
163
+
164
+
165
+ def code_span(text: str) -> str:
166
+ return f"`{text}`" if text else "-"
167
+
168
+
169
+ def game_concept(rec: GameRecord, modules: list[Module]) -> Entry:
170
+ d, b = rec.design, rec.latest
171
+ sections = []
172
+ if rec.research:
173
+ sections.append("[Research](/research/overview.md): similar games, patterns, feel numbers")
174
+ if rec.plan:
175
+ sections.append("[Game plan](/plan/overview.md): the human's requirements, movement "
176
+ "numbers, mechanics, levels, feel and animations") # fmt: skip
177
+ sections += [
178
+ "[Rules](/design/rules.md): controls, rules, progression, difficulty, win and lose",
179
+ "[Events and state](/design/events.md): what every build emits and exposes",
180
+ "[Entities](/entities/index.md): everything the player sees",
181
+ ]
182
+ if rec.structure:
183
+ sections.append("[Structure](/design/structure.md): the levels in order, what carries "
184
+ "over and what is saved") # fmt: skip
185
+ if rec.menus:
186
+ sections.append("[Menus](/menus/overview.md): every screen around play, the theme and "
187
+ "the title art") # fmt: skip
188
+ if rec.art:
189
+ sections.append("[Art style](/art/style.md) and [locked assets](/art/assets/index.md)")
190
+ if modules:
191
+ sections.append("[Code](/code/overview.md): files, scenes and what each one does")
192
+ if rec.qa:
193
+ sections.append("[QA tests](/qa/suite.md): tests written from the design")
194
+ if b:
195
+ sections.append(f"[Builds](/builds/index.md): the latest is [v{b.version}]"
196
+ f"(/builds/v{b.version}.md)") # fmt: skip
197
+ if rec.decisions:
198
+ sections.append("[Decisions](/decisions/index.md): the human's words at each gate")
199
+ if rec.story:
200
+ sections.append("[Story](/story/overview.md), [characters](/characters/index.md) and "
201
+ "[world](/world/index.md)") # fmt: skip
202
+ if b:
203
+ qa = b.report.get("qa") or {}
204
+ status = (
205
+ f"Build v{b.version} (design v{b.report.get('design_version', 1)}): "
206
+ + ("all design checks pass" if b.report.get("passed") else "some design checks fail")
207
+ + (f"; QA {qa['passed']}/{qa['passed'] + qa['failed']} tests pass" if qa else "")
208
+ + f". Play: {code_span(rec.play or '')}"
209
+ )
210
+ else:
211
+ status = "Not built yet: the design is waiting for approval."
212
+ body = f"""
213
+ # {d.title}
214
+ {d.pitch}
215
+
216
+ # At a glance
217
+ {d.camera} camera, a {rec.screen[0]}x{rec.screen[1]} screen. {d.controls}. A full session lasts
218
+ {d.session_seconds} s. Story: {"yes, see [the story](/story/overview.md)" if rec.story else "none (the human did not ask for one)"}.
219
+
220
+ # Current version
221
+ {status}
222
+
223
+ # Sections
224
+ {bullets(sections)}
225
+ """
226
+ sources = [rec.design_source, b.source if b else ""]
227
+ return make_entry("game", "Game", d.title, d.pitch, ["game", d.camera], body, sources)
228
+
229
+
230
+ def rules_concept(rec: GameRecord) -> Entry:
231
+ d = rec.design
232
+ body = f"""
233
+ # Camera and controls
234
+ {d.camera}. {d.controls}
235
+
236
+ # Player
237
+ {d.player}
238
+
239
+ # World
240
+ {d.world}
241
+
242
+ # Rules
243
+ {bullets(d.rules)}
244
+
245
+ # Progression
246
+ {bullets(d.progression)}
247
+
248
+ # Difficulty
249
+ {bullets(d.difficulty)}
250
+
251
+ # Win and lose
252
+ Win: {d.win}
253
+ Lose: {d.lose}
254
+ A full session lasts {d.session_seconds} s.
255
+
256
+ # HUD
257
+ {bullets(d.hud)}
258
+
259
+ # Checks
260
+ Every build must emit these [events](/design/events.md); the bot playtest counts them.
261
+ """ + "\n".join(
262
+ f"- `{c.event}` at least {c.min_count}" + (f" by {c.by_second:g} s" if c.by_second else "")
263
+ + f": {c.description}" for c in d.checks
264
+ ) # fmt: skip
265
+ return make_entry("design/rules", "Game Rules", f"{d.title}: rules",
266
+ f"{d.camera}; {d.controls}", ["design", "rules", d.camera], body,
267
+ [rec.design_source]) # fmt: skip
268
+
269
+
270
+ def events_concept(rec: GameRecord, modules: list[Module]) -> Entry:
271
+ d = rec.design
272
+ emitted = {}
273
+ for m in modules:
274
+ for e in m.events:
275
+ emitted.setdefault(e, []).append(m.path)
276
+ rows, seen = [], set()
277
+ for c in d.checks:
278
+ if c.event in seen:
279
+ continue
280
+ seen.add(c.event)
281
+ when = f"at least {c.min_count}" + (f" by {c.by_second:g} s" if c.by_second else "")
282
+ rows.append((c.event, "design check", f"{c.description} ({when})", emitted.get(c.event)))
283
+ sdk = {"boot": "the game started", "restart": "Enter restarted the run after win or lose",
284
+ "menu": "an sf.choose menu opened", "choice": "an sf.choose option was picked",
285
+ "win": "the session was won", "lose": "the session was lost"} # fmt: skip
286
+ for e in SDK_EVENTS:
287
+ if e not in seen:
288
+ seen.add(e)
289
+ rows.append((e, "SDK" if e not in {"win", "lose"} else "every game", sdk[e],
290
+ emitted.get(e))) # fmt: skip
291
+ for e, files in emitted.items():
292
+ if e not in seen:
293
+ seen.add(e)
294
+ rows.append((e, "code", "emitted by the game (not a design check)", files))
295
+ table = "\n".join(
296
+ f"| `{e}` | {kind} | {what} | {', '.join(f'`{f}`' for f in files) if files else '-'} |"
297
+ for e, kind, what, files in rows
298
+ )
299
+ set_by = {}
300
+ for m in modules:
301
+ for k in m.state:
302
+ set_by.setdefault(k, []).append(m.path)
303
+ keys = list(dict.fromkeys([*STATE_KEYS, *set_by]))
304
+ need = {"hp": "player health", "x": "player x in pixels", "y": "player y in pixels",
305
+ "time": "seconds since this run started (a restart resets it)",
306
+ "level": "the level, when the design has levels",
307
+ "score": "score, gems or kills, when the design has them"} # fmt: skip
308
+ state = "\n".join(
309
+ f"| `{k}` | {need.get(k, 'set by the game')} | "
310
+ f"{'required' if k in {'hp', 'x', 'y', 'time'} else 'optional'} | "
311
+ f"{', '.join(f'`{f}`' for f in set_by.get(k, [])) or 'not set'} |"
312
+ for k in keys
313
+ )
314
+ body = f"""
315
+ # Events
316
+ What the game reports with `sf.event(name, data)`; the playtest and the QA tests count these.
317
+
318
+ # Schema
319
+ ## Events
320
+ | event | from | meaning | emitted in |
321
+ | --- | --- | --- | --- |
322
+ {table}
323
+
324
+ ## sf.state
325
+ A plain object the game updates every frame; QA tests read it.
326
+
327
+ | key | meaning | contract | set in |
328
+ | --- | --- | --- | --- |
329
+ {state}
330
+ """
331
+ return make_entry("design/events", "Event Contract", f"{d.title}: events and state",
332
+ f"{len(rows)} events, {len(keys)} state keys", ["design", "events", "state"],
333
+ body, [rec.design_source, rec.latest.source if rec.latest else ""]) # fmt: skip
334
+
335
+
336
+ def entity_concepts(rec: GameRecord) -> list[Entry]:
337
+ chars = {c.entity: c for c in rec.story.characters} if rec.story else {}
338
+ entries = []
339
+ for e in rec.design.entities:
340
+ a = rec.art.get(e.id)
341
+ art = (
342
+ f"![{e.id}](/references/art/{e.id}.png)\n\n[Locked art](/art/assets/{e.id}.md): "
343
+ f"{a.source}, made in build v{a.version}."
344
+ if a
345
+ else "No art yet: it is made when the game is built."
346
+ )
347
+ c = chars.get(e.id)
348
+ story = (
349
+ f"\n# Character\n[{c.name}](/characters/{e.id}.md), {c.role}. {c.personality}. "
350
+ f"Goal: {c.goal}.\n"
351
+ if c
352
+ else ""
353
+ )
354
+ body = f"""
355
+ # {e.id}
356
+ {e.role}, {e.width}x{e.height} px on a 320x180 screen.
357
+
358
+ # Looks
359
+ {e.look}
360
+
361
+ # Behaviour
362
+ {e.behaviour}
363
+
364
+ # Animations
365
+ {", ".join(e.animations) or "none (static)"}
366
+ {story}
367
+ # Art
368
+ {art}
369
+ """
370
+ entries.append(make_entry(f"entities/{e.id}", "Entity", e.id, f"{e.role}: {e.look}",
371
+ ["entity", e.role, e.id], body, [rec.design_source])) # fmt: skip
372
+ return entries
373
+
374
+
375
+ def art_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
376
+ if not rec.art:
377
+ return [], {}
378
+ d = rec.design
379
+ roles = {e.id: e.role for e in d.entities}
380
+ hero = next((e for e in d.entities if e.role == "player"), None)
381
+ source = rec.latest.source if rec.latest else rec.design_source
382
+ rows = "\n".join(
383
+ f"| [{eid}](/art/assets/{eid}.md) | {roles.get(eid, '-')} | {a.source} | v{a.version} |"
384
+ for eid, a in rec.art.items()
385
+ )
386
+ style = f"""
387
+ # Direction
388
+ {d.look}
389
+
390
+ # Screen and scale
391
+ {d.camera} view, a {rec.screen[0]}x{rec.screen[1]} screen (art scale {rec.scale}); the hero is
392
+ {hero.height * rec.scale if hero else "?"} px tall. Every sprite faces right; the game flips it.
393
+
394
+ # Locked assets
395
+ | entity | role | source | made in |
396
+ | --- | --- | --- | --- |
397
+ {rows}
398
+
399
+ # Rules for new art
400
+ Match the locked art: its outline, shading and pixel size. Colours named by the design win over
401
+ a style example's. Locked art is redrawn only when the human or a change asks for it.
402
+
403
+ # Credits
404
+ {bullets(rec.credits)}
405
+ """
406
+ if rec.motion:
407
+ style += "\n# Motion\nHow each thing moves and reacts: [motion design](/art/motion.md).\n"
408
+ entries = [make_entry("art/style", "Art Style", f"{d.title}: art style", d.look,
409
+ ["art", "style", d.camera], style, [rec.design_source, source])] # fmt: skip
410
+ files = {}
411
+ if rec.motion:
412
+ entry, extra = motion_concept(rec, source)
413
+ entries.append(entry)
414
+ files |= extra
415
+ for eid, a in rec.art.items():
416
+ files[f"references/art/{eid}.png"] = a.portrait
417
+ files[f"references/art/{eid}-sheet.png"] = a.sheet
418
+ body = f"""
419
+ # {eid}
420
+ ![{eid}](/references/art/{eid}.png)
421
+
422
+ The first frame at 4x. The game loads [the sheet](/references/art/{eid}-sheet.png)
423
+ (image {a.digest}). Entity: [{eid}](/entities/{eid}.md).
424
+
425
+ # Source
426
+ {a.source}, locked in build v{a.version}. Redraw it only when a change asks for this entity.
427
+
428
+ # Muse prompt
429
+ {a.prompt.strip() or "- (library art: no prompt)"}
430
+
431
+ # Measured look
432
+ {a.look}
433
+ """
434
+ entries.append(make_entry(f"art/assets/{eid}", "Asset", f"{eid} art",
435
+ f"{roles.get(eid, 'asset')}: {a.source}, v{a.version}",
436
+ ["art", "asset", roles.get(eid, ""), eid], body, [source],
437
+ resource=f"/references/art/{eid}.png")) # fmt: skip
438
+ return entries, files
439
+
440
+
441
+ MOTION_SCHEMA = """# Schema
442
+ `/references/art/motion.json` (the Art Director's motion design, fitted by code):
443
+ * `rows[]`: `entity` (design id), `name` (the animation's name in the sheet), `plays` (when the
444
+ game shows it: idle, move, jump, fall, land, dash, hurt, attack, break, die, form, pickup,
445
+ other), `form` (the ability a form row shows, else ''), `frames[]` (`shows`: what the frame
446
+ shows, `airborne`: off the ground), `fps`, `loop`.
447
+ * `forms[]`: `ability`, `looks`, `tint` (#RRGGBB when its row fails), `particles`.
448
+ * `effects[]`: `name`, `on` (the SDK moment that plays it, or 'game'), `particles`, `colors`,
449
+ `speed` (px/s at 320x180), `flash`, `shake` (0-1), `squash` (+ flat, - tall), `seconds`.
450
+ """
451
+
452
+
453
+ def motion_concept(rec: GameRecord, source: str) -> tuple[Entry, dict[str, bytes]]:
454
+ """art/motion: the motion design (L2.4), what code found in the latest build's rows and
455
+ the rows playing."""
456
+ m = rec.motion
457
+ checks = (rec.latest.report.get("motion") or {}).get("rows", []) if rec.latest else []
458
+ found = "\n".join(f"* {c['entity']}.{c['row']} ({c['plays']}, {c['frames']} frames): "
459
+ + ("; ".join([*c["problems"], *(f"repaired: {r}" for r in c["repaired"])]) or "ok")
460
+ for c in checks) or "- (no build yet)" # fmt: skip
461
+ files = {"references/art/motion.json": (m.brief.model_dump_json(indent=1) + "\n").encode()}
462
+ gif = ""
463
+ if rec.motion_gif:
464
+ files["references/art/motion.gif"] = rec.motion_gif
465
+ gif = "![every animated row playing](/references/art/motion.gif)\n\n"
466
+ body = (gif + motion_markdown(m).replace("# Motion design", "# Rows, forms and effects", 1)
467
+ + f"\n# Checked by code (latest build)\n{found}\n\n{MOTION_SCHEMA}")
468
+ entities = sorted({r.entity for r in m.brief.rows})
469
+ links = " ".join(f"[{e}](/art/assets/{e}.md)" for e in entities if e in rec.art)
470
+ body += f"\n# Assets\n{links or '-'}\n"
471
+ return make_entry("art/motion", "Motion Design", f"{rec.design.title}: motion design",
472
+ f"{len(m.brief.rows)} animation rows, {len(m.brief.forms)} forms, "
473
+ f"{len(m.brief.effects)} effects", ["art", "motion", "animation"], body,
474
+ [rec.motion_source, source], resource="/references/art/motion.json"), files # fmt: skip
475
+
476
+
477
+ def checks_for(rec: GameRecord, events: list[str]) -> list[str]:
478
+ by_event = {c.event: c.id for c in rec.design.checks}
479
+ return [f"`{e}` (check `{by_event[e]}`)" if e in by_event else f"`{e}`" for e in events]
480
+
481
+
482
+ def code_concepts(rec: GameRecord, modules: list[Module]) -> tuple[list[Entry], dict[str, bytes]]:
483
+ if rec.code is None:
484
+ return [], {}
485
+ source = rec.latest.source if rec.latest else ""
486
+ files, entries, rows = {}, [], []
487
+ contents = rec.code.as_dict()
488
+ for m in modules:
489
+ stem = slug(Path(m.path).stem)
490
+ data = contents[m.path].encode("utf-8")
491
+ try:
492
+ ensure_no_secrets(contents[m.path])
493
+ files[f"references/code/{m.path}"] = data
494
+ resource, file_text = f"/references/code/{m.path}", f"[{m.path}](/references/code/{m.path})"
495
+ except UnsafeKnowledge:
496
+ resource, file_text = None, f"{m.path} ({WITHHELD})"
497
+ role = "the entry point (calls sf.start)" if m.starts else "a helper loaded before game.js"
498
+ body = f"""
499
+ # {m.path}
500
+ {file_text}: {m.lines} lines, {role}.
501
+
502
+ # Classes and scenes
503
+ {bullets(m.classes)}
504
+ Scene keys: {", ".join(f"`{s}`" for s in m.scenes) or "-"}
505
+
506
+ # Functions
507
+ {bullets(m.functions)}
508
+
509
+ # Events emitted
510
+ {bullets(checks_for(rec, m.events))}
511
+
512
+ # sf.state keys set
513
+ {", ".join(f"`{k}`" for k in m.state) or "-"}
514
+
515
+ # Input
516
+ {"Reads sf.input (arrows/WASD, action keys; the bot plays through it)." if m.reads_input else "Does not read sf.input."}
517
+ Keys read directly: {", ".join(m.keys) or "-"}. Flags: {", ".join(f"`sf.flags.{f}`" for f in m.flags) or "-"}.
518
+ {"Defines the autoplay bot policy." if m.autoplay else ""}
519
+
520
+ # Asset ids used
521
+ {", ".join(f"[{a}](/entities/{a}.md)" if a in rec.art or any(e.id == a for e in rec.design.entities) else f"`{a}`" for a in m.assets) or "-"}
522
+ Textures it makes itself: {", ".join(f"`{t}`" for t in m.textures) or "-"}
523
+
524
+ # Menus opened
525
+ {bullets(m.menus)}
526
+ """
527
+ entries.append(make_entry(f"code/modules/{stem}", "Code Module", m.path,
528
+ f"{m.lines} lines; scenes {', '.join(m.scenes) or '-'}; "
529
+ f"{len(m.events)} events", ["code", "module", m.path, *m.scenes],
530
+ body, [source], resource=resource)) # fmt: skip
531
+ rows.append(f"| [{m.path}](/code/modules/{stem}.md) | {m.lines} | "
532
+ f"{', '.join(m.scenes) or '-'} | {', '.join(m.events) or '-'} |") # fmt: skip
533
+ total = sum(m.lines for m in modules)
534
+ body = f"""
535
+ # Files
536
+ Loaded in this order (`game.js` last). {total} lines in all.
537
+
538
+ | file | lines | scenes | events |
539
+ | --- | --- | --- | --- |
540
+ {chr(10).join(rows)}
541
+
542
+ # The Programmer's notes
543
+ {safe_text(rec.code.notes).strip() or "-"}
544
+
545
+ # Contract
546
+ The code reads input through `sf.input`, emits the [design's events](/design/events.md), keeps
547
+ `sf.state` up to date and uses only the [locked asset ids](/art/style.md).
548
+ """
549
+ entries.insert(0, make_entry("code/overview", "Code Overview", f"{rec.design.title}: code",
550
+ f"{len(modules)} file(s), {total} lines", ["code", "overview"],
551
+ body, [source])) # fmt: skip
552
+ return entries, files
553
+
554
+
555
+ def step_schema() -> str:
556
+ rows = "\n".join(
557
+ f"| `{name}` | {f.description or ''} |" for name, f in Step.model_fields.items()
558
+ )
559
+ return f"| field | meaning |\n| --- | --- |\n{rows}"
560
+
561
+
562
+ def qa_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes], list[str]]:
563
+ """The suite, one concept per test; returns the ids of tests that were dropped."""
564
+ if rec.qa is None:
565
+ return [], {}, []
566
+ b = rec.latest
567
+ results = {t["name"]: t for t in ((b.report.get("qa") or {}).get("tests", []) if b else [])}
568
+ files, resource = {}, None
569
+ if rec.qa_export:
570
+ try:
571
+ ensure_no_secrets(rec.qa_export.decode("utf-8"))
572
+ files["references/tests/test_game_qa.py"] = rec.qa_export
573
+ resource = "/references/tests/test_game_qa.py"
574
+ except UnsafeKnowledge:
575
+ pass
576
+ entries, rows = [], []
577
+ for test, since in zip(rec.qa.tests, rec.qa.versions, strict=False):
578
+ ident = f"qa/tests/{slug(test.name)}"
579
+ r = results.get(test.name)
580
+ if r is None:
581
+ result = "Not run yet."
582
+ elif r["passed"]:
583
+ result = f"Passed in build v{b.version}."
584
+ else:
585
+ result = f"FAILED in build v{b.version} at step {r['failed_step']}: {r['failure']}"
586
+ steps = "\n".join(f"{n}. {describe_step(s.model_dump())}"
587
+ for n, s in enumerate(test.steps, 1)) # fmt: skip
588
+ body = f"""
589
+ # {test.name}
590
+ {test.purpose}
591
+
592
+ The player {"cannot die (god mode: hurt, but HP stays at least 1)" if test.god else "can die"}.
593
+ Written for build [v{since}](/builds/v{since}.md) from the design; part of [the suite](/qa/suite.md).
594
+
595
+ # Steps
596
+ {steps}
597
+
598
+ # Last result
599
+ {result}
600
+ """
601
+ if not any(x.version == since for x in rec.builds):
602
+ body = body.replace(f"[v{since}](/builds/v{since}.md)", f"v{since}")
603
+ entries.append(make_entry(ident, "QA Test", test.name, test.purpose,
604
+ ["qa", "test", "god" if test.god else "lose-path"], body,
605
+ [b.source if b else ""])) # fmt: skip
606
+ mark = "-" if r is None else ("pass" if r["passed"] else "FAIL")
607
+ rows.append(f"| [{test.name}](/{ident}.md) | v{since} | {mark} |")
608
+ dropped = [f"qa/tests/{slug(n)}" for n in rec.qa.dropped]
609
+ body = f"""
610
+ # Tests
611
+ Written by the QA Playtester from the design (never the code) and played with real key presses
612
+ after the bot playtest; every build reruns the earlier builds' tests.
613
+
614
+ | test | since | last result |
615
+ | --- | --- | --- |
616
+ {chr(10).join(rows)}
617
+
618
+ Dropped by the human: {", ".join(rec.qa.dropped) or "-"}.
619
+ {"Notes: " + "; ".join(safe_text(n) for n in rec.qa.notes) if rec.qa.notes else ""}
620
+
621
+ # Export
622
+ {"[test_game_qa.py](/references/tests/test_game_qa.py): pytest + Playwright, runs next to the build." if resource else "No export yet."}
623
+
624
+ # Schema
625
+ A test is a name, a purpose, `god` (true: the player cannot die) and a list of steps. A step is
626
+ one flat record; the fields a step does not use stay empty.
627
+
628
+ {step_schema()}
629
+ """
630
+ entries.insert(0, make_entry("qa/suite", "QA Suite", f"{rec.design.title}: QA tests",
631
+ f"{len(rec.qa.tests)} tests", ["qa", "suite"], body,
632
+ [b.source if b else ""], resource=resource)) # fmt: skip
633
+ return entries, files, dropped
634
+
635
+
636
+ def build_concepts(rec: GameRecord) -> list[Entry]:
637
+ answered = {}
638
+ for n, d in enumerate(rec.decisions, 1):
639
+ if d.asked_build and d.build:
640
+ answered.setdefault(d.build, n)
641
+ entries = []
642
+ for b in rec.builds:
643
+ r = b.report
644
+ attempts = "\n".join(
645
+ f"{a['attempt']}. {'passed' if a['passed'] else 'failed at ' + str(a.get('stage'))}"
646
+ + (f" (repaired with {a['repair']})" if a.get("repair") else "")
647
+ for a in r.get("attempts", [])
648
+ )
649
+ qa = r.get("qa") or {}
650
+ rv = r.get("art_review") or {}
651
+ review = (
652
+ f"{rv.get('reviewed_by', '-')}; scores "
653
+ + ", ".join(f"{k} {v}/5" for k, v in (rv.get("scores") or {}).items())
654
+ + f"; {len(rv.get('issues', []))} issue(s), "
655
+ f"{sum(bool(f.get('fixed')) for f in rv.get('fixes', []))} fixed"
656
+ if rv
657
+ else "-"
658
+ )
659
+ calls = r.get("model_calls") or {}
660
+ rev = r.get("revision") or {}
661
+ why = (
662
+ f"[Decision {answered[b.version]}](/decisions/{answered[b.version]}.md) asked for it."
663
+ if b.version in answered
664
+ else "The first build of the approved design."
665
+ )
666
+ changed = bullets([
667
+ f"design: {safe_text(rev['design_changes'])}" if rev.get("design_changes") else "",
668
+ "art redrawn: " + ", ".join(c["entity"] for c in rev.get("art_changes", []))
669
+ if rev.get("art_changes") else "",
670
+ f"code: {safe_text(rev['code_instructions'])}" if rev.get("code_instructions") else "",
671
+ "QA tests dropped: " + ", ".join(rev["drop_qa_tests"]) if rev.get("drop_qa_tests") else "",
672
+ f"story: {safe_text(rev['story_changes'])}" if rev.get("story_changes") else "",
673
+ ] if rev else [], "- nothing: a new build") # fmt: skip
674
+ changed = "\n".join(line for line in changed.splitlines() if line.strip() != "-")
675
+ # The build before it (a build a Go back stopped has no page: numbers can skip).
676
+ before = max((x.version for x in rec.builds if x.version < b.version), default=None)
677
+ prev = f"Previous: [v{before}](/builds/v{before}.md). " if before else ""
678
+ body = f"""
679
+ # Build v{b.version}
680
+ {"All design checks pass." if r.get("passed") else "Some design checks FAIL."} Design
681
+ v{r.get("design_version", 1)}, written by {r.get("chosen_by", "-")}. {prev}
682
+
683
+ # Checks
684
+ {bullets(("ok " if c.get("ok") else "FAIL ") + f"`{c['event']}` {c.get('count', '?')}/{c.get('min_count', '?')}" for c in r.get("checks", []))}
685
+ {bullets(safe_text(p) for p in r.get("problems", [])) if r.get("problems") else ""}
686
+
687
+ # Attempts
688
+ {attempts or "-"}
689
+
690
+ # QA
691
+ {f"{qa['passed']}/{qa['passed'] + qa['failed']} tests pass; see [the suite](/qa/suite.md)." if qa else "No QA tests."}
692
+
693
+ # Art review
694
+ {review}
695
+
696
+ # Cost
697
+ {calls.get("chat", 0)} Spark and {calls.get("image", 0)} Muse Image calls, about ${calls.get("estimated_cost_usd", 0)}.
698
+
699
+ # What changed and why
700
+ {why}
701
+ {changed}
702
+ """
703
+ entries.append(make_entry(f"builds/v{b.version}", "Build", f"Build v{b.version}",
704
+ ("passed" if r.get("passed") else "failed")
705
+ + (f"; QA {qa['passed']}/{qa['passed'] + qa['failed']}" if qa else ""),
706
+ ["build", f"v{b.version}"], body, [b.source])) # fmt: skip
707
+ return entries
708
+
709
+
710
+ def decision_concepts(rec: GameRecord) -> list[Entry]:
711
+ known = {b.version for b in rec.builds}
712
+ entries = []
713
+ for n, d in enumerate(rec.decisions, 1):
714
+ if not d.build:
715
+ build = "-"
716
+ elif d.build not in known:
717
+ build = f"Build v{d.build} answers it (not built yet)."
718
+ elif d.asked_build:
719
+ build = f"[Build v{d.build}](/builds/v{d.build}.md) answered it."
720
+ else:
721
+ build = f"It was about [build v{d.build}](/builds/v{d.build}.md)."
722
+ words = safe_text(d.words).strip()
723
+ body = f"""
724
+ # {d.gate}: {d.outcome}
725
+
726
+ # The human's words
727
+ {"> " + words.replace(chr(10), chr(10) + "> ") if words else "(no words: approved as shown)"}
728
+
729
+ # What it changed
730
+ {safe_text(d.changed) or "-"}
731
+
732
+ # Answered by
733
+ {build}
734
+ """
735
+ entries.append(make_entry(f"decisions/{n}", "Decision", f"Decision {n}: {d.gate}",
736
+ f"{d.outcome}" + (f": {words[:120]}" if words else ""),
737
+ ["decision", d.outcome], body, ["gates"])) # fmt: skip
738
+ return entries
739
+
740
+
741
+ def story_concepts(rec: GameRecord) -> list[Entry]:
742
+ story, src = rec.story, rec.story_source
743
+ if story is None:
744
+ return []
745
+ entities = {e.id: e for e in rec.design.entities}
746
+ cast = "\n".join(f"- [{c.name}](/characters/{c.entity}.md) ({c.role}): {c.look}"
747
+ for c in story.characters) # fmt: skip
748
+ places = "\n".join(f"- [{loc.name}](/world/{loc.id}.md): {loc.description}"
749
+ for loc in story.locations) # fmt: skip
750
+ overview = f"""
751
+ # Logline
752
+ {story.logline}
753
+
754
+ # Premise
755
+ {story.premise}
756
+
757
+ # Setting
758
+ {story.setting}
759
+
760
+ # Tone and themes
761
+ {story.tone}. Themes: {", ".join(story.themes) or "-"}.
762
+
763
+ # Characters
764
+ {cast}
765
+
766
+ # Locations
767
+ {places or "- (none)"}
768
+
769
+ The [arc](/story/arc.md) and the [canon](/story/canon.md) no later level may break.
770
+ """
771
+ arc = "\n".join(f"{n}. {beat}" + (" (level 1: the current game)" if n == 1 else " (planned)")
772
+ for n, beat in enumerate(story.arc, 1)) # fmt: skip
773
+ entries = [
774
+ make_entry("story/overview", "Story", f"{story.title}: the story", story.logline,
775
+ ["story", *story.themes], overview, [src]),
776
+ make_entry("story/arc", "Story Arc", f"{story.title}: the arc",
777
+ f"{len(story.arc)} beats; beat 1 is the current game", ["story", "arc", "levels"],
778
+ f"# Beats\n{arc}", [src]),
779
+ make_entry("story/canon", "Canon", f"{story.title}: canon",
780
+ "Facts no later level, menu or cutscene may break", ["story", "canon"],
781
+ f"# Never break\n{bullets(story.canon)}", [src]),
782
+ ] # fmt: skip
783
+ for loc in story.locations:
784
+ body = f"# {loc.name}\n{loc.description}\n\n# Mood\n{loc.mood}"
785
+ entries.append(make_entry(f"world/{loc.id}", "Location", loc.name, loc.description,
786
+ ["location", loc.id], body, [src])) # fmt: skip
787
+ for c in story.characters:
788
+ e = entities.get(c.entity)
789
+ if e is None:
790
+ continue
791
+ art = (f"![{c.name}](/references/art/{c.entity}.png)\n\n[Locked art](/art/assets/{c.entity}.md)."
792
+ if c.entity in rec.art else "No art yet.") # fmt: skip
793
+ body = f"""
794
+ # Who
795
+ {c.name}, {c.role}. {c.look}.
796
+
797
+ # Personality
798
+ {c.personality}
799
+
800
+ # Goal
801
+ {c.goal}
802
+
803
+ # Backstory
804
+ {c.backstory}
805
+
806
+ # Relationships
807
+ {c.relationships or "-"}
808
+
809
+ # In play
810
+ [Entity `{e.id}`](/entities/{e.id}.md): {e.role}, {e.behaviour}. Abilities: {c.abilities}.
811
+
812
+ # Art
813
+ {art}
814
+ """
815
+ entries.append(make_entry(f"characters/{c.entity}", "Character", c.name,
816
+ f"{c.role}: {c.look}", ["character", c.role, e.role, e.id], body,
817
+ [src, rec.design_source])) # fmt: skip
818
+ return entries
819
+
820
+
821
+ def web_page(url: str) -> str:
822
+ """A reference URL as it may go into the record ('' when it looks like a secret)."""
823
+ return url if url and safe_text(url) == url else ""
824
+
825
+
826
+ def research_concepts(rec: GameRecord) -> list[Entry]:
827
+ record, src = rec.research, rec.research_source
828
+ if record is None:
829
+ return []
830
+ r = record.research
831
+ refs, entries = [], []
832
+ for ref, ok in record.references:
833
+ ident = f"research/references/{slug(ref.title)}"
834
+ url = web_page(ref.url)
835
+ checked = ("a search returned this page" if ok else
836
+ "NOT among the pages the searches returned: check it before trusting it"
837
+ if url else "no page") # fmt: skip
838
+ refs.append(f"- [{ref.title}](/{ident}.md): {ref.learn}")
839
+ body = f"""
840
+ # What to learn
841
+ {ref.learn}
842
+
843
+ # Page
844
+ {f"<{url}>" if url else "-"} ({checked})
845
+
846
+ # Use
847
+ A reference teaches patterns only: never copy its levels, characters, story or art.
848
+ """
849
+ entry = make_entry(ident, "Reference Game", ref.title, ref.learn,
850
+ ["research", "reference", "verified" if ok else "unverified"], body, [src]) # fmt: skip
851
+ if url:
852
+ entry.metadata.sources.append(Source(resource=url, title=ref.title))
853
+ entries.append(entry)
854
+ pats = "\n".join(f"- **{x.name}**: {x.how} For this game: {x.use}" for x in r.patterns)
855
+ feel = "\n".join(f"| {f.name} | {f.value} | {f.why} |" for f in r.feel)
856
+ queries = ", ".join(f"`{q}`" for q in record.queries)
857
+ body = f"""
858
+ # How it was made
859
+ {record.by}; {record.searches} search call(s){f": {queries}" if queries else ""}. {len(record.sources)} pages returned.
860
+
861
+ # Reference games
862
+ {chr(10).join(refs) or "- (none)"}
863
+
864
+ # Patterns
865
+ {pats or "- (none)"}
866
+
867
+ # Feel numbers players expect
868
+ | what | value | why |
869
+ | --- | --- | --- |
870
+ {feel}
871
+
872
+ # Pitfalls
873
+ {bullets(r.pitfalls)}
874
+ """
875
+ overview = make_entry("research/overview", "Research", f"{rec.design.title}: research",
876
+ f"{len(r.references)} reference games, {len(r.patterns)} patterns",
877
+ ["research", "patterns", "feel"], body, [src]) # fmt: skip
878
+ for ref, ok in record.references:
879
+ if ok and (url := web_page(ref.url)):
880
+ overview.metadata.sources.append(Source(resource=url, title=ref.title))
881
+ return [overview, *entries]
882
+
883
+
884
+ def plan_concepts(rec: GameRecord) -> list[Entry]:
885
+ record, src = rec.plan, rec.plan_source
886
+ if record is None:
887
+ return []
888
+ p, k, m, title = record.plan, record.kinematics, record.plan.movement, rec.design.title
889
+ covers = {}
890
+ for c in p.coverage:
891
+ covers.setdefault(c.requirement, []).append(f"{', '.join(c.parts)}: {c.how}")
892
+ reqs = "\n".join(f"- **{r.id}** \"{safe_text(r.text)}\": " + ("; ".join(covers.get(r.id, []))
893
+ or "not covered") for r in p.requirements) # fmt: skip
894
+ levels = "\n".join(f"- [Level {lv.n}: {lv.name}](/plan/levels/{lv.n}.md): {lv.new_idea}"
895
+ for lv in p.levels) # fmt: skip
896
+ overview = f"""
897
+ # Requirements (the human's words)
898
+ {reqs or "- (none)"}
899
+
900
+ # Style
901
+ {p.style}
902
+
903
+ # Parts
904
+ - [Movement](/plan/movement.md): numbers and the jump physics code derived from them
905
+ - [Abilities, mechanics and challenges](/plan/mechanics.md)
906
+ - [Feel and animations](/plan/feel.md)
907
+
908
+ # Levels
909
+ {levels or "- (none)"}
910
+
911
+ # Risks
912
+ {bullets(p.risks)}
913
+
914
+ # Problems code found
915
+ {bullets(record.problems, "- none")}
916
+ """
917
+ rows = [("move_speed", m.move_speed, "tiles/s", "running speed"),
918
+ ("jump_height", m.jump_height, "tiles", "the highest jump; 0 = no jump"),
919
+ ("air_time", m.air_time, "s", "take-off to landing at the same height"),
920
+ ("dash_distance", m.dash_distance, "tiles", "0 = no dash"),
921
+ ("dash_cooldown", m.dash_cooldown, "s", "time between dashes"),
922
+ ("coyote_time", m.coyote_time, "s", "a jump still works after leaving a ledge")] # fmt: skip
923
+ if k:
924
+ rows += [("gravity", k.gravity, "px/s^2", "8 * jump height / air time^2 (code)"),
925
+ ("jump_velocity", k.jump_velocity, "px/s", "take-off speed, 4h / T (code)"),
926
+ ("jump_distance", k.jump_distance, "px", "covered in the air at full speed (code)"),
927
+ ("max_rise", k.max_rise, "tiles", "the highest platform top a jump reaches (code)"),
928
+ ("max_gap", k.max_gap, "tiles", "the widest gap a running jump clears (code)"),
929
+ ("max_gap_with_dash", k.max_gap_with_dash, "tiles", "with one dash in the air (code)"),
930
+ ("coyote", k.coyote, "px", "ledge forgiveness at full speed (code)")] # fmt: skip
931
+ table = "\n".join(f"| `{n}` | {v:g} | {u} | {w} |" for n, v, u, w in rows)
932
+ movement = f"""
933
+ # Movement
934
+ {m.move_speed:g} tiles/s; {f"jump {m.jump_height:g} tiles in {m.air_time:g} s" if k else "no jump"}; {f"dash {m.dash_distance:g} tiles every {m.dash_cooldown:g} s" if m.dash_distance else "no dash"}. Tiles are {k.tile if k else 16} px.
935
+
936
+ # Schema
937
+ | field | value | unit | meaning |
938
+ | --- | --- | --- | --- |
939
+ {table}
940
+
941
+ Levels are checked against these numbers: a platform higher than `max_rise` or a gap wider than
942
+ `max_gap` (`max_gap_with_dash` once the dash is available) cannot be crossed.
943
+ """
944
+ abilities = "\n".join(f"- **{a.name}**: {a.does}" + (f" ({a.numbers})" if a.numbers else "")
945
+ + f"; from {a.unlocked_by}" for a in p.abilities) # fmt: skip
946
+ mechanics = "\n".join(f"- **{x.name}**: {x.what} For: {x.purpose}" for x in p.mechanics)
947
+ challenges = "\n".join(f"- **{c.name}**: {c.tests}" + (f" Needs: {', '.join(c.needs)}." if c.needs else "")
948
+ for c in p.challenges) # fmt: skip
949
+ feel = "\n".join(f"| {f.event} | {f.see} | {f.hear or '-'} |" for f in p.feel)
950
+ anims = "\n".join(f"| {a.entity} | {r.name} | {r.frames} | {'loop' if r.loop else 'once'} | {r.shows} |"
951
+ for a in p.animations for r in a.rows) # fmt: skip
952
+ entries = [
953
+ make_entry("plan/overview", "Game Plan", f"{title}: game plan",
954
+ f"{len(p.requirements)} requirements, {len(p.levels)} levels",
955
+ ["plan", "requirements"], overview, [src]),
956
+ make_entry("plan/movement", "Movement", f"{title}: movement and kinematics",
957
+ f"{m.move_speed:g} tiles/s" + (f", jump {m.jump_height:g} tiles, gaps up to {k.max_gap} tiles" if k else ""),
958
+ ["plan", "movement", "kinematics"], movement, [src]),
959
+ make_entry("plan/mechanics", "Mechanics", f"{title}: abilities, mechanics, challenges",
960
+ f"{len(p.abilities)} abilities, {len(p.mechanics)} mechanics, {len(p.challenges)} challenges",
961
+ ["plan", "mechanics", "abilities", "challenges"],
962
+ f"# Abilities\n{abilities or '- (none)'}\n\n# Mechanics\n{mechanics or '- (none)'}\n\n"
963
+ f"# Challenge vocabulary\n{challenges or '- (none)'}", [src]),
964
+ make_entry("plan/feel", "Feel", f"{title}: feel and animations",
965
+ "what the player sees and hears; animation rows per entity", ["plan", "feel", "animation"],
966
+ "# Feedback\n| event | see | hear |\n| --- | --- | --- |\n" + feel
967
+ + "\n\n# Animations\n| entity | row | frames | plays | shows |\n| --- | --- | --- | --- | --- |\n"
968
+ + anims, [src]),
969
+ ] # fmt: skip
970
+ vocabulary = {c.name.casefold(): c for c in p.challenges}
971
+ for lv in p.levels:
972
+ tests = "\n".join(f"- **{name}**: " + (vocabulary[name.casefold()].tests
973
+ if name.casefold() in vocabulary else "(not in the vocabulary)")
974
+ for name in lv.challenges) # fmt: skip
975
+ body = f"""
976
+ # Teaches
977
+ {lv.teaching_goal}
978
+
979
+ # New idea
980
+ {lv.new_idea}
981
+
982
+ # Challenges
983
+ {tests or "- (none)"}
984
+
985
+ # Needs
986
+ {", ".join(lv.abilities) or "-"}. See [movement](/plan/movement.md) for what a jump can cross.
987
+
988
+ # Difficulty
989
+ {lv.difficulty} of 10
990
+ """
991
+ entries.append(make_entry(f"plan/levels/{lv.n}", "Level Plan", f"Level {lv.n}: {lv.name}",
992
+ f"teaches {lv.teaching_goal}; new: {lv.new_idea}",
993
+ ["plan", "level", f"level-{lv.n}"], body, [src])) # fmt: skip
994
+ return entries
995
+
996
+
997
+ LEVEL_SCHEMA = """| field | meaning |
998
+ | --- | --- |
999
+ | `n`, `name` | the level's number and name |
1000
+ | `cols`, `rows` | the map's size in tiles (16 px at scale 1) |
1001
+ | `map` | the tile rows, top first; a character is a tile in `tiles`, ' ' is empty |
1002
+ | `tiles` | character -> `kind` (solid, one_way, hazard) and the `entity` that draws it |
1003
+ | `things` | `id`, `kind` (crate, breakable, pickup, enemy, checkpoint, exit), `entity`, `col`, `row` (bottom cell), `cells`, `needs` (ability that opens or beats it), `opened_by` (touch, dash, never), `holds` (what a crate drops), `gives` (the ability a pickup gives), `patrol` (an enemy's columns) |
1004
+ | `start`, `player` | the player's start cell and entity |
1005
+ | `route` | the bot's steps code found: walk, jump or fall (take-off `x0`, speed `vx`, `wait`, `dash`), touch, dash, collect, exit |
1006
+ | `exclusive` | abilities that replace each other |"""
1007
+
1008
+
1009
+ def level_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
1010
+ """levels/<n>: each level as data (L2.3), its map preview and what code and the bot found."""
1011
+ entries, files = [], {}
1012
+ plans = {lv.n: lv for lv in rec.plan.plan.levels} if rec.plan else {}
1013
+ for r in rec.levels:
1014
+ s, n = r.spec, r.spec.n
1015
+ lp = plans.get(n)
1016
+ play = rec.level_play.get(n) or {}
1017
+ resource = None
1018
+ if n in rec.level_files:
1019
+ files[f"references/levels/{n}.json"] = rec.level_files[n]
1020
+ resource = f"/references/levels/{n}.json"
1021
+ if n in rec.level_previews:
1022
+ files[f"references/levels/{n}.png"] = rec.level_previews[n]
1023
+ # A thing with no entity of its own (a checkpoint the design has no art for) is drawn
1024
+ # by the SDK: no link (live 2026-11-03: /entities/.md failed the bundle's validation).
1025
+ ids = {x.id for x in rec.design.entities}
1026
+ shows = lambda eid: f"[{eid}](/entities/{eid}.md)" if eid in ids else (f"`{eid}`" if eid else "drawn by the SDK")
1027
+ legend = "\n".join(f"| `{e.char}` | {e.kind} | {shows(e.entity)} | {e.needs or '-'} | "
1028
+ f"{e.opened_by} | {e.holds or '-'} | {e.gives or '-'} |" for e in s.legend) # fmt: skip
1029
+ route = ", ".join(st["do"] + (f" {st['thing']}" if st.get("thing") else "")
1030
+ for st in r.route if st["do"] != "walk") # fmt: skip
1031
+ played = (f"cleared by the bot in {play.get('game_seconds')} game seconds" if play.get("cleared")
1032
+ else f"not cleared ({play.get('ended')})" if play else "not played yet") # fmt: skip
1033
+ body = f"""
1034
+ # Plan
1035
+ {f"Teaches {lp.teaching_goal}. New idea: {lp.new_idea}. [Level plan](/plan/levels/{n}.md)" if lp else "-"}
1036
+
1037
+ # Map
1038
+ {s.notes.strip() or "-"}
1039
+
1040
+ """ + ("[Map preview](/references/levels/" + str(n) + ".png) (the bot's route as a line)\n\n" if n in rec.level_previews else "") + f"""```
1041
+ {chr(10).join(s.rows)}
1042
+ ```
1043
+
1044
+ | char | kind | entity | needs | opened by | holds | gives |
1045
+ | --- | --- | --- | --- | --- | --- | --- |
1046
+ {legend}
1047
+
1048
+ Challenges: {", ".join(f"{c.name} (column {c.column})" for c in s.challenges) or "-"}. Events: {", ".join(s.events) or "-"}.
1049
+
1050
+ # Code's check
1051
+ {"The exit can be reached with the plan's movement" if r.solved else "The exit CANNOT be reached"}; difficulty {r.difficulty:g} (code's measure). Bot route: {route or "-"}.
1052
+
1053
+ Problems:
1054
+ {bullets([safe_text(p) for p in r.problems], "- none")}
1055
+
1056
+ # Playtest
1057
+ {played}{"; missing events: " + ", ".join(play.get("missing", [])) if play.get("missing") else ""}
1058
+
1059
+ # Schema
1060
+ {LEVEL_SCHEMA}
1061
+ """
1062
+ entries.append(make_entry(f"levels/{n}", "Level", f"Level {n}: {s.name}",
1063
+ f"{len(s.rows[0]) if s.rows else 0}x{len(s.rows)} tiles; "
1064
+ + (f"teaches {lp.teaching_goal}" if lp else s.notes),
1065
+ ["level", f"level-{n}"], body, [rec.levels_source], resource)) # fmt: skip
1066
+ return entries, files
1067
+
1068
+
1069
+ def structure_concept(rec: GameRecord) -> list[Entry]:
1070
+ """design/structure (L2.5): the levels in order, what carries over and what is saved."""
1071
+ s = rec.structure
1072
+ if s is None:
1073
+ return []
1074
+ links = ", ".join(f"[level {lv.n}](/levels/{lv.n}.md)" for lv in s.levels
1075
+ if any(r.spec.n == lv.n for r in rec.levels)) # fmt: skip
1076
+ body = structure_markdown(s).replace("# Game structure", "# Structure", 1)
1077
+ if links:
1078
+ body += f"\nLevels as data: {links}\n"
1079
+ if rec.menus:
1080
+ body += "\nThe SDK's flow plays it: see [the menus](/menus/overview.md).\n"
1081
+ return [make_entry("design/structure", "Game Structure", f"{rec.design.title}: structure",
1082
+ f"{len(s.levels)} level(s); win: {s.win}", ["design", "structure", "levels"],
1083
+ body, [rec.structure_source])] # fmt: skip
1084
+
1085
+
1086
+ MENUS_SCHEMA = """# Schema
1087
+ `/references/menus.json` (window.SF_MENUS, what the SDK's flow loads):
1088
+ * `title`, `subtitle`: the title screen's words (the SDK draws all text).
1089
+ * `theme`: `panel`, `border`, `text`, `highlight`, `dim` (#RRGGBB, fitted by code to the locked
1090
+ art's measured colours, text contrast checked) and `style` (framed, double, solid).
1091
+ * `screens.<id>`: `title`, `subtitle`, `items[]` (`label`, `action`). Screen ids: title, main,
1092
+ pause, settings, controls, credits, level_select, results, game_over, victory.
1093
+ * `levels[]`: `n`, `name`, `goal` (the structure); `can_lose`; `controls[]`; `credits[]`;
1094
+ `difficulty` (name -> the multiplier the game reads as sf.settings.multiplier); `art`
1095
+ (`title`, `emblem`: image ids in assets.json, role menu).
1096
+ Actions: """ + ", ".join(f"`{a}` ({w})" for a, w in ACTIONS.items()) + "."
1097
+
1098
+
1099
+ def menu_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
1100
+ """menus/overview and menus/<screen> (L2.5): the menus as data, their screenshots and the
1101
+ title art."""
1102
+ m = rec.menus
1103
+ if m is None:
1104
+ return [], {}
1105
+ files, resource = {}, None
1106
+ if rec.menus_file:
1107
+ files["references/menus.json"] = rec.menus_file
1108
+ resource = "/references/menus.json"
1109
+ pictures = ""
1110
+ for part, name in (("title-art", "title"), ("emblem", "emblem")):
1111
+ if part in rec.title_art:
1112
+ files[f"references/art/{name}.png"] = rec.title_art[part]
1113
+ pictures += f"![{part.replace('-', ' ')}](/references/art/{name}.png) "
1114
+ report = (rec.latest.report.get("menus") or {}) if rec.latest else {}
1115
+ art_source = (report.get("title_art") or {}).get("source", "")
1116
+ screens = "\n".join(f"- [{s.id}](/menus/{s.id}.md): " + (", ".join(i.label for i in s.items) or "-")
1117
+ for s in m.spec.screens) # fmt: skip
1118
+ body = (
1119
+ f"{pictures}\n\n" if pictures else ""
1120
+ ) + menus_markdown(m.spec, m.notes, m.problems).replace(f"# Menus: {m.spec.title}", "# Menus", 1) + f"""
1121
+ # Title art
1122
+ {art_source or "(not built yet)"}
1123
+
1124
+ # Screens
1125
+ {screens}
1126
+
1127
+ # Written by
1128
+ {m.by}{" (asked again once with code's problems)" if m.retried else ""}; {m.why or "-"}
1129
+
1130
+ {MENUS_SCHEMA}
1131
+ """
1132
+ entries = [make_entry("menus/overview", "Menus", f"{rec.design.title}: menus",
1133
+ f"{len(m.spec.screens)} screens rendered by the SDK; theme "
1134
+ f"{m.spec.theme.panel} / {m.spec.theme.highlight}",
1135
+ ["menus", "ui", "title"], body, [rec.menus_source], resource)] # fmt: skip
1136
+ for s in m.spec.screens:
1137
+ shot = ""
1138
+ if s.id in rec.menu_shots:
1139
+ files[f"references/menus/{s.id}.png"] = rec.menu_shots[s.id]
1140
+ shot = f"![the {s.id} screen](/references/menus/{s.id}.png)\n\n"
1141
+ items = "\n".join(f"{i}. {it.label} ({it.action}: {ACTIONS.get(it.action, '?')})"
1142
+ for i, it in enumerate(s.items, 1)) or "- (no items)" # fmt: skip
1143
+ body = f"""{shot}# {s.title or m.spec.title}
1144
+ {s.subtitle or ""}
1145
+
1146
+ # Items
1147
+ {items}
1148
+
1149
+ Part of [the menus](/menus/overview.md).
1150
+ """
1151
+ entries.append(make_entry(f"menus/{s.id}", "Menu Screen", f"Menu: {s.id.replace('_', ' ')}",
1152
+ f"{len(s.items)} items: " + ", ".join(i.label for i in s.items),
1153
+ ["menus", s.id], body, [rec.menus_source], resource)) # fmt: skip
1154
+ return entries, files
1155
+
1156
+
1157
+ def bundle(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
1158
+ """Every concept and file of a game's record."""
1159
+ modules = read_code(rec.code.as_dict()) if rec.code else []
1160
+ art, art_files = art_concepts(rec)
1161
+ code, code_files = code_concepts(rec, modules)
1162
+ qa, qa_files, _ = qa_concepts(rec)
1163
+ levels, level_files = level_concepts(rec)
1164
+ menus, menu_files = menu_concepts(rec)
1165
+ entries = [game_concept(rec, modules), rules_concept(rec), events_concept(rec, modules),
1166
+ *entity_concepts(rec), *art, *code, *qa, *build_concepts(rec),
1167
+ *decision_concepts(rec), *story_concepts(rec), *research_concepts(rec),
1168
+ *plan_concepts(rec), *levels, *structure_concept(rec), *menus] # fmt: skip
1169
+ return entries, art_files | code_files | qa_files | level_files | menu_files
1170
+
1171
+
1172
+ def portrait_of(sheet: bytes, frame: tuple[int, int] | None) -> Filled:
1173
+ """A Filled stand-in for art read back from files (sync from a run or a folder)."""
1174
+ kind = "sprite" if frame else "image"
1175
+ if frame is None:
1176
+ w, h = Image.open(io.BytesIO(sheet)).size
1177
+ frame = (w, h)
1178
+ return Filled(png=sheet, source="", reasons=[], meta={"frame": list(frame)}, kind=kind)