c64-kb 0.17.0

package/docs/techniques/transitions.md

@@ -0,0 +1,405 @@
+---
+category: effect
+chip: VIC-II
+---
+
+<!-- doc-type: technique-reference -->
+
+# Transitions
+
+The effects that carry a demo from one part to the next. The demo-design
+pages name the family (`demo-design/demo-design-philosophy.md`, "Amazing
+transitions": palette splits, screen-clearing raster sweeps, charset swap
+flickers, DRAM fades) and say a transition is an effect in its own right,
+not a cut. This page holds the members that have a page and a recipe. A
+raster sweep, a charset flicker and a DRAM fade have no recipe yet.
+
+## colour_fade — Fade to black through a luminance-ordered colour table
+
+**Complexity:** low
+**Region:** both
+**Uses registers:** D020, D021, D012
+**Cost:** cycles_per_frame=400, bytes_data=272
+**Cost basis:** estimated
+**Cost measured on:** kickassembler-colour-fade (per step)
+
+### Why
+
+The VIC-II has sixteen fixed colours and no brightness control, so a
+picture cannot be dimmed by scaling. What it can do is substitute: each
+colour on screen is replaced, step by step, by a darker colour from the
+same sixteen until everything is black. Done over a second or so this
+reads as a fade, and it costs nothing in the picture itself: the shapes
+stay where they are, only the colour registers and colour RAM change.
+
+### How
+
+1. Order the sixteen colours from darkest to brightest. Over the RGB
+   triples VICE emits for its PAL palette (`runtime/vice-reference.md`,
+   "Reading the exit screenshot"), Y = 0.299 R + 0.587 G + 0.114 B gives
+   0, 6, 9, 2, 11, 8, 4, 14, 12, 5, 10, 3, 15, 13, 7, 1 (arithmetic on
+   the table, rung 3). The NTSC triples give the same order except that
+   2 and 11 swap and 4 and 8 swap; the recipe uses the PAL order on both
+   models and the difference is one rank in two places.
+2. Build a table `fade[step][colour]` of seventeen rows by sixteen
+   colours. Row 0 is the identity, row 16 is all zeros, and row `s` maps
+   colour `c` to `order[round(pos(c) * (16 - s) / 16)]`, where `pos(c)`
+   is the colour's rank in the order. Each column is monotone: a colour
+   never gets brighter as the fade goes on. KickAssembler builds the 272
+   bytes at assembly time with two nested `.for` loops.
+3. Every N frames advance the step. For each step, look up every colour
+   the picture uses in the current row and write the result where the
+   picture reads it: `$D020`/`$D021` for bars, colour RAM for text,
+   `$D027`-`$D02E` for sprites, the screen-RAM nibbles for a bitmap.
+4. At step 16 hold; the picture is black. To fade in, walk the rows in
+   the other direction.
+
+### Why it works
+
+The VIC-II reads its colour registers as it draws (see `raster_bars` in
+`raster.md`: the registers are transparent, there is no per-line latch),
+so writing the substituted colour recolours the picture on the next line
+with no redraw of screen or bitmap memory. The luminance order is what
+makes the substitution read as dimming rather than as a palette change:
+at each step the eye sees the same shapes, darker. Hue shifts are the
+price of a fixed palette: white goes through light grey, mid grey and
+dark grey; yellow through light green and green. Rounding in the table
+merges ranks, so two colours adjacent in the order can show the same
+colour for a step; in the recipe, step 9 shows only eight distinct
+colours across the sixteen bars. Dark colours reach black first (blue,
+rank 1, is black from step 9) while white takes all sixteen steps, which
+is what a real fade looks like: the dark parts go first.
+
+### Variations
+
+**Text screen.** Rewrite the thousand colour-RAM bytes through the table.
+Per cell `LDA $D800,X` (4), `AND #15` (2), `TAY` (2), `LDA (ROW),Y` (5),
+`STA $D800,X` (5) is 18 cycles counted from the instruction timings, not
+measured here, so a full screen is about 18,000 cycles, close to a whole
+PAL frame (19,656). Spread it over frames, or keep a list of the colours
+the screen actually uses and only write those.
+
+**Bitmap.** In multicolour bitmap mode three of the four colours per cell
+sit in screen RAM as two nibbles and in colour RAM. A 256-entry table per
+step that maps both nibbles of a screen byte at once halves the work.
+
+**Fade in, or fade to white.** Walk the rows from 16 down to 0 for a fade
+in. For a fade to white, build the order the other way round so every
+column walks up the luminance order.
+
+**Easing.** A table of frames-per-step instead of a constant gives a slow
+start and a quick finish, or the reverse.
+
+**Partial fade.** Fade one region and pin another. The recipe fades the
+bars and leaves the caption's colour RAM at white, so the held frame
+still says which step it is.
+
+### Cycle budget
+
+Not raster critical. The table lookup for sixteen bars in the recipe is
+`LDY base,X` (4), `LDA (ROW),Y` (5), `STA barcol,X` (5), `DEX` (2),
+`BPL` (3): 19 cycles per bar, about 300 per step, from the instruction
+timings. The busy-wait that draws the bars is the raster bars' cost, not
+the fade's. Step 16 needs the row pointer to be formed with the carry
+kept: `step * 16` is 256 at the last step, and a `CLC` after the shifts
+sends the pointer back to row 0, so the picture snaps back to full colour
+instead of going black. An earlier draft of the recipe did exactly that,
+and the run at 8,000,000 cycles showed the step-0 bars under a caption
+reading step 16.
+
+### Recipes
+
+- `recipes/kickassembler/colour-fade.md`
+
+---
+
+## colour_cycling — Rotate a colour table through a fixed set of cells
+
+**Complexity:** low
+**Region:** both
+**Uses registers:** D012, D021
+**Cost:** cycles_per_frame=3265
+**Cost basis:** measured-vice
+**Cost measured on:** kickassembler-colour-cycling (one step, in the vertical blank from line 251)
+
+### Why
+
+Water, a conveyor belt, a glowing rune, a pulsing logo: things that move
+without changing shape. Redrawing them costs screen or bitmap writes every
+frame. Cycling costs colour writes only. The shapes are drawn once, in a
+pattern that steps through a short list of colours, and each step rotates
+which colour each cell shows. The eye reads the rotation as motion along
+the pattern.
+
+### How
+
+1. Choose a short palette, eight colours or fewer, and draw the region so
+   that adjacent cells take consecutive entries. A band that runs down
+   the screen gives each row one entry; a diagonal gives cell `(row, col)`
+   entry `(row + col) mod n`.
+2. Keep a phase counter. Every N frames add one to it, modulo the palette
+   length. The recipe steps every second frame.
+3. On a step, rewrite the region's colour cells: the cell that held entry
+   `k` now takes entry `k + phase`. Write the table twice end to end so an
+   index of `phase + k` never needs masking.
+4. Land the rewrite where the beam is not: after the last text line, or
+   before the first line of the region. Colour RAM is read as each row is
+   drawn, so a rewrite that overlaps the beam shows the old colour above
+   the beam and the new one below it for that frame.
+
+### Why it works
+
+Colour RAM is the picture's colour, not its shape: the VIC-II reads a
+cell's colour nibble on the badline that fetches the row and uses it for
+that row's eight lines (`hardware/vic-ii-reference.md`). A reverse space
+in every cell makes the colour the whole picture, and rotating the colours
+moves the pattern without a single screen-RAM write. The write budget is
+what bounds the region. In the recipe one step rewrites 320 cells at ten
+cycles a cell (`STA abs,X`, `DEX`, `BPL`), and the CIA timer in the
+listing reads 3,265 cycles for it on both models, 52 raster lines,
+measured in VICE. Started at the first line of the lower border, 251,
+that ends on line 303 on PAL and, after the wrap at 263, line 38 on NTSC,
+both before the region's first row is fetched, so no frame shows a torn
+band.
+
+### Variations
+
+**A $D021 triple.** In multicolour text the colours in `$D021`, `$D022`
+and `$D023` are shared by every cell, so rotating three register writes
+cycles the whole screen's pattern in a dozen cycles. It cannot cycle two
+regions differently.
+
+**Sprite colours.** Rotate `$D027` to `$D02E`, or the two shared
+multicolour registers `$D025` and `$D026`, for a glow that costs eight
+writes a step.
+
+**Every frame.** Stepping each frame doubles the speed and the budget
+stays the same per step; the recipe's two-frame step is a choice of pace,
+not a limit.
+
+**Sub-region.** Cycle a list of cell addresses instead of whole rows. The
+cost falls to the cells that carry the pattern; a list of 40 addresses is
+40 indirect stores.
+
+### Cycle budget
+
+Not raster critical as long as the rewrite is off the beam. The step is
+3,265 cycles for eight rows of forty cells, measured by CIA1 timer A in
+the recipe on both models; that is a sixth of a PAL frame and a fifth of
+an NTSC one. A rewrite of the whole thousand cells at the same rate would
+be about 10,200 cycles (arithmetic), which is 162 PAL lines and cannot
+fit between line 251 and the first badline at line 51; a full-screen
+cycle has to run over two frames or use a double buffer, which is the
+`full_field_redraw_exceeds_vblank` case. The step rate is in frames, so
+the pace differs by a fifth between PAL and NTSC.
+
+### Recipes
+
+- `recipes/kickassembler/colour-cycling.md`
+
+---
+
+## screen_wipe — Reveal or hide the screen a row, a column or a line at a time
+
+**Complexity:** low
+**Region:** both
+**Uses registers:** D012, D021
+**Cost:** cycles_per_frame=709
+**Cost basis:** measured-vice
+**Cost measured on:** kickassembler-screen-wipe (one reveal step, worst row)
+
+### Why
+
+A cut between two parts is a discontinuity the eye notices. A wipe turns
+the cut into an event: the old picture goes out along an edge, the new one
+comes in along another. On the C64 the cheap version needs no picture
+buffer at all. The screen stays where it is and its colour is taken away
+or given back, one strip at a time.
+
+### How
+
+1. Draw the screen. Keep a copy of, or a rule for, each row's colours so
+   the reveal can restore them.
+2. Keep a row counter and a direction. Every N frames take one step: in
+   the hide direction write the current row's forty colour RAM cells to
+   the background colour, in the reveal direction write them back from the
+   copy. Advance the row; at the last row turn the direction round or
+   stop.
+3. Land the step where the beam is not, as for `colour_cycling`. A row
+   write is short, so the lower border is more than enough.
+
+### Why it works
+
+A cell whose colour equals `$D021` is invisible whatever character it
+holds, so writing a row's colour RAM to the background colour hides the
+row without touching screen RAM, and writing it back reveals it. Nothing
+about the picture moves, which is why a wipe of this kind is cheap: the
+per-step cost is forty stores. In the recipe the hide step reads 491
+cycles and the reveal step 708 or 709 by CIA1 timer A, measured in VICE,
+the difference being one indirect load per cell for the reveal. Both are
+under a dozen raster lines. The reveal figure depends on the row, not the
+model: 708 at row 3 and 709 at row 11 on PAL, and 709 at row 11 on NTSC.
+The cause of the per-row cycle is not established.
+
+### Variations
+
+**Column by column.** Write one cell in each of the 25 rows per step
+instead of one row. The addresses stride by 40; a table of 25 row bases
+indexed by the column serves.
+
+**Diagonal by cell.** Hide cell `(row, col)` on step `row + col`. Each
+step touches at most 25 cells, one per row, and the edge runs at 45
+degrees.
+
+**Iris by table.** A table of cell addresses ordered by distance from the
+centre, hidden or revealed so many per step, gives a circle closing or
+opening. The table is the whole cost: a thousand two-byte entries, or a
+one-byte index into a row and column pair.
+
+**A $D011 blank moving down.** Clearing the display-enable bit at a
+raster line blanks from that line to the bottom of the frame and shows
+the border colour there. It needs a compare per frame and a raster split,
+which brings `d012_wrap_around` and `badline_cycle_loss` into the
+account; it is not built here and its timing is not measured here.
+
+**A per-line $D021 split.** Change the background colour at a raster line
+that moves down each frame, so the picture's background sweeps to black
+while its ink stays. The split's write must land in the horizontal border
+of the line or it shows as a step in the colour; the recipe does not do
+this and no figure is given for it here.
+
+### Cycle budget
+
+Not raster critical. The step is a single row's colour RAM, 491 cycles
+to hide and at most 709 to reveal, measured by CIA1 timer A in the recipe.
+Twenty-four rows at two frames each make a 48-frame wipe, 0.96 s on PAL
+and 0.8 s on NTSC (arithmetic from 19,656 and 17,095 cycles a frame). The
+step rate is in frames, so the two models finish at different times for
+the same cycle count; the recipe's verdict is taken on the frame count,
+not the cycle count, so it holds on both.
+
+### Recipes
+
+- `recipes/kickassembler/screen-wipe.md`
+
+---
+
+## screen_dissolve_lfsr — Cross-fade two text screens cell by cell in LFSR order
+
+**Complexity:** low
+**Region:** both
+**Uses registers:** D012
+**Requires:** lfsr_random
+**Cost:** cycles_per_frame=3203, cycles_per_frame_typical=3032, bytes_code=483
+**Cost basis:** measured-vice
+**Cost measured on:** kickassembler-screen-dissolve (one frame of 20 cells with its LFSR pulls, the worst and the median of the 50 frames; bytes are the code block less its two captions)
+
+### Why
+
+The fade changes colours, the cycling moves them and the wipe takes them
+away along an edge. None of them can put a second picture in place of
+the first: a fade to black and back is the nearest, and it costs a
+luminance table and a black frame in the middle. A dissolve replaces the
+screen one cell at a time in an order that looks random, so the new
+picture comes up through the old everywhere at once and the eye reads it
+as a cross-fade, with no palette work and no black in between. It needs
+the target screen in RAM, which the wipe does not, and a source of cell
+indices that visits every cell once, which is what a maximal LFSR is.
+
+### How
+
+1. Build the target screen in RAM, screen bytes and colour bytes, 1,000
+   of each. The visible screen holds the source.
+2. Take a 10-bit Galois LFSR with taps `$240`, the polynomial
+   x^10 + x^7 + 1, in the right-shifting form of `lfsr_random`: shift the
+   state right, and if the bit that fell out was 1 XOR the taps in. Seed
+   it with any non-zero value; the recipe uses 1.
+3. Each frame, in the lower border, pull N indices. A state of 1000 to
+   1023 is not a cell: pull again. For each cell copy the target's screen
+   byte and colour byte to the visible screen.
+4. When the state comes back to the seed every value from 1 to 1023 has
+   been produced once, so 999 cells are done. Copy cell 0 by hand; the
+   register never produces it. Then stop, and the picture is static.
+
+At N = 20 the whole screen takes 50 frames, 1.0 s on PAL and 0.83 s on
+NTSC (arithmetic from 19,656 and 17,095 cycles a frame), measured in the
+recipe as the last cell landing on frame 50 on both models, with cell 0
+as the twentieth slot of that frame.
+
+### Why it works
+
+A maximal-length LFSR is a permutation of its 2^n - 1 non-zero states,
+so it produces each cell index exactly once and never repeats one before
+the whole set is out; a random number generator with a repeat would copy
+some cells twice and leave others until the end. The recipe checks the
+permutation two ways: 1,023 steps in Python give 1,023 distinct values
+from 1 to 1,023, and the run comes back to its seed on the 1,023rd pull
+with 999 cells copied.
+
+Ten bits and not sixteen because 2^10 is the first power of two above
+1,000. Every state above 999 is a wasted pull; ten bits wastes 24 in
+1,023, sixteen would waste 64,535 in 65,535 and spend sixty-four pulls
+for every cell. The 24 wasted pulls fall where the sequence puts them,
+and the frame that meets most of them is the worst frame: 3,203 cycles
+against a median of 3,032 in the recipe, so the spread is small and the
+per-frame budget can be taken as N times the per-cell cost plus a little.
+
+The zero cell is the one an LFSR cannot give, for the reason in
+`lfsr_zero_state_lockup` (`pitfalls/cpu.md`): from zero the register
+stays at zero. That is also why the seed must be non-zero. The skip of
+1000 to 1023 keeps the index below the 24 bytes past the last cell that
+`colour_ram_index_past_last_cell_hits_cia1`
+(`pitfalls/text-mode-render.md`) is about: on the screen side those are
+unused bytes and the sprite pointers, on the colour side they are the end
+of the page, and one more past them is CIA1.
+
+### Variations
+
+**Colour RAM only.** Copy the colour byte alone and leave the screen
+bytes, so a picture dissolves from one palette to another; half the
+stores a cell, and no target screen RAM is needed, only 1,000 colour
+bytes. Not built here.
+
+**2 by 2 blocks.** Run a 250-state permutation over block indices (an
+8-bit LFSR wastes 5 in 255) and copy four cells a pull. Fewer, larger
+steps: the same 50 frames at N = 5 blocks, or a faster dissolve at the
+same cost. The block's four cells are at `i`, `i + 1`, `i + 40` and
+`i + 41` from the block's top-left cell. Not built here.
+
+**Bitmap by byte.** The same permutation over 8,000 bitmap bytes with a
+13-bit LFSR (8,191 states, 191 wasted), copying a byte a pull; the
+colour cells follow with a second 10-bit pass or by copying each cell's
+colour with its first byte. Eight times the cells of a text dissolve at
+the same N is eight times the frames, so N has to rise with it. Not
+built or timed here.
+
+### Cycle budget
+
+Not raster critical. The recipe's frame of 20 cells with its LFSR pulls
+costs 3,203 cycles at worst and 3,032 at the median, by CIA1 timer A,
+identical on PAL and NTSC because the work starts on line 251 in the
+lower border where there is no badline and nothing in it depends on the
+model. That is about 150 cycles a cell for the recipe's shape (a
+subroutine call, four pointer high bytes and two indirect copies a
+cell), and the frame is over about 50 lines after line 251: line 302 on
+PAL, and on NTSC, whose frame wraps at 263, about line 37 of the next
+frame, both in the border. The blank the copies have to fit is not the
+same on the two models: about 7,000 cycles on PAL and about 4,100 on
+NTSC between line 251 and line 51 of the next frame (arithmetic:
+(312 - 251 + 51) x 63 and (263 - 251 + 51) x 65). The cost scales with
+N at about 150 cycles a cell, so 40 cells a frame, about 6,000 cycles
+and a 25-frame dissolve, fits the PAL blank only; on NTSC the copies
+stay in the blank up to roughly N = 27 (4,095 / 150; arithmetic, not
+measured here). Past that N the copies run into the display and a cell
+can be caught between its screen byte and its colour byte, which is the
+tearing `full_field_redraw_exceeds_vblank` describes; at N = 20 it is
+not near on either model.
+The sequential control in the recipe, the same copies in index order,
+costs 2,226 at worst, so the LFSR and its skip are about a third of the
+frame.
+
+### Recipes
+
+- `recipes/kickassembler/screen-dissolve.md`
+
+---

package/docs/toolchains/cartconv-reference.md

@@ -0,0 +1,262 @@
+---
+tool: cartconv
+tool_kind: asset-converter
+maintainer: VICE team
+license: GPL-2.0-or-later
+home_url: https://vice-emu.sourceforge.io/
+version_verified: "3.10"
+---
+
+<!-- doc-type: toolchain-reference -->
+
+# cartconv: raw ROM binaries to a .CRT cartridge image, and back
+
+## Tool
+
+cartconv wraps a raw ROM binary in the `.CRT` container that VICE, the
+EasyFlash tools and most cartridge hardware menus read, and unwraps a
+`.CRT` back to a binary. It ships with VICE and is on this machine at
+`/opt/homebrew/bin/cartconv`. `cartconv --version` prints
+`cartconv (VICE 3.10)`. Everything marked "run here" was done with that
+build on 2026-09-23, booting the results in the windowless x64sc 3.10.
+
+A game needs it when its code is assembled or compiled as a flat ROM
+image and the emulator or the flash tool wants the container: the
+header names the hardware type, and from that VICE decides which bank
+register to emulate. The other route is to emit the `.CRT` from the
+assembler itself, which is what the two KickAssembler cartridge recipes
+do; cartconv then serves as the checker (`-c`) and the inspector (`-f`).
+
+The licence in the frontmatter is VICE's, read from
+`/opt/homebrew/opt/vice/COPYING` (GPL version 2 with the "any later
+version" clause). cartconv is a build tool; the output carries none of
+its code.
+
+**Targets:** 6510
+
+## Build pipeline
+
+Input is a raw binary with no load address (what KickAssembler's
+`outBin` and Oscar64's `-tf=bin` write) or a PRG whose two-byte load
+address cartconv strips. Output is a `.CRT`: a 64-byte header and one
+`CHIP` packet per 8 KB or 16 KB of ROM. The reverse direction (`-t bin`)
+concatenates the packets' data back into a binary.
+
+### .CRT — Cartridge image
+**Produced by:** cartconv, kickassembler, oscar64
+**Consumed by:** cartconv, vice
+
+Header, then CHIP packets. The layout as decoded here is under "The
+file, as decoded"; the reference table is in
+[c64-file-formats](../formats/c64-file-formats.md), ".CRT".
+
+### .BIN — Raw ROM image
+**Produced by:** kickassembler, oscar64, cartconv
+**Consumed by:** cartconv
+
+The bytes of the ROM in bank order, nothing else. For a banked type
+the file is bank 0's 8 KB, then bank 1's, and so on.
+
+## Command line
+
+```text
+cartconv -t normal -l 0x8000 -i bank0.bin -o normal.crt -n "NORMAL 8K"   # generic 8 KB, type 0
+cartconv -p -t md -i banks.bin -o md.crt -n "MAGIC DESK"                  # Magic Desk, type 19
+cartconv -p -t ocean -i banks.bin -o ocean.crt -n "OCEAN"                 # Ocean, type 5
+cartconv -f md.crt                                                        # print header and packet table
+cartconv -c md.crt                                                        # check; exit 0 when sound (and when the file is missing)
+cartconv -t bin -i md.crt -o md.bin                                       # unwrap to a raw binary
+cartconv --types                                                          # the type table with each name and id
+```
+
+| Flag | Meaning (from `cartconv` with no arguments, exercised here where the text says so) |
+|---|---|
+| `-t <type>` | Output type, by short name or by `.CRT` hardware id (`md` or `19`). Run here with `normal`, `md`, `ocean`, `easy`. Without `-t` cartconv expects a `.crt` input and unwraps it to a binary; a raw binary given without `-t` is refused with `File is already in binary format` (run here). The `(Default bin->crt)` note in `--types` names the hardware type a binary becomes once `-t normal` or its id is given, not what happens when `-t` is omitted. |
+| `-i`, `-o` | Input and output file names. |
+| `-n <name>` | The 32-byte cartridge name field. Run here: written as given (case kept), zero-padded to 32 bytes. |
+| `-l <addr>` | Load address of the input, decimal or `0x` hex. Run here with `0x8000` for the 8 KB type. Not run here without it. |
+| `-p` | Accept an input whose size is not one of the type's sizes. Run here: a 16 KB binary was refused by `md`, `ocean` and `easy` with "Input file size (16384) doesn't match ... requirements", and accepted with `-p`. A 32 KB binary was accepted by `md` and `ocean` without it. |
+| `-b` | Write every bank, including all-`$FF` ones. Run here on a 32 KB Magic Desk input: the file was byte-identical with and without `-b`, so the two empty banks were kept either way at this size. |
+| `-s <rev>` | Hardware revision, the subtype byte. Run here with `-s 1` on `easy`: the version field became 1.01 and byte `$1A` became 1. |
+| `-f <file>` | Print the header, the mode the EXROM and GAME bytes select, and one line per CHIP packet. |
+| `-c <file>` | Check a `.CRT`. Run here: exit 0 on every file this page built, and also when the file cannot be opened (`Error: Can't open` is printed but the status is 0), so check the file exists before trusting the status. |
+| `-r` | Repair mode: accept a broken input. Not run here. |
+| `-q`, `-v` | Quiet, verbose. |
+| `--options-file` | Write the options that reverse the conversion. Not run here. |
+
+## Type table
+
+Ids and short names are cartconv's own (`--types`, run here). The bank
+register and the bank size are measured only where the row says so: the
+program in "Boot results" wrote the register from RAM and read a marker
+byte back from the new bank.
+
+| Type | Id | Short name | Bank register | Bank at `$8000` | Rung |
+|---|---|---|---|---|---|
+| Generic 8 KB / 16 KB | 0 | `normal` | none | 8 KB, or 16 KB with `$A000` | measured: a write to `$DE00` changed nothing |
+| Ocean | 5 | `ocean` | `$DE00` | 8 KB, and the same 8 KB seen at `$A000` | measured in VICE with a 32 KB image; larger Ocean images not measured here |
+| Magic Desk | 19 | `md` | `$DE00` | 8 KB | measured; the bit that switches the ROM off is not measured here |
+| EasyFlash | 32 | `easy` | `$DE00`, mode in `$DE02` | 8 KB ROML plus 8 KB ROMH per bank | from `cartridge_bank_easyflash` in [memory-banking](../techniques/memory-banking.md) and the `easyflash-save` recipe, not measured here |
+| Magic Desk 16K | 85 | `md16` | not measured here | 16 KB | cartconv's table only |
+| C64 Games System | 15 | `gs` | not measured here | not measured here | cartconv's table only |
+| GMod2 | 60 | `gmod2` | not measured here | not measured here | cartconv's table only |
+| Action Replay V5 | 1 | `ar5` | not measured here | not measured here | cartconv's table only |
+| Final Cartridge III | 3 | `fc3` | not measured here | not measured here | cartconv's table only |
+| Retro Replay | 36 | `rr` | not measured here | not measured here | cartconv's table only |
+
+`ulti` (Ultimax, 4, 8 or 16 KB) has no id of its own: it is type 0 with
+EXROM high and GAME low.
+
+## The file, as decoded
+
+Every `.CRT` this page built was read with the script below and with
+`cartconv -f`, and the two agreed on every field.
+
+```text
+import struct, sys
+for path in sys.argv[1:]:
+    d = open(path, "rb").read()
+    hlen, ver, hw, exrom, game = struct.unpack(">IHHBB", d[16:26])
+    name = d[32:64].split(b"\0")[0].decode("ascii", "replace")
+    print(path, len(d), d[0:16], hlen, f"{ver>>8}.{ver&255:02d}", hw, exrom, game, name)
+    off = hlen
+    while off + 16 <= len(d):
+        plen, ctype, bank, load, size = struct.unpack(">IHHHH", d[off+4:off+16])
+        print(f"  CHIP@{off:#x} {d[off:off+4]} len {plen} type {ctype} bank {bank}"
+              f" load ${load:04X} size {size} first {d[off+16]:02X} last {d[off+16+size-1]:02X}")
+        off += plen
+```
+
+Header, 64 bytes, every multi-byte field big-endian:
+
+| Offset | Size | Field | Run here |
+|---|---|---|---|
+| `$00` | 16 | `C64 CARTRIDGE` and three spaces | every file |
+| `$10` | 4 | header length | `$40` in every file |
+| `$14` | 2 | version | `$0100` (1.00); `$0101` after `-s 1` |
+| `$16` | 2 | hardware type | 0, 5, 19, 32 as ordered |
+| `$18` | 1 | EXROM line level, 0 low | 0 for types 0, 5, 19; 1 for cartconv's EasyFlash |
+| `$19` | 1 | GAME line level, 0 low | 1 for types 0 (8 KB) and 19; 0 for type 5 and cartconv's EasyFlash |
+| `$1A` | 1 | hardware revision (subtype), 0 unless `-s` | 0; 1 after `-s 1`, which `-f` prints as "Hardware Revision: 1" |
+| `$1B` | 5 | reserved | zero |
+| `$20` | 32 | name, zero-padded | as given to `-n`, or `OSCAR` from Oscar64 |
+
+CHIP packet, 16 bytes then the data:
+
+| Offset | Size | Field | Run here |
+|---|---|---|---|
+| `$00` | 4 | `CHIP` | every packet |
+| `$04` | 4 | packet length including these 16 bytes | `$2010` for 8 KB, `$4010` for 16 KB |
+| `$08` | 2 | chip type: 0 ROM, 1 RAM, 2 flash | 0 from cartconv for types 0, 5, 19 and from Oscar64 for every target; 2 from cartconv for `easy` |
+| `$0A` | 2 | bank number | 0, 1, 2, 3 in order for the banked types |
+| `$0C` | 2 | load address | `$8000`; `$A000` for cartconv's EasyFlash ROMH; `$E000` for Oscar64's |
+| `$0E` | 2 | data size | `$2000`, or `$4000` for Oscar64's `crt16` |
+
+Sizes seen: 8,272 bytes for one 8 KB packet (64 + 8,208); 32,896 for
+Magic Desk and Ocean from a 16 KB input, because cartconv padded the
+image to four banks and wrote all four; 16,480 for EasyFlash from the
+same input, split into bank 0 ROML at `$8000` and bank 0 ROMH at `$A000`.
+
+## Boot results
+
+One program, two 8 KB banks (the `crt-banked` recipe's listing, with
+`outBin` writing the raw banks instead of the container). Bank 0 boots
+through the `CBM80` signature, prints the marker byte it sees at `$9FFF`
+and the byte at `$BFFF`, copies a routine to `$0334`, and that routine
+writes 1 to `$DE00`, calls a routine at `$9FF0` in the new bank, reads
+`$9FFF` and `$BFFF`, and writes 0 back. Bank 1's routine turns the border
+green. Bank 0's marker is `$B0`, bank 1's `$B1`. Each file was booted
+with `x64sc -default -warp +sound -limitcycles 4000000 -exitscreenshot
+out.png -cartcrt file.crt`; VICE picked the hardware from the header,
+with no per-type option. The text was read from the PNG with the
+char-ROM decoder.
+
+| File | Line 1 | Line 2 | Border | Reading |
+|---|---|---|---|---|
+| `normal.crt` (type 0, 8 KB) | `BANK 0 BYTE B0 HI E0` | `BANK 1 BYTE B0 HI E0` | red | the `$DE00` write changed nothing; `$BFFF` is BASIC ROM (`$E0`) |
+| `md.crt` (type 19) | `BANK 0 BYTE B0 HI E0` | `BANK 1 BYTE B1 HI E0` | green | `$DE00` = 1 put bank 1 at `$8000`; `$A000` stayed BASIC: 8 KB mode |
+| `ocean.crt` (type 5) | `BANK 0 BYTE B0 HI B0` | `BANK 1 BYTE B1 HI B1` | green | `$DE00` = 1 switched both windows; `$BFFF` reads the same bank as `$9FFF`, so VICE mirrors the 8 KB bank at `$A000` for this image size |
+| `easy.crt` (type 32, from the same binary with `-p`) | none | none | orange screen | no program: EasyFlash boots in Ultimax mode from bank 0 ROMH at `$E000`, and this binary's second 8 KB is bank 1's ROML, not a ROMH with a reset vector |
+
+The red border on the generic type is the program's own failure path:
+the marker did not change, so the switch did not happen, which is the
+correct result for a cartridge with no bank register. The EasyFlash row
+is a statement about the input layout, not about cartconv or the type:
+a working EasyFlash image is built in the `easyflash-save` recipe.
+
+Oscar64's own containers, from a program that sets the border green and
+loops: `-tf=crt8` wrote type 0, EXROM 0, GAME 1, one 8 KB packet;
+`-tf=crt16` wrote type 0, EXROM 0, GAME 0, one 16 KB packet; `-tf=crt`
+wrote type 32 with EXROM 0, GAME 0, bank 0 ROML at `$8000` and bank 0
+ROMH at `$E000`, both chip type 0. `crt8` and `crt` booted green in
+x64sc; `crt16` was not booted here. Note the EasyFlash header
+difference: cartconv writes EXROM 1, GAME 0 and chip type 2 for the same
+hardware id. VICE booted both. Which one a flash tool prefers was not
+measured here.
+
+## Build integration
+
+**KickAssembler.** Two routes. Emit the banks as raw binaries with
+`.segmentdef Bank0 [start=$8000, min=$8000, max=$9fff, fill,
+fillByte=$ff]` per bank, gather them in bank order with `.segmentout`
+into a segment with `outBin="banks.bin"`, and run cartconv. Or write
+the container from the source: a `Crt` segment starting at 0 with
+`outBin="name.crt"` that lays down the 64-byte header, then for each
+bank a 16-byte `CHIP` packet followed by `.segmentout
+[segments="BankN"]`. The `crt-banked` and `easyflash-save` recipes do
+the second; the verifier here boots those files directly, so a recipe's
+listing must take that route. KickAssembler 5.25 has no cartridge
+directive: `.crt` and `.bank` both stop the assembler with `Invalid
+directive` (run here). An earlier version of the formats page said it
+produced `.CRT` files through those two directives; it does not.
+
+**Oscar64.** `-tf=crt8` and `-tf=crt16` write a generic type 0
+container; `-tf=crt` writes EasyFlash, with `-cid`, `-csub` and `-cname`
+to override the id, subtype and name
+([oscar64-reference](oscar64-reference.md), "CLI flags" and "Memory
+layout and banking"). No cartconv step is needed; `cartconv -f` still
+reads the result, and `-t bin` unwraps it when a flash tool wants the
+raw image.
+
+**Checking.** `cartconv -c` exits 0 on a sound file. Run here on three
+damaged copies: a bank 16 bytes short of its packet header's claim, and a
+file cut off before its last bank, both exited 255 with `this file seems
+broken`; a packet length larger than the data that follows it only
+printed `chunk length exceeds data size` and exited 0, so read the
+output as well as the status. It also exits 0 when it cannot open the
+file (run here), so a script should test that the file exists first.
+`cartconv -f`
+prints what VICE will see. Run both on any hand-emitted container before
+blaming the emulator: a wrong packet length makes the next `CHIP`
+signature land in the wrong place, and VICE's error names the offset.
+
+## Pitfalls
+
+**The input size must match the type, or pass `-p`.** Run here: 16 KB
+was refused by `md`, `ocean` and `easy`. The refusal names the size and
+the type. With `-p` cartconv pads to the next size in its table, so the
+file is bigger than the code: 32,896 bytes for two banks of Magic Desk.
+
+**A banked binary is bank order, not address order.** Bank 1's 8 KB
+follows bank 0's in the file even though both map at `$8000`. For
+EasyFlash the order is bank 0 ROML, bank 0 ROMH, bank 1 ROML, and so on
+(from the `-p easy` split, run here, and the `easyflash-save` recipe).
+Feeding a Magic Desk layout to `easy` produces a file that checks clean
+and does not boot.
+
+**Code that switches banks cannot run from the bank it switches out.**
+The routine that writes `$DE00` must be in RAM or in a bank that stays
+mapped. The measurement program copies it to `$0334`.
+
+**`-t` names are short and unlike the hardware names.** `md` is Magic
+Desk, `easy` is EasyFlash, `normal` is the generic type; `--types`
+prints the whole table. A number works too, and it is the `.CRT`
+hardware id, so `-t 19` and `-t md` are the same request.
+
+## See also
+
+- [crt-banked](../recipes/kickassembler/crt-banked.md): the two-bank Magic Desk program above, emitting its own `.CRT`.
+- [easyflash-save](../recipes/kickassembler/easyflash-save.md): an EasyFlash container with a ROMH boot bank, written from KickAssembler.
+- `cartridge_bank_easyflash` in [memory-banking](../techniques/memory-banking.md): the EasyFlash registers.
+- [oscar64-reference](oscar64-reference.md): `-tf=crt`, `-cid`, `-csub`, `-cname` and `__bankof`.
+- [c64-file-formats](../formats/c64-file-formats.md): the `.CRT` field tables.