@henols/c64-re-tools 2.0.0-rc.17 → 2.0.0-rc.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.17",
+  "version": "2.0.0-rc.18",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/skills/c64-docs/SKILL.md

@@ -82,7 +82,13 @@ node <skill>/scripts/link.ts docs --source src --check
 - `tables.md`: each table of addresses, jumps and words, entry by entry, with its target. An RTS table holds each target minus 1. The table gives the target.
 - `memory-map.md`: each region in address order.
 - `symbols.md`: each name in alphabetical order.
-- `graphics.md`: each `sprite`, `bitmap` and `screen` region. A sprite or a bitmap shows in hires and in multicolour, because the knowledge has no graphics mode. A screen shows as text.
+- `graphics.md`: each `sprite`, `bitmap`, `charset` and `screen` region. A sprite, a bitmap or a charset shows in hires and in multicolour, because the knowledge has no graphics mode. A charset shows 16 characters in each row. A screen shows as text.
+
+### Images and assets
+
+- The reference draws each sprite, bitmap and charset region, and it decodes each table. To get the image of a graphic or the entries of a table, classify its region with c64-knowledge. Do not write a script that draws or decodes them.
+- A script of the project decodes only a format of the program, for example a packed map or a music stream. Put the script in `tools/` of the project. Its output files are the assets, for example in `assets/rooms/`.
+- When the code of the program makes the data, run that code in VICE with a run of c64-testing. Observe the memory, or capture the screen. Do not write a 6502 emulator in the script.
 
 In the call graph, a solid arrow is a call, a thick arrow is a table entry, and a dotted arrow is a jump. A table entry goes from each routine that reads the table to each target in code. A table of data addresses gives no arrow.
 

package/skills/c64-docs/references/style.md

@@ -27,7 +27,7 @@ These rules apply to each page that you write. `link.ts` checks the rules that a
 - Use mermaid for the diagrams: `flowchart` for calls and data flow, `stateDiagram-v2` for state machines. Write the name and the address in each node: `"draw_room $09BC"`.
 - A diagram gets no links. Give the links in a table or a list under the diagram.
 - Keep a diagram small: at most about 20 nodes. Make two diagrams before one diagram that a reader cannot read.
-- Embed an image only from the project. It can be an extracted asset (for example `../assets/sprites/bruce.png`), an image of the reference (`reference/images/`), or a PNG that a skill made. `link.ts` checks that each image exists.
+- Embed an image only from the project. It can be an image of the reference (`reference/images/`) or a PNG that a skill made. It can also be an asset that a script of the project made from a format of the program, for example `../assets/rooms/room00.png`. `link.ts` checks that each image exists.
 - Give each image one line of text that tells what it shows.
 
 ## Text

package/skills/c64-docs/scripts/lib/reference.ts

@@ -6,7 +6,7 @@
 import { posix } from "node:path";
 
 import { formatC64Address, POINTER_TABLE_TYPES, pointerTableEntries, type PointerTableType } from "#src/c64.ts";
-import { bitmapFrame, encodePng, PATTERN_PALETTES, scaleFrame, screenText, spriteSheet, type GraphicsMode } from "#src/graphics.ts";
+import { bitmapFrame, charsetFrame, encodePng, PATTERN_PALETTES, scaleFrame, screenText, spriteSheet, type GraphicsMode } from "#src/graphics.ts";
 import { mermaidGraph, ownerOf, routineEdges, routineHeads, type GraphReference, type RoutineHead } from "#src/knowledge/graph.ts";
 import type { CommentRow, ModuleRow, ReferenceRow, RegionRow, SymbolRow } from "#src/knowledge/read.ts";
 import type { RegionType } from "#src/knowledge/schema.ts";
@@ -37,7 +37,7 @@ export interface ReferenceFile {
 /** Files that the source map lists but that hold no code of the program. */
 const NOT_PIECES = new Set(["main.asm", "constants.asm", "macros.asm", "loader.asm"]);
 const TABLE_TYPES: readonly RegionType[] = [...POINTER_TABLE_TYPES, "jumps", "words"];
-const GRAPHICS_TYPES: readonly RegionType[] = ["sprite", "bitmap", "screen"];
+const GRAPHICS_TYPES: readonly RegionType[] = ["sprite", "bitmap", "charset", "screen"];
 /** A list longer than this ends with the number of the rest. */
 const MAX_LISTED = 40;
 /** A call graph with more edges is not readable: then it shows the calls only, and at most this many. */
@@ -327,7 +327,7 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
     const lines = [
       "# Graphics",
       "",
-      `Each sprite, bitmap and screen region of the knowledge. The knowledge gives no display mode and no colours, so a sprite or bitmap shows in hires and in multicolour, in pattern colours: black is pixel value 0, white is 1 in hires; in multicolour light grey is 1, grey is 2 and yellow is 3. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`,
+      `Each sprite, bitmap, charset and screen region of the knowledge. The knowledge gives no display mode and no colours, so a sprite, bitmap or charset shows in hires and in multicolour, in pattern colours: black is pixel value 0, white is 1 in hires; in multicolour light grey is 1, grey is 2 and yellow is 3. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`,
     ];
     if (input.image === undefined && graphics.length > 0) lines.push("", "Generate the reference with --image to show the graphics.");
     for (const region of graphics) {
@@ -343,9 +343,9 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
         continue;
       }
       for (const mode of ["hires", "multicolour"] as GraphicsMode[]) {
-        // A sheet of sprites, or a bitmap of at most 8 rows of cells, is small: each pixel shows as 2 x 2.
-        const raw = region.type === "sprite" ? spriteSheet(bytes, mode, region.element === 63 ? 63 : 64) : bitmapFrame(bytes, mode);
-        const frame = region.type === "sprite" || raw.height <= 64 ? scaleFrame(raw, 2) : raw;
+        // A sheet of sprites, a charset, or a bitmap of at most 8 rows of cells, is small: each pixel shows as 2 x 2.
+        const raw = region.type === "sprite" ? spriteSheet(bytes, mode, region.element === 63 ? 63 : 64) : region.type === "charset" ? charsetFrame(bytes, mode) : bitmapFrame(bytes, mode);
+        const frame = region.type === "sprite" || region.type === "charset" || raw.height <= 64 ? scaleFrame(raw, 2) : raw;
         const image = posix.join(out, "images", `${anchor}-${mode}.png`);
         files.push({ path: image, bytes: encodePng(frame, PATTERN_PALETTES[mode]) });
         lines.push("", `![${anchor} in ${mode}](${rel(page, image)})`);

package/skills/c64-knowledge/SKILL.md

@@ -75,6 +75,7 @@ Region types:
 |---|---|
 | `code` | Instructions. |
 | `bytes`, `words`, `petscii`, `screen`, `bitmap`, `sprite` | Data of that form. |
+| `charset` | Characters of a character set, 8 bytes for each character. |
 | `addresses`, `addresses-split` | A table of addresses: one table of 16-bit values, or a low-byte table and then a high-byte table. |
 | `rts-addresses`, `rts-addresses-split` | The same, with each value the target minus 1, for a PHA, PHA, RTS dispatch. |
 | `jumps` | A table of `JMP abs` instructions. Each 3-byte entry is an entry point. It is code. |

package/skills/c64-reverse-engineering/SKILL.md

@@ -36,6 +36,7 @@ One repository can hold several programs, with one project folder for each progr
 - Put a run file whose results are the evidence for a finding in `runs/`, with its results. Then git keeps the run file and the results, and another person can do the run again.
 - A subagent can have no emulator tools. Give it its experiments as run files of the c64-testing skill. Each run starts its own emulator, so many runs can go at the same time. The emulator of the emulator tools is one machine, for the main session.
 - To name a large program with more agents at the same time, give each agent one range of addresses. Each agent writes a batch with its owner range. Then join the batches with `join` of the c64-knowledge skill, and apply the result one time.
+- Do not write a build script or a merge script. c64-source writes and assembles the loader with `--loader`, and `join` of c64-knowledge joins the batches.
 - Write the knowledge only with the c64-knowledge script. Do not write or edit the files in `.c64-re-tools/knowledge/` yourself.
 
 ## Workflow

package/skills/c64-source/scripts/lib/source.ts

@@ -735,7 +735,7 @@ function dataLines(item: DataItem, layout: Layout, breaks: Set<number>): Array<{
   const cells = cellsOf(item, layout, breaks);
   const element = item.region?.element;
   const perLine = (directive: Directive) =>
-    directive === "!word" ? WORDS_PER_LINE : directive === "!pet" || directive === "!scr" ? CHARS_PER_LINE : item.type === "sprite" ? 3 : element !== undefined && element <= 16 ? element : BYTES_PER_LINE;
+    directive === "!word" ? WORDS_PER_LINE : directive === "!pet" || directive === "!scr" ? CHARS_PER_LINE : item.type === "sprite" ? 3 : item.type === "charset" ? 8 : element !== undefined && element <= 16 ? element : BYTES_PER_LINE;
   const lines: Array<{ address: number; text: string }> = [];
   let group: Cell[] = [];
   const flush = () => {

package/src/graphics.ts

@@ -1,6 +1,6 @@
 // Indexed images: the PNG encoder of emulator frames, and the C64 graphics
 // in memory as images for the documentation (D80). A region of the knowledge
-// gives no display mode and no colours, so a sprite or a bitmap is read
+// gives no display mode and no colours, so a sprite, a bitmap or a charset is read
 // both in hires and in multicolour, with fixed pattern palettes.
 
 import { crc32, deflateSync } from "node:zlib";
@@ -102,15 +102,15 @@ export function spriteSheet(bytes: Uint8Array, mode: GraphicsMode, stride = 64,
   return { width, height, pixels };
 }
 
-/** A bitmap of 8x8 cells of 8 bytes, 40 cells to a row, as the VIC reads it. */
-export function bitmapFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame {
+/** Cells of 8 bytes as 8x8 pixels, `perRow` cells to a row, cell 0 at the top left. */
+function cellFrame(bytes: Uint8Array, mode: GraphicsMode, perRow: number): IndexedFrame {
   const cells = Math.ceil(bytes.length / 8);
-  const width = Math.min(cells, 40) * 8;
-  const height = Math.ceil(cells / 40) * 8;
+  const width = Math.min(cells, perRow) * 8;
+  const height = Math.ceil(cells / perRow) * 8;
   const pixels = new Uint8Array(width * height);
   for (let cell = 0; cell < cells; cell++) {
-    const left = (cell % 40) * 8;
-    const top = Math.floor(cell / 40) * 8;
+    const left = (cell % perRow) * 8;
+    const top = Math.floor(cell / perRow) * 8;
     for (let row = 0; row < 8; row++) {
       bytePixels(bytes[cell * 8 + row] ?? 0, mode).forEach((value, x) => (pixels[(top + row) * width + left + x] = value));
     }
@@ -118,6 +118,16 @@ export function bitmapFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame
   return { width, height, pixels };
 }
 
+/** A bitmap of 8x8 cells of 8 bytes, 40 cells to a row, as the VIC reads it. */
+export function bitmapFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame {
+  return cellFrame(bytes, mode, 40);
+}
+
+/** A character set: characters of 8 bytes, 16 to a row, so character N is in row N / 16 and column N % 16. */
+export function charsetFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame {
+  return cellFrame(bytes, mode, 16);
+}
+
 /** Each pixel as a square of `factor` pixels, so a small image is readable on a page. */
 export function scaleFrame(frame: IndexedFrame, factor: number): IndexedFrame {
   const width = frame.width * factor;

package/src/knowledge/schema.ts

@@ -25,6 +25,7 @@ export const REGION_TYPES = [
   "screen",
   "bitmap",
   "sprite",
+  "charset",
   "workspace",
   "unused",
   "dual-use",
@@ -263,7 +264,7 @@ function createSchema(db: DatabaseSync): void {
 }
 
 /** The version of the index this build makes. An index with another version is emptied and made again. */
-export const INDEX_VERSION = 3;
+export const INDEX_VERSION = 4;
 
 function indexVersion(db: DatabaseSync): number | undefined {
   const hasMeta = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();