c64-kb 0.17.0

package/templates/adventure/tools/world.py

@@ -0,0 +1,356 @@
+"""world.py: STARWATCH, the game's world. Edit this file, then `make gen`.
+
+Everything the game knows is here: rooms, items, words, the action table,
+the messages the engine itself prints, the pictures and the autopilot
+script. tools/gen.py packs it into src/gen_world.h and src/gen_script.h and
+plays the script through its model of the engine.
+
+Text is upper case. Letters, digits, space and . , ' ! ? : - ( ) only.
+"""
+
+# ---- rooms --------------------------------------------------------------------
+# key: (status-bar name, description, exits {dir: room}, dark, picture)
+ROOMS = {
+    "LANE": ("LANE", "YOU STAND ON A MUDDY LANE BESIDE A HIGH STONE WALL. AN IRON GATE "
+             "IN THE WALL STANDS OPEN TO THE NORTH.", {"N": "GARDEN"}, False, "lane"),
+    "GARDEN": ("GARDEN", "AN OVERGROWN GARDEN UNDER THE STARS. THE HOUSE IS NORTH, A SHED "
+               "EAST AND A POND WEST.", {"S": "LANE", "N": "PORCH", "E": "SHED", "W": "POND"},
+               False, "garden"),
+    "SHED": ("SHED", "A DUSTY SHED THAT SMELLS OF TAR.", {"W": "GARDEN"}, False, "shed"),
+    "POND": ("POND", "A STILL POND UNDER A WILLOW. THE MOON LIES ON THE WATER.",
+             {"E": "GARDEN"}, False, "pond"),
+    "PORCH": ("PORCH", "A CREAKING PORCH. THE FRONT DOOR IS NORTH.",
+              {"S": "GARDEN", "N": "HALL"}, False, "porch"),
+    "HALL": ("HALL", "A TALL HALL WITH A GRANDFATHER CLOCK. DOORS LEAD EAST AND WEST, "
+             "STAIRS GO UP AND A STEP LEADS DOWN.",
+             {"S": "PORCH", "E": "KITCHEN", "W": "LIBRARY", "U": "LANDING", "D": "CELLAR"},
+             False, "hall"),
+    "KITCHEN": ("KITCHEN", "A COLD KITCHEN. POTS HANG OVER AN IRON STOVE.", {"W": "HALL"},
+                False, "kitchen"),
+    "LIBRARY": ("LIBRARY", "BOOKS RISE TO THE CEILING ON EVERY WALL.", {"E": "HALL"},
+                False, "library"),
+    "CELLAR": ("CELLAR", "A DAMP CELLAR OF BARE STONE.", {"U": "HALL"}, True, "cellar"),
+    "LANDING": ("LANDING", "A NARROW LANDING. A DOOR LEADS NORTH AND A HATCH IS SET IN THE "
+                "CEILING.", {"D": "HALL", "N": "STUDY", "U": "TOWER"}, False, "landing"),
+    "STUDY": ("STUDY", "THE ASTRONOMER'S STUDY. CHARTS OF THE SKY COVER THE WALLS.",
+              {"S": "LANDING"}, False, "study"),
+    "TOWER": ("TOWER", "THE DOME OF THE TOWER. A SLIT OPENS ON THE NIGHT, AND A GREAT "
+              "TELESCOPE POINTS AT IT.", {"D": "LANDING"}, False, "tower"),
+}
+START = "LANE"
+
+# ---- items --------------------------------------------------------------------
+# key: (description, noun, start, flags, examine text or None)
+# start: a room key, "CARRIED", "IN:<container>" or None (not in play yet).
+# flags: P portable, C container, O container starts open, S scenery (not
+# listed in LOOK; the room text mentions it).
+ITEMS = {
+    "NET": ("A FISHING NET", "NET", "SHED", "P", "A LONG-HANDLED NET, STIFF WITH MUD."),
+    "LAMP": ("A BRASS LAMP", "LAMP", "IN:CHEST", "P", "IT HOLDS OIL BUT IT IS NOT LIT."),
+    "LITLAMP": ("A LIT LAMP", "LAMP", None, "P", "IT BURNS WITH A STEADY FLAME."),
+    "KEY": ("AN IRON KEY", "KEY", None, "P", None),
+    "MATCHES": ("A BOX OF MATCHES", "MATCHES", "IN:DRAWER", "P", None),
+    "LENS": ("A GLASS LENS", "LENS", "IN:CRATE", "P", "A HEAVY LENS, WRAPPED IN FELT."),
+    "WINDER": ("A CLOCK WINDER", "WINDER", "IN:DESK", "P", None),
+    "BOOK": ("A STAR ATLAS", "BOOK", "LIBRARY", "P",
+             "A NOTE IN THE MARGIN SAYS: THE CLOCK KEEPS THE HATCH."),
+    "CHEST": ("A WOODEN CHEST", "CHEST", "SHED", "C", None),
+    "DRAWER": ("A KITCHEN DRAWER", "DRAWER", "KITCHEN", "C", None),
+    "CRATE": ("A PACKING CRATE", "CRATE", "CELLAR", "C", None),
+    "DESK": ("A WRITING DESK", "DESK", "STUDY", "C", None),
+    "DOOR": ("A LOCKED DOOR", "DOOR", "PORCH", "", "IT IS STOUT OAK WITH AN IRON LOCK."),
+    "OPENDOOR": ("AN OPEN DOOR", "DOOR", None, "", None),
+    "POND": ("THE POND", "POND", "POND", "S", None),
+    "CLOCK": ("THE CLOCK", "CLOCK", "HALL", "S",
+              "ITS HANDS ARE STILL. THERE IS A SOCKET FOR A WINDER."),
+    "SCOPE": ("THE TELESCOPE", "TELESCOPE", "TOWER", "S", None),
+}
+# How a container's contents are introduced, e.g. "IN THE CHEST: A BRASS LAMP."
+INSIDE = {"CHEST": "IN THE CHEST", "DRAWER": "IN THE DRAWER", "CRATE": "IN THE CRATE",
+          "DESK": "IN THE DESK"}
+LIGHT_ITEM = "LITLAMP"          # a dark room is lit while this item is in reach
+MAXLOAD = 5                     # items carried at once
+MAXSCORE = 100
+
+# ---- vocabulary -----------------------------------------------------------------
+# Words match on their first four letters; a shorter word must match whole.
+# Synonyms share an id. Directions are nouns 1 to 6, in this order.
+DIRECTIONS = ["N", "S", "E", "W", "U", "D"]
+VERBS = {
+    "GO": ["GO", "WALK", "RUN", "CLIMB"],
+    "GET": ["GET", "TAKE", "GRAB", "PICK"],
+    "DROP": ["DROP", "DISCARD"],
+    "LOOK": ["LOOK", "L", "EXAMINE", "X", "READ", "SEARCH", "INSPECT"],
+    "INV": ["INVENTORY", "INV", "I"],
+    "OPEN": ["OPEN"],
+    "CLOSE": ["CLOSE", "SHUT"],
+    "UNLOCK": ["UNLOCK"],
+    "LIGHT": ["LIGHT", "IGNITE", "BURN"],
+    "WIND": ["WIND", "TURN", "CRANK"],
+    "PUT": ["PUT", "FIT", "INSERT", "PLACE"],
+    "SCORE": ["SCORE"],
+    "SAVE": ["SAVE"],
+    "LOAD": ["LOAD", "RESTORE"],
+    "QUIT": ["QUIT"],
+    "HELP": ["HELP", "HINT"],
+}
+NOUNS = {
+    "N": ["N", "NORTH"], "S": ["S", "SOUTH"], "E": ["E", "EAST"], "W": ["W", "WEST"],
+    "U": ["U", "UP"], "D": ["D", "DOWN"],
+    "NET": ["NET"], "LAMP": ["LAMP", "LANTERN"], "KEY": ["KEY"],
+    "MATCHES": ["MATCHES", "MATCH"], "LENS": ["LENS", "GLASS"],
+    "WINDER": ["WINDER", "CRANK"], "BOOK": ["BOOK", "ATLAS", "NOTE"],
+    "CHEST": ["CHEST", "BOX"], "DRAWER": ["DRAWER"], "CRATE": ["CRATE"], "DESK": ["DESK"],
+    "DOOR": ["DOOR"], "POND": ["POND", "WATER", "MUD"], "CLOCK": ["CLOCK"],
+    "TELESCOPE": ["TELESCOPE", "SCOPE"], "HATCH": ["HATCH"],
+}
+NOISE = ["THE", "A", "AN", "AT", "TO", "IN", "INTO", "ON", "WITH"]   # skipped by the parser
+
+# ---- the action table -------------------------------------------------------------
+# Scanned top to bottom before the built-in verbs; the first row whose verb,
+# noun and conditions all hold runs its commands and ends the turn. Verb None:
+# an occurrence, run after every turn. At most four conditions and four commands.
+# Conditions: AT room, CARRIED item, HERE item, REACH item (carried, here or
+# in an open container here), FLAG f, NOTFLAG f, DARK.
+# Commands: MSG text, GOTO room, LOOK, SETF f, SWAP item (item and the next
+# item in ITEMS trade places), CARRY item, DESTROY item, SCORE n, WIN.
+FLAGS = ["GOTKEY", "DOOROPEN", "HATCHOPEN", "LENSIN"]
+ACTIONS = [
+    ("GO", "N", ["AT PORCH", "NOTFLAG DOOROPEN"], ["MSG THE DOOR IS LOCKED."]),
+    ("GO", "U", ["AT LANDING", "NOTFLAG HATCHOPEN"], ["MSG THE HATCH IS SHUT FAST."]),
+    ("LOOK", "POND", ["AT POND", "NOTFLAG GOTKEY"],
+     ["MSG SOMETHING GLINTS IN THE MUD, JUST OUT OF REACH."]),
+    ("GET", "KEY", ["AT POND", "NOTFLAG GOTKEY", "CARRIED NET"],
+     ["SETF GOTKEY", "CARRY KEY", "SCORE 10",
+      "MSG YOU SWEEP THE NET THROUGH THE MUD AND LIFT OUT AN IRON KEY."]),
+    ("GET", "KEY", ["AT POND", "NOTFLAG GOTKEY"], ["MSG IT IS OUT OF REACH."]),
+    ("UNLOCK", "DOOR", ["AT PORCH", "NOTFLAG DOOROPEN", "CARRIED KEY"],
+     ["SETF DOOROPEN", "SWAP DOOR", "SCORE 10", "MSG THE KEY TURNS AND THE DOOR SWINGS OPEN."]),
+    ("UNLOCK", "DOOR", ["AT PORCH", "NOTFLAG DOOROPEN"], ["MSG YOU HAVE NO KEY."]),
+    ("OPEN", "DOOR", ["AT PORCH", "NOTFLAG DOOROPEN"], ["MSG IT IS LOCKED."]),
+    ("LIGHT", "LAMP", ["REACH LAMP", "CARRIED MATCHES"],
+     ["SWAP LAMP", "SCORE 10", "MSG YOU STRIKE A MATCH. THE LAMP GLOWS."]),
+    ("LIGHT", "LAMP", ["REACH LAMP"], ["MSG YOU HAVE NOTHING TO LIGHT IT WITH."]),
+    ("LIGHT", "LAMP", ["REACH LITLAMP"], ["MSG IT IS ALREADY LIT."]),
+    ("WIND", "CLOCK", ["AT HALL", "NOTFLAG HATCHOPEN", "CARRIED WINDER"],
+     ["SETF HATCHOPEN", "SCORE 15",
+      "MSG YOU WIND THE CLOCK. GEARS WHIRR, AND FAR ABOVE A HATCH GRINDS OPEN."]),
+    ("WIND", "CLOCK", ["AT HALL", "NOTFLAG HATCHOPEN"], ["MSG YOU NEED A WINDER."]),
+    ("WIND", "CLOCK", ["AT HALL"], ["MSG IT IS FULLY WOUND."]),
+    ("PUT", "LENS", ["AT TOWER", "CARRIED LENS"],
+     ["DESTROY LENS", "SETF LENSIN", "SCORE 15", "MSG THE LENS CLICKS INTO THE TELESCOPE."]),
+    ("LOOK", "TELESCOPE", ["AT TOWER", "FLAG LENSIN"],
+     ["SCORE 40", "MSG THROUGH THE GLASS THE COMET BLAZES, ITS TAIL ACROSS HALF THE SKY.",
+      "WIN"]),
+    ("LOOK", "TELESCOPE", ["AT TOWER"], ["MSG THE EYEPIECE IS EMPTY. IT NEEDS A LENS."]),
+    ("LOOK", "HATCH", ["AT LANDING", "FLAG HATCHOPEN"], ["MSG IT STANDS OPEN."]),
+    ("LOOK", "HATCH", ["AT LANDING"], ["MSG IT IS BOLTED FROM ABOVE BY SOME MECHANISM."]),
+    (None, None, ["AT CELLAR", "DARK"], ["MSG SOMETHING SCUTTLES IN THE DARK."]),
+]
+
+# ---- what the engine itself prints --------------------------------------------------
+MESSAGES = {
+    "DARK": "IT IS TOO DARK TO SEE.",
+    "DARKNAME": "DARKNESS",
+    "SEE": "YOU CAN SEE ",
+    "EXITS": "EXITS:",
+    "NOEXITS": "NO EXITS.",
+    "CARRYING": "YOU ARE CARRYING ",
+    "NOTHING": "NOTHING",
+    "EMPTY": "IT IS EMPTY.",
+    "CLOSED": "IT IS CLOSED.",
+    "UNKNOWN": "I DON'T KNOW THE WORD ",
+    "PARDON": "PARDON?",
+    "NOWAY": "YOU CAN'T GO THAT WAY.",
+    "WHICHWAY": "WHICH WAY?",
+    "TAKEN": "TAKEN.",
+    "DROPPED": "DROPPED.",
+    "HAVEIT": "YOU ALREADY HAVE IT.",
+    "NOTHERE": "YOU SEE NO SUCH THING HERE.",
+    "NOTHAVE": "YOU ARE NOT CARRYING IT.",
+    "FULL": "YOUR HANDS ARE FULL.",
+    "FIXED": "IT WON'T BUDGE.",
+    "OPENED": "OPENED.",
+    "CLOSEDOK": "CLOSED.",
+    "ISOPEN": "IT IS ALREADY OPEN.",
+    "ISSHUT": "IT IS ALREADY CLOSED.",
+    "NOTOPEN": "YOU CAN'T OPEN THAT.",
+    "NOTHINGSPECIAL": "YOU SEE NOTHING SPECIAL.",
+    "CANT": "YOU CAN'T DO THAT.",
+    "WHAT": "WHAT?",
+    "SCORED": "YOU HAVE SCORED ",
+    "OUTOF": " OUT OF ",
+    "IN": " IN ",
+    "TURNS": " TURNS.",
+    "TURN": " TURN.",
+    "WITHIT": "WHAT DO YOU WANT TO DO WITH IT?",
+    "WON": "YOU HAVE SEEN THE COMET. THE NIGHT IS YOURS!",
+    "QUITS": "YOU LEAVE THE HOUSE TO ITS DREAMS.",
+    "RANK0": "RANK: STARGAZER.",
+    "RANK1": "RANK: CLOUD WATCHER.",
+    "AGAIN": "PRESS RETURN TO PLAY AGAIN.",
+    "HELP": "TRY VERBS LIKE GO, GET, DROP, OPEN, LOOK, LIGHT, INVENTORY, SCORE, SAVE AND LOAD.",
+    "SAVED": "GAME SAVED ",
+    "LOADED": "GAME LOADED ",
+    "NOSAVE": "NO SAVED GAME ",
+    "BADSAVE": "THE SAVED GAME IS DAMAGED ",
+    "DISKFAIL": "DISK ERROR: ",
+    "NODRIVE": "NO DRIVE ANSWERS AS DEVICE 8.",
+    "OLDSAVE": "THE SAVE IS FROM ANOTHER VERSION ",
+    "INTRO": "STARWATCH. TONIGHT THE COMET PASSES, AND THE OLD ASTRONOMER'S TOWER "
+             "HAS THE ONLY TELESCOPE FOR MILES.",
+}
+
+# ---- pictures --------------------------------------------------------------------------
+# The strip is 40 x 7 cells of multicolour characters. A tile is a glyph of
+# 4 x 8 double-wide pixels: '.' $D021 (black), 'a' $D022 (grey), 'b' $D023
+# (brown), 'c' the cell's own colour (0-7), given with the tile where it is used.
+GLYPHS = {
+    "sky": ["...."] * 8,
+    "star": ["....", "..c.", "....", "....", "....", "....", "....", "...."],
+    "star2": ["....", "....", "....", "....", "....", ".c..", "....", "...."],
+    "solid": ["cccc"] * 8,
+    "stone": ["aaa.", "aaa.", "aaa.", "....", "a.aa", "a.aa", "a.aa", "...."],
+    "plank": ["bbbb", "bbbb", "bbbb", "....", "bbbb", "bbbb", "bbbb", "...."],
+    "wood": ["bbb."] * 8,
+    "earth": ["bbab", "bbbb", "abbb", "bbbb", "bbba", "bbbb", "babb", "bbbb"],
+    "grass": ["..c.", ".c.c", "cccc", "cccc", "cbcc", "cccc", "ccbc", "cccc"],
+    "water": ["cccc", "acca", "cccc", "cc.c", "cccc", "accc", "cccc", "c.cc"],
+    "leaves": [".cc.", "cccc", "cc.c", "cccc", ".ccc", "cccc", "c.cc", ".cc."],
+    "window": ["bbbb", "bccc", "bccc", "bbbb", "bccc", "bccc", "bccc", "bbbb"],
+    "bars": ["c.c.", "c.c.", "c.c.", "c.c.", "c.c.", "c.c.", "c.c.", "c.c."],
+    "knob": ["bbbb", "bbbb", "bbbb", "bbcb", "bbbb", "bbbb", "bbbb", "bbbb"],
+    "books": ["cacb", "cacb", "cacb", "cacb", "cacb", "cacb", "cacb", "bbbb"],
+    "slopel": ["...a", "...a", "..aa", "..aa", ".aaa", ".aaa", "aaaa", "aaaa"],
+    "sloper": ["a...", "a...", "aa..", "aa..", "aaa.", "aaa.", "aaaa", "aaaa"],
+    "net": ["a.a.", ".a.a", "a.a.", ".a.a", "a.a.", ".a.a", "a.a.", ".a.a"],
+    "face": [".cc.", "cccc", "cbcc", "cbbc", "cccc", ".cc.", "..b.", "..b."],
+    "eyes": ["....", "....", "c.c.", "....", "....", "....", "....", "...."],
+    "tube": ["...c", "..cc", ".cc.", "cc..", "c...", "....", "....", "...."],
+    "box": ["bbbb", "b..b", "bbbb", "bcbb", "bbbb", "bbbb", "bbbb", "...."],
+}
+BLACK, WHITE, RED, CYAN, PURPLE, GREEN, BLUE, YELLOW = range(8)
+
+
+def sky(p):
+    """Night sky with a fixed star field."""
+    p.fill(0, 0, 39, 6, "sky")
+    for i, (x, y) in enumerate([(3, 0), (11, 1), (17, 0), (24, 2), (30, 0), (36, 1),
+                                (7, 2), (20, 1), (33, 3), (1, 3), (27, 1), (14, 3)]):
+        p.put(x, y, "star" if i % 2 else "star2", WHITE)
+
+
+def inside(p, wall="stone", floor="plank"):
+    p.fill(0, 0, 39, 5, wall)
+    p.fill(0, 6, 39, 6, floor)
+
+
+def pic_lane(p):
+    sky(p); p.put(4, 1, "solid", WHITE)
+    p.fill(8, 2, 39, 5, "stone"); p.fill(20, 2, 23, 5, "bars", BLUE)
+    p.fill(0, 6, 39, 6, "earth")
+
+
+def pic_garden(p):
+    sky(p); p.fill(0, 5, 39, 6, "grass", GREEN)
+    p.fill(2, 1, 7, 3, "leaves", GREEN); p.fill(4, 4, 5, 5, "wood")
+    p.fill(15, 2, 27, 4, "stone"); p.put(14, 2, "slopel"); p.put(28, 2, "sloper")
+    p.put(18, 3, "window", YELLOW); p.put(24, 3, "window", YELLOW)
+    p.fill(33, 3, 37, 4, "plank"); p.put(35, 3, "window", YELLOW)
+
+
+def pic_shed(p):
+    inside(p, "wood", "earth")
+    p.fill(15, 4, 23, 5, "box"); p.put(19, 4, "knob", YELLOW)
+    p.fill(30, 1, 33, 3, "net")
+
+
+def pic_pond(p):
+    sky(p); p.put(30, 1, "solid", WHITE)
+    p.fill(0, 4, 39, 6, "water", BLUE); p.put(30, 5, "solid", WHITE)
+    p.fill(1, 0, 8, 3, "leaves", GREEN); p.fill(4, 3, 5, 3, "wood")
+
+
+def pic_porch(p):
+    inside(p, "stone", "plank")
+    p.fill(16, 1, 22, 5, "wood"); p.put(21, 3, "knob", YELLOW)
+    p.put(8, 2, "window", YELLOW); p.put(30, 2, "window", YELLOW)
+
+
+def pic_hall(p):
+    inside(p)
+    p.fill(6, 0, 9, 5, "wood"); p.fill(7, 1, 8, 1, "face", WHITE)
+    for i in range(5):
+        p.fill(26 + 2 * i, 5 - i, 39, 5 - i, "plank")
+    p.fill(15, 2, 18, 5, "wood")
+
+
+def pic_kitchen(p):
+    inside(p, "stone", "earth")
+    p.fill(4, 3, 12, 5, "solid", RED); p.fill(5, 1, 6, 2, "solid", BLACK)
+    p.fill(22, 3, 33, 5, "wood"); p.put(27, 4, "knob", YELLOW)
+    p.put(16, 0, "bars", WHITE); p.put(18, 0, "bars", WHITE)
+
+
+def pic_library(p):
+    inside(p, "wood", "plank")
+    colours = [RED, GREEN, YELLOW, BLUE, PURPLE, CYAN]
+    for y in (0, 2, 4):
+        for x in range(1, 39):
+            if x % 7:
+                p.put(x, y, "books", colours[(x + y) % 6])
+
+
+def pic_cellar(p):
+    inside(p, "stone", "earth")
+    p.fill(18, 3, 25, 5, "box"); p.put(21, 4, "knob", YELLOW)
+    p.fill(0, 0, 3, 5, "slopel")
+
+
+def pic_dark(p):
+    p.fill(0, 0, 39, 6, "sky")
+    p.put(12, 3, "eyes", YELLOW); p.put(29, 4, "eyes", YELLOW)
+
+
+def pic_landing(p):
+    inside(p, "wood", "plank")
+    p.fill(0, 4, 39, 4, "bars", WHITE)
+    p.fill(17, 0, 22, 0, "box"); p.fill(30, 1, 34, 5, "wood")
+
+
+def pic_study(p):
+    inside(p, "wood", "plank")
+    p.fill(4, 1, 11, 3, "sky"); p.put(6, 2, "star", WHITE); p.put(9, 1, "star2", WHITE)
+    p.fill(20, 4, 33, 5, "box"); p.put(26, 4, "knob", YELLOW)
+    p.put(22, 3, "solid", YELLOW)
+
+
+def pic_tower(p):
+    p.fill(0, 0, 39, 6, "stone")
+    p.fill(14, 0, 25, 4, "sky")
+    p.put(16, 1, "star", WHITE); p.put(22, 0, "star2", WHITE); p.put(19, 3, "star", WHITE)
+    for i in range(4):
+        p.put(18 + i, 5 - i, "tube", WHITE)
+    p.fill(0, 6, 39, 6, "plank")
+
+
+PICTURES = {"lane": pic_lane, "garden": pic_garden, "shed": pic_shed, "pond": pic_pond,
+            "porch": pic_porch, "hall": pic_hall, "kitchen": pic_kitchen,
+            "library": pic_library, "cellar": pic_cellar, "landing": pic_landing,
+            "study": pic_study, "tower": pic_tower, "dark": pic_dark}
+DARK_PICTURE = "dark"
+TITLE_PICTURE = "tower"
+
+# ---- the autopilot ------------------------------------------------------------------------
+# Typed through the KERNAL keyboard queue, up to ten bytes a frame. The shot
+# plays all of it with a copy of the release disk in drive 8. make disktest
+# splits it at the SAVE: part one ends with the SAVE; part two starts at the
+# LOAD after a cold reset (DISK_SPLIT).
+SCRIPT = [
+    "XYZZY", "N", "E", "OPEN CHEST", "PICK UP LANTERN", "GET NET", "W", "W",
+    "POND", "GET KEY", "DROP NET", "E", "N", "N", "UNLOCK DOOR", "N",
+    "SAVE", "E", "OPEN DRAWER", "GET MATCHES", "DROP LAMP", "LOAD",
+    "W", "E", "E", "OPEN DRAWER", "GET MATCHES", "W", "D", "LIGHT LAMP", "OPEN CRATE", "GET LENS", "U",
+    "U", "U", "N", "OPEN DESK", "GET WINDER", "S", "D", "WIND CLOCK", "U", "U",
+    "PUT LENS IN TELESCOPE", "LOOK AT TELESCOPE",
+]

package/templates/beat-em-up/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "h=\"$CLAUDE_PROJECT_DIR/harness/hooks/plan-gate.py\"; [ -f \"$h\" ] || h=\"$CLAUDE_PROJECT_DIR/../_harness/hooks/plan-gate.py\"; exec python3 \"$h\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/beat-em-up/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "c64-kb": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["../../dist/cli.js", "serve"],
+      "env": {}
+    }
+  }
+}

package/templates/beat-em-up/CLAUDE.md

@@ -0,0 +1,136 @@
+# Rules for an agent working on this C64 program
+
+This program runs on a stock Commodore 64, PAL and NTSC. It is built on the
+c64-kb harness (`./harness`, vendored from c64-kb's `templates/_harness`).
+c64-kb is the reference: its pages give the registers, timings, techniques,
+pitfalls and recipes this program is built from. A wrong number becomes a torn
+screen or a crash, so every claim here is measured or says it is not.
+
+A new program starts in c64-kb with `npm run new-project -- <starter> <dir>`.
+That copies the starter and the harness, points `.mcp.json` and `local.mk`
+at the c64-kb checkout, proves the copy with `make shot check`, and leaves a
+blank `PLAN.md`.
+
+## This starter: beat-em-up
+
+A side-on street brawler that plays: `README.md` has the file map, how a
+frame runs, the measured frame and the three most likely next steps. Rules
+this program depends on:
+
+- The sprite registers belong to the IRQ chain in `src/engine.asm`: three
+  bands a frame (line 251 the GO sign, line 76 the fighters, line 212 the
+  HUD faces). C fills the back half of the tables and publishes it with
+  the next picture's `$D016` and `$D018` (`view_sprites`, `view_publish`).
+- The fighter band holds eight sprites and never reuses one: four sprite
+  fighters of two parts, or three and the brute. A fifth sprite fighter, or
+  a third part, has no sprite on those lines. The nearest fighter takes
+  sprites 0 and 1: depth is the VIC-II's sprite priority. Keep a fighter's
+  highest line at 91 or below (ground line 150, jump 18) so the band's IRQ
+  at line 76 has finished.
+- The brute is character cells (`src/brute.c`): two character sets at
+  `$E000` and `$E800`, one brute a wave, his cells in both street pages.
+  Street glyphs on rows 2-19 use bit pairs 00 and 01 only, or `$D01B`
+  hides fighters behind the street too. His cell moves must finish before
+  his top row: the verdict counts the ones that did not.
+- `make flickercheck` after any change to the fighters, the art, the poses
+  or the IRQs: `tools/flickercheck.py` renders the fighters and the brute
+  from `src/` (the `SPRITE-ART`, `BRUTE-ART` and `POSES` blocks in `art.c`,
+  the enums and colours in `game.h`, the colours in `view.c`: keep their
+  markers and shapes) and matches shots inside the photo stops. A changed
+  wave, AI or art moves the stops: re-pin `FLICKER_PAL` and `FLICKER_NTSC`.
+  `make gameover` checks the GAME OVER screen.
+- The scroll never writes the page on display but for the brute's cells:
+  it prepares the other page four rows a frame (`src/view.c`). Keep the
+  camera at a pixel a frame.
+- The frame is nearly full on NTSC (16,593 of 17,095 at the run's worst, README):
+  meter anything you add, with `-dPROF=n` for one subsystem and
+  `-dMETER_WINDOW=n` for another part of the run.
+- World x stays below 32,768 and is compared as unsigned: Oscar64 compares
+  an `int` loaded from a larger `unsigned` as not negative (c64-kb #30
+  fault 8; README, "Which Oscar64").
+- The autopilot is a bot (`src/autopilot.h`), not a timeline: it reads the
+  game and plays on. `-dDEBUG_AT=n` freezes at frame n and prints the
+  state on the HUD. On a failed verdict, row 24 shows the failed checks as
+  bits and row 22 the counts behind them.
+
+`PLAN.md` here is this starter's plan, filled from real tool output;
+new-project keeps it as `PLAN-beat-em-up-example.md` and gives the new
+program a blank one.
+
+## Before any code
+
+1. Brief: `npx tsx src/cli.ts game-briefing "<concept>" --archetype <name>`
+   (or `demo-briefing`), in the c64-kb checkout. Read what it proposes.
+2. For each technique you keep: `technique-lookup <name>` and
+   `pitfalls-for <name>`. Start from the recipe it names (`recipe-lookup`).
+3. Fill `PLAN.md`: paste the whole output of `check-compatibility` and of
+   `plan-budget` (same techniques) into their sections, list every technique
+   in its table, and replace every `FILL:` line.
+
+Until `PLAN.md` passes, a hook blocks Edit and Write under `src/`, and every
+make target that builds stops (`make plan-gate` says what is missing). With
+C64KB set, `make` re-runs `check-compatibility` and wants the pasted Verdict.
+The gate cannot see writes made through a shell command, or outputs edited
+into shape by hand: do neither. `make PLAN_GATE=off` overrides it; say why in
+`PLAN.md` if you do.
+
+## The loop
+
+```bash
+make                  # build build/<name>.prg
+make shot check       # autopilot build, headless PAL and NTSC, graded by expect.json
+make selftest         # the FORCE_FAULT build must fail the same checks
+make disk             # build/<name>.d64
+make claims           # every store the program makes, against what it declares
+make run              # windowed VICE, for a human
+```
+
+## Rules
+
+- Build before claiming. Code that has not built is not done.
+- Measure screenshots with `check.py` through `expect.json`, never by eye.
+  Every visible claim gets a check. Add one before you trust a change.
+- PAL and NTSC: both shots pass, or it is not done.
+- Name the rung for every number: measured here (`make shot`, the meter, the
+  VICE monitor), taken from a c64-kb page (say which), arithmetic, or not
+  measured. Never call something verified that was not run.
+- Frame cost comes from the meter: CIA2 timer A, printed as
+  `F<frames> W<worst> T<typical>` at row 24, columns 20 to 39, in AUTOPILOT
+  builds. It records the first `hold` frames: make that the autopilot
+  script's play frames. Typical is the median of those frames, the KB's
+  `cycles_per_frame_typical`. Keep grading, logging and printing outside the
+  bracket; work split between the main loop and IRQs is summed with
+  `METER_PAUSE` / `METER_START`.
+- Do not invent a register, routine or address. Look it up:
+  `lookup-register`, `lookup-kernal`, `memory-map`.
+- Lint every source you change: `npx tsx src/cli.ts lint <file>`.
+- Commit named paths only. Never `git add -A` or `git add .`. `build/`,
+  `shots/` and `local.mk` are never committed.
+
+## Harness facts you will need
+
+- `AUTOPILOT=1` builds read a scripted joystick byte instead of `$DC00` and
+  grade themselves: `$02FF` = `$01` and a green border on pass, `$02` and red
+  on fail. `FORCE_FAULT=1` must turn the verdict red and move something a
+  screenshot check can see.
+- Screenshot geometry (c64-kb `docs/runtime/vice-reference.md`): PAL 384 x 272,
+  row = raster line - 16; NTSC 384 x 247, row = line - 28; x = VIC X + 8. A
+  sprite at Y register y is drawn from line y + 1.
+- `check.py` reads text in the ROM character set unless a check names a
+  `charset` file; the meter's cells need 0-9, F, W and T in the set on screen.
+- A KickAssembler part called from C is a raw blob at its own `* =` address,
+  `$0880` or above; `build/asm.h` gives C its labels as `ASM_<LABEL>`
+  (`ASM_<SCOPE>_<LABEL>` inside a scope). Pass arguments through bytes in the
+  blob, not Oscar64's zero page (`$02` to `$52`).
+- The meter takes CIA2 timer A. Do not open RS-232 (device 2) while it runs.
+- The KERNAL serial routines end in `CLI` (ROM bytes `58 60` / `58 18` at
+  `$EDAB`, `$EDB5`, `$EDDB`, `$EE82`). After any disk call, `SEI` again if
+  the program runs with the KERNAL IRQ off: otherwise that IRQ lands inside
+  the meter's brackets and rewrites `$DC00`.
+
+## Calling c64-kb
+
+- CLI, from the c64-kb checkout (`C64KB` in `local.mk`):
+  `npx tsx src/cli.ts <command>`; `npx tsx src/cli.ts --help` lists them.
+- MCP: `.mcp.json` starts `node <c64-kb>/dist/cli.js serve` (run
+  `npm run build` in c64-kb first).

package/templates/beat-em-up/Makefile

@@ -0,0 +1,96 @@
+# beat-em-up: the side-on brawler starter. Every target but flickercheck
+# and joy comes from the harness:
+#   make              build build/beat-em-up.prg (after the PLAN.md gate)
+#   make run          windowed VICE, joystick in port 2
+#   make shot         headless PAL and NTSC exit screenshots of the autopilot build
+#   make check        grade shots/pal.png and shots/ntsc.png against expect.json
+#   make selftest     prove check fails on the FORCE_FAULT=1 build
+#   make flickercheck shoot the autopilot run inside its three photo stops and
+#                     match the fighter band pixel for pixel against a render
+#                     of the fighters the program printed (tools/flickercheck.py);
+#                     then prove the check fails on the FLICKER_DEMO=1 build
+#   make gameover     the AP_GIVE_UP=1 build: the bot never fights, three lives
+#                     go, GAME OVER shows; graded by expect-gameover.json
+#   make joy          the normal game reading its port byte from $02FE, for tools/drive.py
+#   make disk         build/beat-em-up.d64
+#   make claims       c64-kb's claims-watch over the autopilot build
+#   make clean
+NAME     := beat-em-up
+C_MAIN   := src/main.c
+KICK_SRC := src/engine.asm
+
+# Pinned after the verdict (graded before 100M cycles on both models), where
+# nothing on the screen changes: 120M and 130M gave identical PAL pictures,
+# 110M and 130M identical NTSC ones (VICE x64sc 3.10).
+SHOT_CYCLES_PAL  := 120000000
+SHOT_CYCLES_NTSC := 110000000
+
+# What the program may write, for make claims (claims-watch's own grammar).
+# - Oscar64's registers start at $02 (BC_REG_WORK_Y). A function with more
+#   temporaries than BC_REG_TMP ($43) to BC_REG_TMP_SAVED ($53) spills
+#   past $53 (its InterCode.cpp, AddSpace). Measured by claims-watch:
+#   $54-$5F (view_sprites, vic_compare, vic_expect) and $60 (grade, in the
+#   AUTOPILOT build); the first draft used $54-$56. $61-$6F is headroom for
+#   the next such edit; nothing else lives there.
+# - The KERNAL's IRQ runs until main's SEI, so IRQ is declared.
+# - $DC0D (all CIA1 interrupts off) counts against the three CIA1 units.
+# - CIA2 timer A is the harness meter's; timer B times the IRQs for the
+#   meter (engine.asm); the $DD0D stores count against all three CIA2
+#   units, so all three are declared as the harness's.
+# - The whole run, title to verdict, is traced (--cycles, the PAL pin).
+CLAIMS_ARGS := --claim 'sprite_0, sprite_1, sprite_2, sprite_3, sprite_4, sprite_5, sprite_6, sprite_7, vic_raster_irq, irq_vector_fffe, nmi_vector_fffa, cia2_vic_bank, cia1_port_a, cia1_timer_a, cia1_timer_b, cia1_tod, sid_voice_1, sid_voice_2, sid_voice_3, sid_filter_volume, zero_page $$02-$$6F' --range 'colour=$$D800-$$DBFF,result=$$02FF' --harness 'cia2_timer_a, cia2_timer_b, cia2_tod' --kernal IRQ --cycles 120000000
+
+# This starter's own proofs, which npm run verify:templates runs too.
+VERIFY_TARGETS := flickercheck gameover
+
+# The harness sits beside the starter in c64-kb (../_harness) or is vendored
+# into ./harness when the starter is copied out on its own.
+HARNESS ?= $(firstword $(wildcard harness) ../_harness)
+$(if $(wildcard $(HARNESS)/harness.mk),,$(error No harness at '$(HARNESS)'. Copy c64-kb's templates/_harness to ./harness, or make the project with npm run new-project in c64-kb))
+include $(HARNESS)/harness.mk
+
+# ---- flickercheck: every fighter part is on the screen in the crowded moments ----
+# Two pins inside each of the three photo stops (src/verdict.h), found by
+# scanning the run; a stop is 64 frames, about 1.26M cycles on PAL and
+# 1.09M on NTSC. A changed AI, wave or art moves the stops: re-scan with
+# `-dDEBUG_AT=n` builds or shots, and re-pin.
+FLICKER_PAL  := 34200000 34700000 44250000 44750000 80700000 81200000
+FLICKER_NTSC := 30600000 31100000 42900000 43400000 78700000 78950000
+PRG_FLICKER := build/$(NAME)-flicker.prg
+$(PRG_FLICKER): $(C_DEPS) $(ASM_OUT) $(METER_DEPS) | plan-gate
+	@mkdir -p build
+	$(OSCAR64_BUILD) -d$(AUTOPILOT_DEFINE)=1 -dFLICKER_DEMO=1 -o=$@ $(C_MAIN)
+
+FLICKER = $(PYTHON) tools/flickercheck.py --x64sc $(X64SC) --src src
+.PHONY: flickercheck
+flickercheck: $(PRG_AUTO) $(PRG_FLICKER)
+	$(FLICKER) --expect whole --model pal $(PRG_AUTO) $(FLICKER_PAL)
+	$(FLICKER) --expect whole --model ntsc $(PRG_AUTO) $(FLICKER_NTSC)
+	$(FLICKER) --expect dropped --model pal $(PRG_FLICKER) $(FLICKER_PAL)
+
+# ---- gameover: the game reaches GAME OVER, and the message is whole -----------------
+# The AP_GIVE_UP=1 build presses fire on the title and never fights; the
+# program checks the HUD a second into GAME OVER and freezes (verdict.h,
+# grade_gameover). The pins are past that point on each model.
+PRG_OVER := build/$(NAME)-over.prg
+GAMEOVER_PAL  := 60000000
+GAMEOVER_NTSC := 55000000
+$(PRG_OVER): $(C_DEPS) $(ASM_OUT) $(METER_DEPS) | plan-gate
+	@mkdir -p build
+	$(OSCAR64_BUILD) -d$(AUTOPILOT_DEFINE)=1 -dAP_GIVE_UP=1 -o=$@ $(C_MAIN)
+
+.PHONY: gameover
+gameover: $(PRG_OVER)
+	$(call vice_shot,$(PRG_OVER),$(GAMEOVER_PAL),,shots/over-pal.png)
+	$(call vice_shot,$(PRG_OVER),$(GAMEOVER_NTSC),-model ntsc,shots/over-ntsc.png)
+	$(PYTHON) $(HARNESS_DIR)/check.py expect-gameover.json shots/over-pal.png shots/over-ntsc.png
+
+# The normal game with its port byte read from $02FE instead of $DC00, so a
+# VICE monitor can drive it headless (tools/drive.py).
+PRG_JOY := build/$(NAME)-joy.prg
+$(PRG_JOY): $(C_DEPS) $(ASM_OUT) $(METER_DEPS) | plan-gate
+	@mkdir -p build
+	$(OSCAR64_BUILD) -dJOY_SOURCE=0x02fe -o=$@ $(C_MAIN)
+
+.PHONY: joy
+joy: $(PRG_JOY)