c64-kb 0.17.0

package/docs/toolchains/kickassembler-reference.md

@@ -0,0 +1,1020 @@
+---
+tool: kickassembler
+tool_kind: assembler
+maintainer: Mads Nielsen (Camelot)
+license: Freeware (royalty-free for non-commercial; commercial use permitted)
+home_url: http://theweb.dk/KickAssembler/
+version_verified: "5.25"
+---
+
+<!-- doc-type: toolchain-reference -->
+
+# KickAssembler — 6502 Cross-Assembler
+
+## Tool
+
+KickAssembler (version 5.25 as of this writing) is a cross-assembler for the
+MOS 65xx family, written and maintained by Mads Nielsen (Camelot). It pairs a
+traditional assembler with a JavaScript-like script language that runs at
+assembly time. The script layer makes it straightforward to generate sine
+tables, sprite coordinate arrays, and other data directly in the source file
+without reaching for an external tool. The script and the assembler are
+integrated — script variables, constants, and loops interleave with mnemonics
+rather than running as a separate pre-pass.
+
+**Targets:** 6510
+
+KickAssembler is the second tool in the c64-kb toolchain ranking. It is the
+preferred choice when a task demands cycle-counted raster effects, sprite
+multiplexing, FLI/AFLI modes, or a full-assembly cracktro where every cycle
+matters. It is not the general-purpose workhorse; for projects where
+readability, refactorability, and C-level abstractions matter more than
+squeezing a handful of cycles per scanline, Oscar64 is the better pick.
+
+## Quick reference
+
+Install a Java runtime — Java 11 or later recommended, but the vendor's
+stated minimum is Java 8: the bundled 5.25 manual says "Java 8.0 or higher",
+and the 5.25 jar is compiled as Java 8 bytecode (all 548 classes are
+class-file major 52, read from the jar). The download page offers a Java 11
+runtime as a convenience; Java 11/17/21 LTS and Java 26 are the versions
+exercised here. An earlier version of this page said "Java 11 or later" as if
+it were the minimum. Download `KickAssembler.zip` from
+`http://theweb.dk/KickAssembler/`, unzip to a convenient directory, and
+assemble with:
+
+```
+java -jar KickAss.jar source.asm
+```
+
+Common flags:
+
+| Flag | Effect |
+|------|--------|
+| `-o output.prg` | Rename the output file |
+| `-odir dir/` | Write all output files to a directory |
+| `-symbolfile` | Write a `.sym` label file alongside the output |
+| `-vicesymbols` | Write a `.vs` VICE monitor label file |
+| `-libdir path` | Add a search path for `#import` and `LoadSid`/`LoadBinary` |
+| `-define SYM` | Define a preprocessor symbol |
+| `-showmem` | Print a memory map after assembly |
+| `-asminfo all` | Write assembly metadata to `asminfo.txt` — a plain-text file with `[section]` headers and semicolon-separated fields (not XML; an earlier version of this row gave `-asminfo file.xml`, which 5.25 rejects with "Invalid asminfo type: file.xml" and writes nothing). The argument is a selector, not a file name: `all`, `allPredefined`, `allSourceSpecific`, or section names (`version`, `libraries`, `directives`, `ppdirectives`, `errors`, `syntax`, `files`) joined with `\|`. Use `-asminfofile name.txt` to rename the output, or `-asminfotostdout` to print it instead. `labels` is not a selector ("Invalid asminfo type: labels") |
+| `-pseudoc3x` | Accept 3.x pseudo-command argument separator (semicolon) |
+
+By default, KickAssembler writes a single `.prg` file whose name matches the
+source file. Multiple output files (`.prg`, `.d64`, `.bin`, `.sym`, `.vs`) are
+produced when segments or the `-symbolfile` / `-vicesymbols` flags request
+them.
+
+## Build pipeline
+
+**Targets:** 6510
+
+### .PRG — Program file (executable)
+**Produced by:** kickassembler, oscar64, cc65
+**Consumed by:** vice
+
+The primary output. KickAssembler prepends a two-byte load address (little-
+endian) before the assembled bytes. The default name matches the source file.
+Use `-o` to override.
+
+### .BIN — Raw binary
+**Produced by:** kickassembler
+**Consumed by:** vice
+
+A headerless byte dump. Produced when a segment uses `outBin="filename.bin"`.
+Useful for code that is not loaded by the KERNAL (cartridge ROMs, raw block
+copy targets).
+
+### .D64 — 1541 disk image
+**Produced by:** kickassembler
+**Consumed by:** vice
+
+KickAssembler can create D64 images directly via the `.disk` directive, which
+wraps the CC1541 library. You can mix assembled segments and files from the
+host filesystem in the same image.
+
+### .SYM — KickAssembler symbol file
+**Produced by:** kickassembler
+
+Generated by `-symbolfile`. Contains `.label` declarations; labels declared
+inside `.namespace` blocks (or under `.filenamespace`) are exported inside
+matching `.namespace` blocks, everything else is flat (an earlier version of
+this page said every label was wrapped in a namespace; measured on 5.25, a
+top-level `clearScreen:` exports as a bare `.label clearScreen=$80e`). Other
+source files consume it via `.import source "file.sym"` to reference labels
+across separately assembled units. `KickAss.cfg` on this machine already
+contains `-symbolfile -showmem`, so a `.sym` is written on every build without
+the flag.
+
+### .VS — VICE monitor symbol file
+**Produced by:** kickassembler
+**Consumed by:** vice
+
+Generated by `-vicesymbols`. Each line is `al C:<hex address> .<name>` (an
+`add_label` monitor command; the `C:` memspace prefix was missing from an
+earlier version of this line). Load at startup with `-moncommands file.vs`,
+or interactively with `ll "file.vs"` (load_labels) — not `:load`, which is not
+a monitor command.
+vice-mcp reads `.vs` files to resolve label names during introspection.
+
+## Syntax overview
+
+### Labels
+
+Labels end with a colon at declaration and are bare at the call site:
+
+```asm
+loop:
+    inc $d020
+    jmp loop
+```
+
+Multi-labels (anonymous) start with `!`. Reference them with `!label-` (previous)
+or `!label+` (next). Bare `!:` and `!+` / `!-` work for quick forward/backward
+jumps:
+
+```asm
+ldx #100
+!loop:
+    dex
+    bne !loop-
+```
+
+Argument labels name the argument of a mnemonic for self-modifying code:
+
+```asm
+    ldx tmpX:#$00   // 'tmpX' names the immediate byte
+```
+
+`*` returns the current program counter value.
+
+### Number formats
+
+| Prefix | Base | Example |
+|--------|------|---------|
+| (none) | Decimal | `42` |
+| `$` | Hexadecimal | `$d020` |
+| `%` | Binary | `%10110001` |
+
+`<` is the low-byte operator; `>` is the high-byte operator.
+
+### Addressing modes
+
+| Notation | Mode |
+|----------|------|
+| `lda #$30` | Immediate |
+| `lda $30` | Zero-page |
+| `lda $30,x` | Zero-page,X |
+| `ldx $30,y` | Zero-page,Y |
+| `lda ($30,x)` | Indirect zero-page,X |
+| `lda ($30),y` | Indirect zero-page,Y |
+| `lda $1000` | Absolute |
+| `lda $1000,x` | Absolute,X |
+| `lda $1000,y` | Absolute,Y |
+| `jmp ($1000)` | Indirect |
+| `bne loop` | Relative (branch) |
+
+Force absolute mode with `.abs` / `.a`; force zero-page with `.zp` / `.z`:
+
+```kickassembler
+lda.abs $0030,x   // force absolute even though address fits in zero-page
+```
+
+### Comments
+
+Line comments are `//` only. `;` is NOT a comment — the semicolon is the
+statement separator (`lda #$00 ; sta $d020` assembles both instructions) and
+the separator inside `.for(init; cond; step)` headers — so text after it is
+parsed as code, giving "Pseudo command '<word>' not defined" and/or "Unknown
+symbol '<word>'" (measured on 5.25). Block comments `/* ... */` ARE
+supported, may span lines, and may appear inside a statement
+(`sta /* note */ $d021`). An earlier version of this page had both facts
+backwards, and four of its own fences carried `;` comments that did not
+assemble.
+
+## Directives
+
+The assembler directive set covers both classic output and the script layer.
+
+| Directive | Syntax example | Purpose |
+|-----------|----------------|---------|
+| `.byte` / `.by` | `.byte $01,$02,$03` | Output bytes |
+| `.word` / `.wo` | `.word $1000` | Output 16-bit little-endian words |
+| `.dword` / `.dw` | `.dword $12341234` | Output 32-bit little-endian values |
+| `.text` / `.te` | `.text "Hello"` | Output text using current encoding |
+| `.encoding` | `.encoding "petscii_upper"` | Set character encoding for `.text` |
+| `.fill` | `.fill 256, 127.5+127.5*sin(toRadians(i*360/256))` | Fill N bytes with an expression (loop var: `i`); sine, reciprocal and multiply table forms and their verification are `table_generation` in `../techniques/cpu-cycle-tricks.md` |
+| `.fillword` | `.fillword 5, i*$80` | Fill N words |
+| `.lohifill` | `.lohifill $100, i*40` | Fill a lo-byte table followed by a hi-byte table |
+| `.const` | `.const DELAY=7` | Define an immutable script constant |
+| `.var` | `.var x=27` | Define a mutable script variable |
+| `.eval` | `.eval x=x+1` | Evaluate a script expression |
+| `.if` | `.if(x>10) { ... } else { ... }` | Conditional assembly |
+| `.for` | `.for(var i=0; i<8; i++) { ... }` | Counted loop |
+| `.while` | `.while(i<10) { ... }` | Condition loop |
+| `.return` | `.return width*height` | Return from a `.function` |
+| `.assert` | `.assert "msg", got, expected` | Compare two values at assembly time and print the result. A mismatch prints `ERROR IN ASSERTION` but still writes the PRG and exits 0 (measured on 5.25) — it does not guard the build; use `.errorif` for that |
+| `.errorif` | `.errorif addr >= $100, "operand not in zero page"` | Abort assembly with a message if the condition is true: exit 1, no output file (measured on 5.25) |
+| `.error` | `.error "unsupported configuration"` | Unconditionally abort assembly with a message: exit 1, no output file (measured on 5.25) |
+| `.label` | `.label color=$d020` | Assign a value to a label name |
+| `.align` | `.align $100` | Advance PC to next multiple of value |
+| `.cpu` | `.cpu _65c02` | Switch CPU instruction set |
+| `.zp` | `.zp { reg: .byte 0 }` | Mark unresolved labels as zero-page |
+| `.print` | `.print "init=$"+toHexString(init)` | Print to console at assembly time |
+
+Supported CPU identifiers: `_6502NoIllegals`, `_6502` (default; includes
+illegal opcodes), `dtv`, `_65c02`.
+
+## Memory layout
+
+The whole-program view (which constraints decide a layout, one worked layout in all three toolchains, and how to confirm it from `-showmem`) is `memory-layout-planning.md`, with the recipe `../recipes/kickassembler/memory-layout.md`.
+
+The program counter is set with `*=` (preferred in 5.x) or the older `.pc=`
+alias:
+
+```asm
+*=$0801 "BASIC start"
+    BasicUpstart2(main)
+
+*=$0810 "main"
+main:
+    lda #0
+    sta $d020
+    jmp *
+```
+
+The optional string after the address names the memory block. The `-showmem`
+flag prints a memory map of all named blocks after assembly.
+
+Use `virtual` to reserve an address range without writing it to the output
+file:
+
+```asm
+*=$0002 "ZP scratch" virtual
+zpTmp1: .byte 0
+zpTmp2: .byte 0
+```
+
+Virtual blocks can overlap non-virtual blocks; only the non-virtual bytes are
+written.
+
+### Segments
+
+Segments let you split output into multiple files or disk tracks:
+
+```asm
+.segment Code [outPrg="code.prg"]
+    *=$1000
+    jsr init
+    jmp *
+
+.segment Data [outBin="data.bin"]
+    *=$2000
+    .fill 1024, 0
+```
+
+Only the Default segment goes to the normal output file (the one named after
+the source, or by `-o`). A named segment whose bytes are not directed anywhere
+— no `outPrg`/`outBin` parameter, not listed in a `.file` or `.disk`
+directive, and not pulled into another segment via `segments=` — is
+assembled, appears in the `-showmem` map, and is written nowhere, with no
+warning (measured on 5.25: an earlier version of this example declared
+`.segment Code []`, and the Code segment vanished silently, with and without
+`-o`).
+
+Define a segment explicitly with `.segmentdef`:
+
+```asm
+.segmentdef Code  [start=$1000, max=$1fff]
+.segmentdef Music [start=$2000, max=$4fff]
+.segmentdef Screen [start=$0400, max=$07ff]
+```
+
+Switch the active segment with `.segment SegName`. Use
+`.file [name="out.prg", segments="Code,Data"]` to write a combined `.prg`
+from multiple segments.
+
+## Multi-file projects
+
+KickAssembler has no object files and no linker. A program is split in one of
+two ways. Both were built on 5.25 with the files below and produced a
+byte-identical `main.prg` (2,056 bytes); each PRG was run in VICE x64sc 3.10
+and turned the border and screen green.
+
+**`#import`: one assembly.** The module is pasted into the caller's parse, so
+it shares one symbol table, one memory map and every macro and `.const`.
+This is the right form for almost everything: shared macros, constants,
+zero-page allocations, and code that changes as often as the caller does.
+Put `#importonce` at the top of a library file (see Preprocessor). The module
+wraps its labels in a `.namespace` so the caller writes `border.set`:
+
+```asm
+// border_inc.asm
+.namespace border {
+*=$1000 "border module"
+set:
+    sta $d020
+    sta $d021
+    rts
+}
+```
+
+```text
+// inc_main.asm
+#import "border_inc.asm"
+*=$0801 "basic"
+BasicUpstart2(main)
+*=$0810 "main"
+main:
+    lda #5
+    jsr border.set
+    jmp *
+```
+
+```
+java -jar KickAss.jar inc_main.asm -o main.prg -showmem
+```
+
+**Separate assembly: `-symbolfile` plus `.import source`.** Each file is
+assembled on its own. The module writes a `.sym` file of its label addresses;
+the caller reads that file for the addresses and the module's `.prg` for the
+bytes. This is the right form when the module is large and rarely changes (a
+music player, a converted picture), lives at a fixed address, or is assembled
+by a different build step. The module declares `.filenamespace`, which is what
+puts its labels in a named block in the `.sym`:
+
+```asm
+// border.asm: assembled first, on its own
+.filenamespace border
+*=$1000 "border module"
+set:            // A = colour
+    sta $d020
+    sta $d021
+    rts
+```
+
+```
+java -jar KickAss.jar border.asm -o border.prg -symbolfile
+```
+
+That writes `border.prg` (9 bytes: a two-byte load address and seven bytes of
+code) and `border.sym`, which is exactly:
+
+```text
+.namespace border {
+  .label set=$1000
+}
+```
+
+The caller imports the addresses and places the bytes at the same `*=`; the
+`, 2` on `.import binary` skips the module's load address:
+
+```asm
+// main.asm: assembled second
+.import source "border.sym"
+*=$0801 "basic"
+BasicUpstart2(main)
+*=$0810 "main"
+main:
+    lda #5
+    jsr border.set
+    jmp *
+*=$1000 "border bytes"
+.import binary "border.prg", 2
+```
+
+```
+java -jar KickAss.jar main.asm -o main.prg -showmem
+```
+
+Two things go wrong with this form, both measured on 5.25 (sources in
+`error-sources/kickassembler/`):
+
+- The module has no `.filenamespace`, so its `.sym` is a flat
+  `.label set=$1000` and a namespaced call fails. The shipped source
+  (`import-source-no-namespace.asm`, against `flat-lib.sym`) calls
+  `jsr lib.set`:
+
+  ```text
+  Error: Unknown symbol 'lib'
+  at line 4, column 9 in import-source-no-namespace.asm
+  ```
+
+  Either add `.filenamespace border` to the module, or call the flat name
+  (`jsr set`).
+
+- Without a namespace the module's labels land in the caller's own scope, so a
+  label both files use (here `main`) collides:
+
+  ```text
+  Error: The symbol 'main' is already defined
+  at line 4, column 1 in symbol-clash-main.asm
+  ```
+
+  `.filenamespace` in the module is the fix for this too.
+
+The `.sym` holds addresses, nothing else: no macros, no `.const` values, no
+code. And it is a snapshot. Rebuild the module and the caller's copy of the
+addresses is stale until the caller is assembled again, so a build script
+always assembles the module first and the caller second. For the `.sym` and
+`.vs` formats themselves see "Symbol export for VICE/vice-mcp" below;
+`-showmem` on the caller lists the imported bytes as an ordinary block
+(`$1000-$1006 border bytes`).
+
+## Macros and pseudocommands
+
+### Macros
+
+A macro groups assembler directives for inline expansion. Call site labels do
+not collide across invocations because each call gets its own scope:
+
+```asm
+.macro FillColourRam(colour) {
+        lda #colour
+        ldx #250
+next:   dex                     // 249 down to 0, four quarters of 250
+        sta $d800,x
+        sta $d800+250,x
+        sta $d800+500,x
+        sta $d800+750,x
+        bne next                // Z from dex; sta leaves the flags alone
+}
+
+FillColourRam(1)                // white
+FillColourRam(14)               // light blue; this call's `next` is its own label
+```
+
+The leading `:` before a macro call is optional from version 4.0 but
+disambiguates a macro call from a mnemonic of the same name.
+
+Macros may call other macros or themselves (recursive, with a termination
+condition). They may be used before they are declared.
+
+### Pseudocommands
+
+Pseudocommands behave like custom mnemonics: they accept addressing-mode
+arguments separated by colons. Inside the body, arguments are `CmdValue`
+objects; inspect them with `.getType()` and `.getValue()`:
+
+```kickassembler
+.pseudocommand store value : dest {
+    lda value
+    sta dest
+}
+
+store #0 : $d020          // lda #0 / sta $d020
+store table,y : $0400,x   // lda table,y / sta $0400,x
+```
+
+Use `CmdArgument(AT_IMMEDIATE, value)` to construct new argument values
+programmatically inside a pseudocommand body.
+
+## Functions and scripting
+
+`.function` defines a reusable script-layer computation that returns a value.
+Functions may be overloaded by argument count:
+
+```asm
+.function area(w, h) {
+    .return w * h
+}
+
+.const SPRITE_BYTES = area(3, 21)
+lda #area(4, 8) + 10
+```
+
+Functions support `.if`, `.for`, `.while`, `.var`, and `.return` but do not
+generate bytes directly. The script language includes:
+
+- **Math**: `sin()`, `cos()`, `toRadians()`, `abs()`, `floor()`, `round()`,
+  `min()`, `max()`, `pow()`, `log()`, `sqrt()`, `mod()`
+- **String**: `toHexString()`, `toBinaryString()`, string concatenation with `+`
+- **Collections**: `List()`, `Hashtable()`, `.add()`, `.get()`, `.set()`,
+  `.size()`
+- **Type conversion**: `.asNumber()`, `.asBoolean()`, `.asString()`
+
+Use `.eval` to mutate a variable in-line; use `.var` to declare mutable
+script variables; use `.const` for true constants.
+
+## Preprocessor
+
+KickAssembler's preprocessor runs before the main parse pass. It mirrors C#
+preprocessor conventions. Directives start with `#`.
+
+| Directive | Example | Effect |
+|-----------|---------|--------|
+| `#define` | `#define NTSC` | Define a preprocessor symbol |
+| `#undef` | `#undef NTSC` | Remove a symbol |
+| `#if` | `#if NTSC` ... `#endif` | Conditional include |
+| `#elif` | `#elif DEBUG` ... | Else-if branch |
+| `#else` | `#else` ... | Else branch |
+| `#endif` | `#endif` | Close a `#if` block |
+| `#import` | `#import "lib.asm"` | Include a file |
+| `#importif` | `#importif STANDALONE "upstart.asm"` | Conditional import |
+| `#importonce` | `#importonce` | Guard a file against double inclusion |
+
+Define from the command line: `java -jar KickAss.jar src.asm -define NTSC`.
+
+`#importonce` belongs in library files. Unlike a traditional include guard it
+is a per-file flag, not a macro:
+
+```asm
+// lib.asm
+#importonce
+.macro WaitRaster(line) { ... }
+```
+
+## Importing data
+
+### Binary files
+
+`.import binary "file.bin"` embeds the raw bytes of a file at the current PC.
+Optional offset and length parameters trim the import:
+
+```asm
+.import binary "charset.bin", 0, $0800   // first 2 KB only
+```
+
+For programmatic access to individual bytes, use `LoadBinary()`:
+
+```asm
+.var data = LoadBinary("mytable.bin")
+table: .fill data.getSize(), data.get(i)
+```
+
+`data.uget(i)` returns unsigned bytes (0–255); `data.get(i)` returns signed
+(Java convention, so `$ff` = -1).
+
+KickAssembler ships built-in format constants for common graphics formats:
+
+| Constant | Blocks |
+|----------|--------|
+| `BF_C64FILE` | Skips the two-byte load address |
+| `BF_KOALA` | `Bitmap, ScreenRam, ColorRam, BackgroundColor` |
+| `BF_BITMAP_SINGLECOLOR` | `Bitmap, ScreenRam` (Bitmap at +$0000, ScreenRam at +$2000; `.print BF_BITMAP_SINGLECOLOR` on 5.25 — an earlier version of this row had the order reversed) |
+| `BF_FLI` | `ColorRam, ScreenRam, Bitmap` |
+| `BF_DOODLE` | `ColorRam, Bitmap` |
+
+```asm
+.var pic = LoadBinary("scene.prg", BF_KOALA)
+*=$2000; .fill pic.getBitmapSize(),   pic.getBitmap(i)
+*=$3f40; .fill pic.getScreenRamSize(), pic.getScreenRam(i)
+*=$4328; .fill pic.getColorRamSize(),  pic.getColorRam(i)
+```
+
+### Graphics from PNG/GIF
+
+`LoadPicture("file.png")` returns a picture object. Access individual pixels
+or request pre-converted C64 byte sequences:
+
+```asm
+*=$2000
+.var logo = LoadPicture("logo.png")
+.fill $800, logo.getSinglecolorByte((i>>3)&$1f, (i&7)|(i>>8)<<3)
+```
+
+For multi-color, supply a color table mapping RGB values to bit patterns.
+`getMulticolorByte(x, y)` takes `x` as a byte column (pixel position / 8) and
+`y` as a pixel row, so the fill must match the image's geometry:
+
+```asm
+// The manual's example: a 16x16-character (128x128-pixel) multicolour charset
+.var chars = LoadPicture("charset.gif",
+          List().add($000000, $ffffff, $888888, $444444))
+.fill $800, chars.getMulticolorByte(i>>7, i&$7f)   // x = byte column 0-15, y = pixel row 0-127
+
+// A 24x21 sprite: 3 byte columns x 21 rows = 63 bytes, padded to a 64-byte block
+.var mc = LoadPicture("sprite.gif",
+          List().add($000000, $ffffff, $888888, $444444))
+.fill 63, mc.getMulticolorByte(mod(i,3), floor(i/3))
+.byte 0
+```
+
+An earlier version of this page applied the `$800` / `i>>7` / `i&$7f` charset
+fill to `sprite.gif`; on a 24×21 image that fails with "y coordinate out of
+range : 21" (measured on 5.25). The trailing `.byte 0` keeps the next sprite
+pointer on a 64-byte boundary.
+
+`getPixel(x, y)` returns the RGB value for custom processing.
+
+## SID file support
+
+`LoadSid("file.sid")` parses a PSID or RSID file and exposes its header
+fields and binary data as script properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `music.location` | number | Load address of the SID data |
+| `music.init` | number | Init routine address |
+| `music.play` | number | Play routine address |
+| `music.songs` | number | Number of sub-songs |
+| `music.startSong` | number | Default song index (1-based) |
+| `music.size` | number | Byte length of the SID data |
+| `music.getData(i)` | number | i-th byte of the SID data |
+| `music.name` | string | Song title |
+| `music.author` | string | Author name |
+
+A raster-interrupt player built on those properties:
+
+```asm
+.var music = LoadSid("tune.sid")
+
+BasicUpstart2(main)
+
+main:   sei
+        lda #$7f
+        sta $dc0d               // CIA1: no timer interrupts
+        lda $dc0d               // acknowledge one already pending
+        lda #<player
+        ldx #>player
+        sta $0314               // KERNAL IRQ vector
+        stx $0315
+        lda #$f8                // raster line 248, below the text
+        sta $d012
+        lda $d011
+        and #$7f                // raster compare bit 8 = 0
+        sta $d011
+        lda #$01
+        sta $d01a               // raster interrupt on
+        lda #music.startSong-1  // the tune's default song, 0-based
+        jsr music.init
+        cli
+!:      jmp !-
+
+player: lda #$01
+        sta $d019               // acknowledge the raster interrupt
+        jsr music.play
+        jmp $ea81               // KERNAL: restore Y, X, A and RTI
+
+        *= music.location "SID data"
+        .fill music.size, music.getData(i)
+```
+
+The assembler resolves `music.init` and `music.play` to the actual addresses
+inside the SID data block, so changing the SID file requires no manual address
+updates.
+
+Use `-libdir /path/to/HVSC` so that `LoadSid("Artist/Title.sid")` searches
+the HVSC tree without absolute paths in source.
+
+## Symbol export for VICE/vice-mcp
+
+Two export modes produce label files for VICE:
+
+**`-vicesymbols`** writes `source.vs`:
+
+```
+java -jar KickAss.jar main.asm -vicesymbols
+```
+
+Each line in the `.vs` file is:
+
+```
+al C:<hex_address> .<label_name>
+```
+
+e.g. `al C:812 .clearScreen`. The `C:` is VICE's memspace prefix (computer
+memory) and the address is unpadded lowercase hex; an earlier version of this
+page omitted the `C:`, so a parser written from it mis-read every line.
+`BasicUpstart2` also emits an `.upstartEnd` label. Only labels (`name:` and
+`.label`) are exported; `.const` symbols are not.
+
+VICE loads these at startup with:
+
+```
+x64sc -moncommands main.vs main.prg
+```
+
+Or load interactively from the VICE monitor with `ll` (load_labels):
+
+```
+ll "main.vs"
+```
+
+VICE's `load` is the binary memory loader; `ll`/`load_labels` reads label
+files (an earlier version of this page gave `load "main.vs"`). The
+`-moncommands main.vs` form works because a `.vs` file is itself a list of
+`al` monitor commands.
+
+**vice-mcp** reads `.vs` files to resolve address-to-label mappings when
+setting breakpoints by name or displaying memory annotated with symbol names.
+
+**`-symbolfile`** writes `source.sym` in KickAssembler's own namespace format.
+This is for linking separately assembled files, not for VICE:
+
+```asm
+// main.asm  -- optional: .filenamespace main   (wraps main.sym in .namespace main { })
+// other.asm
+.import source "main.sym"
+jsr clearScreen        // labels are flat unless main.asm declares .filenamespace (or .namespace) - then jsr main.clearScreen
+jsr ns.sub             // an explicit .namespace ns { } in main.asm is exported as a block
+```
+
+An earlier version of this fence wrote `jsr main.clearScreen` with no
+`.filenamespace` in `main.asm`; that fails with "Unknown symbol 'main'"
+(measured on 5.25).
+
+The `.label` directive also creates labels that appear in both outputs:
+
+```asm
+.label SCREEN = $0400
+.label COLOR  = $d800
+```
+
+## Idioms — KickAss vs Oscar64-inline-asm vs cc65
+
+### Decision flow
+
+**Use KickAssembler as the standalone assembler when:**
+
+- The entire project is assembly — a demo, cracktro, or game where C-level
+  abstraction buys nothing.
+- You need cycle-exact raster IRQ timing (stable raster, FLD, FLI, AFLI).
+- You are writing a sprite multiplexer where every cycle in the sort and
+  update loop must be accounted for.
+- You need the script layer to generate large data tables (sine waves, trigonometry
+  tables, sprite coordinate arrays) without leaving the source file.
+
+Example: a raster bar that must hit a specific scanline within ±0 cycles on
+both PAL and NTSC requires hand-scheduled code with `.if` guards around
+NTSC-compensating nops. The KickAssembler `.if`/`.const` system handles this
+cleanly.
+
+**Use Oscar64 with a KickAssembler-built hot path when** the project is
+C-driven but one loop (inner sample loop, sprite sort, copper-list generator)
+needs more precision than the Oscar64 code generator can deliver.
+
+Oscar64 has no object-level link with foreign assemblers; an earlier version
+of this page said to "have the linker stitch them together", which does not
+work. Measured (Oscar64 build 2026-05-19): every positional argument is
+compiled as a C/C++ translation unit — an `.asm` input fails to parse as C,
+and a KickAssembler `.prg` passed alongside a `.c` file is accepted silently
+while the extern stays undefined (error 3022) and nothing is written. The
+working routes are (a) `__asm { }` inline assembly inside the C function, or
+(b) a KickAssembler-built raw binary (`KickAss.jar hot.asm -binfile -o
+hot.bin`) brought in with `#embed` and called through a function pointer:
+
+```c
+__export const char hot[] = {
+    #embed "hot.bin"      // directive must be on its own line
+};
+((void (*)(void))hot)();
+```
+
+The binary must be position-independent or assembled for the address the
+array lands at (pin it with `#pragma section`/`#pragma region`/`#pragma data`
+and check the `.map`), and any arguments must follow the Oscar64 calling
+convention by hand. `#embed` consumes the rest of its line:
+`{ #embed "hot.bin" };` on one line fails to parse.
+
+**Use cc65 when:**
+
+- A large cc65 code corpus (e.g., a mature library or port) already exists
+  and porting it to Oscar64 would cost more than the performance difference.
+- The task is purely text-mode utility work where the cc65 standard library
+  is convenient.
+
+**Do not reach for KickAssembler when:**
+
+- Readability, refactoring, and test-driven development matter more than
+  tight cycle counts (use Oscar64).
+- You are saving 5–10 cycles per scanline on code that runs once per frame
+  at non-display time — the overhead is not worth the cost in maintainability.
+- You need C standard library functions, data structures, or C++ features.
+
+## Debugging with VICE
+
+
+Reaching the monitor prompt headless, the register line, breakpoints, watchpoints and measuring cycles between two points are in `../runtime/vice-reference.md`, "Text monitor for debugging".
+Generate the `.vs` symbol file during assembly:
+
+```
+java -jar KickAss.jar main.asm -vicesymbols
+```
+
+Launch x64sc with the symbols pre-loaded:
+
+```
+x64sc -moncommands main.vs main.prg
+```
+
+Inside the VICE monitor, labels are available for `break`, `watch`, and
+`goto`:
+
+```
+break .clearScreen      ; break when PC hits clearScreen label
+watch store .COLOR      ; watch writes to the COLOR address
+dis .irq                ; disassemble from irq label
+```
+
+VICE reports breakpoint addresses alongside their label names when the `.vs`
+file is loaded.
+
+vice-mcp uses the same `.vs` file format. Set breakpoints by label, request
+memory reads by symbolic address, and receive register dumps annotated with
+label context — all without hard-coding addresses in the agent loop.
+
+## Pitfalls
+
+**Overlapping blocks are an assembly error, not a silent merge (5.25).** An
+earlier version of this page said the later block overwrote the earlier one
+"without any warning or error"; it does not. Two non-virtual blocks that
+overlap within the same segment — including the Default segment — stop the
+build with `Error: In segment 'Default' the memoryblock ... ($1000-$1003)
+overlaps ... ($1002-$1003)`, and no PRG is written; the message itself names
+both blocks and their ranges. Segments that are combined into one output are
+checked again at the `.file` level, so two segments that overlap and land in
+the same file also error; they only go unchecked when written to different
+files or when one is thrown away (manual §10.12). To permit an overlap
+deliberately — e.g. patching a base PRG — use `allowOverlap` on the
+`.segmentdef` for an overlap inside one segment, `allowOverlap` on the
+`.file` for an overlap between segments it combines (a `.file`-level
+`allowOverlap` does not cover an intra-segment overlap), or the `-aom`
+command-line switch, which lifts the check globally. In every allowed case
+the later block wins byte-for-byte (`*=$1000 .byte 1,2,3,4` then `*=$1002
+.byte 9,9` yields `01 02 09 09`, measured with `-aom`). `-showmem` prints
+nothing on a build that fails this check, so it is not the diagnostic here.
+Declare scratch regions `virtual`: a virtual block may overlap anything and
+is never written to the file.
+
+**Java version.** An earlier version of this page said "Java 8 is not
+supported in KickAssembler 5.x"; the jar says otherwise. KickAss.jar 5.25 is
+Java 8 bytecode throughout (all 548 classes are class-file version 52, built
+with JDK 13 but targeting 8), references no Java 9+ API, and the bundled
+manual states "Java 8.0 or higher". The only requirement the author has ever
+posted in the changelog is "now need java8 or higher" (v4.x, 2016); no 5.x
+release note changes it. The download page links an OpenJDK 11 runtime as a
+convenience, not as a stated minimum — do not read that as Java 8 being
+refused. It runs here under Temurin 26; Java 11/17/21 LTS are the sensible
+installs today, and nothing in the jar refuses Java 8, though execution on a
+Java 8 runtime was not tested on this machine.
+
+**Encoding issues with `.text`.** The default encoding is `screencode_mixed`.
+If your screen target uses the uppercase+graphics charset (the power-on
+default on a stock C64), strings written with `screencode_mixed` will
+produce garbled output. Switch with `.encoding "screencode_upper"` before
+any `.text` directive that targets upper-case-only output.
+
+**Macro hygiene.** Labels declared inside a macro are scoped to the macro
+call, so `loop:` in a macro does not collide across invocations. A `.var`
+declared inside the macro body is scoped to that invocation too (`Unknown
+symbol` afterwards, and a body-local `.var v` merely shadows a caller's `v`);
+an earlier version of this page said such variables leaked out, which is the
+wrong direction. The leak runs the other way: the body resolves names in the
+scope where the macro was defined, so `.eval v = v + 10` inside a macro
+changes the caller's `v` (measured on 5.25: two calls took `v` from 1 to 21).
+Keep the caller's state in a `.namespace` that the macro is defined outside
+of if the macro must not touch it; a macro defined inside the same namespace
+still sees and mutates it.
+
+**Pseudocommand argument separator changed between 3.x and 4.x.** The
+separator changed from semicolon to colon. Old 3.x code fails with `Invalid
+token` / `Pseudo command '...' not defined` unless you pass `-pseudoc3x` — it
+is loud, with no output; an earlier version of this page said it "fails
+silently or misassembles". If you are adapting code from CSDB or similar
+archives written for 3.x, check the separator.
+
+**`LoadPicture` accepts GIF and JPEG as well as PNG.** The manual's
+examples use GIF files. PNG works but the function name does not imply it;
+do not assume the function is PNG-only.
+
+The next five were each found by assembling this knowledge base's own
+listings with KickAssembler 5.25 (see `scripts/check-listings.ts`); every
+one of them had shipped in a recipe.
+
+**`(addr),y` with a non-zero-page operand assembles without a diagnostic.**
+Indirect-indexed addressing exists only for zero page. Give it a label in
+ordinary RAM and the assembler emits the zero-page opcode with the low byte
+of the address, so the code reads a pointer from wherever `$xx` happens to
+be — BASIC's workspace, in the case that was caught (`sine-scroller`
+printed a screen of `3`s). Keep every `(ptr),y` pointer below `$0100` and
+check with `-showmem` or a `.vs` dump if in doubt.
+
+**`.if (n)` on a number is an error, not a truthiness test.** "Can't get a
+boolean representation from a value of type number." Write `.if (n != 0)`.
+The same applies to the ternary `n ? a : b` in expressions.
+
+**Semicolons do not start comments.** KickAssembler comments are `//` and
+`/* */`. A `;` is parsed as code: `; SID player` becomes "pseudo command
+'SID' not defined". Listings pasted from ca65 or ACME sources fail this
+way, as do `txa : pha` colon-chained statements, which ca65 accepts and
+KickAssembler does not. Worse than the error is the comment that does not
+fail: `; inc $d020` assembles the `inc` (measured on 5.25, exit 0), so a
+commented-out instruction in pasted code is live.
+
+**A `!:` outside a `.for` is one label for every iteration.** `bpl !-`
+inside the body then resolves to the single `!:` above the loop and, once the
+expansion is long, fails with `relative address is illegal (jump distance is
+too far: -132)`. A `!:` placed *inside* the body is per-iteration — each
+`bpl !-` branches to its own (measured on 5.25, 40 × 11-byte bodies, offset
+−11 every time) — and so is a named label inside the body, because each
+iteration is its own scope. Neither is visible after the loop, nor from the
+body if it sits in a nested `.for`, `.if` or macro (`Unknown symbol '!-'`).
+Put the label inside the body; a label outside the loop only works while the
+whole expansion stays within 127 bytes. An earlier version of this pitfall
+said the opposite — that a `!:` inside the body was shared across iterations
+— and prescribed a label outside the loop, which is the form that fails.
+
+**A branch target more than 127 bytes away is an assembly error, and
+unrolled `.for` bodies get there fast.** `beq exit` across 700 bytes of
+macro expansion fails with "relative address is illegal". Invert the branch
+around a `jmp`.
+
+## Reading the errors
+
+Every message below was provoked on KickAssembler 5.25 with the minimal
+source named in the second column; the sources are files in
+`error-sources/kickassembler/` and are shown after the table. Each error
+prints the offending line, a caret under the token, the `Error:` line and an
+`at line L, column C in file` line, and the assembler exits 1 with no PRG
+written. The one exception is the failed `.assert`, which exits 0 and writes
+the PRG.
+
+| Message (verbatim) | Source | Cause | Fix |
+|---|---|---|---|
+| `Error: Unknown symbol 'nowhere'` | `unknown-symbol.asm` | A label or constant is used and never defined; also a typo, a label inside a `.namespace` or `.filenamespace` used without its prefix, or a `.sym` import whose module had no namespace (see Multi-file projects) | Define it, prefix it, or add `.filenamespace` to the module |
+| `Error: relative address is illegal (jump distance is too far: -202).` | `branch-out-of-range.asm` | A branch to a target more than 128 bytes back or 127 forward. There is no message with the words "branch out of range"; this is the wording | Invert the branch around a `jmp`, or move the code |
+| `Error: In segment 'Default' the memoryblock 'first' ($1000-$100f) overlaps 'second' ($1008-$1017)` | `memory-block-overlap.asm` | Two `*=` blocks in the same segment write the same bytes. The message names both blocks and their ranges; unnamed blocks appear as `Unnamed` | Move one block, or mark a reservation `virtual` (see Memory layout) |
+| `  one plus one=2 (3) -- ERROR IN ASSERTION!!!` then `Made 1 asserts , 1 FAILED!` | `failed-assert.asm` | `.assert "name", actual, expected` disagreed. The build still says `Writing prg file:`, still writes it (3 bytes here) and exits 0 | Grep the build log for `FAILED` in scripts; the exit code will not tell you |
+| `Error: Pseudo command 'Blink' not defined` | `macro-without-parentheses.asm` | A macro called without parentheses (`Blink` for `Blink()`) is parsed as a pseudocommand. A `;` line pasted from a ca65 source is parsed the same way, not skipped, and what it prints depends on the words: on 5.25 `;comment` gives `Pseudo command 'comment' not defined`, `; Comment text` gives that plus `Unknown symbol 'text'`, `; a comment here` gives `Syntax error`, and `; inc $d020` or `; lda #0` gives no error at all, the instruction after the `;` assembles into the PRG. The silent case is the one to look for | Write `Blink()`; use `//` for comments |
+| `Error: The symbol 'main' is already defined` | `symbol-clash-main.asm` with `symbol-clash-lib.asm` | Two definitions of one label in one scope, here through a flat `.sym` import | Rename, or give the module a `.filenamespace` |
+
+Sources (each is meant to fail, so none is in a buildable fence):
+
+`unknown-symbol.asm`
+
+```text
+*=$1000
+    lda #0
+    jsr nowhere
+    rts
+```
+
+`branch-out-of-range.asm`
+
+```text
+*=$1000
+loop:
+    .fill 200, $ea
+    bne loop
+```
+
+`memory-block-overlap.asm`
+
+```text
+*=$1000 "first"
+    .fill 16, 0
+*=$1008 "second"
+    .fill 16, 0
+```
+
+`failed-assert.asm`
+
+```text
+*=$1000
+    rts
+.assert "one plus one", 1+1, 3
+```
+
+`macro-without-parentheses.asm`
+
+```text
+.macro Blink() {
+    inc $d020
+}
+*=$1000
+    Blink
+    rts
+```
+
+`import-source-no-namespace.asm`, after `flat-lib.asm` (no `.filenamespace`)
+has been assembled with `-symbolfile`:
+
+```text
+// flat-lib.sym was written by a flat-lib.asm that has no .filenamespace
+.import source "flat-lib.sym"
+*=$0810
+    jsr lib.set
+    rts
+```
+
+`symbol-clash-main.asm`, after `symbol-clash-lib.asm` (which defines a flat
+`main:` at `$1000`) has been assembled with `-symbolfile`:
+
+```text
+.import source "symbol-clash-lib.sym"
+*=$0801 "basic"
+BasicUpstart2(main)
+main:
+    jsr main
+    jmp *
+```
+
+## See also
+
+- [oscar64-reference.md](../toolchains/oscar64-reference.md) — primary C compiler; use as the project driver when mixing C and asm
+- [recipes/kickassembler/hello-world.md](../recipes/kickassembler/hello-world.md) — minimal working PRG with BASIC upstart
+- [vice-reference.md](../runtime/vice-reference.md) — VICE emulator flags, monitor commands, `.vs` file loading
+- [memory-layout-planning.md](memory-layout-planning.md) — whole-program layout: the constraints, one worked layout in all three toolchains, confirmed from `-showmem`; recipe `../recipes/kickassembler/memory-layout.md`
+- [release-disk.md](release-disk.md) — putting the built PRG on a bootable D64 with c1541, proving it boots by autostarting the image headless, and a Makefile target that does both