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.
- spriteforge/__init__.py +1 -0
- spriteforge/__main__.py +3 -0
- spriteforge/agents/__init__.py +0 -0
- spriteforge/agents/assets.py +109 -0
- spriteforge/agents/cancellation.py +12 -0
- spriteforge/agents/director.py +50 -0
- spriteforge/agents/models.py +63 -0
- spriteforge/agents/roles/art-director.md +15 -0
- spriteforge/agents/roles/art-reviewer.md +14 -0
- spriteforge/agents/roles/director.md +14 -0
- spriteforge/agents/roles/game-designer.md +15 -0
- spriteforge/agents/roles/level-tile-designer.md +16 -0
- spriteforge/agents/roles/librarian.md +13 -0
- spriteforge/agents/roles/menu-designer.md +15 -0
- spriteforge/agents/roles/pixel-artist.md +14 -0
- spriteforge/agents/roles/programmer.md +14 -0
- spriteforge/agents/roles/qa-playtester.md +13 -0
- spriteforge/agents/roles/sound-director.md +14 -0
- spriteforge/agents/roles.py +39 -0
- spriteforge/agents/router.py +233 -0
- spriteforge/agents/router_eval.py +145 -0
- spriteforge/agents/routing_state.py +133 -0
- spriteforge/agents/runtime.py +430 -0
- spriteforge/agents/workflow.py +389 -0
- spriteforge/app/__init__.py +0 -0
- spriteforge/app/agents_view.py +248 -0
- spriteforge/app/chat.py +114 -0
- spriteforge/app/extensions.py +115 -0
- spriteforge/app/index.html +279 -0
- spriteforge/app/local_only.py +49 -0
- spriteforge/app/server.py +358 -0
- spriteforge/app/static/assets/index-L2s1wlcp.css +1 -0
- spriteforge/app/static/assets/index-aBfzgLQl.js +71 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-BKfmdmKK.woff +0 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-xj9lRvVs.woff2 +0 -0
- spriteforge/app/static/index.html +13 -0
- spriteforge/app/static/press-start-2p-LICENSE.txt +93 -0
- spriteforge/app/studio.py +278 -0
- spriteforge/app/workers.py +73 -0
- spriteforge/cli.py +241 -0
- spriteforge/config.py +193 -0
- spriteforge/config.yaml +157 -0
- spriteforge/core/__init__.py +0 -0
- spriteforge/core/acting.py +16 -0
- spriteforge/core/cost.py +236 -0
- spriteforge/core/credentials.py +24 -0
- spriteforge/core/demo.py +79 -0
- spriteforge/core/forms.py +20 -0
- spriteforge/core/gates.py +175 -0
- spriteforge/core/security.py +42 -0
- spriteforge/core/state.py +222 -0
- spriteforge/core/team.py +15 -0
- spriteforge/core/usage.py +68 -0
- spriteforge/game/__init__.py +0 -0
- spriteforge/game/actors.py +377 -0
- spriteforge/game/agent_tools.py +178 -0
- spriteforge/game/art.py +2097 -0
- spriteforge/game/art_checks.py +190 -0
- spriteforge/game/art_review.py +518 -0
- spriteforge/game/build.py +134 -0
- spriteforge/game/bundle.py +1178 -0
- spriteforge/game/cli.py +119 -0
- spriteforge/game/codegen.py +433 -0
- spriteforge/game/codeinfo.py +154 -0
- spriteforge/game/dbsource.py +137 -0
- spriteforge/game/design.py +342 -0
- spriteforge/game/export.py +62 -0
- spriteforge/game/gamedb.py +191 -0
- spriteforge/game/image_cache.py +61 -0
- spriteforge/game/lessons.py +259 -0
- spriteforge/game/level_gen.py +118 -0
- spriteforge/game/level_preview.py +97 -0
- spriteforge/game/levels.py +934 -0
- spriteforge/game/loops.py +38 -0
- spriteforge/game/menus.py +712 -0
- spriteforge/game/mock_game.js +109 -0
- spriteforge/game/mock_platformer.js +58 -0
- spriteforge/game/motion.py +881 -0
- spriteforge/game/pipeline.py +1768 -0
- spriteforge/game/plan.py +502 -0
- spriteforge/game/playtest.py +318 -0
- spriteforge/game/qa.py +664 -0
- spriteforge/game/qa_checks.py +223 -0
- spriteforge/game/qa_runtime.py +565 -0
- spriteforge/game/reach.py +807 -0
- spriteforge/game/record.py +138 -0
- spriteforge/game/research.py +262 -0
- spriteforge/game/revision.py +225 -0
- spriteforge/game/sdk/API.md +104 -0
- spriteforge/game/sdk/FLOW.md +19 -0
- spriteforge/game/sdk/LEVELS.md +65 -0
- spriteforge/game/sdk/sf.js +418 -0
- spriteforge/game/sdk/sfflow.js +442 -0
- spriteforge/game/sdk/sflevel.js +683 -0
- spriteforge/game/sdk/sfsound-editor.js +225 -0
- spriteforge/game/sdk/sfsound.js +260 -0
- spriteforge/game/sdk/sounds.html +67 -0
- spriteforge/game/sounds.py +793 -0
- spriteforge/game/story.py +188 -0
- spriteforge/game/structure.py +98 -0
- spriteforge/game/team_reports.py +394 -0
- spriteforge/game/tilesets.py +70 -0
- spriteforge/game/title_art.py +186 -0
- spriteforge/genres/__init__.py +0 -0
- spriteforge/library/__init__.py +15 -0
- spriteforge/library/cli.py +126 -0
- spriteforge/library/describe.py +242 -0
- spriteforge/library/looks.py +154 -0
- spriteforge/library/models.py +79 -0
- spriteforge/library/store.py +422 -0
- spriteforge/library/tilesets/README.md +32 -0
- spriteforge/library/tilesets/gandalf-seasons.json +111 -0
- spriteforge/library/tilesets/pixel-crawler-dungeon.json +66 -0
- spriteforge/mcp/__init__.py +0 -0
- spriteforge/mcp/cli.py +58 -0
- spriteforge/mcp/client.py +57 -0
- spriteforge/mcp/filesystem_read.py +32 -0
- spriteforge/mcp/gamedb.py +56 -0
- spriteforge/mcp/library.py +179 -0
- spriteforge/mcp/memory.py +37 -0
- spriteforge/mcp/pixel_tools.py +145 -0
- spriteforge/mcp/registry.py +145 -0
- spriteforge/mcp/service.py +224 -0
- spriteforge/mcp/templates/context7.json +6 -0
- spriteforge/mcp/templates/fetch.json +6 -0
- spriteforge/mcp/templates/filesystem-read.json +6 -0
- spriteforge/mcp/templates/pixel-tools.json +6 -0
- spriteforge/memory/README.md +10 -0
- spriteforge/memory/__init__.py +0 -0
- spriteforge/memory/cli.py +131 -0
- spriteforge/memory/okf/__init__.py +1 -0
- spriteforge/memory/okf/catalog.py +331 -0
- spriteforge/memory/okf/codec.py +63 -0
- spriteforge/memory/okf/git.py +104 -0
- spriteforge/memory/okf/indexes.py +50 -0
- spriteforge/memory/okf/models.py +114 -0
- spriteforge/memory/okf/search.py +53 -0
- spriteforge/memory/okf/seed.py +81 -0
- spriteforge/memory/okf/seeds/genres.yaml +121 -0
- spriteforge/memory/okf/seeds/other.yaml +150 -0
- spriteforge/memory/okf/store.py +402 -0
- spriteforge/memory/okf/validate.py +115 -0
- spriteforge/pixel/__init__.py +17 -0
- spriteforge/pixel/atlas.py +110 -0
- spriteforge/pixel/grid.py +174 -0
- spriteforge/pixel/palette.py +156 -0
- spriteforge/pixel/palettes/dungeon.json +9 -0
- spriteforge/pixel/postprocess.py +170 -0
- spriteforge/pixel/preview.py +40 -0
- spriteforge/pixel/schemas.py +139 -0
- spriteforge/pixel/source.py +237 -0
- spriteforge/pixel/terrain.py +48 -0
- spriteforge/pixel/validate.py +138 -0
- spriteforge/prompts/anim_frame.txt +1 -0
- spriteforge/prompts/character.txt +1 -0
- spriteforge/prompts/item.txt +1 -0
- spriteforge/prompts/tile.txt +1 -0
- spriteforge/prompts/ui.txt +1 -0
- spriteforge/providers/__init__.py +0 -0
- spriteforge/providers/base.py +97 -0
- spriteforge/providers/http.py +38 -0
- spriteforge/providers/mock.py +111 -0
- spriteforge/providers/muse_image.py +60 -0
- spriteforge/providers/muse_search.py +91 -0
- spriteforge/providers/muse_spark.py +66 -0
- spriteforge/skills/__init__.py +0 -0
- spriteforge/skills/builtin/LICENSE-awesome-gamedev-agent-skills.txt +201 -0
- spriteforge/skills/builtin/NOTICE-awesome-gamedev-agent-skills.txt +15 -0
- spriteforge/skills/builtin/THIRD_PARTY.md +21 -0
- spriteforge/skills/builtin/audio-design/SKILL.md +190 -0
- spriteforge/skills/builtin/game-feel/SKILL.md +174 -0
- spriteforge/skills/builtin/game-ui-ux/SKILL.md +167 -0
- spriteforge/skills/builtin/level-design/SKILL.md +169 -0
- spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md +17 -0
- spriteforge/skills/builtin/physics-tuning/SKILL.md +164 -0
- spriteforge/skills/builtin/pixel-art-prompting/SKILL.md +12 -0
- spriteforge/skills/builtin/platformer/SKILL.md +153 -0
- spriteforge/skills/builtin/puzzle/SKILL.md +143 -0
- spriteforge/skills/builtin/sprite-animation-frames/SKILL.md +11 -0
- spriteforge/skills/builtin/tileset-design/SKILL.md +10 -0
- spriteforge/skills/catalog.py +200 -0
- spriteforge/skills/cli.py +41 -0
- spriteforge/stages/__init__.py +0 -0
- spriteforge/stages/asset_context.py +301 -0
- spriteforge/stages/asset_models.py +192 -0
- spriteforge/stages/asset_render.py +366 -0
- spriteforge/stages/asset_review.py +140 -0
- spriteforge/stages/asset_store.py +94 -0
- spriteforge/stages/chat_changes.py +236 -0
- spriteforge/stages/concept.py +42 -0
- spriteforge/stages/game.py +1699 -0
- spriteforge/stages/game_confirm.py +112 -0
- spriteforge/stages/game_final.py +220 -0
- spriteforge/stages/game_record.py +246 -0
- spriteforge/stages/gameplay.py +218 -0
- spriteforge/stages/intake.py +372 -0
- spriteforge/stages/preview_assets.py +212 -0
- spriteforge/stages/preview_models.py +167 -0
- spriteforge/stages/preview_render.py +169 -0
- spriteforge/stages/preview_repair.py +61 -0
- spriteforge/stages/preview_review.py +169 -0
- spriteforge/stages/production.py +170 -0
- spriteforge/stages/references.py +105 -0
- spriteforge/stages/rewind.py +128 -0
- spriteforge/stages/workflow.py +440 -0
- spriteforge/templates/phaser/audit.js +45 -0
- spriteforge/templates/phaser/font.png +0 -0
- spriteforge/templates/phaser/font.xml +1 -0
- spriteforge/templates/phaser/preview.html +9 -0
- spriteforge/templates/phaser/room.js +49 -0
- spriteforge/templates/phaser/vendor/LICENSE.md +20 -0
- spriteforge/templates/phaser/vendor/phaser.min.js +1 -0
- spriteforge-0.1.1.dist-info/METADATA +364 -0
- spriteforge-0.1.1.dist-info/RECORD +218 -0
- spriteforge-0.1.1.dist-info/WHEEL +5 -0
- spriteforge-0.1.1.dist-info/entry_points.txt +2 -0
- spriteforge-0.1.1.dist-info/licenses/LICENSE +27 -0
- spriteforge-0.1.1.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,1178 @@
|
|
|
1
|
+
"""The concepts of a game's OKF bundle, written by code from a `GameRecord` (no model call).
|
|
2
|
+
|
|
3
|
+
`bundle(record)` returns every concept and file; `gamedb.sync` writes them. See gamedb for
|
|
4
|
+
the layout.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import hashlib
|
|
8
|
+
import io
|
|
9
|
+
import re
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from PIL import Image
|
|
14
|
+
|
|
15
|
+
from spriteforge.core.security import redact
|
|
16
|
+
from spriteforge.library.looks import measure
|
|
17
|
+
from spriteforge.memory.okf.codec import UnsafeKnowledge, ensure_no_secrets
|
|
18
|
+
from spriteforge.memory.okf.models import Entry, Metadata, Source
|
|
19
|
+
|
|
20
|
+
from .art import Filled
|
|
21
|
+
from .art_review import sheet_image, thumb
|
|
22
|
+
from .codegen import GameCode
|
|
23
|
+
from .codeinfo import Module, read_code
|
|
24
|
+
from .design import GameDesign
|
|
25
|
+
from .levels import LevelRecord
|
|
26
|
+
from .menus import ACTIONS, MenuRecord, menus_markdown
|
|
27
|
+
from .motion import MotionRecord, motion_markdown
|
|
28
|
+
from .plan import PlanRecord
|
|
29
|
+
from .qa import SDK_EVENTS, STATE_KEYS, QASuite, Step
|
|
30
|
+
from .qa_runtime import describe_step
|
|
31
|
+
from .research import ResearchRecord
|
|
32
|
+
from .story import StoryBible
|
|
33
|
+
from .structure import GameStructure, structure_markdown
|
|
34
|
+
|
|
35
|
+
WITHHELD = "withheld from the record: it looked like a credential"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
# --- what a game is made of ------------------------------------------------------------------
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass
|
|
42
|
+
class ArtInfo:
|
|
43
|
+
"""One entity's locked art."""
|
|
44
|
+
|
|
45
|
+
source: str # "muse", "library <id>", "muse (locked, from v1)" ...
|
|
46
|
+
version: int # the build that made it
|
|
47
|
+
sheet: bytes # the sprite sheet / image the game loads (PNG)
|
|
48
|
+
portrait: bytes # its first frame at 4x (PNG)
|
|
49
|
+
look: str # measured colours, brightness, detail
|
|
50
|
+
prompt: str = "" # the Muse prompt, '' for library art
|
|
51
|
+
|
|
52
|
+
@property
|
|
53
|
+
def digest(self) -> str:
|
|
54
|
+
return hashlib.sha256(self.sheet).hexdigest()[:12]
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def art_info(filled: dict[str, Filled], version: int) -> dict[str, ArtInfo]:
|
|
58
|
+
"""The locked art of a build, by entity id."""
|
|
59
|
+
out = {}
|
|
60
|
+
for eid, f in filled.items():
|
|
61
|
+
made = int(f.record.get("version") or f.record.get("reused_from") or version)
|
|
62
|
+
prompt = f.record.get("muse_prompt") or f.record.get("prompt") or ""
|
|
63
|
+
out[eid] = ArtInfo(f.source, made, f.png, thumb(f), measure(sheet_image(f)).text,
|
|
64
|
+
str(prompt)) # fmt: skip
|
|
65
|
+
return out
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass
|
|
69
|
+
class Build:
|
|
70
|
+
version: int
|
|
71
|
+
source: str # the report's artifact or file name
|
|
72
|
+
report: dict # report.json
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
@dataclass
|
|
76
|
+
class Decision:
|
|
77
|
+
"""The human at a gate: what they said and what it changed."""
|
|
78
|
+
|
|
79
|
+
gate: str # "G2 design v1", "G4 playtest v2"
|
|
80
|
+
outcome: str # "approved" | "changes requested" | "story added"
|
|
81
|
+
words: str # their feedback (redacted), '' for a plain approval
|
|
82
|
+
changed: str # what it changed
|
|
83
|
+
build: int | None = None # the build it is about, or the build that answered it
|
|
84
|
+
asked_build: bool = False # it asked for that build (approving a design, changes at G4)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@dataclass
|
|
88
|
+
class GameRecord:
|
|
89
|
+
design: GameDesign
|
|
90
|
+
design_source: str
|
|
91
|
+
story: StoryBible | None = None
|
|
92
|
+
story_source: str = ""
|
|
93
|
+
builds: list[Build] = field(default_factory=list)
|
|
94
|
+
art: dict[str, ArtInfo] = field(default_factory=dict) # the latest build's
|
|
95
|
+
screen: tuple[int, int] = (320, 180)
|
|
96
|
+
scale: int = 1
|
|
97
|
+
credits: list[str] = field(default_factory=list)
|
|
98
|
+
code: GameCode | None = None # the latest build's
|
|
99
|
+
qa: QASuite | None = None # the latest build's suite
|
|
100
|
+
qa_export: bytes | None = None # test_game_qa.py
|
|
101
|
+
decisions: list[Decision] = field(default_factory=list)
|
|
102
|
+
play: str | None = None
|
|
103
|
+
research: ResearchRecord | None = None # L2.2: similar games studied with web search
|
|
104
|
+
research_source: str = ""
|
|
105
|
+
plan: PlanRecord | None = None # L2.2: the game plan of the current design
|
|
106
|
+
plan_source: str = ""
|
|
107
|
+
levels: list[LevelRecord] = field(default_factory=list) # L2.3: the levels as data
|
|
108
|
+
levels_source: str = ""
|
|
109
|
+
level_files: dict[int, bytes] = field(default_factory=dict) # what the SDK loads, per level
|
|
110
|
+
level_previews: dict[int, bytes] = field(default_factory=dict) # map previews (PNG)
|
|
111
|
+
level_play: dict[int, dict] = field(default_factory=dict) # the latest build's playtest
|
|
112
|
+
motion: MotionRecord | None = None # L2.4: the motion design of the current design
|
|
113
|
+
motion_source: str = ""
|
|
114
|
+
motion_gif: bytes | None = None # the latest build's rows playing
|
|
115
|
+
structure: GameStructure | None = None # L2.5: levels in order, carries, saved, win
|
|
116
|
+
structure_source: str = ""
|
|
117
|
+
menus: MenuRecord | None = None # L2.5: the menus as data (the latest build's version)
|
|
118
|
+
menus_source: str = ""
|
|
119
|
+
menus_file: bytes | None = None # menus.json as the SDK loads it (theme in the art's colours)
|
|
120
|
+
menu_shots: dict[str, bytes] = field(default_factory=dict) # screen id -> PNG
|
|
121
|
+
title_art: dict[str, bytes] = field(default_factory=dict) # "title-art", "emblem" -> PNG
|
|
122
|
+
|
|
123
|
+
@property
|
|
124
|
+
def latest(self) -> Build | None:
|
|
125
|
+
return self.builds[-1] if self.builds else None
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
# --- concepts --------------------------------------------------------------------------------
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def make_entry(ident: str, type_: str, title: str, description: str, tags, body: str,
|
|
132
|
+
sources: list[str], resource: str | None = None,
|
|
133
|
+
status: str = "stable") -> Entry: # fmt: skip
|
|
134
|
+
fields = {
|
|
135
|
+
"type": type_,
|
|
136
|
+
"title": title,
|
|
137
|
+
"description": re.sub(r"\s+", " ", description).strip()[:300],
|
|
138
|
+
"tags": sorted({str(t).lower() for t in tags if str(t).strip()}),
|
|
139
|
+
"sources": [Source(resource="spriteforge game", id=s) for s in sources if s],
|
|
140
|
+
"status": status,
|
|
141
|
+
}
|
|
142
|
+
if resource:
|
|
143
|
+
fields["resource"] = resource
|
|
144
|
+
return Entry(id=ident, metadata=Metadata(**fields), body=body.strip() + "\n")
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def bullets(items, empty: str = "- (none)") -> str:
|
|
148
|
+
return "\n".join(f"- {i}" for i in items) or empty
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def slug(text: str) -> str:
|
|
152
|
+
return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:60] or "x"
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def safe_text(text: str) -> str:
|
|
156
|
+
"""Text the human or a model wrote, as it may go into the record."""
|
|
157
|
+
text = redact(text)
|
|
158
|
+
try:
|
|
159
|
+
ensure_no_secrets(text)
|
|
160
|
+
except UnsafeKnowledge:
|
|
161
|
+
return f"({WITHHELD})"
|
|
162
|
+
return text
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def code_span(text: str) -> str:
|
|
166
|
+
return f"`{text}`" if text else "-"
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def game_concept(rec: GameRecord, modules: list[Module]) -> Entry:
|
|
170
|
+
d, b = rec.design, rec.latest
|
|
171
|
+
sections = []
|
|
172
|
+
if rec.research:
|
|
173
|
+
sections.append("[Research](/research/overview.md): similar games, patterns, feel numbers")
|
|
174
|
+
if rec.plan:
|
|
175
|
+
sections.append("[Game plan](/plan/overview.md): the human's requirements, movement "
|
|
176
|
+
"numbers, mechanics, levels, feel and animations") # fmt: skip
|
|
177
|
+
sections += [
|
|
178
|
+
"[Rules](/design/rules.md): controls, rules, progression, difficulty, win and lose",
|
|
179
|
+
"[Events and state](/design/events.md): what every build emits and exposes",
|
|
180
|
+
"[Entities](/entities/index.md): everything the player sees",
|
|
181
|
+
]
|
|
182
|
+
if rec.structure:
|
|
183
|
+
sections.append("[Structure](/design/structure.md): the levels in order, what carries "
|
|
184
|
+
"over and what is saved") # fmt: skip
|
|
185
|
+
if rec.menus:
|
|
186
|
+
sections.append("[Menus](/menus/overview.md): every screen around play, the theme and "
|
|
187
|
+
"the title art") # fmt: skip
|
|
188
|
+
if rec.art:
|
|
189
|
+
sections.append("[Art style](/art/style.md) and [locked assets](/art/assets/index.md)")
|
|
190
|
+
if modules:
|
|
191
|
+
sections.append("[Code](/code/overview.md): files, scenes and what each one does")
|
|
192
|
+
if rec.qa:
|
|
193
|
+
sections.append("[QA tests](/qa/suite.md): tests written from the design")
|
|
194
|
+
if b:
|
|
195
|
+
sections.append(f"[Builds](/builds/index.md): the latest is [v{b.version}]"
|
|
196
|
+
f"(/builds/v{b.version}.md)") # fmt: skip
|
|
197
|
+
if rec.decisions:
|
|
198
|
+
sections.append("[Decisions](/decisions/index.md): the human's words at each gate")
|
|
199
|
+
if rec.story:
|
|
200
|
+
sections.append("[Story](/story/overview.md), [characters](/characters/index.md) and "
|
|
201
|
+
"[world](/world/index.md)") # fmt: skip
|
|
202
|
+
if b:
|
|
203
|
+
qa = b.report.get("qa") or {}
|
|
204
|
+
status = (
|
|
205
|
+
f"Build v{b.version} (design v{b.report.get('design_version', 1)}): "
|
|
206
|
+
+ ("all design checks pass" if b.report.get("passed") else "some design checks fail")
|
|
207
|
+
+ (f"; QA {qa['passed']}/{qa['passed'] + qa['failed']} tests pass" if qa else "")
|
|
208
|
+
+ f". Play: {code_span(rec.play or '')}"
|
|
209
|
+
)
|
|
210
|
+
else:
|
|
211
|
+
status = "Not built yet: the design is waiting for approval."
|
|
212
|
+
body = f"""
|
|
213
|
+
# {d.title}
|
|
214
|
+
{d.pitch}
|
|
215
|
+
|
|
216
|
+
# At a glance
|
|
217
|
+
{d.camera} camera, a {rec.screen[0]}x{rec.screen[1]} screen. {d.controls}. A full session lasts
|
|
218
|
+
{d.session_seconds} s. Story: {"yes, see [the story](/story/overview.md)" if rec.story else "none (the human did not ask for one)"}.
|
|
219
|
+
|
|
220
|
+
# Current version
|
|
221
|
+
{status}
|
|
222
|
+
|
|
223
|
+
# Sections
|
|
224
|
+
{bullets(sections)}
|
|
225
|
+
"""
|
|
226
|
+
sources = [rec.design_source, b.source if b else ""]
|
|
227
|
+
return make_entry("game", "Game", d.title, d.pitch, ["game", d.camera], body, sources)
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def rules_concept(rec: GameRecord) -> Entry:
|
|
231
|
+
d = rec.design
|
|
232
|
+
body = f"""
|
|
233
|
+
# Camera and controls
|
|
234
|
+
{d.camera}. {d.controls}
|
|
235
|
+
|
|
236
|
+
# Player
|
|
237
|
+
{d.player}
|
|
238
|
+
|
|
239
|
+
# World
|
|
240
|
+
{d.world}
|
|
241
|
+
|
|
242
|
+
# Rules
|
|
243
|
+
{bullets(d.rules)}
|
|
244
|
+
|
|
245
|
+
# Progression
|
|
246
|
+
{bullets(d.progression)}
|
|
247
|
+
|
|
248
|
+
# Difficulty
|
|
249
|
+
{bullets(d.difficulty)}
|
|
250
|
+
|
|
251
|
+
# Win and lose
|
|
252
|
+
Win: {d.win}
|
|
253
|
+
Lose: {d.lose}
|
|
254
|
+
A full session lasts {d.session_seconds} s.
|
|
255
|
+
|
|
256
|
+
# HUD
|
|
257
|
+
{bullets(d.hud)}
|
|
258
|
+
|
|
259
|
+
# Checks
|
|
260
|
+
Every build must emit these [events](/design/events.md); the bot playtest counts them.
|
|
261
|
+
""" + "\n".join(
|
|
262
|
+
f"- `{c.event}` at least {c.min_count}" + (f" by {c.by_second:g} s" if c.by_second else "")
|
|
263
|
+
+ f": {c.description}" for c in d.checks
|
|
264
|
+
) # fmt: skip
|
|
265
|
+
return make_entry("design/rules", "Game Rules", f"{d.title}: rules",
|
|
266
|
+
f"{d.camera}; {d.controls}", ["design", "rules", d.camera], body,
|
|
267
|
+
[rec.design_source]) # fmt: skip
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def events_concept(rec: GameRecord, modules: list[Module]) -> Entry:
|
|
271
|
+
d = rec.design
|
|
272
|
+
emitted = {}
|
|
273
|
+
for m in modules:
|
|
274
|
+
for e in m.events:
|
|
275
|
+
emitted.setdefault(e, []).append(m.path)
|
|
276
|
+
rows, seen = [], set()
|
|
277
|
+
for c in d.checks:
|
|
278
|
+
if c.event in seen:
|
|
279
|
+
continue
|
|
280
|
+
seen.add(c.event)
|
|
281
|
+
when = f"at least {c.min_count}" + (f" by {c.by_second:g} s" if c.by_second else "")
|
|
282
|
+
rows.append((c.event, "design check", f"{c.description} ({when})", emitted.get(c.event)))
|
|
283
|
+
sdk = {"boot": "the game started", "restart": "Enter restarted the run after win or lose",
|
|
284
|
+
"menu": "an sf.choose menu opened", "choice": "an sf.choose option was picked",
|
|
285
|
+
"win": "the session was won", "lose": "the session was lost"} # fmt: skip
|
|
286
|
+
for e in SDK_EVENTS:
|
|
287
|
+
if e not in seen:
|
|
288
|
+
seen.add(e)
|
|
289
|
+
rows.append((e, "SDK" if e not in {"win", "lose"} else "every game", sdk[e],
|
|
290
|
+
emitted.get(e))) # fmt: skip
|
|
291
|
+
for e, files in emitted.items():
|
|
292
|
+
if e not in seen:
|
|
293
|
+
seen.add(e)
|
|
294
|
+
rows.append((e, "code", "emitted by the game (not a design check)", files))
|
|
295
|
+
table = "\n".join(
|
|
296
|
+
f"| `{e}` | {kind} | {what} | {', '.join(f'`{f}`' for f in files) if files else '-'} |"
|
|
297
|
+
for e, kind, what, files in rows
|
|
298
|
+
)
|
|
299
|
+
set_by = {}
|
|
300
|
+
for m in modules:
|
|
301
|
+
for k in m.state:
|
|
302
|
+
set_by.setdefault(k, []).append(m.path)
|
|
303
|
+
keys = list(dict.fromkeys([*STATE_KEYS, *set_by]))
|
|
304
|
+
need = {"hp": "player health", "x": "player x in pixels", "y": "player y in pixels",
|
|
305
|
+
"time": "seconds since this run started (a restart resets it)",
|
|
306
|
+
"level": "the level, when the design has levels",
|
|
307
|
+
"score": "score, gems or kills, when the design has them"} # fmt: skip
|
|
308
|
+
state = "\n".join(
|
|
309
|
+
f"| `{k}` | {need.get(k, 'set by the game')} | "
|
|
310
|
+
f"{'required' if k in {'hp', 'x', 'y', 'time'} else 'optional'} | "
|
|
311
|
+
f"{', '.join(f'`{f}`' for f in set_by.get(k, [])) or 'not set'} |"
|
|
312
|
+
for k in keys
|
|
313
|
+
)
|
|
314
|
+
body = f"""
|
|
315
|
+
# Events
|
|
316
|
+
What the game reports with `sf.event(name, data)`; the playtest and the QA tests count these.
|
|
317
|
+
|
|
318
|
+
# Schema
|
|
319
|
+
## Events
|
|
320
|
+
| event | from | meaning | emitted in |
|
|
321
|
+
| --- | --- | --- | --- |
|
|
322
|
+
{table}
|
|
323
|
+
|
|
324
|
+
## sf.state
|
|
325
|
+
A plain object the game updates every frame; QA tests read it.
|
|
326
|
+
|
|
327
|
+
| key | meaning | contract | set in |
|
|
328
|
+
| --- | --- | --- | --- |
|
|
329
|
+
{state}
|
|
330
|
+
"""
|
|
331
|
+
return make_entry("design/events", "Event Contract", f"{d.title}: events and state",
|
|
332
|
+
f"{len(rows)} events, {len(keys)} state keys", ["design", "events", "state"],
|
|
333
|
+
body, [rec.design_source, rec.latest.source if rec.latest else ""]) # fmt: skip
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def entity_concepts(rec: GameRecord) -> list[Entry]:
|
|
337
|
+
chars = {c.entity: c for c in rec.story.characters} if rec.story else {}
|
|
338
|
+
entries = []
|
|
339
|
+
for e in rec.design.entities:
|
|
340
|
+
a = rec.art.get(e.id)
|
|
341
|
+
art = (
|
|
342
|
+
f"\n\n[Locked art](/art/assets/{e.id}.md): "
|
|
343
|
+
f"{a.source}, made in build v{a.version}."
|
|
344
|
+
if a
|
|
345
|
+
else "No art yet: it is made when the game is built."
|
|
346
|
+
)
|
|
347
|
+
c = chars.get(e.id)
|
|
348
|
+
story = (
|
|
349
|
+
f"\n# Character\n[{c.name}](/characters/{e.id}.md), {c.role}. {c.personality}. "
|
|
350
|
+
f"Goal: {c.goal}.\n"
|
|
351
|
+
if c
|
|
352
|
+
else ""
|
|
353
|
+
)
|
|
354
|
+
body = f"""
|
|
355
|
+
# {e.id}
|
|
356
|
+
{e.role}, {e.width}x{e.height} px on a 320x180 screen.
|
|
357
|
+
|
|
358
|
+
# Looks
|
|
359
|
+
{e.look}
|
|
360
|
+
|
|
361
|
+
# Behaviour
|
|
362
|
+
{e.behaviour}
|
|
363
|
+
|
|
364
|
+
# Animations
|
|
365
|
+
{", ".join(e.animations) or "none (static)"}
|
|
366
|
+
{story}
|
|
367
|
+
# Art
|
|
368
|
+
{art}
|
|
369
|
+
"""
|
|
370
|
+
entries.append(make_entry(f"entities/{e.id}", "Entity", e.id, f"{e.role}: {e.look}",
|
|
371
|
+
["entity", e.role, e.id], body, [rec.design_source])) # fmt: skip
|
|
372
|
+
return entries
|
|
373
|
+
|
|
374
|
+
|
|
375
|
+
def art_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
|
|
376
|
+
if not rec.art:
|
|
377
|
+
return [], {}
|
|
378
|
+
d = rec.design
|
|
379
|
+
roles = {e.id: e.role for e in d.entities}
|
|
380
|
+
hero = next((e for e in d.entities if e.role == "player"), None)
|
|
381
|
+
source = rec.latest.source if rec.latest else rec.design_source
|
|
382
|
+
rows = "\n".join(
|
|
383
|
+
f"| [{eid}](/art/assets/{eid}.md) | {roles.get(eid, '-')} | {a.source} | v{a.version} |"
|
|
384
|
+
for eid, a in rec.art.items()
|
|
385
|
+
)
|
|
386
|
+
style = f"""
|
|
387
|
+
# Direction
|
|
388
|
+
{d.look}
|
|
389
|
+
|
|
390
|
+
# Screen and scale
|
|
391
|
+
{d.camera} view, a {rec.screen[0]}x{rec.screen[1]} screen (art scale {rec.scale}); the hero is
|
|
392
|
+
{hero.height * rec.scale if hero else "?"} px tall. Every sprite faces right; the game flips it.
|
|
393
|
+
|
|
394
|
+
# Locked assets
|
|
395
|
+
| entity | role | source | made in |
|
|
396
|
+
| --- | --- | --- | --- |
|
|
397
|
+
{rows}
|
|
398
|
+
|
|
399
|
+
# Rules for new art
|
|
400
|
+
Match the locked art: its outline, shading and pixel size. Colours named by the design win over
|
|
401
|
+
a style example's. Locked art is redrawn only when the human or a change asks for it.
|
|
402
|
+
|
|
403
|
+
# Credits
|
|
404
|
+
{bullets(rec.credits)}
|
|
405
|
+
"""
|
|
406
|
+
if rec.motion:
|
|
407
|
+
style += "\n# Motion\nHow each thing moves and reacts: [motion design](/art/motion.md).\n"
|
|
408
|
+
entries = [make_entry("art/style", "Art Style", f"{d.title}: art style", d.look,
|
|
409
|
+
["art", "style", d.camera], style, [rec.design_source, source])] # fmt: skip
|
|
410
|
+
files = {}
|
|
411
|
+
if rec.motion:
|
|
412
|
+
entry, extra = motion_concept(rec, source)
|
|
413
|
+
entries.append(entry)
|
|
414
|
+
files |= extra
|
|
415
|
+
for eid, a in rec.art.items():
|
|
416
|
+
files[f"references/art/{eid}.png"] = a.portrait
|
|
417
|
+
files[f"references/art/{eid}-sheet.png"] = a.sheet
|
|
418
|
+
body = f"""
|
|
419
|
+
# {eid}
|
|
420
|
+

|
|
421
|
+
|
|
422
|
+
The first frame at 4x. The game loads [the sheet](/references/art/{eid}-sheet.png)
|
|
423
|
+
(image {a.digest}). Entity: [{eid}](/entities/{eid}.md).
|
|
424
|
+
|
|
425
|
+
# Source
|
|
426
|
+
{a.source}, locked in build v{a.version}. Redraw it only when a change asks for this entity.
|
|
427
|
+
|
|
428
|
+
# Muse prompt
|
|
429
|
+
{a.prompt.strip() or "- (library art: no prompt)"}
|
|
430
|
+
|
|
431
|
+
# Measured look
|
|
432
|
+
{a.look}
|
|
433
|
+
"""
|
|
434
|
+
entries.append(make_entry(f"art/assets/{eid}", "Asset", f"{eid} art",
|
|
435
|
+
f"{roles.get(eid, 'asset')}: {a.source}, v{a.version}",
|
|
436
|
+
["art", "asset", roles.get(eid, ""), eid], body, [source],
|
|
437
|
+
resource=f"/references/art/{eid}.png")) # fmt: skip
|
|
438
|
+
return entries, files
|
|
439
|
+
|
|
440
|
+
|
|
441
|
+
MOTION_SCHEMA = """# Schema
|
|
442
|
+
`/references/art/motion.json` (the Art Director's motion design, fitted by code):
|
|
443
|
+
* `rows[]`: `entity` (design id), `name` (the animation's name in the sheet), `plays` (when the
|
|
444
|
+
game shows it: idle, move, jump, fall, land, dash, hurt, attack, break, die, form, pickup,
|
|
445
|
+
other), `form` (the ability a form row shows, else ''), `frames[]` (`shows`: what the frame
|
|
446
|
+
shows, `airborne`: off the ground), `fps`, `loop`.
|
|
447
|
+
* `forms[]`: `ability`, `looks`, `tint` (#RRGGBB when its row fails), `particles`.
|
|
448
|
+
* `effects[]`: `name`, `on` (the SDK moment that plays it, or 'game'), `particles`, `colors`,
|
|
449
|
+
`speed` (px/s at 320x180), `flash`, `shake` (0-1), `squash` (+ flat, - tall), `seconds`.
|
|
450
|
+
"""
|
|
451
|
+
|
|
452
|
+
|
|
453
|
+
def motion_concept(rec: GameRecord, source: str) -> tuple[Entry, dict[str, bytes]]:
|
|
454
|
+
"""art/motion: the motion design (L2.4), what code found in the latest build's rows and
|
|
455
|
+
the rows playing."""
|
|
456
|
+
m = rec.motion
|
|
457
|
+
checks = (rec.latest.report.get("motion") or {}).get("rows", []) if rec.latest else []
|
|
458
|
+
found = "\n".join(f"* {c['entity']}.{c['row']} ({c['plays']}, {c['frames']} frames): "
|
|
459
|
+
+ ("; ".join([*c["problems"], *(f"repaired: {r}" for r in c["repaired"])]) or "ok")
|
|
460
|
+
for c in checks) or "- (no build yet)" # fmt: skip
|
|
461
|
+
files = {"references/art/motion.json": (m.brief.model_dump_json(indent=1) + "\n").encode()}
|
|
462
|
+
gif = ""
|
|
463
|
+
if rec.motion_gif:
|
|
464
|
+
files["references/art/motion.gif"] = rec.motion_gif
|
|
465
|
+
gif = "\n\n"
|
|
466
|
+
body = (gif + motion_markdown(m).replace("# Motion design", "# Rows, forms and effects", 1)
|
|
467
|
+
+ f"\n# Checked by code (latest build)\n{found}\n\n{MOTION_SCHEMA}")
|
|
468
|
+
entities = sorted({r.entity for r in m.brief.rows})
|
|
469
|
+
links = " ".join(f"[{e}](/art/assets/{e}.md)" for e in entities if e in rec.art)
|
|
470
|
+
body += f"\n# Assets\n{links or '-'}\n"
|
|
471
|
+
return make_entry("art/motion", "Motion Design", f"{rec.design.title}: motion design",
|
|
472
|
+
f"{len(m.brief.rows)} animation rows, {len(m.brief.forms)} forms, "
|
|
473
|
+
f"{len(m.brief.effects)} effects", ["art", "motion", "animation"], body,
|
|
474
|
+
[rec.motion_source, source], resource="/references/art/motion.json"), files # fmt: skip
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
def checks_for(rec: GameRecord, events: list[str]) -> list[str]:
|
|
478
|
+
by_event = {c.event: c.id for c in rec.design.checks}
|
|
479
|
+
return [f"`{e}` (check `{by_event[e]}`)" if e in by_event else f"`{e}`" for e in events]
|
|
480
|
+
|
|
481
|
+
|
|
482
|
+
def code_concepts(rec: GameRecord, modules: list[Module]) -> tuple[list[Entry], dict[str, bytes]]:
|
|
483
|
+
if rec.code is None:
|
|
484
|
+
return [], {}
|
|
485
|
+
source = rec.latest.source if rec.latest else ""
|
|
486
|
+
files, entries, rows = {}, [], []
|
|
487
|
+
contents = rec.code.as_dict()
|
|
488
|
+
for m in modules:
|
|
489
|
+
stem = slug(Path(m.path).stem)
|
|
490
|
+
data = contents[m.path].encode("utf-8")
|
|
491
|
+
try:
|
|
492
|
+
ensure_no_secrets(contents[m.path])
|
|
493
|
+
files[f"references/code/{m.path}"] = data
|
|
494
|
+
resource, file_text = f"/references/code/{m.path}", f"[{m.path}](/references/code/{m.path})"
|
|
495
|
+
except UnsafeKnowledge:
|
|
496
|
+
resource, file_text = None, f"{m.path} ({WITHHELD})"
|
|
497
|
+
role = "the entry point (calls sf.start)" if m.starts else "a helper loaded before game.js"
|
|
498
|
+
body = f"""
|
|
499
|
+
# {m.path}
|
|
500
|
+
{file_text}: {m.lines} lines, {role}.
|
|
501
|
+
|
|
502
|
+
# Classes and scenes
|
|
503
|
+
{bullets(m.classes)}
|
|
504
|
+
Scene keys: {", ".join(f"`{s}`" for s in m.scenes) or "-"}
|
|
505
|
+
|
|
506
|
+
# Functions
|
|
507
|
+
{bullets(m.functions)}
|
|
508
|
+
|
|
509
|
+
# Events emitted
|
|
510
|
+
{bullets(checks_for(rec, m.events))}
|
|
511
|
+
|
|
512
|
+
# sf.state keys set
|
|
513
|
+
{", ".join(f"`{k}`" for k in m.state) or "-"}
|
|
514
|
+
|
|
515
|
+
# Input
|
|
516
|
+
{"Reads sf.input (arrows/WASD, action keys; the bot plays through it)." if m.reads_input else "Does not read sf.input."}
|
|
517
|
+
Keys read directly: {", ".join(m.keys) or "-"}. Flags: {", ".join(f"`sf.flags.{f}`" for f in m.flags) or "-"}.
|
|
518
|
+
{"Defines the autoplay bot policy." if m.autoplay else ""}
|
|
519
|
+
|
|
520
|
+
# Asset ids used
|
|
521
|
+
{", ".join(f"[{a}](/entities/{a}.md)" if a in rec.art or any(e.id == a for e in rec.design.entities) else f"`{a}`" for a in m.assets) or "-"}
|
|
522
|
+
Textures it makes itself: {", ".join(f"`{t}`" for t in m.textures) or "-"}
|
|
523
|
+
|
|
524
|
+
# Menus opened
|
|
525
|
+
{bullets(m.menus)}
|
|
526
|
+
"""
|
|
527
|
+
entries.append(make_entry(f"code/modules/{stem}", "Code Module", m.path,
|
|
528
|
+
f"{m.lines} lines; scenes {', '.join(m.scenes) or '-'}; "
|
|
529
|
+
f"{len(m.events)} events", ["code", "module", m.path, *m.scenes],
|
|
530
|
+
body, [source], resource=resource)) # fmt: skip
|
|
531
|
+
rows.append(f"| [{m.path}](/code/modules/{stem}.md) | {m.lines} | "
|
|
532
|
+
f"{', '.join(m.scenes) or '-'} | {', '.join(m.events) or '-'} |") # fmt: skip
|
|
533
|
+
total = sum(m.lines for m in modules)
|
|
534
|
+
body = f"""
|
|
535
|
+
# Files
|
|
536
|
+
Loaded in this order (`game.js` last). {total} lines in all.
|
|
537
|
+
|
|
538
|
+
| file | lines | scenes | events |
|
|
539
|
+
| --- | --- | --- | --- |
|
|
540
|
+
{chr(10).join(rows)}
|
|
541
|
+
|
|
542
|
+
# The Programmer's notes
|
|
543
|
+
{safe_text(rec.code.notes).strip() or "-"}
|
|
544
|
+
|
|
545
|
+
# Contract
|
|
546
|
+
The code reads input through `sf.input`, emits the [design's events](/design/events.md), keeps
|
|
547
|
+
`sf.state` up to date and uses only the [locked asset ids](/art/style.md).
|
|
548
|
+
"""
|
|
549
|
+
entries.insert(0, make_entry("code/overview", "Code Overview", f"{rec.design.title}: code",
|
|
550
|
+
f"{len(modules)} file(s), {total} lines", ["code", "overview"],
|
|
551
|
+
body, [source])) # fmt: skip
|
|
552
|
+
return entries, files
|
|
553
|
+
|
|
554
|
+
|
|
555
|
+
def step_schema() -> str:
|
|
556
|
+
rows = "\n".join(
|
|
557
|
+
f"| `{name}` | {f.description or ''} |" for name, f in Step.model_fields.items()
|
|
558
|
+
)
|
|
559
|
+
return f"| field | meaning |\n| --- | --- |\n{rows}"
|
|
560
|
+
|
|
561
|
+
|
|
562
|
+
def qa_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes], list[str]]:
|
|
563
|
+
"""The suite, one concept per test; returns the ids of tests that were dropped."""
|
|
564
|
+
if rec.qa is None:
|
|
565
|
+
return [], {}, []
|
|
566
|
+
b = rec.latest
|
|
567
|
+
results = {t["name"]: t for t in ((b.report.get("qa") or {}).get("tests", []) if b else [])}
|
|
568
|
+
files, resource = {}, None
|
|
569
|
+
if rec.qa_export:
|
|
570
|
+
try:
|
|
571
|
+
ensure_no_secrets(rec.qa_export.decode("utf-8"))
|
|
572
|
+
files["references/tests/test_game_qa.py"] = rec.qa_export
|
|
573
|
+
resource = "/references/tests/test_game_qa.py"
|
|
574
|
+
except UnsafeKnowledge:
|
|
575
|
+
pass
|
|
576
|
+
entries, rows = [], []
|
|
577
|
+
for test, since in zip(rec.qa.tests, rec.qa.versions, strict=False):
|
|
578
|
+
ident = f"qa/tests/{slug(test.name)}"
|
|
579
|
+
r = results.get(test.name)
|
|
580
|
+
if r is None:
|
|
581
|
+
result = "Not run yet."
|
|
582
|
+
elif r["passed"]:
|
|
583
|
+
result = f"Passed in build v{b.version}."
|
|
584
|
+
else:
|
|
585
|
+
result = f"FAILED in build v{b.version} at step {r['failed_step']}: {r['failure']}"
|
|
586
|
+
steps = "\n".join(f"{n}. {describe_step(s.model_dump())}"
|
|
587
|
+
for n, s in enumerate(test.steps, 1)) # fmt: skip
|
|
588
|
+
body = f"""
|
|
589
|
+
# {test.name}
|
|
590
|
+
{test.purpose}
|
|
591
|
+
|
|
592
|
+
The player {"cannot die (god mode: hurt, but HP stays at least 1)" if test.god else "can die"}.
|
|
593
|
+
Written for build [v{since}](/builds/v{since}.md) from the design; part of [the suite](/qa/suite.md).
|
|
594
|
+
|
|
595
|
+
# Steps
|
|
596
|
+
{steps}
|
|
597
|
+
|
|
598
|
+
# Last result
|
|
599
|
+
{result}
|
|
600
|
+
"""
|
|
601
|
+
if not any(x.version == since for x in rec.builds):
|
|
602
|
+
body = body.replace(f"[v{since}](/builds/v{since}.md)", f"v{since}")
|
|
603
|
+
entries.append(make_entry(ident, "QA Test", test.name, test.purpose,
|
|
604
|
+
["qa", "test", "god" if test.god else "lose-path"], body,
|
|
605
|
+
[b.source if b else ""])) # fmt: skip
|
|
606
|
+
mark = "-" if r is None else ("pass" if r["passed"] else "FAIL")
|
|
607
|
+
rows.append(f"| [{test.name}](/{ident}.md) | v{since} | {mark} |")
|
|
608
|
+
dropped = [f"qa/tests/{slug(n)}" for n in rec.qa.dropped]
|
|
609
|
+
body = f"""
|
|
610
|
+
# Tests
|
|
611
|
+
Written by the QA Playtester from the design (never the code) and played with real key presses
|
|
612
|
+
after the bot playtest; every build reruns the earlier builds' tests.
|
|
613
|
+
|
|
614
|
+
| test | since | last result |
|
|
615
|
+
| --- | --- | --- |
|
|
616
|
+
{chr(10).join(rows)}
|
|
617
|
+
|
|
618
|
+
Dropped by the human: {", ".join(rec.qa.dropped) or "-"}.
|
|
619
|
+
{"Notes: " + "; ".join(safe_text(n) for n in rec.qa.notes) if rec.qa.notes else ""}
|
|
620
|
+
|
|
621
|
+
# Export
|
|
622
|
+
{"[test_game_qa.py](/references/tests/test_game_qa.py): pytest + Playwright, runs next to the build." if resource else "No export yet."}
|
|
623
|
+
|
|
624
|
+
# Schema
|
|
625
|
+
A test is a name, a purpose, `god` (true: the player cannot die) and a list of steps. A step is
|
|
626
|
+
one flat record; the fields a step does not use stay empty.
|
|
627
|
+
|
|
628
|
+
{step_schema()}
|
|
629
|
+
"""
|
|
630
|
+
entries.insert(0, make_entry("qa/suite", "QA Suite", f"{rec.design.title}: QA tests",
|
|
631
|
+
f"{len(rec.qa.tests)} tests", ["qa", "suite"], body,
|
|
632
|
+
[b.source if b else ""], resource=resource)) # fmt: skip
|
|
633
|
+
return entries, files, dropped
|
|
634
|
+
|
|
635
|
+
|
|
636
|
+
def build_concepts(rec: GameRecord) -> list[Entry]:
|
|
637
|
+
answered = {}
|
|
638
|
+
for n, d in enumerate(rec.decisions, 1):
|
|
639
|
+
if d.asked_build and d.build:
|
|
640
|
+
answered.setdefault(d.build, n)
|
|
641
|
+
entries = []
|
|
642
|
+
for b in rec.builds:
|
|
643
|
+
r = b.report
|
|
644
|
+
attempts = "\n".join(
|
|
645
|
+
f"{a['attempt']}. {'passed' if a['passed'] else 'failed at ' + str(a.get('stage'))}"
|
|
646
|
+
+ (f" (repaired with {a['repair']})" if a.get("repair") else "")
|
|
647
|
+
for a in r.get("attempts", [])
|
|
648
|
+
)
|
|
649
|
+
qa = r.get("qa") or {}
|
|
650
|
+
rv = r.get("art_review") or {}
|
|
651
|
+
review = (
|
|
652
|
+
f"{rv.get('reviewed_by', '-')}; scores "
|
|
653
|
+
+ ", ".join(f"{k} {v}/5" for k, v in (rv.get("scores") or {}).items())
|
|
654
|
+
+ f"; {len(rv.get('issues', []))} issue(s), "
|
|
655
|
+
f"{sum(bool(f.get('fixed')) for f in rv.get('fixes', []))} fixed"
|
|
656
|
+
if rv
|
|
657
|
+
else "-"
|
|
658
|
+
)
|
|
659
|
+
calls = r.get("model_calls") or {}
|
|
660
|
+
rev = r.get("revision") or {}
|
|
661
|
+
why = (
|
|
662
|
+
f"[Decision {answered[b.version]}](/decisions/{answered[b.version]}.md) asked for it."
|
|
663
|
+
if b.version in answered
|
|
664
|
+
else "The first build of the approved design."
|
|
665
|
+
)
|
|
666
|
+
changed = bullets([
|
|
667
|
+
f"design: {safe_text(rev['design_changes'])}" if rev.get("design_changes") else "",
|
|
668
|
+
"art redrawn: " + ", ".join(c["entity"] for c in rev.get("art_changes", []))
|
|
669
|
+
if rev.get("art_changes") else "",
|
|
670
|
+
f"code: {safe_text(rev['code_instructions'])}" if rev.get("code_instructions") else "",
|
|
671
|
+
"QA tests dropped: " + ", ".join(rev["drop_qa_tests"]) if rev.get("drop_qa_tests") else "",
|
|
672
|
+
f"story: {safe_text(rev['story_changes'])}" if rev.get("story_changes") else "",
|
|
673
|
+
] if rev else [], "- nothing: a new build") # fmt: skip
|
|
674
|
+
changed = "\n".join(line for line in changed.splitlines() if line.strip() != "-")
|
|
675
|
+
# The build before it (a build a Go back stopped has no page: numbers can skip).
|
|
676
|
+
before = max((x.version for x in rec.builds if x.version < b.version), default=None)
|
|
677
|
+
prev = f"Previous: [v{before}](/builds/v{before}.md). " if before else ""
|
|
678
|
+
body = f"""
|
|
679
|
+
# Build v{b.version}
|
|
680
|
+
{"All design checks pass." if r.get("passed") else "Some design checks FAIL."} Design
|
|
681
|
+
v{r.get("design_version", 1)}, written by {r.get("chosen_by", "-")}. {prev}
|
|
682
|
+
|
|
683
|
+
# Checks
|
|
684
|
+
{bullets(("ok " if c.get("ok") else "FAIL ") + f"`{c['event']}` {c.get('count', '?')}/{c.get('min_count', '?')}" for c in r.get("checks", []))}
|
|
685
|
+
{bullets(safe_text(p) for p in r.get("problems", [])) if r.get("problems") else ""}
|
|
686
|
+
|
|
687
|
+
# Attempts
|
|
688
|
+
{attempts or "-"}
|
|
689
|
+
|
|
690
|
+
# QA
|
|
691
|
+
{f"{qa['passed']}/{qa['passed'] + qa['failed']} tests pass; see [the suite](/qa/suite.md)." if qa else "No QA tests."}
|
|
692
|
+
|
|
693
|
+
# Art review
|
|
694
|
+
{review}
|
|
695
|
+
|
|
696
|
+
# Cost
|
|
697
|
+
{calls.get("chat", 0)} Spark and {calls.get("image", 0)} Muse Image calls, about ${calls.get("estimated_cost_usd", 0)}.
|
|
698
|
+
|
|
699
|
+
# What changed and why
|
|
700
|
+
{why}
|
|
701
|
+
{changed}
|
|
702
|
+
"""
|
|
703
|
+
entries.append(make_entry(f"builds/v{b.version}", "Build", f"Build v{b.version}",
|
|
704
|
+
("passed" if r.get("passed") else "failed")
|
|
705
|
+
+ (f"; QA {qa['passed']}/{qa['passed'] + qa['failed']}" if qa else ""),
|
|
706
|
+
["build", f"v{b.version}"], body, [b.source])) # fmt: skip
|
|
707
|
+
return entries
|
|
708
|
+
|
|
709
|
+
|
|
710
|
+
def decision_concepts(rec: GameRecord) -> list[Entry]:
|
|
711
|
+
known = {b.version for b in rec.builds}
|
|
712
|
+
entries = []
|
|
713
|
+
for n, d in enumerate(rec.decisions, 1):
|
|
714
|
+
if not d.build:
|
|
715
|
+
build = "-"
|
|
716
|
+
elif d.build not in known:
|
|
717
|
+
build = f"Build v{d.build} answers it (not built yet)."
|
|
718
|
+
elif d.asked_build:
|
|
719
|
+
build = f"[Build v{d.build}](/builds/v{d.build}.md) answered it."
|
|
720
|
+
else:
|
|
721
|
+
build = f"It was about [build v{d.build}](/builds/v{d.build}.md)."
|
|
722
|
+
words = safe_text(d.words).strip()
|
|
723
|
+
body = f"""
|
|
724
|
+
# {d.gate}: {d.outcome}
|
|
725
|
+
|
|
726
|
+
# The human's words
|
|
727
|
+
{"> " + words.replace(chr(10), chr(10) + "> ") if words else "(no words: approved as shown)"}
|
|
728
|
+
|
|
729
|
+
# What it changed
|
|
730
|
+
{safe_text(d.changed) or "-"}
|
|
731
|
+
|
|
732
|
+
# Answered by
|
|
733
|
+
{build}
|
|
734
|
+
"""
|
|
735
|
+
entries.append(make_entry(f"decisions/{n}", "Decision", f"Decision {n}: {d.gate}",
|
|
736
|
+
f"{d.outcome}" + (f": {words[:120]}" if words else ""),
|
|
737
|
+
["decision", d.outcome], body, ["gates"])) # fmt: skip
|
|
738
|
+
return entries
|
|
739
|
+
|
|
740
|
+
|
|
741
|
+
def story_concepts(rec: GameRecord) -> list[Entry]:
|
|
742
|
+
story, src = rec.story, rec.story_source
|
|
743
|
+
if story is None:
|
|
744
|
+
return []
|
|
745
|
+
entities = {e.id: e for e in rec.design.entities}
|
|
746
|
+
cast = "\n".join(f"- [{c.name}](/characters/{c.entity}.md) ({c.role}): {c.look}"
|
|
747
|
+
for c in story.characters) # fmt: skip
|
|
748
|
+
places = "\n".join(f"- [{loc.name}](/world/{loc.id}.md): {loc.description}"
|
|
749
|
+
for loc in story.locations) # fmt: skip
|
|
750
|
+
overview = f"""
|
|
751
|
+
# Logline
|
|
752
|
+
{story.logline}
|
|
753
|
+
|
|
754
|
+
# Premise
|
|
755
|
+
{story.premise}
|
|
756
|
+
|
|
757
|
+
# Setting
|
|
758
|
+
{story.setting}
|
|
759
|
+
|
|
760
|
+
# Tone and themes
|
|
761
|
+
{story.tone}. Themes: {", ".join(story.themes) or "-"}.
|
|
762
|
+
|
|
763
|
+
# Characters
|
|
764
|
+
{cast}
|
|
765
|
+
|
|
766
|
+
# Locations
|
|
767
|
+
{places or "- (none)"}
|
|
768
|
+
|
|
769
|
+
The [arc](/story/arc.md) and the [canon](/story/canon.md) no later level may break.
|
|
770
|
+
"""
|
|
771
|
+
arc = "\n".join(f"{n}. {beat}" + (" (level 1: the current game)" if n == 1 else " (planned)")
|
|
772
|
+
for n, beat in enumerate(story.arc, 1)) # fmt: skip
|
|
773
|
+
entries = [
|
|
774
|
+
make_entry("story/overview", "Story", f"{story.title}: the story", story.logline,
|
|
775
|
+
["story", *story.themes], overview, [src]),
|
|
776
|
+
make_entry("story/arc", "Story Arc", f"{story.title}: the arc",
|
|
777
|
+
f"{len(story.arc)} beats; beat 1 is the current game", ["story", "arc", "levels"],
|
|
778
|
+
f"# Beats\n{arc}", [src]),
|
|
779
|
+
make_entry("story/canon", "Canon", f"{story.title}: canon",
|
|
780
|
+
"Facts no later level, menu or cutscene may break", ["story", "canon"],
|
|
781
|
+
f"# Never break\n{bullets(story.canon)}", [src]),
|
|
782
|
+
] # fmt: skip
|
|
783
|
+
for loc in story.locations:
|
|
784
|
+
body = f"# {loc.name}\n{loc.description}\n\n# Mood\n{loc.mood}"
|
|
785
|
+
entries.append(make_entry(f"world/{loc.id}", "Location", loc.name, loc.description,
|
|
786
|
+
["location", loc.id], body, [src])) # fmt: skip
|
|
787
|
+
for c in story.characters:
|
|
788
|
+
e = entities.get(c.entity)
|
|
789
|
+
if e is None:
|
|
790
|
+
continue
|
|
791
|
+
art = (f"\n\n[Locked art](/art/assets/{c.entity}.md)."
|
|
792
|
+
if c.entity in rec.art else "No art yet.") # fmt: skip
|
|
793
|
+
body = f"""
|
|
794
|
+
# Who
|
|
795
|
+
{c.name}, {c.role}. {c.look}.
|
|
796
|
+
|
|
797
|
+
# Personality
|
|
798
|
+
{c.personality}
|
|
799
|
+
|
|
800
|
+
# Goal
|
|
801
|
+
{c.goal}
|
|
802
|
+
|
|
803
|
+
# Backstory
|
|
804
|
+
{c.backstory}
|
|
805
|
+
|
|
806
|
+
# Relationships
|
|
807
|
+
{c.relationships or "-"}
|
|
808
|
+
|
|
809
|
+
# In play
|
|
810
|
+
[Entity `{e.id}`](/entities/{e.id}.md): {e.role}, {e.behaviour}. Abilities: {c.abilities}.
|
|
811
|
+
|
|
812
|
+
# Art
|
|
813
|
+
{art}
|
|
814
|
+
"""
|
|
815
|
+
entries.append(make_entry(f"characters/{c.entity}", "Character", c.name,
|
|
816
|
+
f"{c.role}: {c.look}", ["character", c.role, e.role, e.id], body,
|
|
817
|
+
[src, rec.design_source])) # fmt: skip
|
|
818
|
+
return entries
|
|
819
|
+
|
|
820
|
+
|
|
821
|
+
def web_page(url: str) -> str:
|
|
822
|
+
"""A reference URL as it may go into the record ('' when it looks like a secret)."""
|
|
823
|
+
return url if url and safe_text(url) == url else ""
|
|
824
|
+
|
|
825
|
+
|
|
826
|
+
def research_concepts(rec: GameRecord) -> list[Entry]:
|
|
827
|
+
record, src = rec.research, rec.research_source
|
|
828
|
+
if record is None:
|
|
829
|
+
return []
|
|
830
|
+
r = record.research
|
|
831
|
+
refs, entries = [], []
|
|
832
|
+
for ref, ok in record.references:
|
|
833
|
+
ident = f"research/references/{slug(ref.title)}"
|
|
834
|
+
url = web_page(ref.url)
|
|
835
|
+
checked = ("a search returned this page" if ok else
|
|
836
|
+
"NOT among the pages the searches returned: check it before trusting it"
|
|
837
|
+
if url else "no page") # fmt: skip
|
|
838
|
+
refs.append(f"- [{ref.title}](/{ident}.md): {ref.learn}")
|
|
839
|
+
body = f"""
|
|
840
|
+
# What to learn
|
|
841
|
+
{ref.learn}
|
|
842
|
+
|
|
843
|
+
# Page
|
|
844
|
+
{f"<{url}>" if url else "-"} ({checked})
|
|
845
|
+
|
|
846
|
+
# Use
|
|
847
|
+
A reference teaches patterns only: never copy its levels, characters, story or art.
|
|
848
|
+
"""
|
|
849
|
+
entry = make_entry(ident, "Reference Game", ref.title, ref.learn,
|
|
850
|
+
["research", "reference", "verified" if ok else "unverified"], body, [src]) # fmt: skip
|
|
851
|
+
if url:
|
|
852
|
+
entry.metadata.sources.append(Source(resource=url, title=ref.title))
|
|
853
|
+
entries.append(entry)
|
|
854
|
+
pats = "\n".join(f"- **{x.name}**: {x.how} For this game: {x.use}" for x in r.patterns)
|
|
855
|
+
feel = "\n".join(f"| {f.name} | {f.value} | {f.why} |" for f in r.feel)
|
|
856
|
+
queries = ", ".join(f"`{q}`" for q in record.queries)
|
|
857
|
+
body = f"""
|
|
858
|
+
# How it was made
|
|
859
|
+
{record.by}; {record.searches} search call(s){f": {queries}" if queries else ""}. {len(record.sources)} pages returned.
|
|
860
|
+
|
|
861
|
+
# Reference games
|
|
862
|
+
{chr(10).join(refs) or "- (none)"}
|
|
863
|
+
|
|
864
|
+
# Patterns
|
|
865
|
+
{pats or "- (none)"}
|
|
866
|
+
|
|
867
|
+
# Feel numbers players expect
|
|
868
|
+
| what | value | why |
|
|
869
|
+
| --- | --- | --- |
|
|
870
|
+
{feel}
|
|
871
|
+
|
|
872
|
+
# Pitfalls
|
|
873
|
+
{bullets(r.pitfalls)}
|
|
874
|
+
"""
|
|
875
|
+
overview = make_entry("research/overview", "Research", f"{rec.design.title}: research",
|
|
876
|
+
f"{len(r.references)} reference games, {len(r.patterns)} patterns",
|
|
877
|
+
["research", "patterns", "feel"], body, [src]) # fmt: skip
|
|
878
|
+
for ref, ok in record.references:
|
|
879
|
+
if ok and (url := web_page(ref.url)):
|
|
880
|
+
overview.metadata.sources.append(Source(resource=url, title=ref.title))
|
|
881
|
+
return [overview, *entries]
|
|
882
|
+
|
|
883
|
+
|
|
884
|
+
def plan_concepts(rec: GameRecord) -> list[Entry]:
|
|
885
|
+
record, src = rec.plan, rec.plan_source
|
|
886
|
+
if record is None:
|
|
887
|
+
return []
|
|
888
|
+
p, k, m, title = record.plan, record.kinematics, record.plan.movement, rec.design.title
|
|
889
|
+
covers = {}
|
|
890
|
+
for c in p.coverage:
|
|
891
|
+
covers.setdefault(c.requirement, []).append(f"{', '.join(c.parts)}: {c.how}")
|
|
892
|
+
reqs = "\n".join(f"- **{r.id}** \"{safe_text(r.text)}\": " + ("; ".join(covers.get(r.id, []))
|
|
893
|
+
or "not covered") for r in p.requirements) # fmt: skip
|
|
894
|
+
levels = "\n".join(f"- [Level {lv.n}: {lv.name}](/plan/levels/{lv.n}.md): {lv.new_idea}"
|
|
895
|
+
for lv in p.levels) # fmt: skip
|
|
896
|
+
overview = f"""
|
|
897
|
+
# Requirements (the human's words)
|
|
898
|
+
{reqs or "- (none)"}
|
|
899
|
+
|
|
900
|
+
# Style
|
|
901
|
+
{p.style}
|
|
902
|
+
|
|
903
|
+
# Parts
|
|
904
|
+
- [Movement](/plan/movement.md): numbers and the jump physics code derived from them
|
|
905
|
+
- [Abilities, mechanics and challenges](/plan/mechanics.md)
|
|
906
|
+
- [Feel and animations](/plan/feel.md)
|
|
907
|
+
|
|
908
|
+
# Levels
|
|
909
|
+
{levels or "- (none)"}
|
|
910
|
+
|
|
911
|
+
# Risks
|
|
912
|
+
{bullets(p.risks)}
|
|
913
|
+
|
|
914
|
+
# Problems code found
|
|
915
|
+
{bullets(record.problems, "- none")}
|
|
916
|
+
"""
|
|
917
|
+
rows = [("move_speed", m.move_speed, "tiles/s", "running speed"),
|
|
918
|
+
("jump_height", m.jump_height, "tiles", "the highest jump; 0 = no jump"),
|
|
919
|
+
("air_time", m.air_time, "s", "take-off to landing at the same height"),
|
|
920
|
+
("dash_distance", m.dash_distance, "tiles", "0 = no dash"),
|
|
921
|
+
("dash_cooldown", m.dash_cooldown, "s", "time between dashes"),
|
|
922
|
+
("coyote_time", m.coyote_time, "s", "a jump still works after leaving a ledge")] # fmt: skip
|
|
923
|
+
if k:
|
|
924
|
+
rows += [("gravity", k.gravity, "px/s^2", "8 * jump height / air time^2 (code)"),
|
|
925
|
+
("jump_velocity", k.jump_velocity, "px/s", "take-off speed, 4h / T (code)"),
|
|
926
|
+
("jump_distance", k.jump_distance, "px", "covered in the air at full speed (code)"),
|
|
927
|
+
("max_rise", k.max_rise, "tiles", "the highest platform top a jump reaches (code)"),
|
|
928
|
+
("max_gap", k.max_gap, "tiles", "the widest gap a running jump clears (code)"),
|
|
929
|
+
("max_gap_with_dash", k.max_gap_with_dash, "tiles", "with one dash in the air (code)"),
|
|
930
|
+
("coyote", k.coyote, "px", "ledge forgiveness at full speed (code)")] # fmt: skip
|
|
931
|
+
table = "\n".join(f"| `{n}` | {v:g} | {u} | {w} |" for n, v, u, w in rows)
|
|
932
|
+
movement = f"""
|
|
933
|
+
# Movement
|
|
934
|
+
{m.move_speed:g} tiles/s; {f"jump {m.jump_height:g} tiles in {m.air_time:g} s" if k else "no jump"}; {f"dash {m.dash_distance:g} tiles every {m.dash_cooldown:g} s" if m.dash_distance else "no dash"}. Tiles are {k.tile if k else 16} px.
|
|
935
|
+
|
|
936
|
+
# Schema
|
|
937
|
+
| field | value | unit | meaning |
|
|
938
|
+
| --- | --- | --- | --- |
|
|
939
|
+
{table}
|
|
940
|
+
|
|
941
|
+
Levels are checked against these numbers: a platform higher than `max_rise` or a gap wider than
|
|
942
|
+
`max_gap` (`max_gap_with_dash` once the dash is available) cannot be crossed.
|
|
943
|
+
"""
|
|
944
|
+
abilities = "\n".join(f"- **{a.name}**: {a.does}" + (f" ({a.numbers})" if a.numbers else "")
|
|
945
|
+
+ f"; from {a.unlocked_by}" for a in p.abilities) # fmt: skip
|
|
946
|
+
mechanics = "\n".join(f"- **{x.name}**: {x.what} For: {x.purpose}" for x in p.mechanics)
|
|
947
|
+
challenges = "\n".join(f"- **{c.name}**: {c.tests}" + (f" Needs: {', '.join(c.needs)}." if c.needs else "")
|
|
948
|
+
for c in p.challenges) # fmt: skip
|
|
949
|
+
feel = "\n".join(f"| {f.event} | {f.see} | {f.hear or '-'} |" for f in p.feel)
|
|
950
|
+
anims = "\n".join(f"| {a.entity} | {r.name} | {r.frames} | {'loop' if r.loop else 'once'} | {r.shows} |"
|
|
951
|
+
for a in p.animations for r in a.rows) # fmt: skip
|
|
952
|
+
entries = [
|
|
953
|
+
make_entry("plan/overview", "Game Plan", f"{title}: game plan",
|
|
954
|
+
f"{len(p.requirements)} requirements, {len(p.levels)} levels",
|
|
955
|
+
["plan", "requirements"], overview, [src]),
|
|
956
|
+
make_entry("plan/movement", "Movement", f"{title}: movement and kinematics",
|
|
957
|
+
f"{m.move_speed:g} tiles/s" + (f", jump {m.jump_height:g} tiles, gaps up to {k.max_gap} tiles" if k else ""),
|
|
958
|
+
["plan", "movement", "kinematics"], movement, [src]),
|
|
959
|
+
make_entry("plan/mechanics", "Mechanics", f"{title}: abilities, mechanics, challenges",
|
|
960
|
+
f"{len(p.abilities)} abilities, {len(p.mechanics)} mechanics, {len(p.challenges)} challenges",
|
|
961
|
+
["plan", "mechanics", "abilities", "challenges"],
|
|
962
|
+
f"# Abilities\n{abilities or '- (none)'}\n\n# Mechanics\n{mechanics or '- (none)'}\n\n"
|
|
963
|
+
f"# Challenge vocabulary\n{challenges or '- (none)'}", [src]),
|
|
964
|
+
make_entry("plan/feel", "Feel", f"{title}: feel and animations",
|
|
965
|
+
"what the player sees and hears; animation rows per entity", ["plan", "feel", "animation"],
|
|
966
|
+
"# Feedback\n| event | see | hear |\n| --- | --- | --- |\n" + feel
|
|
967
|
+
+ "\n\n# Animations\n| entity | row | frames | plays | shows |\n| --- | --- | --- | --- | --- |\n"
|
|
968
|
+
+ anims, [src]),
|
|
969
|
+
] # fmt: skip
|
|
970
|
+
vocabulary = {c.name.casefold(): c for c in p.challenges}
|
|
971
|
+
for lv in p.levels:
|
|
972
|
+
tests = "\n".join(f"- **{name}**: " + (vocabulary[name.casefold()].tests
|
|
973
|
+
if name.casefold() in vocabulary else "(not in the vocabulary)")
|
|
974
|
+
for name in lv.challenges) # fmt: skip
|
|
975
|
+
body = f"""
|
|
976
|
+
# Teaches
|
|
977
|
+
{lv.teaching_goal}
|
|
978
|
+
|
|
979
|
+
# New idea
|
|
980
|
+
{lv.new_idea}
|
|
981
|
+
|
|
982
|
+
# Challenges
|
|
983
|
+
{tests or "- (none)"}
|
|
984
|
+
|
|
985
|
+
# Needs
|
|
986
|
+
{", ".join(lv.abilities) or "-"}. See [movement](/plan/movement.md) for what a jump can cross.
|
|
987
|
+
|
|
988
|
+
# Difficulty
|
|
989
|
+
{lv.difficulty} of 10
|
|
990
|
+
"""
|
|
991
|
+
entries.append(make_entry(f"plan/levels/{lv.n}", "Level Plan", f"Level {lv.n}: {lv.name}",
|
|
992
|
+
f"teaches {lv.teaching_goal}; new: {lv.new_idea}",
|
|
993
|
+
["plan", "level", f"level-{lv.n}"], body, [src])) # fmt: skip
|
|
994
|
+
return entries
|
|
995
|
+
|
|
996
|
+
|
|
997
|
+
LEVEL_SCHEMA = """| field | meaning |
|
|
998
|
+
| --- | --- |
|
|
999
|
+
| `n`, `name` | the level's number and name |
|
|
1000
|
+
| `cols`, `rows` | the map's size in tiles (16 px at scale 1) |
|
|
1001
|
+
| `map` | the tile rows, top first; a character is a tile in `tiles`, ' ' is empty |
|
|
1002
|
+
| `tiles` | character -> `kind` (solid, one_way, hazard) and the `entity` that draws it |
|
|
1003
|
+
| `things` | `id`, `kind` (crate, breakable, pickup, enemy, checkpoint, exit), `entity`, `col`, `row` (bottom cell), `cells`, `needs` (ability that opens or beats it), `opened_by` (touch, dash, never), `holds` (what a crate drops), `gives` (the ability a pickup gives), `patrol` (an enemy's columns) |
|
|
1004
|
+
| `start`, `player` | the player's start cell and entity |
|
|
1005
|
+
| `route` | the bot's steps code found: walk, jump or fall (take-off `x0`, speed `vx`, `wait`, `dash`), touch, dash, collect, exit |
|
|
1006
|
+
| `exclusive` | abilities that replace each other |"""
|
|
1007
|
+
|
|
1008
|
+
|
|
1009
|
+
def level_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
|
|
1010
|
+
"""levels/<n>: each level as data (L2.3), its map preview and what code and the bot found."""
|
|
1011
|
+
entries, files = [], {}
|
|
1012
|
+
plans = {lv.n: lv for lv in rec.plan.plan.levels} if rec.plan else {}
|
|
1013
|
+
for r in rec.levels:
|
|
1014
|
+
s, n = r.spec, r.spec.n
|
|
1015
|
+
lp = plans.get(n)
|
|
1016
|
+
play = rec.level_play.get(n) or {}
|
|
1017
|
+
resource = None
|
|
1018
|
+
if n in rec.level_files:
|
|
1019
|
+
files[f"references/levels/{n}.json"] = rec.level_files[n]
|
|
1020
|
+
resource = f"/references/levels/{n}.json"
|
|
1021
|
+
if n in rec.level_previews:
|
|
1022
|
+
files[f"references/levels/{n}.png"] = rec.level_previews[n]
|
|
1023
|
+
# A thing with no entity of its own (a checkpoint the design has no art for) is drawn
|
|
1024
|
+
# by the SDK: no link (live 2026-11-03: /entities/.md failed the bundle's validation).
|
|
1025
|
+
ids = {x.id for x in rec.design.entities}
|
|
1026
|
+
shows = lambda eid: f"[{eid}](/entities/{eid}.md)" if eid in ids else (f"`{eid}`" if eid else "drawn by the SDK")
|
|
1027
|
+
legend = "\n".join(f"| `{e.char}` | {e.kind} | {shows(e.entity)} | {e.needs or '-'} | "
|
|
1028
|
+
f"{e.opened_by} | {e.holds or '-'} | {e.gives or '-'} |" for e in s.legend) # fmt: skip
|
|
1029
|
+
route = ", ".join(st["do"] + (f" {st['thing']}" if st.get("thing") else "")
|
|
1030
|
+
for st in r.route if st["do"] != "walk") # fmt: skip
|
|
1031
|
+
played = (f"cleared by the bot in {play.get('game_seconds')} game seconds" if play.get("cleared")
|
|
1032
|
+
else f"not cleared ({play.get('ended')})" if play else "not played yet") # fmt: skip
|
|
1033
|
+
body = f"""
|
|
1034
|
+
# Plan
|
|
1035
|
+
{f"Teaches {lp.teaching_goal}. New idea: {lp.new_idea}. [Level plan](/plan/levels/{n}.md)" if lp else "-"}
|
|
1036
|
+
|
|
1037
|
+
# Map
|
|
1038
|
+
{s.notes.strip() or "-"}
|
|
1039
|
+
|
|
1040
|
+
""" + ("[Map preview](/references/levels/" + str(n) + ".png) (the bot's route as a line)\n\n" if n in rec.level_previews else "") + f"""```
|
|
1041
|
+
{chr(10).join(s.rows)}
|
|
1042
|
+
```
|
|
1043
|
+
|
|
1044
|
+
| char | kind | entity | needs | opened by | holds | gives |
|
|
1045
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
1046
|
+
{legend}
|
|
1047
|
+
|
|
1048
|
+
Challenges: {", ".join(f"{c.name} (column {c.column})" for c in s.challenges) or "-"}. Events: {", ".join(s.events) or "-"}.
|
|
1049
|
+
|
|
1050
|
+
# Code's check
|
|
1051
|
+
{"The exit can be reached with the plan's movement" if r.solved else "The exit CANNOT be reached"}; difficulty {r.difficulty:g} (code's measure). Bot route: {route or "-"}.
|
|
1052
|
+
|
|
1053
|
+
Problems:
|
|
1054
|
+
{bullets([safe_text(p) for p in r.problems], "- none")}
|
|
1055
|
+
|
|
1056
|
+
# Playtest
|
|
1057
|
+
{played}{"; missing events: " + ", ".join(play.get("missing", [])) if play.get("missing") else ""}
|
|
1058
|
+
|
|
1059
|
+
# Schema
|
|
1060
|
+
{LEVEL_SCHEMA}
|
|
1061
|
+
"""
|
|
1062
|
+
entries.append(make_entry(f"levels/{n}", "Level", f"Level {n}: {s.name}",
|
|
1063
|
+
f"{len(s.rows[0]) if s.rows else 0}x{len(s.rows)} tiles; "
|
|
1064
|
+
+ (f"teaches {lp.teaching_goal}" if lp else s.notes),
|
|
1065
|
+
["level", f"level-{n}"], body, [rec.levels_source], resource)) # fmt: skip
|
|
1066
|
+
return entries, files
|
|
1067
|
+
|
|
1068
|
+
|
|
1069
|
+
def structure_concept(rec: GameRecord) -> list[Entry]:
|
|
1070
|
+
"""design/structure (L2.5): the levels in order, what carries over and what is saved."""
|
|
1071
|
+
s = rec.structure
|
|
1072
|
+
if s is None:
|
|
1073
|
+
return []
|
|
1074
|
+
links = ", ".join(f"[level {lv.n}](/levels/{lv.n}.md)" for lv in s.levels
|
|
1075
|
+
if any(r.spec.n == lv.n for r in rec.levels)) # fmt: skip
|
|
1076
|
+
body = structure_markdown(s).replace("# Game structure", "# Structure", 1)
|
|
1077
|
+
if links:
|
|
1078
|
+
body += f"\nLevels as data: {links}\n"
|
|
1079
|
+
if rec.menus:
|
|
1080
|
+
body += "\nThe SDK's flow plays it: see [the menus](/menus/overview.md).\n"
|
|
1081
|
+
return [make_entry("design/structure", "Game Structure", f"{rec.design.title}: structure",
|
|
1082
|
+
f"{len(s.levels)} level(s); win: {s.win}", ["design", "structure", "levels"],
|
|
1083
|
+
body, [rec.structure_source])] # fmt: skip
|
|
1084
|
+
|
|
1085
|
+
|
|
1086
|
+
MENUS_SCHEMA = """# Schema
|
|
1087
|
+
`/references/menus.json` (window.SF_MENUS, what the SDK's flow loads):
|
|
1088
|
+
* `title`, `subtitle`: the title screen's words (the SDK draws all text).
|
|
1089
|
+
* `theme`: `panel`, `border`, `text`, `highlight`, `dim` (#RRGGBB, fitted by code to the locked
|
|
1090
|
+
art's measured colours, text contrast checked) and `style` (framed, double, solid).
|
|
1091
|
+
* `screens.<id>`: `title`, `subtitle`, `items[]` (`label`, `action`). Screen ids: title, main,
|
|
1092
|
+
pause, settings, controls, credits, level_select, results, game_over, victory.
|
|
1093
|
+
* `levels[]`: `n`, `name`, `goal` (the structure); `can_lose`; `controls[]`; `credits[]`;
|
|
1094
|
+
`difficulty` (name -> the multiplier the game reads as sf.settings.multiplier); `art`
|
|
1095
|
+
(`title`, `emblem`: image ids in assets.json, role menu).
|
|
1096
|
+
Actions: """ + ", ".join(f"`{a}` ({w})" for a, w in ACTIONS.items()) + "."
|
|
1097
|
+
|
|
1098
|
+
|
|
1099
|
+
def menu_concepts(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
|
|
1100
|
+
"""menus/overview and menus/<screen> (L2.5): the menus as data, their screenshots and the
|
|
1101
|
+
title art."""
|
|
1102
|
+
m = rec.menus
|
|
1103
|
+
if m is None:
|
|
1104
|
+
return [], {}
|
|
1105
|
+
files, resource = {}, None
|
|
1106
|
+
if rec.menus_file:
|
|
1107
|
+
files["references/menus.json"] = rec.menus_file
|
|
1108
|
+
resource = "/references/menus.json"
|
|
1109
|
+
pictures = ""
|
|
1110
|
+
for part, name in (("title-art", "title"), ("emblem", "emblem")):
|
|
1111
|
+
if part in rec.title_art:
|
|
1112
|
+
files[f"references/art/{name}.png"] = rec.title_art[part]
|
|
1113
|
+
pictures += f" "
|
|
1114
|
+
report = (rec.latest.report.get("menus") or {}) if rec.latest else {}
|
|
1115
|
+
art_source = (report.get("title_art") or {}).get("source", "")
|
|
1116
|
+
screens = "\n".join(f"- [{s.id}](/menus/{s.id}.md): " + (", ".join(i.label for i in s.items) or "-")
|
|
1117
|
+
for s in m.spec.screens) # fmt: skip
|
|
1118
|
+
body = (
|
|
1119
|
+
f"{pictures}\n\n" if pictures else ""
|
|
1120
|
+
) + menus_markdown(m.spec, m.notes, m.problems).replace(f"# Menus: {m.spec.title}", "# Menus", 1) + f"""
|
|
1121
|
+
# Title art
|
|
1122
|
+
{art_source or "(not built yet)"}
|
|
1123
|
+
|
|
1124
|
+
# Screens
|
|
1125
|
+
{screens}
|
|
1126
|
+
|
|
1127
|
+
# Written by
|
|
1128
|
+
{m.by}{" (asked again once with code's problems)" if m.retried else ""}; {m.why or "-"}
|
|
1129
|
+
|
|
1130
|
+
{MENUS_SCHEMA}
|
|
1131
|
+
"""
|
|
1132
|
+
entries = [make_entry("menus/overview", "Menus", f"{rec.design.title}: menus",
|
|
1133
|
+
f"{len(m.spec.screens)} screens rendered by the SDK; theme "
|
|
1134
|
+
f"{m.spec.theme.panel} / {m.spec.theme.highlight}",
|
|
1135
|
+
["menus", "ui", "title"], body, [rec.menus_source], resource)] # fmt: skip
|
|
1136
|
+
for s in m.spec.screens:
|
|
1137
|
+
shot = ""
|
|
1138
|
+
if s.id in rec.menu_shots:
|
|
1139
|
+
files[f"references/menus/{s.id}.png"] = rec.menu_shots[s.id]
|
|
1140
|
+
shot = f"\n\n"
|
|
1141
|
+
items = "\n".join(f"{i}. {it.label} ({it.action}: {ACTIONS.get(it.action, '?')})"
|
|
1142
|
+
for i, it in enumerate(s.items, 1)) or "- (no items)" # fmt: skip
|
|
1143
|
+
body = f"""{shot}# {s.title or m.spec.title}
|
|
1144
|
+
{s.subtitle or ""}
|
|
1145
|
+
|
|
1146
|
+
# Items
|
|
1147
|
+
{items}
|
|
1148
|
+
|
|
1149
|
+
Part of [the menus](/menus/overview.md).
|
|
1150
|
+
"""
|
|
1151
|
+
entries.append(make_entry(f"menus/{s.id}", "Menu Screen", f"Menu: {s.id.replace('_', ' ')}",
|
|
1152
|
+
f"{len(s.items)} items: " + ", ".join(i.label for i in s.items),
|
|
1153
|
+
["menus", s.id], body, [rec.menus_source], resource)) # fmt: skip
|
|
1154
|
+
return entries, files
|
|
1155
|
+
|
|
1156
|
+
|
|
1157
|
+
def bundle(rec: GameRecord) -> tuple[list[Entry], dict[str, bytes]]:
|
|
1158
|
+
"""Every concept and file of a game's record."""
|
|
1159
|
+
modules = read_code(rec.code.as_dict()) if rec.code else []
|
|
1160
|
+
art, art_files = art_concepts(rec)
|
|
1161
|
+
code, code_files = code_concepts(rec, modules)
|
|
1162
|
+
qa, qa_files, _ = qa_concepts(rec)
|
|
1163
|
+
levels, level_files = level_concepts(rec)
|
|
1164
|
+
menus, menu_files = menu_concepts(rec)
|
|
1165
|
+
entries = [game_concept(rec, modules), rules_concept(rec), events_concept(rec, modules),
|
|
1166
|
+
*entity_concepts(rec), *art, *code, *qa, *build_concepts(rec),
|
|
1167
|
+
*decision_concepts(rec), *story_concepts(rec), *research_concepts(rec),
|
|
1168
|
+
*plan_concepts(rec), *levels, *structure_concept(rec), *menus] # fmt: skip
|
|
1169
|
+
return entries, art_files | code_files | qa_files | level_files | menu_files
|
|
1170
|
+
|
|
1171
|
+
|
|
1172
|
+
def portrait_of(sheet: bytes, frame: tuple[int, int] | None) -> Filled:
|
|
1173
|
+
"""A Filled stand-in for art read back from files (sync from a run or a folder)."""
|
|
1174
|
+
kind = "sprite" if frame else "image"
|
|
1175
|
+
if frame is None:
|
|
1176
|
+
w, h = Image.open(io.BytesIO(sheet)).size
|
|
1177
|
+
frame = (w, h)
|
|
1178
|
+
return Filled(png=sheet, source="", reasons=[], meta={"frame": list(frame)}, kind=kind)
|