Targets & output formats

FantASM separates two ideas: the target machine you’re assembling for, and the output format of the file it produces. You can set both on the command line or from within the source.

Targets

The target sets the memory model — the unit memory is paged in, and how many pages the machine has:

• On zx128, memory pages in 16 KiB banks (0–7); BANK sets the origin to 0xC000 automatically (the paged region).
• On zxnext, memory pages in 8 KiB pages/slots (8 slots of 8 KiB). BANK <bank> [, <slot>] places a 16 KiB bank into a slot, and PAGE <page>, <slot> places a single 8 KiB page — both route emitted bytes into the right physical page, and the debug info records it.

Select the target with -t, --target or the !target directive in source:

!target zxnext

RAM variant

Machines ship in different RAM sizes. Pick the variant with --ram (or fantasm.toml [assembler] ram) so BANK/PAGE numbers are range-checked against the real RAM:

fantasm game.asm -t zxnext --ram 1mb   # 1 MiB Next -> 64 banks / 128 pages

Accepts 2mb, 1mb, 512k, or a bare number of KiB; the default is the target’s maximum (2 MiB on the Next). The paging context is available in expressions as _page (8 KiB page), _bank (16 KiB bank) and _slot (slot index).

Output formats

Select the format with -f, --format or the !format directive:

!format nex

bin and hex are generic Z80 output, usable on any Z80 system; sna and nex are ZX Spectrum and ZX Spectrum Next formats.

Format-specific headers

Some formats carry a header you can populate from source.

NEX — use !nex <command> <value> to set header fields such as the entry point, stack, initial bank, loading screen and border:

!nex pc main        ; entry point
!nex sp $ff40       ; initial stack pointer

The full set of commands (sp, pc, bank, screen, bar, border, core, entry, preserve, crc) is documented in the NEX file format reference.

SNA — use !sna <command> <value> to set the snapshot’s pc and sp.

Setting options from source

As well as !target and !format, the !opt directive can flip assembler options mid-source (target, format, z80n, cspect, case-insensitive, maxcodesize, verbose). Command-line flags still take precedence over anything set in source or a project file.