NEX file format

The NEX (Next Executable) format is the primary distribution format for the ZX Spectrum Next. It loads multi-bank programs quickly, with support for loading screens, custom border colours and machine configuration. FantASM implements versions 1.2 and 1.3 (matching sjasmplus).

Set the header fields from source with the !nex directive; see the example below.

Header structure (512 bytes)

The file begins with a 512-byte header. All multi-byte values are little-endian.

Offset	Size	Name	Description
0	4	Magic	“Next”
4	4	Version	“V1.2” or “V1.3”
8	1	RAM Req	0 = 768K, 1 = 1792K
9	1	Num Banks	Number of 16K banks to load (0–112).
10	1	Screen	Loading screen flags.
11	1	Border	Border colour (0–7).
12	2	SP	Stack pointer (0 = do not set).
14	2	PC	Entry point (0 = no start).
16	2	Obsolete	Obsolete numFiles.
18	112	Bank Bitmap	Bitmap of which 16K banks are present.
130	1	Load Bar	0 = disable, 1 = enable loading progress bar.
131	1	Load Bar Colour	Colour of the progress bar.
132	1	Load Delay	Delay (frames) after each bank is loaded.
133	1	Start Delay	Delay (frames) after all banks are loaded.
134	1	Preserve Regs	0 = reset machine state, 1 = preserve most NextRegs.
135	3	Core Version	Minimum required core version (major, minor, subminor).
138	1	HiRes Colour	Bits 5–3 for port 255.
139	1	Entry Bank	16K bank mapped into `$C000–$FFFF` at start.
140	2	File Handle Cfg	0 = close, 1 = handle in BC, 0x4000+ = address.
142	1	Exp Bus Disable	V1.3: 0 = disable expansion bus, 1 = no-op.
143	1	Has Checksum	V1.3: 0 = no checksum, 1 = CRC-32C in header.
144	4	Banks Offset	V1.3: file offset where bank data starts.
148	2	CLI Buffer	V1.3: address of buffer for command-line copy.
150	2	CLI Buffer Size	V1.3: size of the provided buffer.
152	1	Screen 2	V1.3: extended screen flag.
153	1	Copper Flag	V1.3: 0 = no copper, 1 = 2048-byte copper block.
154	4	Tilemap Config	V1.3: NextReg `$6B`, `$6C`, `$6E`, `$6F` values.
158	1	L2 Bar Pos Y	V1.3: Y position of the loading bar for Layer 2 modes.
508	4	CRC32C	V1.3: CRC-32C checksum (Castagnoli).

Bank mapping

NEX stores data in 16KB “banks” — even though the Next pages memory in 8KB banks internally, the NEX format uses the traditional 16KB numbering:

Bank 5 → $4000–$7FFF
Bank 2 → $8000–$BFFF
Bank 0 → typically $C000–$FFFF (along with banks 1, 3, 4, 6, 7…)

The Bank Bitmap (offset 18) records which banks are present.

File layout

Header (512 bytes).
Loading screen data (optional).
Copper data (optional, V1.3).
Bank data — 16,384 bytes per bank marked in the bitmap.

Banks are usually stored in the order 5, 2, 0, 1, 3, 4, 6, 7, 8, 9, 10, …

Assembler directives

Configure the header from source with !nex:

!nex pc start_label     ; entry point PC
!nex sp $FF00           ; initial SP
!nex bank 10            ; explicitly include bank 10
!nex screen 1           ; loading screen type
!nex bar 1, 4, 10, 5    ; loadBar, barColour, startDelay, loadDelay
!nex border 3           ; initial border colour
!nex core 2, 0, 28      ; minimum required core version
!nex entry 10           ; entry bank mapped at start
!nex preserve 1         ; preserve NextRegs
!nex crc 1              ; enable CRC-32C checksum (V1.3)

V1.3 enhancements

Version 1.3 adds a CRC-32C integrity checksum, a flexible banks-offset (data can follow screens at any position), expansion-bus disable during load, and enhanced 320×256 / 640×256 loading screens.