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,139 @@
1
+ """Pixel contracts shared by processing, checks, and saved palettes."""
2
+
3
+ from typing import Annotated, Literal
4
+
5
+ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
6
+
7
+ Dimension = Annotated[int, Field(ge=1, le=4096)]
8
+
9
+
10
+ def hex_color(value: str) -> str:
11
+ if (
12
+ len(value) != 7
13
+ or not value.startswith("#")
14
+ or any(c not in "0123456789abcdefABCDEF" for c in value[1:])
15
+ ):
16
+ raise ValueError("Colors must use #RRGGBB")
17
+ return value.upper()
18
+
19
+
20
+ class Schema(BaseModel):
21
+ model_config = ConfigDict(extra="forbid")
22
+
23
+
24
+ class Palette(Schema):
25
+ name: str = "custom"
26
+ colors: list[str] = Field(min_length=1, max_length=256)
27
+
28
+ @field_validator("colors")
29
+ @classmethod
30
+ def normalize(cls, colors):
31
+ return list(dict.fromkeys(hex_color(c) for c in colors))
32
+
33
+
34
+ class Style(Schema):
35
+ palette: list[str] = Field(min_length=1, max_length=256)
36
+ background: str = "#FF00FF"
37
+ chroma_tolerance: float = Field(default=45, ge=0, le=442)
38
+ alpha_threshold: int = Field(default=128, ge=1, le=255)
39
+ min_cluster_size: int = Field(default=2, ge=0)
40
+ outline: bool = False
41
+ outline_color: str | None = None
42
+ max_colors: int = Field(default=16, ge=1, le=256)
43
+ character_canvas: tuple[Dimension, Dimension] = (48, 48)
44
+ character_logical_limit: tuple[Dimension, Dimension] = (40, 40)
45
+ tile_canvas: tuple[Dimension, Dimension] = (16, 16)
46
+ outline_dark_lightness: float = Field(default=35, ge=0, le=100)
47
+ outline_dark_tolerance: float = Field(default=12, ge=0)
48
+
49
+ @field_validator("palette")
50
+ @classmethod
51
+ def normalize(cls, colors):
52
+ return list(dict.fromkeys(hex_color(c) for c in colors))
53
+
54
+ @field_validator("background", "outline_color")
55
+ @classmethod
56
+ def normalize_color(cls, color):
57
+ return hex_color(color) if color is not None else None
58
+
59
+ @model_validator(mode="after")
60
+ def outline_is_in_palette(self):
61
+ if self.outline_color and self.outline_color not in self.palette:
62
+ raise ValueError("outline_color must belong to the palette")
63
+ return self
64
+
65
+
66
+ class AssetSpec(Schema):
67
+ id: str = "sprite"
68
+ type: Literal["sprite", "character", "tile", "item", "ui"] = "sprite"
69
+ size: tuple[Dimension, Dimension] = (32, 32)
70
+ padding: int | None = Field(default=None, ge=0)
71
+ allow_edge_touch: bool | None = None
72
+ max_colors: int | None = Field(default=None, ge=1, le=256)
73
+ min_fill_ratio: float = Field(default=0.05, ge=0, le=1)
74
+ seam_threshold: float = Field(default=0.05, ge=0, le=1)
75
+
76
+ @model_validator(mode="before")
77
+ @classmethod
78
+ def canvas_defaults(cls, values):
79
+ if isinstance(values, dict) and "size" not in values:
80
+ if values.get("type") == "character":
81
+ return {**values, "size": (48, 48)}
82
+ if values.get("type") == "tile":
83
+ return {**values, "size": (16, 16)}
84
+ return values
85
+
86
+ @property
87
+ def margin(self) -> int:
88
+ return self.padding if self.padding is not None else (0 if self.type == "tile" else 1)
89
+
90
+ @property
91
+ def edges_allowed(self) -> bool:
92
+ return self.allow_edge_touch if self.allow_edge_touch is not None else self.type == "tile"
93
+
94
+ @model_validator(mode="after")
95
+ def usable_canvas(self):
96
+ if min(self.size) <= 2 * self.margin:
97
+ raise ValueError("padding leaves no usable canvas")
98
+ return self
99
+
100
+
101
+ class Failure(Schema):
102
+ code: str
103
+ message: str
104
+ fix_hint: str
105
+
106
+
107
+ class ProcessingOptions(Schema):
108
+ """Real-output cleanup; omitted options preserve the original low-level API behavior."""
109
+
110
+ background_tolerance: float = Field(default=18, ge=0, le=200)
111
+ despill_tolerance: float = Field(default=45, ge=0, le=200)
112
+ keep_detached: bool = False
113
+ detached_min_area_ratio: float = Field(default=0.02, ge=0, le=1)
114
+ detect_grid: bool = True
115
+ scale_mode: Literal["auto", "native", "fit"] = "auto"
116
+ baseline: Literal["bottom", "center"] = "center"
117
+ native_grid_confidence: float = Field(default=0.35, ge=0, le=1)
118
+
119
+
120
+ class DroppedComponent(Schema):
121
+ area: int
122
+ bbox: tuple[int, int, int, int]
123
+ area_ratio: float
124
+
125
+
126
+ class ProcessingReport(Schema):
127
+ background: str | None = None
128
+ dropped: list[DroppedComponent] = Field(default_factory=list)
129
+ grid_size: int | None = None
130
+ grid_offset: tuple[int, int] = (0, 0)
131
+ despilled_pixels: int = 0
132
+ grid_confidence: float = 0
133
+ logical_subject_size: tuple[int, int] | None = None
134
+ scale_mode: str = "fit"
135
+ scale_factor: float | None = None
136
+ palette_size: int = 0
137
+ palette_usage: dict[str, int] = Field(default_factory=dict)
138
+ tinted_dark_colors: list[str] = Field(default_factory=list)
139
+ warnings: list[str] = Field(default_factory=list)
@@ -0,0 +1,237 @@
1
+ """Source-image cleanup before final pixel sizing. No provider dependencies."""
2
+
3
+ import numpy as np
4
+ from PIL import Image
5
+
6
+ from .palette import rgb_to_lab
7
+ from .schemas import DroppedComponent, ProcessingOptions, ProcessingReport
8
+
9
+
10
+ def components(
11
+ mask: np.ndarray,
12
+ ) -> tuple[np.ndarray, list[tuple[int, int, tuple[int, int, int, int]]]]:
13
+ """4-connected components using scanline runs (avoids per-source-pixel Python objects)."""
14
+ labels = np.zeros(mask.shape, dtype=np.int32)
15
+ parents = [0]
16
+ records = []
17
+ previous = []
18
+
19
+ def root(i):
20
+ while parents[i] != i:
21
+ parents[i] = parents[parents[i]]
22
+ i = parents[i]
23
+ return i
24
+
25
+ for y, row in enumerate(mask):
26
+ changes = np.diff(np.pad(row.astype(np.int8), 1))
27
+ starts, ends = np.flatnonzero(changes == 1), np.flatnonzero(changes == -1)
28
+ current = []
29
+ before = 0
30
+ for left, right in zip(starts, ends, strict=True):
31
+ label = len(parents)
32
+ parents.append(label)
33
+ while before < len(previous) and previous[before][1] <= left:
34
+ before += 1
35
+ j = before
36
+ while j < len(previous) and previous[j][0] < right:
37
+ a, b = root(label), root(previous[j][2])
38
+ parents[max(a, b)] = min(a, b)
39
+ j += 1
40
+ labels[y, left:right] = label
41
+ current.append((int(left), int(right), label))
42
+ records.append((label, y, int(left), int(right)))
43
+ previous = current
44
+ lookup = np.array([root(i) for i in range(len(parents))], dtype=np.int32)
45
+ labels = lookup[labels]
46
+ groups = {}
47
+ for label, y, left, right in records:
48
+ ident = int(lookup[label])
49
+ if ident not in groups:
50
+ groups[ident] = [0, left, y, right, y + 1]
51
+ group = groups[ident]
52
+ group[0] += right - left
53
+ group[1:] = [
54
+ min(group[1], left),
55
+ min(group[2], y),
56
+ max(group[3], right),
57
+ max(group[4], y + 1),
58
+ ]
59
+ return labels, sorted(
60
+ [(ident, data[0], tuple(data[1:])) for ident, data in groups.items()],
61
+ key=lambda c: (-c[1], c[0]),
62
+ )
63
+
64
+
65
+ def estimate_background(image: Image.Image) -> np.ndarray | None:
66
+ rgba = np.asarray(image.convert("RGBA"))
67
+ band = max(1, min(image.size) // 100)
68
+ border = np.concatenate(
69
+ [
70
+ rgba[:band].reshape(-1, 4),
71
+ rgba[-band:].reshape(-1, 4),
72
+ rgba[:, :band].reshape(-1, 4),
73
+ rgba[:, -band:].reshape(-1, 4),
74
+ ]
75
+ )
76
+ # An already transparent border is not a chroma background.
77
+ if np.count_nonzero(border[:, 3] > 0) < len(border) // 2:
78
+ return None
79
+ return np.median(border[border[:, 3] > 0, :3], axis=0).round().astype(np.uint8)
80
+
81
+
82
+ def key_background(
83
+ raw: Image.Image, options: ProcessingOptions, report: ProcessingReport
84
+ ) -> Image.Image:
85
+ pixels = np.array(raw.convert("RGBA"))
86
+ background = estimate_background(raw)
87
+ if background is None:
88
+ return Image.fromarray(pixels)
89
+ report.background = "#" + "".join(f"{v:02X}" for v in background)
90
+ reference = rgb_to_lab(background)
91
+ distances = np.empty(pixels.shape[:2], dtype=np.float32)
92
+ for y in range(0, len(pixels), 128):
93
+ distances[y : y + 128] = np.linalg.norm(
94
+ rgb_to_lab(pixels[y : y + 128, :, :3]) - reference, axis=-1
95
+ )
96
+ pixels[distances <= options.background_tolerance, 3] = 0
97
+ # Decontaminate only background-like pixels adjoining removed background. Iterate
98
+ # a narrow band so a genuine purple accent inside the subject is never globally erased.
99
+ for _ in range(3):
100
+ transparent = pixels[..., 3] == 0
101
+ p = np.pad(transparent, 1, constant_values=True)
102
+ edge = p[:-2, 1:-1] | p[2:, 1:-1] | p[1:-1, :-2] | p[1:-1, 2:]
103
+ spill = edge & ~transparent & (distances <= options.despill_tolerance)
104
+ report.despilled_pixels += int(spill.sum())
105
+ pixels[spill, 3] = 0
106
+ pixels[pixels[..., 3] == 0] = 0
107
+ return Image.fromarray(pixels)
108
+
109
+
110
+ def isolate_subject(
111
+ image: Image.Image, options: ProcessingOptions, report: ProcessingReport
112
+ ) -> Image.Image:
113
+ pixels = np.array(image.convert("RGBA"))
114
+ labels, groups = components(pixels[..., 3] > 0)
115
+ if not groups:
116
+ return image.copy()
117
+ largest = groups[0][1]
118
+ keep = [groups[0][0]]
119
+ for ident, area, bbox in groups[1:]:
120
+ ratio = area / largest
121
+ if options.keep_detached and ratio >= options.detached_min_area_ratio:
122
+ keep.append(ident)
123
+ else:
124
+ report.dropped.append(DroppedComponent(area=area, bbox=bbox, area_ratio=ratio))
125
+ pixels[~np.isin(labels, keep)] = 0
126
+ return Image.fromarray(pixels)
127
+
128
+
129
+ def mode_resize(image: Image.Image, size: tuple[int, int]) -> Image.Image:
130
+ """Area-footprint mode, with transparent coverage voting and deterministic RGB ties.
131
+
132
+ Upscaling is nearest-neighbor. Shrinking chooses a source color, never an average.
133
+ """
134
+ rgba = np.asarray(image.convert("RGBA"))
135
+ width, height = size
136
+ if width >= image.width and height >= image.height:
137
+ return image.resize(size, Image.Resampling.NEAREST)
138
+ output = np.zeros((height, width, 4), dtype=np.uint8)
139
+ for y in range(height):
140
+ top, bottom = (
141
+ y * image.height // height,
142
+ max(y * image.height // height + 1, (y + 1) * image.height // height),
143
+ )
144
+ for x in range(width):
145
+ left, right = (
146
+ x * image.width // width,
147
+ max(x * image.width // width + 1, (x + 1) * image.width // width),
148
+ )
149
+ block = rgba[top:bottom, left:right].reshape(-1, 4)
150
+ visible = block[block[:, 3] > 0]
151
+ if len(visible) * 2 < len(block) or not len(visible):
152
+ continue
153
+ colors, counts = np.unique(visible, axis=0, return_counts=True)
154
+ output[y, x] = colors[counts.argmax()]
155
+ return Image.fromarray(output)
156
+
157
+
158
+ def detect_grid(
159
+ image: Image.Image, report: ProcessingReport | None = None
160
+ ) -> tuple[int | None, tuple[int, int]]:
161
+ """Estimate repeated horizontal/vertical color-run lengths, ignoring low-level texture."""
162
+ rgba = np.asarray(image.convert("RGBA"))
163
+ rgb = rgba[..., :3].astype(np.int16)
164
+ candidates = []
165
+ positions_by_axis = []
166
+ confidence = []
167
+ for axis in (1, 0):
168
+ delta = np.linalg.norm(np.diff(rgb, axis=axis), axis=-1)
169
+ alpha = rgba[..., 3] > 0
170
+ valid = (alpha[:, 1:] & alpha[:, :-1]) if axis == 1 else (alpha[1:] & alpha[:-1])
171
+ edges = (delta >= 30) & valid
172
+ lines = edges if axis == 1 else edges.T
173
+ gaps, positions = [], []
174
+ # Sample bounded, evenly-spaced scanlines through the source.
175
+ for row in lines[np.linspace(0, len(lines) - 1, min(128, len(lines)), dtype=int)]:
176
+ found = np.flatnonzero(row)
177
+ if len(found):
178
+ found = found[np.r_[True, np.diff(found) > 1]] + 1
179
+ positions.extend(found.tolist())
180
+ gaps.extend(np.diff(found).tolist())
181
+ gaps = np.array(gaps)
182
+ useful = gaps[(gaps >= 2) & (gaps <= 64)]
183
+ if len(useful) < 12:
184
+ return None, (0, 0)
185
+ histogram = np.bincount(useful, minlength=66)
186
+ scores = histogram[2:65] + 0.4 * (histogram[1:64] + histogram[3:66])
187
+ block = int(scores.argmax() + 2)
188
+ nearby = useful[np.abs(useful - block) <= 1]
189
+ block = int(np.median(nearby).round())
190
+ # A grid needs a repeated fundamental, not just one long rectangle edge.
191
+ if len(nearby) < 8 or len(nearby) / len(useful) < 0.2:
192
+ return None, (0, 0)
193
+ candidates.append(block)
194
+ confidence.append(len(nearby) / len(useful))
195
+ positions_by_axis.append(positions)
196
+ if abs(candidates[0] - candidates[1]) > 1:
197
+ return None, (0, 0)
198
+ block = round(sum(candidates) / 2)
199
+ if report is not None:
200
+ report.grid_confidence = min(confidence)
201
+ offsets = tuple(
202
+ int(np.bincount(np.array(p) % block, minlength=block).argmax()) for p in positions_by_axis
203
+ )
204
+ return block, offsets
205
+
206
+
207
+ def snap_grid(image: Image.Image, block: int, offset: tuple[int, int]) -> Image.Image:
208
+ """Pad to the detected lattice, then take the mode in each source grid cell."""
209
+ x, y = offset
210
+ left, top = (-x) % block, (-y) % block
211
+ width = (image.width + left + block - 1) // block
212
+ height = (image.height + top + block - 1) // block
213
+ canvas = Image.new("RGBA", (width * block, height * block))
214
+ canvas.paste(image, (left, top))
215
+ return mode_resize(canvas, (width, height))
216
+
217
+
218
+ def prepare_source(
219
+ raw: Image.Image, options: ProcessingOptions, report: ProcessingReport
220
+ ) -> Image.Image:
221
+ image = isolate_subject(key_background(raw, options, report), options, report)
222
+ bbox = image.getbbox()
223
+ if bbox:
224
+ image = image.crop(bbox)
225
+ if options.detect_grid and bbox:
226
+ report.grid_size, report.grid_offset = detect_grid(image, report)
227
+ if report.grid_size and report.grid_confidence >= options.native_grid_confidence:
228
+ image = snap_grid(image, report.grid_size, report.grid_offset)
229
+ logical_bbox = image.getbbox()
230
+ if logical_bbox:
231
+ image = image.crop(logical_bbox)
232
+ report.logical_subject_size = image.size
233
+ elif report.grid_size:
234
+ report.warnings.append(
235
+ f"Source grid confidence {report.grid_confidence:.2f} is too low; using unsnapped fit."
236
+ )
237
+ return image
@@ -0,0 +1,48 @@
1
+ """Deterministic seam cleanup and measured terrain/actor visual hierarchy."""
2
+
3
+ import numpy as np
4
+ from PIL import Image
5
+ from pydantic import BaseModel
6
+
7
+ from .palette import quantize
8
+
9
+
10
+ class VisualWeight(BaseModel):
11
+ local_contrast: float
12
+ distinct_colors: int
13
+
14
+
15
+ def visual_weight(image):
16
+ rgba = np.asarray(image.convert("RGBA"))
17
+ visible = rgba[..., 3] > 0
18
+ luminance = rgba[..., :3] @ np.array([0.2126, 0.7152, 0.0722]) / 255
19
+ deltas = []
20
+ for axis in (0, 1):
21
+ pairs = np.take(visible, range(visible.shape[axis] - 1), axis=axis) & np.take(
22
+ visible, range(1, visible.shape[axis]), axis=axis
23
+ )
24
+ deltas.extend(np.abs(np.diff(luminance, axis=axis))[pairs].tolist())
25
+ return VisualWeight(
26
+ local_contrast=float(np.mean(deltas)) if deltas else 0,
27
+ distinct_colors=len(set(map(tuple, rgba[..., :3][visible]))),
28
+ )
29
+
30
+
31
+ def repair_seams(image, palette):
32
+ """Blend opposing edges symmetrically, then snap to the approved palette."""
33
+ pixels = np.asarray(image.convert("RGBA")).copy()
34
+ rgb = pixels[..., :3].astype(float)
35
+ edge = (rgb[:, 0] + rgb[:, -1]) / 2
36
+ rgb[:, 0] = rgb[:, -1] = edge
37
+ if rgb.shape[1] > 3:
38
+ rgb[:, 1] = (3 * rgb[:, 1] + edge) / 4
39
+ rgb[:, -2] = (3 * rgb[:, -2] + edge) / 4
40
+ edge = (rgb[0] + rgb[-1]) / 2
41
+ rgb[0] = rgb[-1] = edge
42
+ if rgb.shape[0] > 3:
43
+ rgb[1] = (3 * rgb[1] + edge) / 4
44
+ rgb[-2] = (3 * rgb[-2] + edge) / 4
45
+ pixels[..., :3] = quantize(np.rint(rgb).astype(np.uint8), palette)
46
+ pixels[:, -1, 3] = pixels[:, 0, 3]
47
+ pixels[-1, :, 3] = pixels[0, :, 3]
48
+ return Image.fromarray(pixels)
@@ -0,0 +1,138 @@
1
+ from collections.abc import Mapping
2
+
3
+ import numpy as np
4
+ from PIL import Image
5
+
6
+ from .palette import palette_rgb
7
+ from .schemas import AssetSpec, Failure, Style
8
+
9
+
10
+ def seam_scores(img: Image.Image) -> tuple[float, float]:
11
+ """Normalized premultiplied RGBA differences (0..1).
12
+
13
+ Edge score measures opposite edges. Wrap score moves the original seam to
14
+ the middle with a half-offset roll and measures the join there. Both use
15
+ the maximum channel difference along the seam, so isolated defects count.
16
+ """
17
+ rgba = np.asarray(img.convert("RGBA"), dtype=float) / 255
18
+ rgba[..., :3] *= rgba[..., 3:4]
19
+ height, width = rgba.shape[:2]
20
+ edge = max(np.abs(rgba[:, 0] - rgba[:, -1]).max(), np.abs(rgba[0] - rgba[-1]).max())
21
+ wrapped = np.roll(rgba, (height // 2, width // 2), axis=(0, 1))
22
+ scores = [0.0]
23
+ if width > 1:
24
+ middle = width // 2
25
+ scores.append(np.abs(wrapped[:, middle - 1] - wrapped[:, middle]).max())
26
+ if height > 1:
27
+ middle = height // 2
28
+ scores.append(np.abs(wrapped[middle - 1] - wrapped[middle]).max())
29
+ return float(edge), float(max(scores))
30
+
31
+
32
+ def validate(img: Image.Image, spec: AssetSpec, style: Style) -> list[Failure]:
33
+ failures = []
34
+
35
+ def fail(code, message, fix_hint):
36
+ failures.append(Failure(code=code, message=message, fix_hint=fix_hint))
37
+
38
+ if img.size != spec.size:
39
+ fail(
40
+ "dimensions",
41
+ f"Expected {spec.size}, got {img.size}.",
42
+ "Fit and pad to the target canvas.",
43
+ )
44
+ rgba = np.asarray(img.convert("RGBA"))
45
+ alpha = rgba[..., 3]
46
+ visible = alpha > 0
47
+ colors = set(map(tuple, rgba[..., :3][visible]))
48
+ allowed = set(map(tuple, palette_rgb(style.palette)))
49
+ if colors - allowed:
50
+ fail(
51
+ "palette",
52
+ f"{len(colors - allowed)} off-palette colors.",
53
+ "Quantize visible RGB to the style palette without dithering.",
54
+ )
55
+ if np.any((alpha != 0) & (alpha != 255)):
56
+ fail("alpha", "Alpha contains intermediate values.", "Snap alpha to 0 or 255.")
57
+ limit = spec.max_colors or style.max_colors
58
+ if len(colors) > limit:
59
+ fail(
60
+ "max_colors",
61
+ f"Uses {len(colors)} colors; limit is {limit}.",
62
+ "Use a smaller approved palette or simplify the sprite shading.",
63
+ )
64
+ if not spec.edges_allowed and (
65
+ visible[0].any() or visible[-1].any() or visible[:, 0].any() or visible[:, -1].any()
66
+ ):
67
+ fail(
68
+ "clipped",
69
+ "Silhouette touches the canvas edge.",
70
+ "Add transparent padding and leave room for the outline.",
71
+ )
72
+ fill = float(visible.mean())
73
+ if fill < spec.min_fill_ratio:
74
+ fail(
75
+ "fill_ratio",
76
+ f"Fill ratio {fill:.3f} is below {spec.min_fill_ratio:.3f}.",
77
+ "Enlarge the subject or remove excess transparent space.",
78
+ )
79
+ if spec.type == "tile":
80
+ edge, wrap = seam_scores(img)
81
+ if edge > spec.seam_threshold:
82
+ fail(
83
+ "tile_edges",
84
+ f"Opposite-edge difference {edge:.3f} exceeds threshold.",
85
+ "Make opposite tile edges match in RGB and alpha.",
86
+ )
87
+ if wrap > spec.seam_threshold:
88
+ fail(
89
+ "tile_wrap",
90
+ f"Half-offset join difference {wrap:.3f} exceeds threshold.",
91
+ "Repair the central horizontal and vertical joins in the half-offset tile.",
92
+ )
93
+ return failures
94
+
95
+
96
+ def validate_animation(
97
+ frames: Mapping[str, Image.Image], spec: AssetSpec, style: Style
98
+ ) -> list[Failure]:
99
+ """Check every frame, consistent canvases and a common approved palette.
100
+
101
+ Frames may use different subsets of the style palette. An animation need not
102
+ show every color in every pose; a new unapproved color is palette drift.
103
+ """
104
+ if not frames:
105
+ return [
106
+ Failure(
107
+ code="animation_empty",
108
+ message="Animation has no frames.",
109
+ fix_hint="Supply at least one named frame.",
110
+ )
111
+ ]
112
+ failures = []
113
+ for name, frame in frames.items():
114
+ failures.extend(
115
+ f.model_copy(update={"message": f"{name}: {f.message}"})
116
+ for f in validate(frame, spec, style)
117
+ )
118
+ if len({frame.size for frame in frames.values()}) > 1:
119
+ failures.append(
120
+ Failure(
121
+ code="animation_size",
122
+ message="Frame canvases differ.",
123
+ fix_hint="Fit every frame to the same spec.size canvas.",
124
+ )
125
+ )
126
+ allowed = set(map(tuple, palette_rgb(style.palette)))
127
+ for frame in frames.values():
128
+ rgba = np.asarray(frame.convert("RGBA"))
129
+ if set(map(tuple, rgba[..., :3][rgba[..., 3] > 0])) - allowed:
130
+ failures.append(
131
+ Failure(
132
+ code="animation_palette",
133
+ message="Frame palette drift detected.",
134
+ fix_hint="Quantize every frame to the same style palette.",
135
+ )
136
+ )
137
+ break
138
+ return failures
@@ -0,0 +1 @@
1
+ EDIT the first reference (the accepted idle base sprite), changing ONLY its pose to the requested animation state/frame. Preserve identity, outfit, proportions, colors, outline, camera, top-left lighting and foot baseline. The second reference is the style anchor. Flat solid #FF00FF magenta background, chunky pixels, one centered subject, no text or watermark. Do not introduce props or redesign the character.
@@ -0,0 +1 @@
1
+ Create one idle base sprite. Flat solid #FF00FF magenta background, chunky logical pixels, one centered subject, no text, watermark, scenery or HUD. Keep the complete silhouette inside the requested logical bounds. Use the anchor only for style, never copy its scene. Use the game's camera and consistent top-left lighting.
@@ -0,0 +1 @@
1
+ Create one centered collectible or effect sprite. Flat solid #FF00FF magenta background, chunky pixels, strong readable silhouette and simple shading. No scenery, lettering, watermark or HUD. Leave clear padding around the complete subject. Match the anchor's style and top-left lighting.
@@ -0,0 +1 @@
1
+ Create one square repeating terrain tile, viewed in the game's camera. Chunky pixels; no objects, text, watermark or perspective distortion. The material must fill the tile completely. Opposite edges must match exactly and repeat seamlessly in both axes. If any exterior background is needed, use flat solid #FF00FF magenta outside the single centered tile only. Use the anchor only for material style and lighting.
@@ -0,0 +1 @@
1
+ Create one centered UI icon, flat solid #FF00FF magenta background, chunky pixels, simple high-contrast silhouette. No baked-in text, numerals, watermark, panel or scene. Preserve padding and match the approved palette. Use the anchor as a style reference only.
File without changes
@@ -0,0 +1,97 @@
1
+ from typing import Literal, Protocol
2
+
3
+ from pydantic import BaseModel, Field
4
+
5
+
6
+ class ImageRequest(BaseModel):
7
+ prompt: str
8
+ size: tuple[int, int] = (1024, 1024)
9
+ reasoning_strength: Literal["low", "high"] = "low"
10
+ references: list[bytes] = Field(default_factory=list, max_length=10)
11
+
12
+
13
+ class ImageResult(BaseModel):
14
+ data: bytes
15
+ mime: str = "image/png"
16
+ metadata: dict = Field(default_factory=dict)
17
+
18
+
19
+ class Message(BaseModel):
20
+ role: Literal["system", "user", "assistant", "tool"]
21
+ content: str | None = None
22
+ images: list[bytes] = Field(default_factory=list)
23
+ tool_calls: list[dict] = Field(default_factory=list)
24
+ tool_call_id: str | None = None
25
+
26
+
27
+ class ChatRequest(BaseModel):
28
+ messages: list[Message]
29
+ tools: list[dict] = Field(default_factory=list)
30
+ json_schema: dict | None = None
31
+ # Spark `reasoning_effort` (None: the model chooses) and `prompt_cache_key`, which routes
32
+ # requests sharing a prefix to the same cache.
33
+ reasoning_effort: str | None = None
34
+ cache_key: str | None = None
35
+
36
+
37
+ class ChatResult(BaseModel):
38
+ content: str | None = None
39
+ tool_calls: list[dict] = Field(default_factory=list)
40
+ metadata: dict = Field(default_factory=dict)
41
+
42
+
43
+ class SearchRequest(BaseModel):
44
+ """A research question answered with live web search (Responses API, `web_search`)."""
45
+
46
+ instructions: str # the role prompt
47
+ prompt: str
48
+ json_schema: dict | None = None
49
+ max_searches: int = Field(default=8, ge=1)
50
+ reasoning_effort: str | None = None
51
+ cache_key: str | None = None
52
+
53
+
54
+ class WebSource(BaseModel):
55
+ url: str
56
+ title: str = ""
57
+
58
+
59
+ class SearchResult(BaseModel):
60
+ content: str | None = None # the last message's text (the structured answer)
61
+ text: str = "" # every message's text, in order
62
+ queries: list[str] = Field(default_factory=list) # what the model searched for
63
+ sources: list[WebSource] = Field(default_factory=list) # pages the searches returned
64
+ cited: list[WebSource] = Field(default_factory=list) # url_citation annotations
65
+ searches: int = 0 # web_search_call items (searches and page opens)
66
+ metadata: dict = Field(default_factory=dict)
67
+
68
+
69
+ class ImageProvider(Protocol):
70
+ def generate(self, request: ImageRequest) -> ImageResult: ...
71
+ def edit(self, request: ImageRequest) -> ImageResult: ...
72
+
73
+
74
+ class LLMProvider(Protocol):
75
+ def chat(self, request: ChatRequest) -> ChatResult: ...
76
+
77
+
78
+ class SearchProvider(Protocol):
79
+ def research(self, request: SearchRequest) -> SearchResult: ...
80
+
81
+
82
+ def chat_json(provider: LLMProvider, request: ChatRequest, schema: type[BaseModel]) -> BaseModel:
83
+ """Validate every structured answer; one corrective retry only."""
84
+ from pydantic import ValidationError
85
+
86
+ request = request.model_copy(deep=True)
87
+ request.json_schema = schema.model_json_schema()
88
+ for attempt in range(2):
89
+ result = provider.chat(request)
90
+ try:
91
+ return schema.model_validate_json(result.content or "")
92
+ except ValidationError as exc:
93
+ if attempt:
94
+ raise
95
+ request.messages.append(Message(role="assistant", content=result.content or ""))
96
+ request.messages.append(Message(role="user", content=f"Correct JSON errors: {exc}"))
97
+ raise AssertionError("unreachable")