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,218 @@
1
+ """Gate 2 gameplay preview. All image spending and final locking stay behind gates."""
2
+
3
+ from pydantic import model_validator
4
+
5
+ from spriteforge.core.cost import BudgetExceeded
6
+ from spriteforge.core.gates import Gates, new_gate
7
+
8
+ from .asset_models import Manifest, ProductionPlan
9
+ from .preview_assets import PreviewContext, asset_record, build_block, mood_board
10
+ from .preview_models import BlockDescription, BlockDescriptions, PreviewPlan, block_manifest
11
+ from .preview_review import request_change, revised_plan, room_layout
12
+
13
+
14
+ def gameplay_step(store, run_id):
15
+ ctx = PreviewContext(store, run_id)
16
+ try:
17
+ return _step(ctx)
18
+ except BudgetExceeded as exc:
19
+ message = (
20
+ f"Gameplay preview stopped at its call/cost cap: {exc}. Saved assets are preserved."
21
+ )
22
+ with store.connect() as db:
23
+ db.execute("UPDATE runs SET status='budget_exhausted' WHERE id=?", (run_id,))
24
+ store._event(db, run_id, "Director", "preview.budget_exhausted", {"message": message})
25
+ return False
26
+
27
+
28
+ def open_gate(ctx, stage, title, names, **kwargs):
29
+ Gates(ctx.store).open(
30
+ ctx.run_id, new_gate(stage, title, [ctx.artifacts[n].id for n in names], **kwargs)
31
+ )
32
+
33
+
34
+ def manifest_for(ctx):
35
+ name = "preview/manifest.json"
36
+ if name not in ctx.artifacts:
37
+ fixture = block_manifest(ctx.brief)
38
+
39
+ class ValidDescriptions(BlockDescriptions):
40
+ @model_validator(mode="after")
41
+ def required_ids(self):
42
+ block_manifest(ctx.brief, self)
43
+ return self
44
+
45
+ descriptions = ctx.ask(
46
+ "preview/descriptions-v2.json",
47
+ "Game Designer",
48
+ "Describe each of these exact 12 building blocks for this brief, preserving ids. "
49
+ "Return each id and a concise visual description only. Choose two distinct enemies, three "
50
+ "floor variants, three wall variants, two props and a key appropriate to this environment "
51
+ "and perspective. NO baked-in UI or text. Brief: "
52
+ + ctx.brief.model_dump_json()
53
+ + ". Blocks: "
54
+ + fixture.model_dump_json(),
55
+ ValidDescriptions,
56
+ BlockDescriptions(
57
+ assets=[BlockDescription(id=a.id, description=a.desc) for a in fixture.assets]
58
+ ),
59
+ )
60
+ manifest = block_manifest(ctx.brief, descriptions)
61
+ ctx.save(name, manifest.model_dump(), "Game Designer")
62
+ return Manifest.model_validate(ctx.read(name))
63
+
64
+
65
+ def approve_preview(ctx, gate, plan, manifest):
66
+ from spriteforge.core.usage import usage_report
67
+
68
+ records = [asset_record(ctx, ident, version) for ident, version in plan.versions.items()]
69
+ if any(r.status != "accepted" for r in records):
70
+ raise ValueError("Fix failing asset validators before approving this preview")
71
+ report = ctx.read(f"preview/v{plan.version}/readability.json")
72
+ # Include colors actually used in rendered assets and the code-drawn HUD.
73
+ style = plan.style.model_copy(
74
+ update={"palette": report["palette"], "max_colors": len(report["palette"])}
75
+ )
76
+ ctx.save("style.json", style.model_dump(), "Art Director")
77
+ hero = next(r for r in records if r.id == "hero")
78
+ ctx.save("anchor.png", ctx.data(hero.artifact), "Art Director", "image/png")
79
+ locking = ProductionPlan(versions=plan.versions, instructions=plan.instructions)
80
+ for record in records:
81
+ ctx.lock(record, locking)
82
+ ctx.save("preview/locked-assets.json", {r.id: r.model_dump() for r in records}, "Director")
83
+ ctx.save(
84
+ "preview/run-report.json", usage_report(ctx.store, ctx.run_id).model_dump(), "Director"
85
+ )
86
+ ctx.save(
87
+ "approval.json",
88
+ {
89
+ "gate": gate.id,
90
+ "version": plan.version,
91
+ "screen": [320, 180],
92
+ "style_anchor": "anchor.png",
93
+ "style": "style.json",
94
+ "manifest": f"preview/v{plan.version}/manifest.json",
95
+ "registry": "preview/locked-assets.json",
96
+ "preview": f"preview/v{plan.version}/gameplay.png",
97
+ },
98
+ "Director",
99
+ )
100
+ # G2 stops here. A later explicit --assets resume can use these exact accepted bases.
101
+ ctx.store.advance(
102
+ ctx.run_id,
103
+ ctx.run.cursor,
104
+ "G2 approved; gameplay preview and building blocks locked",
105
+ final=True,
106
+ )
107
+
108
+
109
+ def _step(ctx):
110
+ ctx.restore_files()
111
+ history = Gates(ctx.store).all(ctx.run_id)
112
+ last = history[-1]
113
+ if ctx.use_mood and "preview/reference.json" not in ctx.artifacts:
114
+ name = mood_board(ctx)
115
+ if last.stage == "styles":
116
+ open_gate(ctx, "mood_board", "G2 Optional mood board, not final art", [name])
117
+ return False
118
+ if last.stage == "mood_board" and last.status == "approved":
119
+ ctx.save(
120
+ "preview/reference.json",
121
+ {"artifact": name, "approved_gate": last.id},
122
+ "Art Director",
123
+ )
124
+ manifest = manifest_for(ctx)
125
+ versions = [
126
+ int(n.split("/")[1][1:])
127
+ for n in ctx.artifacts
128
+ if n.startswith("preview/v") and n.endswith("/plan.json")
129
+ ]
130
+ version = max(versions, default=1)
131
+ if last.stage == "preview_revise" and last.status == "approved":
132
+ parent = next(g for g in history if g.id == last.parent_id)
133
+ reviewed = next(
134
+ a
135
+ for a in ctx.artifacts.values()
136
+ if a.id in parent.artifacts_to_show and a.name.endswith("/readability.json")
137
+ )
138
+ version = ctx.read(reviewed.name)["version"] + 1
139
+ name = f"preview/v{version}/plan.json"
140
+ if name in ctx.artifacts:
141
+ plan = PreviewPlan.model_validate(ctx.read(name))
142
+ else:
143
+ plan = (
144
+ revised_plan(
145
+ ctx, PreviewPlan.model_validate(ctx.read(f"preview/v{version - 1}/plan.json")), last
146
+ )
147
+ if version > 1
148
+ else PreviewPlan(
149
+ version=1,
150
+ versions={a.id: 1 for a in manifest.assets},
151
+ instructions={},
152
+ style=ctx.style,
153
+ )
154
+ )
155
+ ctx.save(name, plan.model_dump(), "Director")
156
+ ctx.style = plan.style
157
+ for spec in manifest.assets:
158
+ if spec.id in plan.canvas_overrides:
159
+ if spec.type in {"character", "tile"}:
160
+ raise ValueError("Character and tile canvases remain fixed")
161
+ spec.size = plan.canvas_overrides[spec.id]
162
+ ctx.save(f"preview/v{plan.version}/manifest.json", manifest.model_dump(), "Game Designer")
163
+ if last.stage == "gameplay":
164
+ if last.status == "changes_requested":
165
+ request_change(ctx, last, manifest, plan)
166
+ return False
167
+ if last.status == "approved":
168
+ approve_preview(ctx, last, plan, manifest)
169
+ return False
170
+ if not ctx.use_mood and "preview/reference.json" not in ctx.artifacts:
171
+ hero = build_block(ctx, manifest.tasks()[0], plan)
172
+ if last.stage == "sprite_anchor" and last.status == "approved":
173
+ ctx.save(
174
+ "preview/reference.json",
175
+ {"artifact": hero.artifact, "approved_gate": last.id},
176
+ "Art Director",
177
+ )
178
+ else:
179
+ open_gate(
180
+ ctx,
181
+ "sprite_anchor",
182
+ "G2 Approve the first sprite as style reference",
183
+ [hero.artifact, hero.provenance],
184
+ )
185
+ return False
186
+ for task in manifest.tasks():
187
+ if f"preview/assets/{task.id}/v{plan.versions[task.id]}/record.json" not in ctx.artifacts:
188
+ build_block(ctx, task, plan)
189
+ return True
190
+ layout = room_layout(ctx, manifest, plan)
191
+ from .preview_render import render_preview
192
+
193
+ names = render_preview(ctx, plan, layout)
194
+ if ctx.use_mood:
195
+ names.append("mood/v1/landscape.png")
196
+ open_gate(
197
+ ctx,
198
+ "gameplay",
199
+ f"G2 Gameplay preview v{version}",
200
+ names,
201
+ form_schema={
202
+ "type": "object",
203
+ "properties": {
204
+ "targets": {
205
+ "type": "string",
206
+ "title": "Change targets (assets, layout or palette)",
207
+ "default": "",
208
+ "suggestions": [a.id for a in manifest.assets] + ["layout", "palette"],
209
+ },
210
+ "palette": {
211
+ "type": "string",
212
+ "title": "New palette (comma-separated hex colors, for palette changes)",
213
+ "default": "",
214
+ },
215
+ },
216
+ },
217
+ )
218
+ return False
@@ -0,0 +1,372 @@
1
+ """Validated brief and role proposals grounded in the local genre/style corpus."""
2
+
3
+ import re
4
+ from typing import Literal
5
+
6
+ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
7
+
8
+ from spriteforge.agents.models import Contract
9
+ from spriteforge.agents.roles import load_roles
10
+ from spriteforge.pixel.schemas import hex_color
11
+ from spriteforge.providers.base import ChatRequest, Message, chat_json
12
+
13
+ NO_STORY = "No story"
14
+ YES_STORY = "Yes: named characters, a world and a story arc"
15
+ STORY_CHOICES = [NO_STORY, YES_STORY]
16
+ # Words with which a human asks for a story; the brief draft may suggest one only then.
17
+ STORY_WORDS = re.compile(
18
+ r"\b(stor(y|ies|yline)|plot|narrative|lore|backstor(y|ies)|cutscenes?|dialogues?|"
19
+ r"quests?|tales?|sagas?|characters? (named|called)|named characters?)\b",
20
+ re.IGNORECASE,
21
+ )
22
+
23
+
24
+ # Research (L2.2): before designing, the Game Designer studies similar games with web search.
25
+ RESEARCH_YES = "Yes: study similar games on the web first (up to 8 searches, about $0.05)"
26
+ RESEARCH_NO = "No research"
27
+ RESEARCH_CHOICES = [RESEARCH_YES, RESEARCH_NO]
28
+
29
+
30
+ def research_choice(value: str) -> str:
31
+ """'no', 'No research' -> RESEARCH_NO; anything else (yes, empty) -> RESEARCH_YES."""
32
+ return RESEARCH_NO if re.match(r"\s*no\b", str(value or ""), re.IGNORECASE) else RESEARCH_YES
33
+
34
+
35
+ def story_choice(value: str) -> str:
36
+ """'yes', 'Yes: ...', 'Add a story' -> YES_STORY; anything else -> NO_STORY."""
37
+ return YES_STORY if re.match(r"\s*(yes|add)\b", str(value), re.IGNORECASE) else NO_STORY
38
+
39
+
40
+ def asks_for_story(text: str) -> bool:
41
+ return bool(STORY_WORDS.search(text or ""))
42
+
43
+
44
+ class GameBrief(BaseModel):
45
+ model_config = ConfigDict(extra="forbid")
46
+ genre: str = "genres/top-down-dungeon-crawler"
47
+ perspective: str = "top-down"
48
+ environment: str = "A mossy ruined dungeon"
49
+ mood: str = "Mysterious, readable greens and warm amber"
50
+ character: str = "A small brave explorer"
51
+ core_loop: str = "Explore rooms, dodge enemies, collect keys and reach the exit"
52
+ difficulty: str = "Forgiving"
53
+ session_length: str = "5 minutes"
54
+ controls: str = "keyboard"
55
+ references: str = "No specific reference games"
56
+ # Only when the human asks: a story means named characters, a world and an arc.
57
+ story: str = NO_STORY
58
+ # Research similar games with web search before the plan and design (default yes).
59
+ research: str = RESEARCH_YES
60
+ answers: dict[str, str] = Field(default_factory=dict)
61
+ notes: list[str] = Field(default_factory=list)
62
+ screen: tuple[Literal[320], Literal[180]] = (320, 180)
63
+
64
+ @field_validator("story", mode="before")
65
+ @classmethod
66
+ def normalise_story(cls, value):
67
+ return story_choice(value or NO_STORY)
68
+
69
+ @field_validator("research", mode="before")
70
+ @classmethod
71
+ def normalise_research(cls, value):
72
+ return research_choice(value)
73
+
74
+ @property
75
+ def wants_story(self) -> bool:
76
+ return self.story == YES_STORY
77
+
78
+ @property
79
+ def wants_research(self) -> bool:
80
+ return self.research == RESEARCH_YES
81
+
82
+
83
+ class GenrePick(Contract):
84
+ """The Game Designer's reading of the prompt: a genre in its own words plus seeded references."""
85
+
86
+ genre: str = Field(min_length=2, max_length=80)
87
+ description: str = Field(min_length=1)
88
+ closest: list[str] = Field(max_length=3)
89
+ questions: list[str] = Field(min_length=2, max_length=6)
90
+
91
+
92
+ BRIEF_FIELDS = (
93
+ "perspective",
94
+ "environment",
95
+ "mood",
96
+ "character",
97
+ "core_loop",
98
+ "difficulty",
99
+ "session_length",
100
+ "controls",
101
+ "references",
102
+ "story",
103
+ )
104
+
105
+
106
+ class BriefDraft(Contract):
107
+ """G1 brief defaults drafted from the prompt, so the form starts from the human's idea."""
108
+
109
+ perspective: str
110
+ environment: str
111
+ mood: str
112
+ character: str
113
+ core_loop: str
114
+ difficulty: str
115
+ session_length: str
116
+ controls: str
117
+ references: str
118
+ story: str = Field(
119
+ description=f"'{NO_STORY}' unless the human's own words ask for a story (named "
120
+ f"characters, plot, lore): then '{YES_STORY}'"
121
+ )
122
+
123
+ @model_validator(mode="before")
124
+ @classmethod
125
+ def older(cls, data):
126
+ """Drafts saved before the story question default to no story."""
127
+ if isinstance(data, dict) and "story" not in data:
128
+ data = {**data, "story": NO_STORY}
129
+ return data
130
+
131
+
132
+ class Questions(Contract):
133
+ questions: list[str] = Field(min_length=2, max_length=4)
134
+
135
+
136
+ class StyleOption(Contract):
137
+ name: str
138
+ description: str
139
+ colors: list[str] = Field(min_length=4, max_length=16)
140
+
141
+ @field_validator("colors")
142
+ @classmethod
143
+ def validate_colors(cls, colors):
144
+ return [hex_color(c) for c in colors]
145
+
146
+
147
+ class Options(Contract):
148
+ options: list[StyleOption] = Field(min_length=2, max_length=3)
149
+
150
+
151
+ def propose(provider, role, prompt, schema):
152
+ instructions = load_roles()[role]
153
+ return chat_json(
154
+ provider,
155
+ ChatRequest(
156
+ messages=[
157
+ Message(
158
+ role="system",
159
+ content=str(instructions.model_dump())
160
+ + "\nHuman notes are part of the brief and override untouched template defaults. Ask about genuine conflicts instead of discarding the notes.",
161
+ ),
162
+ Message(role="user", content=prompt),
163
+ ],
164
+ cache_key="spriteforge-intake",
165
+ ),
166
+ schema,
167
+ )
168
+
169
+
170
+ def section(body, heading):
171
+ part = body.split("# " + heading + "\n", 1)
172
+ return part[1].split("\n# ", 1)[0].strip() if len(part) == 2 else ""
173
+
174
+
175
+ def seeded_questions(entry):
176
+ return seeded_questions_from(entry.body)
177
+
178
+
179
+ def seeded_questions_from(body):
180
+ return [
181
+ re.sub(r"^\d+\.\s*", "", line)
182
+ for line in section(body, "Adaptive questions").splitlines()
183
+ if line.strip()
184
+ ]
185
+
186
+
187
+ def field(title, default="", choices=None):
188
+ return {
189
+ "type": "string",
190
+ "title": title,
191
+ "default": default,
192
+ "suggestions": choices
193
+ or [default or "Use the genre convention", "Keep it simple for the first build"],
194
+ }
195
+
196
+
197
+ STOP_WORDS = {"a", "an", "and", "the", "of", "to", "in", "on", "with", "where", "game", "will"}
198
+
199
+
200
+ def words(text):
201
+ return set(re.findall(r"[a-z]+", text.lower())) - STOP_WORDS
202
+
203
+
204
+ def genre_prompt(goal, genres):
205
+ catalog = "\n".join(f"- {e.id}: {e.title}. {e.metadata.description}" for e in genres)
206
+ return (
207
+ "Read the human's game idea and name its genre in the idea's own terms (for example "
208
+ "'Top-down arena survival'). Use a seeded genre's exact title only when the idea fits "
209
+ "that genre's rules; otherwise name a new genre. description: camera, controls, core "
210
+ "loop and how a session ends, in 2-4 sentences, taken from the idea. closest: up to 3 "
211
+ "seeded genre ids that are useful references (may be empty). questions: 2-6 questions "
212
+ "about this genre that the idea leaves open.\nIdea: "
213
+ + goal
214
+ + "\nSeeded genres:\n"
215
+ + catalog
216
+ )
217
+
218
+
219
+ def guess_genre(goal, genres):
220
+ """Offline pick: the seeded genre sharing the most words with the idea."""
221
+ fallback = next((e for e in genres if e.id.endswith("/top-down-dungeon-crawler")), genres[0])
222
+ if not goal.strip():
223
+ best = [fallback]
224
+ else:
225
+ idea = words(goal)
226
+ scored = sorted(
227
+ genres,
228
+ key=lambda e: -len(idea & words(e.title + " " + e.metadata.description)),
229
+ )
230
+ best = [e for e in scored if idea & words(e.title + " " + e.metadata.description)][:3]
231
+ if not best:
232
+ return GenrePick(
233
+ genre="Custom game",
234
+ description=goal,
235
+ closest=[],
236
+ questions=["What does the player do most of the time?", "How does a session end?"],
237
+ )
238
+ return GenrePick(
239
+ genre=best[0].title,
240
+ description=best[0].metadata.description,
241
+ closest=[e.id for e in best],
242
+ questions=seeded_questions(best[0])[:6] or ["How does a session end?", "What is hard?"],
243
+ )
244
+
245
+
246
+ def genre_form(pick, genres, note):
247
+ titles = {e.id: e.title for e in genres}
248
+ suggestions = [pick.genre] + [titles[i] for i in pick.closest if i in titles]
249
+ suggestions += [t for t in titles.values() if t not in suggestions]
250
+ return {
251
+ "type": "object",
252
+ "properties": {
253
+ "genre": {
254
+ "type": "string",
255
+ "title": "Genre",
256
+ "description": f"{note} Suggested from your idea: {pick.description}",
257
+ "default": pick.genre,
258
+ "suggestions": suggestions,
259
+ }
260
+ },
261
+ }
262
+
263
+
264
+ def match_genre(text, genres):
265
+ """A typed or picked genre that names a seeded genre (by id or title), else None."""
266
+ key = text.strip().lower()
267
+ return next((e for e in genres if key in {e.id.lower(), e.title.lower()}), None)
268
+
269
+
270
+ def custom_genre_body(pick, genres):
271
+ """A genre written for this idea, in the seeded entries' section format."""
272
+ refs = [e for e in genres if e.id in pick.closest]
273
+ return (
274
+ f"# Core mechanics template\n{pick.description}\n\n# Adaptive questions\n"
275
+ + "".join(f"{i}. {q}\n" for i, q in enumerate(pick.questions, 1))
276
+ + "\n# Related seeded genres (references only; the idea's rules win)\n"
277
+ + ("".join(f"* {e.title}: {e.metadata.description}\n" for e in refs) or "* none\n")
278
+ )
279
+
280
+
281
+ def brief_prompt(goal, genre_title, body):
282
+ return (
283
+ "Draft the G1 brief fields from the human's idea and the chosen genre. Keep every "
284
+ "detail the idea states (camera, session length, enemies, pickups, upgrades, how it "
285
+ "gets harder); fill only what it leaves open with the simplest choice for the genre. "
286
+ f"Each field is one short line. story: '{NO_STORY}' unless the idea itself asks for a "
287
+ f"story (named characters, a plot, lore, cutscenes): then '{YES_STORY}'. Never suggest "
288
+ "a story the human did not ask for.\nIdea: " + goal + f"\nGenre: {genre_title}\n" + body
289
+ )
290
+
291
+
292
+ def fit_draft(draft, words):
293
+ """The draft as code allows it: a story only when the human's own words ask for one."""
294
+ story = story_choice(draft.story)
295
+ if story == YES_STORY and not asks_for_story(words):
296
+ story = NO_STORY
297
+ return draft.model_copy(update={"story": story})
298
+
299
+
300
+ def default_draft(body):
301
+ """Offline brief defaults: the generic brief, with the genre's loop and camera."""
302
+ defaults = GameBrief().model_dump(include=set(BRIEF_FIELDS))
303
+ defaults["core_loop"] = section(body, "Core mechanics template") or defaults["core_loop"]
304
+ if "Side-" in section(body, "Perspective and camera"):
305
+ defaults["perspective"] = "side-scroll"
306
+ return BriefDraft(**defaults)
307
+
308
+
309
+ def brief_form(body, draft):
310
+ properties = {
311
+ name: field(name.replace("_", " ").title(), value)
312
+ for name, value in draft.model_dump().items()
313
+ }
314
+ suggestions = {
315
+ "perspective": ["top-down", "side-scroll", "isometric"],
316
+ "controls": ["keyboard", "gamepad", "touch"],
317
+ "difficulty": ["Forgiving", "Balanced", "Challenging", "Starts easy, gets hard"],
318
+ "session_length": ["3 minutes", "5 minutes", "10 minutes", "15 minutes"],
319
+ "references": ["No specific reference games"],
320
+ }
321
+ properties["story"] = {
322
+ "type": "string",
323
+ "title": "Story?",
324
+ "description": "A story means named characters, a world and a story arc; without one "
325
+ "the game is described by its design alone.",
326
+ "enum": STORY_CHOICES,
327
+ "default": story_choice(draft.story),
328
+ }
329
+ properties["research"] = {
330
+ "type": "string",
331
+ "title": "Research similar games?",
332
+ "description": "Before the plan and the design, the Game Designer studies 3-6 published "
333
+ "games of this genre with web search and shows the sources and patterns at G2. "
334
+ "References teach patterns only; the game stays original.",
335
+ "enum": RESEARCH_CHOICES,
336
+ "default": RESEARCH_YES,
337
+ }
338
+ for name, rule in properties.items():
339
+ if "enum" not in rule:
340
+ rule["suggestions"] = list(dict.fromkeys([rule["default"], *suggestions.get(name, [])]))
341
+ for i, question in enumerate(seeded_questions_from(body)):
342
+ properties[f"seed_{i}"] = field(question)
343
+ return {"type": "object", "properties": properties}
344
+
345
+
346
+ def followups(brief):
347
+ return Questions(
348
+ questions=[
349
+ f"For {brief.character} in {brief.environment}, what should the first discovery be?",
350
+ f"With {brief.controls} controls and {brief.difficulty.lower()} difficulty, what assistance would help?",
351
+ f"What should end a {brief.session_length} session of '{brief.core_loop}'?",
352
+ ]
353
+ )
354
+
355
+
356
+ def default_options(brief, entries):
357
+ palettes = {
358
+ "dungeon-muted": ["#181825", "#454452", "#848078", "#CFBD91", "#4A994A", "#E7AD46"],
359
+ "bright-adventure": ["#172B49", "#805538", "#CF9656", "#66AA55", "#82C8DB", "#FFF0BA"],
360
+ "limited-monochrome": ["#101820", "#486858", "#90A880", "#E0E8B0"],
361
+ "night-neon": ["#101827", "#29354C", "#536783", "#65DFEB", "#F5BA54", "#E75B65"],
362
+ }
363
+ return Options(
364
+ options=[
365
+ StyleOption(
366
+ name=e.title,
367
+ description=e.metadata.description or e.title,
368
+ colors=palettes.get(e.id.split("/")[-1], palettes["bright-adventure"]),
369
+ )
370
+ for e in entries[:3]
371
+ ]
372
+ )