zwitschi/security-game
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
a2a0ded527b589e900b042124a068dda5f8d93ff
security-game/tools/screen_designs.py
T
zwitschi 6684d36739
Full build / Import + headless tests (push) Successful in 26s
Details
Full build / Full desktop build + optional release (push) Failing after 3m58s
Details
Fix release publishing and add a CI token fallback 
Tag builds since v0.2.2 built all artifacts but never published a release:
- tools/publish_release.sh only assembled AUTH in the GITEA_TOKEN branch; the
  ~/.git-credentials branch set CRED and then used an unbound ${AUTH[@]} under
  `set -u`, so every API call failed and the job ended "could not create or find
  release". It now sets AUTH=(-u "$CRED").
- The repo has no GITEA_TOKEN secret and the runner has no git credentials, so the
  workflow now falls back to the built-in workflow token:
  GITEA_TOKEN: ${{ secrets.GITEA_TOKEN || github.token }}.

v0.2.9 was then built and published locally with all five artifacts (portable
Linux/Windows/macOS, NSIS installer, AppImage) and the release page verified via
the API. v0.2.4-v0.2.8 remain unpublished; they are superseded by the latest.

Docs
- docs/RELEASING.md records the incident and the local-publish fallback.
- TODO gains a release-pipeline follow-up (verify CI on the next tag).
- MEMORY notes the root cause, the missing secret, and which releases exist.
- Version 0.2.10.
2026-10-31 21:23:09 +01:00

622 lines
26 KiB
Python
Raw Blame History

#!/usr/bin/env python3
"""Generate screen-design reference images for Step Line and compare captures.
This tool turns the screen descriptions that already live in `docs/`
(README screenshot captions, ADRs 0007-0010, PLAN.md, architecture.md, and the
HUD strings in `content/strings.en.json`) into reference "design" images, then
uses those images as the expected state to check the game's captured
screenshots against.
Two commands:
generate write one reference image per screen to docs/screens/designs/.
Two modes:
--ai realistic 3D game scenes and in-game screen designs via
the OpenRouter image API (default; requires
OPENROUTER_API_KEY, same as tools/asset_pipeline.py).
--draft deterministic wireframe sketches drawn with Pillow
(no network or API key; good for CI and layout checks).
compare compare docs/screenshots/*.png against the reference designs and
flag gross drift. Semantic composition is judged with coarse,
Pillow-only signals (aspect ratio, frame size, blank-frame
contrast, grayscale MAE, colour-histogram distance, edge density).
These catch "wrong screen / blank frame / wrong time of day"
regressions; they are NOT a pixel-exact or semantic match. A
vision-model pass is the documented next step (see PLAN.md).
Run from the repo root:
python3 tools/screen_designs.py generate
python3 tools/screen_designs.py generate --draft
python3 tools/screen_designs.py compare
"""
import argparse
import os
import sys
from pathlib import Path
from PIL import Image, ImageChops, ImageDraw, ImageFilter, ImageOps, ImageStat
import generate_textures
ROOT = Path(__file__).resolve().parent.parent
DESIGNS_DIR = ROOT / "docs" / "screens" / "designs"
SCREENSHOTS_DIR = ROOT / "docs" / "screenshots"
# Reference "design" dimensions — match the capture tool and the README gallery.
WIDTH, HEIGHT = 1280, 720
ASPECT = 16 / 9
# Default image model for screen mockups (validated role-aware model, per
# MEMORY.md; seedream rejects small sizes and ignores transparency, so we use
# the model asset_pipeline.py already trusts for non-alpha roles).
DEFAULT_MODEL = "openai/gpt-5-image-mini"
# Shared art direction, appended to every prompt so the generated frames read
# as one coherent game. "scene" entries are first-person 3D world views;
# "ui" entries are in-game panels overlaid on a softened scene.
SCENE_STYLE = (
"rendered in a modern 3D game engine, first-person perspective, cinematic "
"lighting, physically based materials, soft shadows, ambient occlusion, "
"subtle depth of field, photorealistic detail, no watermark or UI clutter"
)
UI_STYLE = (
"clean modern in-game user interface, dark translucent panels, readable "
"sans-serif labels, consistent game UI colour theme, crisp vector text"
)
# Landscape source ratio requested from the API before cropping to 16:9.
# 3:2 is the validated non-square ratio for the default model (see MEMORY.md).
SOURCE_ASPECT = "3:2"
# ---------------------------------------------------------------------------
# Screen catalogue. Each entry is grounded in a doc; `prompt` feeds --ai and
# `regions` feed --draft (normalised rects + a short label). `ref` names the
# captured screenshot, if one exists, so `compare` can pair them up.
# ---------------------------------------------------------------------------
SCREENS = [
{
"name": "venue_overview",
"kind": "scene",
"title": "Venue overview",
"source": "README screenshot 01",
"ref": "01-venue-overview.png",
"description": "First-person view from the guard post at the top of the "
"steps: Hollywood Boulevard entrance, wide concrete steps, "
"sidewalk, street lamps, planters, crosswalk, and building "
"signage/marquee under early-morning light.",
"prompt": (
"Realistic 3D first-person game scene: a security guard's view from "
"the top of wide concrete steps outside a grand Hollywood Boulevard "
"building entrance, early-morning golden light, sidewalk with street "
"lamps, planters, a crosswalk and distant pedestrians, detailed brick "
"facade with a striped awning and glowing marquee sign"),
"regions": [
(0.00, 0.55, 1.00, 1.00, "steps + sidewalk"),
(0.20, 0.08, 0.80, 0.60, "building facade / marquee"),
(0.05, 0.60, 0.20, 0.75, "street lamp"),
(0.78, 0.60, 0.95, 0.75, "street lamp"),
],
},
{
"name": "targeting_npc",
"kind": "scene",
"title": "Targeting an NPC",
"source": "README screenshot 02 · ADR-0008 cone focus + focus circle",
"ref": "02-targeting-npc.png",
"description": "An approaching NPC is in the focus cone: a blue "
"semi-transparent circle in front of their face, a display "
"name under the circle, and the HUD shows a target line "
"with the interaction hint.",
"prompt": (
"Realistic 3D first-person game scene: a friendly pedestrian "
"standing on a city sidewalk, a blue semi-transparent circle in front "
"of their face as a game selection marker, a small name label under "
"the circle, minimal HUD target text at the bottom, daytime"),
"regions": [
(0.35, 0.15, 0.65, 0.60, "NPC in focus"),
(0.44, 0.10, 0.56, 0.16, "face circle"),
(0.05, 0.85, 0.95, 0.95, "HUD: name + hint"),
],
},
{
"name": "access_inspection",
"kind": "ui",
"title": "Access inspection",
"source": "README screenshot 03 · ADR-0003 access verification",
"ref": "03-access-inspection.png",
"description": "An inspection panel shows the access artifact (wristband / "
"ID / ticket / credential / guest list) with its colour, "
"pattern, date, and event marking, plus allow and deny "
"prompts.",
"prompt": (
"Realistic 3D game screenshot with an in-game access inspection panel "
"overlaid: a centered card showing a wristband or ID credential with a "
"photo placeholder, colour band, date and event marking, and two "
"buttons labelled Allow and Deny, dark translucent panel over a "
"softly blurred city street background"),
"regions": [
(0.25, 0.10, 0.75, 0.90, "inspection panel"),
(0.30, 0.18, 0.70, 0.60, "artifact card"),
(0.30, 0.65, 0.48, 0.72, "allow"),
(0.52, 0.65, 0.70, 0.72, "deny"),
],
},
{
"name": "radio_report",
"kind": "ui",
"title": "Radio report",
"source": "README screenshot 04 · PLAN level 4 radio assistance",
"ref": "04-radio-report.png",
"description": "A radio dispatch panel with fields for location, "
"description, behaviour, whether weapons were seen, and "
"whether anyone is in immediate danger, plus a send action.",
"prompt": (
"Realistic 3D game screenshot with an in-game radio dispatch panel "
"overlaid: form fields for location, description, behaviour, a threat "
"assessment and whether anyone is in danger, and a Send button, dark "
"translucent panel over a softly blurred city street background"),
"regions": [
(0.30, 0.08, 0.70, 0.92, "radio panel"),
(0.34, 0.16, 0.66, 0.30, "location / description"),
(0.34, 0.34, 0.66, 0.56, "behaviour / weapons / danger"),
(0.42, 0.60, 0.58, 0.66, "send"),
],
},
{
"name": "late_night_avenue",
"kind": "scene",
"title": "Late night avenue",
"source": "README screenshot 05",
"ref": "05-late-night-avenue.png",
"description": "Night-time view down Hollywood Boulevard: street lamps "
"lit, marquee glowing, dark blue street, no flashlight.",
"prompt": (
"Realistic 3D first-person game scene at night: a dark Hollywood "
"Boulevard avenue receding into the distance, lit street lamps, a "
"glowing neon marquee sign, deep blue night sky, wet reflective "
"pavement, no flashlight"),
"regions": [
(0.00, 0.55, 1.00, 1.00, "dark avenue"),
(0.15, 0.25, 0.85, 0.55, "glowing marquee"),
(0.10, 0.45, 0.30, 0.70, "lit street lamp"),
(0.70, 0.45, 0.90, 0.70, "lit street lamp"),
],
},
{
"name": "night_flashlight",
"kind": "scene",
"title": "Night flashlight",
"source": "README screenshot 06",
"ref": "06-night-flashlight.png",
"description": "Night shift: the guard's flashlight beam cuts through the "
"dark toward the entrance, illuminating the steps and door.",
"prompt": (
"Realistic 3D first-person game scene at night: a flashlight beam "
"cutting through darkness toward a building entrance and steps, a "
"bright spotlight pool illuminating the door, dark surroundings and "
"deep shadows"),
"regions": [
(0.35, 0.30, 0.65, 0.80, "flashlight beam pool"),
(0.40, 0.20, 0.60, 0.35, "lit door"),
(0.00, 0.00, 1.00, 0.25, "dark sky"),
],
},
{
"name": "radial_menu",
"kind": "ui",
"title": "Radial action menu",
"source": "ADR-0009 · content/strings.en.json",
"ref": None,
"description": "A round doughnut menu centred on screen, 12 slices in "
"de-escalation order: Stop, Look, Point, No, Ask, Inspect, "
"Wand, Warn, Block, Reason, Recognize, Radio. The focused "
"person's display name sits in the centre.",
"prompt": (
"Realistic 3D game screenshot with an in-game radial action menu "
"overlaid: a round doughnut wheel centered on screen with twelve "
"labelled slices reading Stop, Look, Point, No, Ask, Inspect, Wand, "
"Warn, Block, Reason, Recognize, Radio, one slice highlighted, a name "
"in the center of the ring, over a softly blurred city street scene"),
"regions": [
(0.38, 0.12, 0.62, 0.88, "radial wheel (12 slices)"),
(0.46, 0.44, 0.54, 0.56, "name"),
(0.62, 0.12, 0.70, 0.20, "highlight"),
],
},
{
"name": "shift_review",
"kind": "ui",
"title": "Shift review",
"source": "PLAN reputation / shift review · architecture.md ShiftReview",
"ref": None,
"description": "End-of-shift performance review: access decisions, "
"escalation choices, incident list, battery and crowd "
"outcomes, and reputation/score feedback.",
"prompt": (
"Realistic 3D game end-of-shift review screen: a full-screen "
"performance summary panel listing incident decisions, escalation "
"choices, a reputation score, crowd reaction and battery use, with a "
"Continue button, dark themed game UI"),
"regions": [
(0.30, 0.06, 0.70, 0.94, "review panel"),
(0.36, 0.14, 0.64, 0.24, "score / reputation"),
(0.36, 0.28, 0.64, 0.70, "incident list"),
(0.42, 0.76, 0.58, 0.84, "continue"),
],
},
{
"name": "start_menu",
"kind": "ui",
"title": "Start menu",
"source": "MEMORY session shell (StartMenu, layer 20)",
"ref": None,
"description": "The boot screen: a venue-selection menu (Hollywood "
"Boulevard, The Joke Shop, TV Studio) before a shift.",
"prompt": (
"Realistic 3D game start menu screen: a game title and three venue "
"selection buttons labelled Hollywood Boulevard, The Joke Shop and TV "
"Studio, dark themed menu over a softly blurred city street backdrop"),
"regions": [
(0.25, 0.10, 0.75, 0.26, "title"),
(0.36, 0.36, 0.64, 0.44, "Hollywood Boulevard"),
(0.36, 0.48, 0.64, 0.56, "The Joke Shop"),
(0.36, 0.60, 0.64, 0.68, "TV Studio"),
],
},
{
"name": "pause_overlay",
"kind": "ui",
"title": "Pause overlay",
"source": "MEMORY session shell (PauseOverlay, layer 18)",
"ref": None,
"description": "Pause menu: resume, restart, settings, and quit-to-menu.",
"prompt": (
"Realistic 3D game pause menu overlay: buttons labelled Resume, "
"Restart, Settings and Quit to Menu, dark translucent overlay over a "
"paused, softly blurred city street scene"),
"regions": [
(0.38, 0.26, 0.62, 0.74, "pause menu"),
(0.42, 0.32, 0.58, 0.38, "Resume"),
(0.42, 0.42, 0.58, 0.48, "Restart"),
(0.42, 0.52, 0.58, 0.58, "Settings"),
(0.42, 0.62, 0.58, 0.68, "Quit to Menu"),
],
},
{
"name": "settings_panel",
"kind": "ui",
"title": "Settings",
"source": "MEMORY session shell (SettingsPanel, layer 22)",
"ref": None,
"description": "Settings: look sensitivity and HUD font scale controls.",
"prompt": (
"Realistic 3D game settings screen: sliders labelled look sensitivity "
"and HUD font scale, dark themed settings panel"),
"regions": [
(0.30, 0.16, 0.70, 0.84, "settings panel"),
(0.36, 0.30, 0.64, 0.40, "look sensitivity"),
(0.36, 0.46, 0.64, 0.56, "HUD font scale"),
],
},
{
"name": "emergency_radio",
"kind": "ui",
"title": "Emergency radio",
"source": "PLAN level 5 · strings radio.emergency_dispatched",
"ref": None,
"description": "Hold-to-confirm emergency radio panel with a confirmation "
"prompt and a cooldown indicator.",
"prompt": (
"Realistic 3D game emergency radio hold-to-confirm panel: a large "
"warning prompt with a hold progress bar and a cooldown label, red "
"accent, dark translucent overlay over a softly blurred city street "
"scene"),
"regions": [
(0.30, 0.28, 0.70, 0.72, "emergency panel"),
(0.36, 0.36, 0.64, 0.46, "confirm prompt"),
(0.38, 0.52, 0.62, 0.60, "hold progress"),
(0.36, 0.64, 0.64, 0.68, "cooldown"),
],
},
]
def resolve_path(value):
path = Path(value).expanduser()
return path if path.is_absolute() else ROOT / path
def _design_path(name):
return DESIGNS_DIR / f"{name}.png"
# ---------------------------------------------------------------------------
# Draft (wireframe) rendering — deterministic, offline.
# ---------------------------------------------------------------------------
def _draw_wireframe(screen, path):
image = Image.new("RGB", (WIDTH, HEIGHT), (24, 26, 38))
draw = ImageDraw.Draw(image)
title_font = generate_textures.font(52)
body_font = generate_textures.font(24)
label_font = generate_textures.font(26)
draw.text((40, 28), screen["title"], font=title_font, fill=(240, 240, 245))
draw.text((40, 98), screen["source"], font=body_font, fill=(150, 155, 175))
# wrap the description into a small caption block
words = screen["description"].split()
lines, line = [], ""
for word in words:
if draw.textlength(line + " " + word, font=body_font) < WIDTH - 80:
line = (line + " " + word).strip()
else:
lines.append(line)
line = word
lines.append(line)
for index, text in enumerate(lines[:4]):
draw.text((40, 132 + index * 30), text,
font=body_font, fill=(120, 125, 145))
for region in screen["regions"]:
x0, y0, x1, y1, label = region
box = (int(x0 * WIDTH), int(y0 * HEIGHT),
int(x1 * WIDTH), int(y1 * HEIGHT))
draw.rounded_rectangle(box, radius=10,
outline=(120, 130, 170), width=2)
cx = (box[0] + box[2]) / 2
cy = (box[1] + box[3]) / 2
draw.text((cx - draw.textlength(label, font=label_font) / 2,
cy - 14), label, font=label_font, fill=(170, 180, 210))
image.save(path)
shown = path.relative_to(ROOT) if path.is_relative_to(ROOT) else path
print(f"wrote {shown} {image.size}")
# ---------------------------------------------------------------------------
# AI generation (reuses the OpenRouter backend from generate_textures).
# ---------------------------------------------------------------------------
def _compose_prompt(screen):
"""Append the shared art direction to a screen's content prompt."""
style = UI_STYLE if screen.get("kind") == "ui" else SCENE_STYLE
return f"{screen['prompt']}. {style}. 16:9 widescreen composition."
def _generate_ai(screen, model, request_size):
prompt = _compose_prompt(screen)
# Request a landscape source and crop to the 16:9 capture dimensions rather
# than a square that loses framing when centre-cropped.
image = generate_textures.generate_image(
prompt, model, request_size, transparent=False,
aspect_ratio=SOURCE_ASPECT)
image = ImageOps.fit(image, (WIDTH, HEIGHT),
method=Image.Resampling.LANCZOS)
if image.mode in ("RGBA", "LA", "P"):
image = image.convert("RGB")
path = _design_path(screen["name"])
path.parent.mkdir(parents=True, exist_ok=True)
image.save(path)
shown = path.relative_to(ROOT) if path.is_relative_to(ROOT) else path
print(f"wrote {shown} {image.size}")
def generate(args):
DESIGNS_DIR.mkdir(parents=True, exist_ok=True)
failed = []
for screen in SCREENS:
print(f"generating {screen['name']} ...")
try:
if args.draft:
_draw_wireframe(screen, _design_path(screen["name"]))
else:
_generate_ai(screen, args.model, args.request_size)
except SystemExit as exc:
failed.append(screen["name"])
print(f" FAILED {screen['name']}: {exc}", file=sys.stderr)
print("done")
if failed:
print(f"failed: {', '.join(failed)}", file=sys.stderr)
return 1
return 0
# ---------------------------------------------------------------------------
# Comparison metrics (Pillow only; no numpy/scikit-image dependency).
# ---------------------------------------------------------------------------
def _load_rgb(path):
with Image.open(path) as image:
image.load()
return image.convert("RGB")
def _grayscale(image):
return ImageOps.grayscale(image)
def _mae(left, right):
"""Mean absolute error between two same-size grayscale images, 0..255."""
left_gray = _grayscale(left).resize((256, 144))
right_gray = _grayscale(right).resize((256, 144))
diff = ImageChops.difference(left_gray, right_gray)
return ImageStat.Stat(diff).mean[0]
def _histogram_distance(left, right):
"""Normalised L1 distance between 3x256-bin colour histograms, 0..1."""
left_hist = left.resize((256, 144)).histogram()
right_hist = right.resize((256, 144)).histogram()
total = sum(left_hist)
if total == 0:
return 1.0
distance = sum(abs(a - b) for a, b in zip(left_hist, right_hist))
return distance / (2 * total)
def _edge_density(image):
"""Mean brightness of an edge-detected frame; higher = more detail."""
edges = _grayscale(image).filter(ImageFilter.FIND_EDGES)
return ImageStat.Stat(edges).mean[0]
def _contrast(image):
"""Standard deviation of grayscale brightness; low = near-blank frame."""
return ImageStat.Stat(_grayscale(image)).stddev[0]
def _aspect_ok(image, tolerance=0.12):
width, height = image.size
actual = width / height
return abs(actual - ASPECT) / ASPECT <= tolerance
def compare_screenshot(reference, capture):
"""Compare one capture against its reference design; return a dict report."""
ref = _load_rgb(reference)
cap = _load_rgb(capture)
width, height = cap.size
report = {
"capture": str(capture),
"reference": str(reference),
"size": [width, height],
}
errors, warnings = [], []
if width < WIDTH or height < HEIGHT:
errors.append(f"too small: {width}x{height}; minimum {WIDTH}x{HEIGHT}")
if not _aspect_ok(cap):
errors.append(f"wrong aspect ratio: {width / height:.3f}; "
f"expected about {ASPECT:.3f}")
contrast = _contrast(cap)
report["contrast"] = round(contrast, 1)
if contrast < 5.0:
errors.append(f"near-blank frame: contrast {contrast:.1f} below 5.0")
mae = _mae(ref, cap)
hist = _histogram_distance(ref, cap)
edge_ref = _edge_density(ref)
edge_cap = _edge_density(cap)
report["mae"] = round(mae, 1)
report["hist_distance"] = round(hist, 3)
report["edge_density_ref"] = round(edge_ref, 1)
report["edge_density_cap"] = round(edge_cap, 1)
# Coarse drift warnings (not hard failures: an AI mockup will never match a
# real render pixel-for-pixel, but a wildly different frame will still
# stand out on these signals).
if mae > 90:
warnings.append(
f"grayscale MAE {mae:.1f} is high (very different layout)")
if hist > 0.75:
warnings.append(f"colour histogram distance {hist:.3f} is high "
"(very different palette / time of day)")
edge_delta = abs(edge_cap - edge_ref)
report["edge_delta"] = round(edge_delta, 1)
if edge_delta > 18:
warnings.append(f"edge density differs by {edge_delta:.1f} "
"(very different amount of detail)")
report["quality"] = "bad" if errors else "good"
report["errors"] = errors
report["warnings"] = warnings
return report
def compare(args):
if not SCREENSHOTS_DIR.is_dir():
sys.exit(f"error: no screenshots directory at {SCREENSHOTS_DIR}; "
"run src/test/capture_screenshots.gd first")
captures = sorted(SCREENSHOTS_DIR.glob("*.png"))
if not captures:
sys.exit(f"error: no .png screenshots found in {SCREENSHOTS_DIR}")
refs = {screen["name"]: screen["ref"]
for screen in SCREENS if screen["ref"]}
results = []
for capture in captures:
name = capture.name
# find the screen whose ref matches this capture filename
design_name = next((n for n, ref in refs.items() if ref == name), None)
if design_name is None:
results.append({"capture": str(capture), "reference": None,
"errors": [f"no design reference for {name}"],
"warnings": [], "quality": "bad"})
continue
reference = _design_path(design_name)
if not reference.is_file():
results.append({"capture": str(capture),
"reference": str(reference),
"errors": [f"missing reference design "
f"({reference.name}); run generate first"],
"warnings": [], "quality": "bad"})
continue
results.append(compare_screenshot(reference, capture))
if args.json:
import json
print(json.dumps(results, indent=2))
else:
good_count = sum(r["quality"] == "good" for r in results)
for result in results:
ref = (Path(result["reference"]).name
if result.get("reference") else "-")
size = ("x".join(map(str, result["size"]))
if result.get("size") else "unreadable")
print(f"{result['quality'].upper():4} {result['capture']}")
print(f" ref={ref} size={size} "
f"mae={result.get('mae', '-')} "
f"hist={result.get('hist_distance', '-')}")
for message in result["errors"] + result["warnings"]:
print(f" - {message}")
print(f"Summary: {good_count} good, {len(results) - good_count} bad")
return 1 if any(r["quality"] == "bad" for r in results) else 0
# ---------------------------------------------------------------------------
def build_parser():
parser = argparse.ArgumentParser(
description="Generate and compare Step Line screen-design references.")
commands = parser.add_subparsers(dest="command", required=True)
gen = commands.add_parser(
"generate", help="write reference design images to docs/screens/designs/")
mode = gen.add_mutually_exclusive_group()
mode.add_argument("--draft", action="store_true",
help="draw deterministic wireframes (no API/network)")
mode.add_argument("--ai", action="store_true",
help="generate mockups via OpenRouter (default)")
gen.add_argument("--model", default=DEFAULT_MODEL)
gen.add_argument("--request-size", type=int,
default=generate_textures.GEN_SIZE)
gen.set_defaults(handler=generate, draft=False)
cmp = commands.add_parser(
"compare", help="compare docs/screenshots/*.png against the designs")
cmp.add_argument("--json", action="store_true")
cmp.set_defaults(handler=compare)
return parser
def main(argv=None):
args = build_parser().parse_args(argv)
try:
result = args.handler(args)
return result if isinstance(result, int) else 0
except (OSError, ValueError) as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if __name__ == "__main__":
raise SystemExit(main())
Reference in new issue View Git Blame Copy Permalink