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,212 @@
1
+ """Muse building blocks through the shared pixel pipeline; one call per targeted version."""
2
+
3
+ import io
4
+
5
+ from PIL import Image
6
+
7
+ from spriteforge.config import BudgetConfig, Config
8
+ from spriteforge.core.cost import Budget
9
+ from spriteforge.core.gates import Gates
10
+ from spriteforge.pixel.schemas import Style
11
+ from spriteforge.pixel.validate import validate
12
+ from spriteforge.providers.base import ImageRequest
13
+
14
+ from .asset_context import ProductionContext
15
+ from .asset_models import AssetRecord
16
+ from .asset_render import deterministic_repair, pixelspec, process
17
+ from .asset_store import ProductionStore, digest
18
+ from .concept import center_crop, png
19
+ from .intake import GameBrief, Options
20
+
21
+
22
+ class PreviewContext(ProductionContext):
23
+ def __init__(self, store, run_id):
24
+ ProductionStore.__init__(self, store, run_id)
25
+ self.run = store.get_run(run_id)
26
+ self.cfg = Config.model_validate(self.run.config["settings"])
27
+ cap = BudgetConfig.model_validate(self.run.config["budget"])
28
+ cap.max_image_calls = min(cap.max_image_calls, self.cfg.preview.max_image_calls)
29
+ cap.per_request = False # the preview's cap is for the whole stage
30
+ self.budget = Budget(store, run_id, cap)
31
+ self.brief = GameBrief.model_validate(self.read("brief.json"))
32
+ history = Gates(store).all(run_id)
33
+ self.brief.notes = list(
34
+ dict.fromkeys(
35
+ [
36
+ *self.brief.notes,
37
+ *[
38
+ g.response.text
39
+ for g in history
40
+ if g.stage in {"genre", "brief", "followups"}
41
+ and g.response
42
+ and g.response.text.strip()
43
+ ],
44
+ ]
45
+ )
46
+ )
47
+ if self.brief.perspective not in {"top-down", "side-scroll", "isometric"}:
48
+ raise ValueError(
49
+ "Gameplay previews support top-down, side-scroll or isometric perspective"
50
+ )
51
+ options = Options.model_validate(self.read("options.json"))
52
+ gate = next(g for g in history if g.stage == "styles")
53
+ chosen = gate.response.form.get("style") or options.options[0].name
54
+ self.option = next(o for o in options.options if o.name == chosen)
55
+ self.style = Style(palette=self.option.colors, max_colors=len(self.option.colors))
56
+ self.use_mood = (
57
+ gate.response.form.get("mood_board", "yes" if self.cfg.preview.mood_board else "no")
58
+ == "yes"
59
+ )
60
+
61
+ def restore_files(self):
62
+ for name, artifact in list(self.artifacts.items()):
63
+ if name.startswith(("preview/", "mood/")):
64
+ self.save(name, artifact.data, mime=artifact.mime)
65
+
66
+ def image(self, prefix, prompt, refs=(), size=(1024, 1024)):
67
+ raw_name, request_name = prefix + "/raw.png", prefix + "/request.json"
68
+ if raw_name in self.artifacts:
69
+ return self.data(raw_name)
70
+ if request_name in self.artifacts:
71
+ raise RuntimeError(
72
+ "Image request was interrupted. Saved reservations are retained; automatic replay is disabled."
73
+ )
74
+ # Reserve checking occurs in the provider before dispatch. The request checkpoint
75
+ # prevents an ambiguous interrupted network call from being replayed on resume.
76
+ self.save(
77
+ request_name,
78
+ {
79
+ "prompt": prompt,
80
+ "size": list(size),
81
+ "model": self.cfg.image.model,
82
+ "references": [{"path": r, "sha256": digest(self.data(r))} for r in refs],
83
+ },
84
+ )
85
+ provider = self.image_provider()
86
+ try:
87
+ request = ImageRequest(
88
+ prompt=prompt, size=size, references=[self.data(r) for r in refs]
89
+ )
90
+ result = provider.edit(request) if refs else provider.generate(request)
91
+ self.save(raw_name, result.data, mime="image/png")
92
+ self.save(prefix + "/response.json", result.metadata)
93
+ return result.data
94
+ finally:
95
+ if hasattr(provider, "close"):
96
+ provider.close()
97
+
98
+
99
+ def mood_board(ctx):
100
+ name = "mood/v1/landscape.png"
101
+ if name not in ctx.artifacts:
102
+ raw = ctx.image(
103
+ "mood/v1",
104
+ "Mood board, not final art. A simple low-detail landscape study of "
105
+ + ctx.brief.environment
106
+ + ". Broad shapes, sparse detail, chunky pixels. "
107
+ "No text, lettering, captions, logos or HUD. Mood: "
108
+ + ctx.brief.mood
109
+ + ". Perspective: "
110
+ + ctx.brief.perspective
111
+ + ". Human brief notes: "
112
+ + str(ctx.brief.notes)
113
+ + ". Palette and style: "
114
+ + ctx.option.model_dump_json(),
115
+ size=(1536, 1024),
116
+ )
117
+ source = Image.open(io.BytesIO(raw)).convert("RGB")
118
+ cropped = center_crop(source)
119
+ ctx.save(name, png(cropped), "Art Director", "image/png")
120
+ ctx.save(
121
+ "mood/v1/crop.json",
122
+ {
123
+ "source": source.size,
124
+ "cropped": cropped.size,
125
+ "requested": [1536, 1024],
126
+ "method": "center-crop; no stretching",
127
+ },
128
+ "Art Director",
129
+ )
130
+ return name
131
+
132
+
133
+ def asset_record(ctx, ident, version):
134
+ return AssetRecord.model_validate(ctx.read(f"preview/assets/{ident}/v{version}/record.json"))
135
+
136
+
137
+ def build_block(ctx, task, plan):
138
+ version = plan.versions[task.id]
139
+ prefix = f"preview/assets/{task.id}/v{version}"
140
+ if prefix + "/record.json" in ctx.artifacts:
141
+ return asset_record(ctx, task.id, version)
142
+ ctx.style = plan.style
143
+ previous = f"preview/assets/{task.id}/v{version - 1}"
144
+ reprocess = plan.recolor or task.id in plan.reprocess_targets
145
+ if reprocess:
146
+ raw = ctx.data(previous + "/raw.png")
147
+ ctx.save(prefix + "/raw.png", raw, mime="image/png")
148
+ ctx.save(
149
+ prefix + "/request.json", {"operation": "reprocess", "source": previous + "/raw.png"}
150
+ )
151
+ else:
152
+ refs = []
153
+ if version > 1:
154
+ refs.append(previous + "/sprite.png")
155
+ if "preview/reference.json" in ctx.artifacts:
156
+ refs.append(ctx.read("preview/reference.json")["artifact"])
157
+ prompt = ctx.prompt(task, plan.instructions.get(task.id, ""))
158
+ prompt += (
159
+ "\nGATE 2 NATIVE GRID: deliver ONE asset only, not a scene or sprite sheet. "
160
+ "Use a uniform square logical pixel grid with crisp flat color clusters and no subpixel detail. "
161
+ "For characters: 48x48 logical canvas, full subject 32-40 pixels tall, generous flat magenta margin, "
162
+ "keep eyes and silhouette readable at 1x. For props and key: 16x16 logical canvas on flat magenta. "
163
+ "For tiles: fill the entire square with an opaque seamless 16x16 material, no margin or background, "
164
+ "low contrast floor detail. No letters or HUD. Use the reference for STYLE ONLY, draw only the requested object. "
165
+ "Camera must be " + ctx.brief.perspective + "."
166
+ )
167
+ raw = ctx.image(prefix, prompt, list(dict.fromkeys(refs)))
168
+ image, failures, report = process(raw, task, plan.style, scale_mode="native")
169
+ repaired = False
170
+ if failures and task.spec.type == "tile":
171
+ image = deterministic_repair(image, task, plan.style)
172
+ failures = validate(image, pixelspec(task, plan.style), plan.style)
173
+ repaired = True
174
+ # Report rendered, logical height rather than source-model pixels or canvas height.
175
+ bbox = image.getbbox()
176
+ height = bbox[3] - bbox[1] if bbox else 0
177
+ if task.id == "hero" and height < 24:
178
+ report.warnings.append(
179
+ f"Hero logical pixel height is {height}; below the 24-pixel readability threshold"
180
+ )
181
+ ctx.save(prefix + "/sprite.png", png(image), mime="image/png")
182
+ ctx.save(
183
+ prefix + "/readability-4x.png",
184
+ png(image.resize((image.width * 4, image.height * 4), Image.Resampling.NEAREST)),
185
+ mime="image/png",
186
+ )
187
+ ctx.save(
188
+ prefix + "/validation.json",
189
+ {
190
+ "failures": [f.model_dump() for f in failures],
191
+ "processing": report.model_dump(),
192
+ "logical_height": height,
193
+ "native_grid_requested": True,
194
+ },
195
+ )
196
+ record = AssetRecord(
197
+ id=task.id,
198
+ version=version,
199
+ type=task.spec.type,
200
+ parent=task.spec.id,
201
+ state="idle",
202
+ index=0,
203
+ artifact=prefix + "/sprite.png",
204
+ status="placeholder" if failures else "accepted",
205
+ attempts=0 if reprocess else 1,
206
+ deterministic_fix=repaired,
207
+ scores=None,
208
+ issues=[f.message for f in failures],
209
+ provenance=prefix + "/validation.json",
210
+ )
211
+ ctx.save(prefix + "/record.json", record.model_dump())
212
+ return record
@@ -0,0 +1,167 @@
1
+ """Gate 2 contracts. Layouts refer only to the building blocks in this run."""
2
+
3
+ from typing import Literal
4
+
5
+ from pydantic import Field, field_validator, model_validator
6
+
7
+ from spriteforge.agents.models import Contract
8
+ from spriteforge.pixel.schemas import Style
9
+
10
+ from .asset_models import AssetSpec, Manifest, Size
11
+
12
+
13
+ class Placement(Contract):
14
+ asset: str
15
+ x: int = Field(ge=0, lt=320)
16
+ y: int = Field(ge=0, lt=180)
17
+
18
+
19
+ class HUD(Contract):
20
+ hearts: int = Field(ge=1, le=5)
21
+ pickup_count: int = Field(ge=0, le=99)
22
+ weapon: str = Field(min_length=1, max_length=16, pattern=r"^[A-Za-z0-9 -]+$")
23
+
24
+
25
+ class RoomLayout(Contract):
26
+ perspective: Literal["top-down", "side-scroll", "isometric"]
27
+ environment: str
28
+ width: Literal[20]
29
+ height: Literal[11]
30
+ tile_size: Literal[16]
31
+ tiles: list[list[str]] = Field(min_length=11, max_length=11)
32
+ entities: list[Placement] = Field(min_length=6, max_length=20)
33
+ hud: HUD
34
+
35
+ @model_validator(mode="after")
36
+ def grid(self):
37
+ if any(len(row) != 20 for row in self.tiles):
38
+ raise ValueError("Room must have exactly 20 columns and 11 rows")
39
+ return self
40
+
41
+ def validate_for(self, brief, manifest):
42
+ if self.perspective != brief.perspective or self.environment != brief.environment:
43
+ raise ValueError("Layout must preserve the brief's perspective and environment exactly")
44
+ specs = {s.id: s for s in manifest.assets}
45
+ tile_ids = {s.id for s in manifest.assets if s.type == "tile"}
46
+ if any(cell not in tile_ids | {"empty"} for row in self.tiles for cell in row):
47
+ raise ValueError("Layout references an unknown tile")
48
+ if tile_ids - {cell for row in self.tiles for cell in row}:
49
+ raise ValueError(
50
+ "Layout must show every floor and wall variant, with walls representing the environment"
51
+ )
52
+ required = set(specs) - tile_ids
53
+ if {e.asset for e in self.entities} != required:
54
+ raise ValueError("Room must display every character, prop and pickup")
55
+ if sum(e.asset == "hero" for e in self.entities) != 1:
56
+ raise ValueError("Room needs exactly one hero")
57
+ for entity in self.entities:
58
+ width, height = specs[entity.asset].size
59
+ if not width // 2 <= entity.x <= 320 - width // 2 or not height + 16 <= entity.y <= 176:
60
+ raise ValueError("Entity canvas overlaps the HUD or leaves the screen")
61
+ if self.perspective == "top-down" and self.tiles[(entity.y - 1) // 16][
62
+ entity.x // 16
63
+ ].startswith("wall"):
64
+ raise ValueError("Entity feet must not be inside a wall")
65
+ return self
66
+
67
+
68
+ class PreviewPlan(Contract):
69
+ version: int = Field(ge=1)
70
+ versions: dict[str, int]
71
+ instructions: dict[str, str]
72
+ style: Style
73
+ layout_instruction: str = ""
74
+ recolor: bool = False
75
+ reprocess_targets: list[str] = Field(default_factory=list)
76
+ canvas_overrides: dict[str, Size] = Field(default_factory=dict)
77
+
78
+
79
+ class PreviewChange(Contract):
80
+ targets: list[str] = Field(min_length=1, max_length=14)
81
+ instruction: str = Field(min_length=1)
82
+ palette: list[str] = Field(max_length=16)
83
+
84
+ @field_validator("palette")
85
+ @classmethod
86
+ def colors(cls, value):
87
+ return Style(palette=value).palette if value else []
88
+
89
+
90
+ class BlockDescription(Contract):
91
+ id: str
92
+ description: str = Field(min_length=1, max_length=1000)
93
+
94
+
95
+ class BlockDescriptions(Contract):
96
+ assets: list[BlockDescription] = Field(min_length=12, max_length=12)
97
+
98
+
99
+ def block_manifest(brief, descriptions=None):
100
+ """Fixed bounded scope; the designer supplies brief-specific descriptions."""
101
+ blocks = [
102
+ ("hero", "character", brief.character),
103
+ ("enemy_1", "character", "First distinct enemy"),
104
+ ("enemy_2", "character", "Second distinct enemy"),
105
+ *[
106
+ (f"floor_{i}", "tile", f"Subtle seamless floor material variation {i}")
107
+ for i in range(1, 4)
108
+ ],
109
+ *[(f"wall_{i}", "tile", f"Seamless wall material variation {i}") for i in range(1, 4)],
110
+ ("prop_1", "item", "Environment prop, a small obstacle"),
111
+ ("prop_2", "item", "Environment prop, a landmark"),
112
+ ("pickup", "item", "A bright readable key pickup"),
113
+ ]
114
+ chosen = {a.id: a.description for a in descriptions.assets} if descriptions else {}
115
+ if descriptions and (set(chosen) != {b[0] for b in blocks} or len(chosen) != 12):
116
+ raise ValueError("Designer must describe exactly the requested 12 building blocks")
117
+ return Manifest(
118
+ assets=[
119
+ AssetSpec(
120
+ id=ident,
121
+ type=kind,
122
+ size=(48, 48) if kind == "character" else (16, 16),
123
+ frames={"idle": 1},
124
+ desc=chosen.get(ident, desc) + "; " + brief.environment,
125
+ depends_on=[],
126
+ refs=["anchor"],
127
+ )
128
+ for ident, kind, desc in blocks
129
+ ]
130
+ )
131
+
132
+
133
+ def example_layout(brief):
134
+ side = brief.perspective == "side-scroll"
135
+ tiles = [
136
+ [
137
+ (
138
+ "wall_" + str(1 + x % 3)
139
+ if (y == 10 if side else x in (0, 19) or y in (0, 10))
140
+ else "empty"
141
+ if side and y < 9
142
+ else "floor_" + str(1 + (x + y) % 3)
143
+ )
144
+ for x in range(20)
145
+ ]
146
+ for y in range(11)
147
+ ]
148
+ positions = (
149
+ [(80, 144), (176, 144), (256, 144), (40, 144), (216, 144), (128, 128)]
150
+ if side
151
+ else [(112, 112), (224, 96), (208, 144), (56, 96), (264, 128), (144, 144)]
152
+ )
153
+ return RoomLayout(
154
+ perspective=brief.perspective,
155
+ environment=brief.environment,
156
+ width=20,
157
+ height=11,
158
+ tile_size=16,
159
+ tiles=tiles,
160
+ entities=[
161
+ Placement(asset=a, x=x, y=y)
162
+ for a, (x, y) in zip(
163
+ ["hero", "enemy_1", "enemy_2", "prop_1", "prop_2", "pickup"], positions, strict=True
164
+ )
165
+ ],
166
+ hud=HUD(hearts=3, pickup_count=0, weapon="SWORD"),
167
+ )
@@ -0,0 +1,169 @@
1
+ """Export the real atlas/layout and capture Phaser at device scale 1 via Playwright."""
2
+
3
+ import io
4
+ from functools import partial
5
+ from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
6
+ from pathlib import Path
7
+ from tempfile import TemporaryDirectory
8
+ from threading import Thread
9
+
10
+ from PIL import Image, ImageColor
11
+ from playwright.sync_api import sync_playwright
12
+
13
+ from spriteforge.game.record import wait_until
14
+ from spriteforge.pixel.atlas import pack
15
+
16
+ from .concept import png
17
+ from .preview_assets import asset_record
18
+
19
+ TEMPLATE = Path(__file__).parents[1] / "templates" / "phaser"
20
+
21
+
22
+ def hud_text_color(palette):
23
+ return max(
24
+ palette,
25
+ key=lambda c: sum(
26
+ w * v for w, v in zip((0.2126, 0.7152, 0.0722), ImageColor.getrgb(c), strict=True)
27
+ ),
28
+ )
29
+
30
+
31
+ class QuietHandler(SimpleHTTPRequestHandler):
32
+ def log_message(self, *args):
33
+ pass
34
+
35
+
36
+ def capture(directory):
37
+ return capture_scene(directory)[0]
38
+
39
+
40
+ def capture_scene(directory):
41
+ server = ThreadingHTTPServer(
42
+ ("127.0.0.1", 0), partial(QuietHandler, directory=str(directory.parent))
43
+ )
44
+ thread = Thread(target=server.serve_forever, daemon=True)
45
+ thread.start()
46
+ try:
47
+ with sync_playwright() as pw:
48
+ browser = pw.chromium.launch(headless=True)
49
+ try:
50
+ page = browser.new_page(
51
+ viewport={"width": 320, "height": 180}, device_scale_factor=1
52
+ )
53
+ errors = []
54
+ # Expose the Game instance in historical snapshots without changing drawing.
55
+ html = (directory / "index.html").read_text(encoding="utf-8")
56
+ if "window.previewGame=" not in html:
57
+ html = html.replace("new Phaser.Game(", "window.previewGame=new Phaser.Game(")
58
+ page.route(
59
+ "**/index.html",
60
+ lambda route: route.fulfill(body=html, content_type="text/html"),
61
+ )
62
+ page.on("pageerror", lambda error: errors.append(str(error)))
63
+ page.goto(f"http://127.0.0.1:{server.server_port}/{directory.name}/index.html")
64
+ if not wait_until(page, "window.previewReady === true"):
65
+ raise RuntimeError("Phaser preview never became ready")
66
+ errors += page.evaluate("window.previewErrors")
67
+ if errors:
68
+ raise RuntimeError("Phaser preview failed: " + "; ".join(errors))
69
+ if page.evaluate("Phaser.VERSION") != "3.90.0":
70
+ raise RuntimeError("Unexpected Phaser runtime version")
71
+ audit = page.evaluate((TEMPLATE / "audit.js").read_text(encoding="utf-8"))
72
+ return page.locator("canvas").screenshot(), audit
73
+ finally:
74
+ browser.close()
75
+ finally:
76
+ server.shutdown()
77
+ server.server_close()
78
+ thread.join(timeout=5)
79
+
80
+
81
+ def render_preview(ctx, plan, layout):
82
+ prefix = f"preview/v{plan.version}"
83
+ names = [prefix + "/gameplay-4x.png", prefix + "/readability.json"]
84
+ if all(n in ctx.artifacts for n in names):
85
+ return names
86
+ records = [asset_record(ctx, ident, version) for ident, version in plan.versions.items()]
87
+ sprites = {r.id: Image.open(io.BytesIO(ctx.data(r.artifact))).convert("RGBA") for r in records}
88
+ with TemporaryDirectory() as temp:
89
+ pack(sprites, Path(temp))
90
+ for filename in ("atlas.png", "atlas.json"):
91
+ ctx.save(
92
+ prefix + "/" + filename,
93
+ (Path(temp) / filename).read_bytes(),
94
+ "Programmer",
95
+ "image/png" if filename.endswith("png") else "application/json",
96
+ )
97
+ for filename, source in [
98
+ ("phaser.min.js", "vendor/phaser.min.js"),
99
+ ("room.js", "room.js"),
100
+ ("font.xml", "font.xml"),
101
+ ("LICENSE.md", "vendor/LICENSE.md"),
102
+ ]:
103
+ ctx.save(
104
+ prefix + "/runtime/" + filename,
105
+ (TEMPLATE / source).read_bytes(),
106
+ "Programmer",
107
+ "text/plain",
108
+ )
109
+ ctx.save(
110
+ prefix + "/index.html", (TEMPLATE / "preview.html").read_bytes(), "Programmer", "text/html"
111
+ )
112
+ ctx.save(prefix + "/style.json", plan.style.model_dump(), "Art Director")
113
+ font = Image.open(TEMPLATE / "font.png").convert("RGBA")
114
+ text_color = hud_text_color(plan.style.palette)
115
+ tinted = Image.new("RGBA", font.size, ImageColor.getrgb(text_color))
116
+ tinted.putalpha(font.getchannel("A"))
117
+ ctx.save(prefix + "/font.png", png(tinted), "Programmer", "image/png")
118
+ raw, audit = capture_scene(ctx.root / prefix)
119
+ ctx.save(prefix + "/render-audit.json", audit, "QA Playtester")
120
+ native = Image.open(io.BytesIO(raw)).convert("RGB")
121
+ if native.size != (320, 180):
122
+ raise ValueError("Phaser screenshot must be exactly 320x180")
123
+ ctx.save(prefix + "/gameplay.png", raw, "Programmer", "image/png")
124
+ ctx.save(
125
+ prefix + "/gameplay-4x.png",
126
+ png(native.resize((1280, 720), Image.Resampling.NEAREST)),
127
+ "Programmer",
128
+ "image/png",
129
+ )
130
+ colors = {
131
+ "#" + "".join(f"{c:02X}" for c in pixel[:3])
132
+ for sprite in sprites.values()
133
+ for pixel in sprite.getdata()
134
+ if pixel[3]
135
+ }
136
+ colors.update(
137
+ [plan.style.palette[0], plan.style.palette[1], plan.style.palette[-1], text_color]
138
+ )
139
+ palette = [c for c in plan.style.palette if c in colors]
140
+ checks = {r.id: ctx.read(r.provenance) for r in records}
141
+ ctx.save(
142
+ prefix + "/readability.json",
143
+ {
144
+ "version": plan.version,
145
+ "hero_logical_height": checks["hero"]["logical_height"],
146
+ "hero_on_screen_height": audit["hero"]["on_screen_height"],
147
+ "palette_size": len(palette),
148
+ "palette": palette,
149
+ "warnings": [
150
+ f"{ident}: {warning}"
151
+ for ident, check in checks.items()
152
+ for warning in check["processing"]["warnings"]
153
+ ],
154
+ "assets": {
155
+ r.id: {
156
+ "version": r.version,
157
+ "status": r.status,
158
+ "failures": checks[r.id]["failures"],
159
+ }
160
+ for r in records
161
+ },
162
+ "screen": [320, 180],
163
+ "scale": 4,
164
+ "renderer": "Phaser 3.90.0 / Canvas",
165
+ },
166
+ "QA Playtester",
167
+ )
168
+ ctx.save(prefix + "/registry.json", {r.id: r.model_dump() for r in records}, "Director")
169
+ return names
@@ -0,0 +1,61 @@
1
+ """Repair a defective unapproved draft without repainting or altering its history."""
2
+
3
+ from spriteforge.core.gates import Gates
4
+ from spriteforge.memory.okf.git import write_lock
5
+
6
+ from .preview_assets import PreviewContext
7
+ from .preview_models import PreviewPlan
8
+
9
+
10
+ def reprocess_draft(
11
+ store,
12
+ run_id,
13
+ targets,
14
+ reason,
15
+ layout_instruction="",
16
+ *,
17
+ generate_targets=(),
18
+ canvas_overrides=None,
19
+ ):
20
+ with write_lock(store.path.parent / f".{run_id}.runtime.lock"):
21
+ ctx = PreviewContext(store, run_id)
22
+ gate = Gates(store).pending(run_id)
23
+ if not gate or gate.stage != "gameplay":
24
+ raise ValueError("Repairs require an unapproved gameplay review")
25
+ report = next(
26
+ a
27
+ for a in ctx.artifacts.values()
28
+ if a.id in gate.artifacts_to_show and a.name.endswith("/readability.json")
29
+ )
30
+ previous = ctx.read(report.name)["version"]
31
+ plan = PreviewPlan.model_validate(ctx.read(f"preview/v{previous}/plan.json"))
32
+ targets = list(dict.fromkeys([*targets, *generate_targets]))
33
+ if set(targets) - plan.versions.keys():
34
+ raise ValueError("Repair targets must name existing assets")
35
+ if generate_targets and not reason.startswith("User requested"):
36
+ raise ValueError(
37
+ "New generation during draft repair requires a user-requested revision"
38
+ )
39
+ plan.version += 1
40
+ plan.recolor = False
41
+ plan.reprocess_targets = [ident for ident in targets if ident not in generate_targets]
42
+ plan.canvas_overrides.update(canvas_overrides or {})
43
+ plan.instructions = {ident: reason for ident in targets}
44
+ plan.layout_instruction = layout_instruction
45
+ for ident in targets:
46
+ plan.versions[ident] += 1
47
+ ctx.save(f"preview/v{plan.version}/plan.json", plan.model_dump(), "QA Playtester")
48
+ ctx.save(
49
+ f"preview/v{plan.version}/repair.json",
50
+ {
51
+ "reason": reason,
52
+ "targets": targets,
53
+ "previous_gate": gate.id,
54
+ "operation": "user-requested targeted revision"
55
+ if generate_targets
56
+ else "reprocess saved source; no image calls",
57
+ "generate_targets": list(generate_targets),
58
+ },
59
+ "QA Playtester",
60
+ )
61
+ Gates(store).supersede_preview(run_id, gate.id, reason)