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,169 @@
1
+ """Targeted, confirmed changes and validated Level/Tile Designer layouts."""
2
+
3
+ import re
4
+
5
+ from pydantic import model_validator
6
+
7
+ from spriteforge.agents.models import ChangeRequest, Changes
8
+ from spriteforge.core.gates import Gates, new_gate
9
+ from spriteforge.pixel.schemas import Style
10
+
11
+ from .preview_models import PreviewChange, RoomLayout, example_layout
12
+
13
+
14
+ def validate_change(change, manifest):
15
+ known = {a.id for a in manifest.assets} | {"layout", "palette"}
16
+ if set(change.targets) - known:
17
+ raise ValueError("Change targets must name existing assets, layout or palette")
18
+ if "palette" in change.targets and set(change.targets) != {"palette"}:
19
+ raise ValueError("Request palette changes separately from asset or layout changes")
20
+ if ("palette" in change.targets) != bool(change.palette):
21
+ raise ValueError("Palette changes need 4-16 explicit palette colors")
22
+ if change.palette and not 4 <= len(change.palette) <= 16:
23
+ raise ValueError("Palette changes need 4-16 explicit palette colors")
24
+ return change
25
+
26
+
27
+ def request_change(ctx, gate, manifest, plan):
28
+ prefix = f"preview/changes/{gate.id}"
29
+ known = [a.id for a in manifest.assets]
30
+ target_text = gate.response.form.get("targets", "").strip()
31
+ palette_text = gate.response.form.get("palette", "").strip()
32
+ targets = [s.strip() for s in target_text.split(",") if s.strip()]
33
+ colors = [s.strip() for s in palette_text.split(",") if s.strip()]
34
+ if targets:
35
+ change = validate_change(
36
+ PreviewChange(targets=targets, instruction=gate.response.text, palette=colors), manifest
37
+ )
38
+ ctx.save(prefix + ".json", change.model_dump(), "Director")
39
+ else:
40
+ text = gate.response.text.lower()
41
+ guessed = [ident for ident in known if re.search(r"\b" + re.escape(ident) + r"\b", text)]
42
+ if not guessed:
43
+ guessed = ["palette"] if colors else ["layout"]
44
+ fallback = PreviewChange(targets=guessed, instruction=gate.response.text, palette=colors)
45
+
46
+ class ValidChange(PreviewChange):
47
+ @model_validator(mode="after")
48
+ def known_targets(self):
49
+ return validate_change(self, manifest)
50
+
51
+ change = ctx.ask(
52
+ prefix + ".json",
53
+ "Director",
54
+ "Interpret this preview feedback as minimal targeted changes. Assets: "
55
+ + ", ".join(known)
56
+ + ". 'hero rounder' targets ONLY hero; 'add more walls' targets layout. Palette changes target ONLY palette "
57
+ "and require a complete 4-16 hex-color palette. Asset and layout requests have an empty palette array. "
58
+ "Do not regenerate unaffected assets. Current palette: "
59
+ + str(plan.style.palette)
60
+ + ". Feedback: "
61
+ + gate.response.text,
62
+ ValidChange,
63
+ fallback,
64
+ )
65
+ changes = Changes(
66
+ requests=[
67
+ ChangeRequest(
68
+ target="style"
69
+ if target == "palette"
70
+ else "level"
71
+ if target == "layout"
72
+ else [target],
73
+ instruction=change.instruction,
74
+ severity="minor",
75
+ scope="Reprocess existing sources without image calls"
76
+ if target == "palette"
77
+ else "Change the room layout without image calls"
78
+ if target == "layout"
79
+ else "Regenerate only " + target,
80
+ needs_regen=target not in {"layout", "palette"},
81
+ )
82
+ for target in change.targets
83
+ ]
84
+ )
85
+ ctx.save(prefix + "-requests.json", changes.model_dump(), "Director")
86
+ Gates(ctx.store).open(
87
+ ctx.run_id,
88
+ new_gate(
89
+ "preview_revise",
90
+ "Confirm gameplay preview changes",
91
+ [ctx.artifacts[prefix + "-requests.json"].id, ctx.artifacts[prefix + ".json"].id],
92
+ kind="confirm_changes",
93
+ parent_id=gate.id,
94
+ changes=changes,
95
+ ),
96
+ )
97
+
98
+
99
+ def revised_plan(ctx, previous, gate):
100
+ change = PreviewChange.model_validate(ctx.read(f"preview/changes/{gate.parent_id}.json"))
101
+ plan = previous.model_copy(deep=True)
102
+ plan.version += 1
103
+ plan.instructions, plan.layout_instruction = {}, ""
104
+ plan.reprocess_targets = []
105
+ plan.recolor = "palette" in change.targets
106
+ if plan.recolor:
107
+ plan.style = Style(palette=change.palette, max_colors=len(change.palette))
108
+ for ident in plan.versions:
109
+ plan.versions[ident] += 1
110
+ plan.instructions[ident] = change.instruction
111
+ else:
112
+ for target in change.targets:
113
+ if target == "layout":
114
+ plan.layout_instruction = change.instruction
115
+ else:
116
+ plan.versions[target] += 1
117
+ plan.instructions[target] = change.instruction
118
+ return plan
119
+
120
+
121
+ def room_layout(ctx, manifest, plan):
122
+ name = f"preview/v{plan.version}/layout.json"
123
+ if name in ctx.artifacts:
124
+ return RoomLayout.model_validate(ctx.read(name)).validate_for(ctx.brief, manifest)
125
+ previous = f"preview/v{plan.version - 1}/layout.json"
126
+ if plan.version > 1 and not plan.layout_instruction:
127
+ layout = RoomLayout.model_validate(ctx.read(previous)).validate_for(ctx.brief, manifest)
128
+ ctx.save(name, layout.model_dump(), "Level/Tile Designer")
129
+ return layout
130
+
131
+ class ValidRoom(RoomLayout):
132
+ @model_validator(mode="after")
133
+ def brief_and_assets(self):
134
+ return self.validate_for(ctx.brief, manifest)
135
+
136
+ fallback = example_layout(ctx.brief)
137
+ if plan.layout_instruction and ctx.run.config["mock"]:
138
+ fallback = RoomLayout.model_validate(ctx.read(previous))
139
+ fallback.tiles[3][5] = "wall_2"
140
+ return ctx.ask(
141
+ name,
142
+ "Level/Tile Designer",
143
+ "Design a readable room using only these assets: "
144
+ + manifest.model_dump_json()
145
+ + ". Return a 20x11 grid of 16x16 tile IDs (or 'empty'), for a 320x180 screen. "
146
+ "Use the exact brief perspective and environment strings. Entity x,y are SCREEN PIXELS, center-bottom "
147
+ "of the full sprite canvas. Character canvases are 48x48; use the manifest dimensions for props and pickup. Keep full entities below the "
148
+ "16-pixel top HUD and inside the screen: character x=24..296,y=64..176. "
149
+ "Exactly one hero; display both enemies, both props, and key. Space characters apart. "
150
+ "Use EVERY floor and wall tile variant at least once. Make the environment visible with tile-built "
151
+ "structures, not an empty backdrop: for a city, arrange wall tiles into broken building facades "
152
+ "with varied heights and gaps, behind the actors. The walls may be scenery in side-scroll views. "
153
+ "Top-down: leave floor beneath entity feet, make connected traversable floor and walls. "
154
+ "Side-scroll: empty sky, floor/platform tiles BELOW standing characters, not a top-down room. "
155
+ "Isometric: grid projected with screen x=88+(column-row)*8,y=36+(column+row)*4; "
156
+ "place entities on that diamond. HUD hearts, key counter and short ASCII weapon label. "
157
+ "Brief: "
158
+ + ctx.brief.model_dump_json()
159
+ + (
160
+ "\nPrevious room: "
161
+ + str(ctx.read(previous))
162
+ + "\nRequested change: "
163
+ + plan.layout_instruction
164
+ if plan.layout_instruction
165
+ else ""
166
+ ),
167
+ ValidRoom,
168
+ fallback,
169
+ )
@@ -0,0 +1,170 @@
1
+ """G3 asset production: one checkpointed task per step, explicit targeted revisions."""
2
+
3
+ import json
4
+
5
+ from spriteforge.agents.models import ChangeRequest, Changes
6
+ from spriteforge.core.cost import BudgetExceeded
7
+ from spriteforge.core.gates import Gates, new_gate
8
+ from spriteforge.providers.http import ProviderError
9
+
10
+ from .asset_context import ProductionContext, make_manifest
11
+ from .asset_models import Manifest, ProductionPlan, dependents
12
+ from .asset_render import generate_task
13
+ from .asset_review import review_set
14
+ from .asset_store import ProductionStore
15
+
16
+
17
+ def enable_production(store, run_id):
18
+ """Opt in to G3 without changing any prior gate answer or approved art."""
19
+ run = store.get_run(run_id)
20
+ if run.config.get("workflow") != "intake-concept-v1":
21
+ raise ValueError("Asset production requires an intake/concept run")
22
+ if run.status in {"aborted", "budget_exhausted"}:
23
+ raise ValueError("This run cannot start production")
24
+ if run.config.get("asset_production") and run.status != "completed":
25
+ return
26
+ names = {a.name for a in store.artifacts(run_id)}
27
+ if (
28
+ run.status == "completed"
29
+ and not {"brief.json", "style.json", "anchor.png", "approval.json"} <= names
30
+ ):
31
+ raise ValueError("Production needs an approved G2 style and anchor")
32
+ config = {
33
+ **run.config,
34
+ "asset_production": True,
35
+ "preview_production_enabled": run.config.get("gameplay_preview", False),
36
+ }
37
+ with store.connect() as db:
38
+ db.execute(
39
+ "UPDATE runs SET config=?,status=? WHERE id=?",
40
+ (json.dumps(config), "running" if run.status == "completed" else run.status, run_id),
41
+ )
42
+ store._event(db, run_id, "Human", "production.enabled", {})
43
+
44
+
45
+ def selected_targets(store, run_id, feedback):
46
+ ctx = ProductionStore(store, run_id)
47
+ manifest = Manifest.model_validate(ctx.read("production/manifest.json"))
48
+ value = feedback.form.get("targets", "")
49
+ if not isinstance(value, str):
50
+ raise ValueError("Asset targets must be comma-separated ids") # noqa: TRY004 -- UI validation
51
+ selected = {s.strip() for s in value.split(",") if s.strip()}
52
+ return selected, dependents(manifest.tasks(), selected)
53
+
54
+
55
+ def production_step(store, run_id):
56
+ ctx = ProductionContext(store, run_id)
57
+ try:
58
+ return _step(ctx)
59
+ except BudgetExceeded as exc:
60
+ message = f"Asset production stopped: {exc}. Accepted assets and attempts are saved; no more provider calls will be made."
61
+ with store.connect() as db:
62
+ db.execute("UPDATE runs SET status='budget_exhausted' WHERE id=?", (run_id,))
63
+ store._event(
64
+ db, run_id, "Director", "production.budget_exhausted", {"message": message}
65
+ )
66
+ return False
67
+ except ProviderError as exc:
68
+ ctx.store.fail(
69
+ run_id,
70
+ "Asset production paused after a provider failure; resume to retry the same attempt. "
71
+ + str(exc),
72
+ )
73
+ return False
74
+
75
+
76
+ def _step(ctx):
77
+ ctx.restore_files()
78
+ gates = Gates(ctx.store)
79
+ history = gates.all(ctx.run_id)
80
+ last = history[-1]
81
+ manifest = make_manifest(ctx)
82
+ tasks = manifest.tasks()
83
+ if last.stage == "assets" and last.status == "approved":
84
+ ctx.save(
85
+ "production/approval.json",
86
+ {"gate": last.id, "assets": {k: r.version for k, r in ctx.records().items()}},
87
+ "Director",
88
+ )
89
+ ctx.store.advance(ctx.run_id, ctx.run.cursor, "G3 approved; assets locked", final=True)
90
+ return False
91
+ if last.stage == "assets" and last.status == "changes_requested":
92
+ selected, affected = selected_targets(ctx.store, ctx.run_id, last.response)
93
+ changes = Changes(
94
+ requests=[
95
+ ChangeRequest(
96
+ target=sorted(affected),
97
+ instruction=last.response.text,
98
+ severity="minor",
99
+ scope="Selected: "
100
+ + ", ".join(sorted(selected))
101
+ + ". Regenerate these assets and their dependent frames/references: "
102
+ + ", ".join(sorted(affected)),
103
+ needs_regen=True,
104
+ )
105
+ ]
106
+ )
107
+ name = f"production/changes/{last.id}.json"
108
+ ctx.save(name, changes.model_dump(), "Director")
109
+ gates.open(
110
+ ctx.run_id,
111
+ new_gate(
112
+ "asset_revise",
113
+ "Confirm asset changes and dependent frames",
114
+ [ctx.artifacts[name].id],
115
+ kind="confirm_changes",
116
+ parent_id=last.id,
117
+ changes=changes,
118
+ ),
119
+ )
120
+ return False
121
+ confirmations = [g for g in history if g.stage == "asset_revise" and g.status == "approved"]
122
+ cycle = len(confirmations)
123
+ plan_name = f"production/cycles/{cycle}/plan.json"
124
+ if plan_name in ctx.artifacts:
125
+ plan = ProductionPlan.model_validate(ctx.read(plan_name))
126
+ elif cycle:
127
+ previous = ProductionPlan.model_validate(
128
+ ctx.read(f"production/cycles/{cycle - 1}/plan.json")
129
+ )
130
+ plan = ProductionPlan(versions=dict(previous.versions), instructions={})
131
+ for change in confirmations[-1].changes.requests:
132
+ if not isinstance(change.target, list):
133
+ raise ValueError("G3 revisions must name specific asset ids") # noqa: TRY004
134
+ for target in change.target:
135
+ plan.versions[target] += 1
136
+ plan.instructions[target] = change.instruction
137
+ ctx.save(plan_name, plan.model_dump(), "Director")
138
+ else:
139
+ records = ctx.records()
140
+ plan = ProductionPlan(
141
+ versions={t.id: records[t.id].version if t.id in records else 1 for t in tasks},
142
+ instructions={},
143
+ )
144
+ ctx.save(plan_name, plan.model_dump(), "Director")
145
+ records = ctx.records()
146
+ for task in tasks:
147
+ if task.id not in records or records[task.id].version < plan.versions[task.id]:
148
+ generate_task(ctx, task, plan)
149
+ return True
150
+ names = review_set(ctx, manifest, cycle)
151
+ gates.open(
152
+ ctx.run_id,
153
+ new_gate(
154
+ "assets",
155
+ "G3 Asset contact sheet",
156
+ [ctx.artifacts[n].id for n in names],
157
+ form_schema={
158
+ "type": "object",
159
+ "properties": {
160
+ "targets": {
161
+ "type": "string",
162
+ "title": "Asset ids to change (comma-separated)",
163
+ "default": "",
164
+ "suggestions": [s.id for s in manifest.assets],
165
+ }
166
+ },
167
+ },
168
+ ),
169
+ )
170
+ return False
@@ -0,0 +1,105 @@
1
+ """Reference images the human gives the agents (docs/ui-plan.md, phase 4).
2
+
3
+ A reference belongs to one agent, or to every agent when it is added in the Director's chat. It
4
+ is stored as a locked artifact (`references/<n>-<name>.png`), only after the human confirms they
5
+ have the right to use it, and only when it is a real image within the size cap: code decodes it,
6
+ drops its metadata and scales it to at most `MAX_SIDE` pixels (fewer image tokens for Spark).
7
+
8
+ How the agents use it:
9
+ * Spark (vision): every Spark call of the agent carries its references (`Models.references`).
10
+ * Muse Image: the art agents' (Pixel Artist, Art Director) references steer the style of new and
11
+ redrawn art (`MuseOptions.style`). Accepted art stays locked: a reference changes a picture
12
+ only when a change asks for that picture.
13
+ """
14
+
15
+ import io
16
+ import re
17
+ from uuid import uuid4
18
+
19
+ from PIL import Image, UnidentifiedImageError
20
+
21
+ from spriteforge.core.state import Artifact, Store
22
+
23
+ MAX_BYTES = 8 * 1024 * 1024 # upload cap
24
+ MAX_PIXELS = 40_000_000 # a decompression bomb is refused before it is decoded
25
+ MAX_SIDE = 1024 # stored size: the longest side
26
+ PER_CALL = 3 # references sent with one call (the newest)
27
+ EVERYONE = "Director" # a reference added in the Director's chat is for every agent
28
+ ART = ("Pixel Artist", "Art Director") # their references steer Muse Image's style
29
+ MIMES = {"image/png", "image/jpeg", "image/webp", "image/gif"}
30
+
31
+
32
+ class ReferenceError(ValueError):
33
+ pass
34
+
35
+
36
+ def normalize(data: bytes) -> bytes:
37
+ """The upload as a clean PNG (no metadata), at most MAX_SIDE px; ReferenceError if it is
38
+ not an image or is too big."""
39
+ if len(data) > MAX_BYTES:
40
+ raise ReferenceError(f"The image is larger than {MAX_BYTES // (1024 * 1024)} MB")
41
+ try:
42
+ with Image.open(io.BytesIO(data)) as probe:
43
+ if probe.width * probe.height > MAX_PIXELS:
44
+ raise ReferenceError("The image has too many pixels")
45
+ image = probe.convert("RGBA")
46
+ except (UnidentifiedImageError, OSError) as exc:
47
+ raise ReferenceError("That file is not an image (PNG, JPEG, WebP or GIF)") from exc
48
+ image.thumbnail((MAX_SIDE, MAX_SIDE))
49
+ out = io.BytesIO()
50
+ image.save(out, "PNG")
51
+ return out.getvalue()
52
+
53
+
54
+ def slug(filename: str) -> str:
55
+ stem = re.sub(r"[^a-z0-9]+", "-", filename.rsplit(".", 1)[0].lower()).strip("-")
56
+ return stem[:40] or "reference"
57
+
58
+
59
+ def add_reference(store: Store, run_id: str, agent: str, filename: str, data: bytes,
60
+ rights: bool) -> dict: # fmt: skip
61
+ """Store an upload as a locked artifact for `agent` (the Director: every agent)."""
62
+ if not rights:
63
+ raise ReferenceError("Confirm that you have the right to use this image")
64
+ png = normalize(data)
65
+ n = len(references(store, run_id)) + 1
66
+ artifact = Artifact(id=uuid4().hex, run_id=run_id, name=f"references/{n}-{slug(filename)}.png",
67
+ mime="image/png", data=png) # fmt: skip
68
+ store.save_artifact(artifact, "Human", "artifact.created")
69
+ ref = {"id": artifact.id, "name": artifact.name, "file": filename[:120], "agent": agent,
70
+ "everyone": agent == EVERYONE} # fmt: skip
71
+ store.append_event(run_id, "Human", "reference.added", ref)
72
+ return ref
73
+
74
+
75
+ def references(store: Store, run_id: str) -> list[dict]:
76
+ return [e.payload for e in store.events(run_id) if e.type == "reference.added"]
77
+
78
+
79
+ def for_agent(refs: list[dict], agent: str) -> list[dict]:
80
+ """The references an agent uses: its own and every agent's, newest first."""
81
+ return [r for r in reversed(refs) if r["agent"] in (agent, EVERYONE)]
82
+
83
+
84
+ def images(store: Store, run_id: str, agents) -> dict[str, list[bytes]]:
85
+ """agent -> the PNGs of its newest references (at most PER_CALL)."""
86
+ refs = references(store, run_id)
87
+ if not refs:
88
+ return {}
89
+ with store.connect() as db:
90
+ data = {r[0]: r[1] for r in db.execute(
91
+ "SELECT id,data FROM artifacts WHERE run_id=? AND name GLOB 'references/*'", (run_id,))} # fmt: skip
92
+ out = {}
93
+ for agent in agents:
94
+ mine = [data[r["id"]] for r in for_agent(refs, agent) if r["id"] in data][:PER_CALL]
95
+ if mine:
96
+ out[agent] = mine
97
+ return out
98
+
99
+
100
+ def style(refs: dict[str, list[bytes]]) -> list[bytes]:
101
+ """The art agents' references for Muse Image (no duplicates, at most PER_CALL)."""
102
+ out = []
103
+ for agent in ART:
104
+ out += [r for r in refs.get(agent, []) if r not in out]
105
+ return out[:PER_CALL]
@@ -0,0 +1,128 @@
1
+ """Interrupt and rewind (docs/ui-plan.md, phase 3b).
2
+
3
+ When the human changes the work of an agent that is running or already finished while a round
4
+ of work is in progress (the first build, a G3 or G4/G5 change round), **Go back** stops the
5
+ round instead of spending tokens on work the change would throw away:
6
+
7
+ 1. `request_stop` records a stop request. `Budget.reserve`, the one place every model call
8
+ passes through, refuses to start any new call while it is set and raises `Cancelled`; calls
9
+ already in flight finish and are kept (Muse images land in the image cache, so asking for the
10
+ same picture again costs nothing).
11
+ 2. The worker catches `Cancelled` and calls `rewind`: the stopped round is recorded as
12
+ superseded (its artifacts stay, never deleted), the chat changes it had taken are queued
13
+ again, and the round starts over under a new round key (`gate-5.1`) with every queued change.
14
+ Its build gets a new number: the stopped one's is never reused, so nothing locked is touched.
15
+ 3. The revision flow redoes only what the changes are about (unchanged art stays locked and is
16
+ reused from the shown build, code is edited, not rewritten) and goes on to the next gate;
17
+ earlier gates are not reopened.
18
+
19
+ A round of the design gate (G2 changes) is one or two Spark calls: it is not stopped, and a
20
+ change asked meanwhile waits for the G2 card that follows.
21
+ """
22
+
23
+ import json
24
+
25
+ from spriteforge.core.gates import Gate, Gates
26
+ from spriteforge.core.state import Store
27
+
28
+ # Answered gates whose round of work can be stopped and redone.
29
+ REWINDABLE = {("design", "approved"), ("menus", "changes_requested"),
30
+ ("playtest", "changes_requested"), ("final", "changes_requested")} # fmt: skip
31
+
32
+
33
+ def current_round(store: Store, run_id: str) -> tuple[Gate, int] | None:
34
+ """The answered gate whose work is in progress and its number, when that work can be
35
+ stopped; None at an open gate or in a round that cannot be."""
36
+ gates = Gates(store)
37
+ history = gates.all(run_id)
38
+ if not history or gates.pending(run_id):
39
+ return None
40
+ last = history[-1]
41
+ if last.stage == "confirm": # the plan answered: the work is its G4/G5 gate's round
42
+ i = next(i for i, g in enumerate(history) if g.id == last.parent_id)
43
+ return history[i], i + 1
44
+ return (last, len(history)) if (last.stage, last.status) in REWINDABLE else None
45
+
46
+
47
+ def rewinds(store: Store, run_id: str, gate_id: str) -> int:
48
+ # A correction of the Director's plan (game_confirm.py) starts the round again as well.
49
+ return sum(1 for e in store.events(run_id)
50
+ if e.type in ("round.rewound", "round.replanned")
51
+ and e.payload.get("gate") == gate_id) # fmt: skip
52
+
53
+
54
+ def round_key(store: Store, run_id: str, gate: Gate, n: int) -> str:
55
+ """The key of gate n's round of work: "5", or "5.1" after one Go back. Every checkpoint of
56
+ the round (its revision, its chat changes, its build number) is named with it."""
57
+ k = rewinds(store, run_id, gate.id)
58
+ return f"{n}.{k}" if k else str(n)
59
+
60
+
61
+ def request_stop(store: Store, run_id: str, ids: list[int]) -> None:
62
+ store.append_event(run_id, "Human", "run.stop_requested", {"changes": ids})
63
+
64
+
65
+ def clear_stop(store: Store, run_id: str, why: str) -> None:
66
+ store.append_event(run_id, "Director", "run.stop_cleared", {"why": why})
67
+
68
+
69
+ def rewind(store: Store, run_id: str) -> str | None:
70
+ """After `Cancelled`: supersede the stopped round and start it again with every queued
71
+ change. Returns the new round key (None when no round could be redone: the step simply
72
+ starts again from its checkpoints and the changes stay queued)."""
73
+ found = current_round(store, run_id)
74
+ if found is None:
75
+ clear_stop(store, run_id, "nothing to go back to")
76
+ return None
77
+ gate, n = found
78
+ old = round_key(store, run_id, gate, n)
79
+ with store.connect() as db:
80
+ row = db.execute("SELECT data FROM artifacts WHERE run_id=? AND name=?",
81
+ (run_id, f"game/feedback/gate-{old}-build.json")).fetchone() # fmt: skip
82
+ build = json.loads(row[0])["version"] if row else None
83
+ # The chat changes the stopped round took: at its start (the first build's round takes them
84
+ # as "build-1") and late, just before its Programmer ran.
85
+ steps = {f"gate-{old}", f"build-{old}", f"code-v{build}"}
86
+ if gate.stage == "design" and "." not in old:
87
+ steps.add("build-1")
88
+ taken = [i for e in store.events(run_id) if e.type == "chat.applied"
89
+ and e.payload.get("where") in steps for i in e.payload.get("ids", [])] # fmt: skip
90
+ if taken:
91
+ store.append_event(run_id, "Director", "chat.unapplied", {"ids": taken, "where": old})
92
+ store.append_event(run_id, "Director", "round.superseded",
93
+ {"gate": gate.id, "round": old, "build": build}) # fmt: skip
94
+ new = f"{n}.{rewinds(store, run_id, gate.id) + 1}"
95
+ store.append_event(run_id, "Director", "round.rewound", {
96
+ "gate": gate.id, "from": old, "round": new, "build": build,
97
+ "message": (f"Went back: build v{build} was stopped" if build else "Went back")
98
+ + " to apply your changes"}) # fmt: skip
99
+ clear_stop(store, run_id, "rewound")
100
+ return new
101
+
102
+
103
+ # Taken just before the agent runs in a build (build_version), so a change for it asked while
104
+ # earlier agents of the round work needs no stop.
105
+ LATE = {"code_instructions"}
106
+
107
+
108
+ def round_info(store: Store, run_id: str) -> dict | None:
109
+ """The round of work in progress, for the Go back card: its gate, key, first event, the
110
+ build it makes and what it has cost so far. None when no round can be stopped."""
111
+ found = current_round(store, run_id)
112
+ if found is None:
113
+ return None
114
+ gate, n = found
115
+ key = round_key(store, run_id, gate, n)
116
+ start, cost = 0, 0.0
117
+ for e in store.events(run_id):
118
+ if e.payload.get("id" if e.type == "gate.responded" else "gate") == gate.id and e.type in (
119
+ "gate.responded", "round.rewound"
120
+ ):
121
+ start, cost = e.id, 0.0
122
+ elif e.type == "cost.succeeded" and e.id > start:
123
+ cost += e.payload["usage"].get("estimated_cost") or 0.0
124
+ with store.connect() as db:
125
+ row = db.execute("SELECT data FROM artifacts WHERE run_id=? AND name=?",
126
+ (run_id, f"game/feedback/gate-{key}-build.json")).fetchone() # fmt: skip
127
+ build = json.loads(row[0])["version"] if row else None
128
+ return {"gate": gate.id, "round": key, "start": start, "build": build, "cost": round(cost, 4)}