XBN Reference

The binary layout GAME.XBN must follow, the checks the loader applies to it, and the frozen addresses author code relies on. See Externs for how to build and use one; this page is the format itself.

Fourteen bytes at the start of the file, loaded to $C000:

The header is fourteen bytes either way - format 3 does not grow it, it just gives the four bytes format 2 reserved a meaning. xbn.inc's XBN_HEADER macro emits the format 2 layout from two labels (or 0); XBN_HEADER3 emits the format 3 layout from four. Collection modules use xbnmod.inc's XBN_BEGIN or XBN_BEGIN3 instead, which emit the same header followed by the CALL slot table at $C00E (see Externs). You never build either header by hand.

A version 1 binary (ten-byte header, version byte 1) is rejected by this interpreter and the game plays with externs off: rebuild it against the current xbn.inc. The other direction is equally closed - an interpreter that predates format 2 rejects a version 2 file, and one that predates format 3 (this release) rejects a version 3 file the same way, whatever its lineEntry and outEntry declare.

The loader checks a GAME.XBN it finds at boot, in this order, and rejects the file - freeing anything it had already allocated and leaving the game to play with externs off - on the first check that fails:

1. The file is no larger than 16384 bytes ($4000) on disk.
2. The file holds at least the fourteen header bytes (a shorter file is truncated).
3. The magic bytes read exactly "XBN".
4. The version byte reads 2 or 3.
5. Format 2: the four reserved bytes at offsets 10-13 are all zero. Format 3: offsets 10-11 (lineEntry) and 12-13 (outEntry) are each validated like extEntry - 0, or a genuine address strictly inside the loaded binary's extent.
6. The size field is no larger than $4000.
7. The size field matches the number of bytes actually read from the file - a size field that disagrees with the real file length is rejected, whichever way it disagrees.
8. Each of extEntry and intEntry is either 0 (unused - always valid) or a genuine address strictly inside the loaded binary's extent ($C000 up to, but not including, $C000 + size).

Any rejection is silent in a Release build - the game plays exactly as it would with no GAME.XBN present at all, with no error shown to the player. A DEBUG build prints a rejection marker on the boot screen. No partially-valid state is ever committed: a file that fails validation never has its entry points wired up, whatever they contained.

A GAME.XBN with both extEntry and intEntry set to 0 is legal and loads without complaint - it simply never gets called, by anything.

Absent file (no GAME.XBN next to GAME.DDB at all) is not a rejection in the sense above - it is the ordinary "feature off" case, indistinguishable from a game that never used externs.

A binary whose size field is exactly $4000 - the maximum - loads with its usable range clamped to end at $FFFF rather than wrapping. $C000 + $4000 is $10000, one past the top of addressable memory; the interpreter treats the window as ending at $FFFF inclusive in that case. The one byte this affects is the very last byte of a maximum-size binary: it is loaded and present, but it is not a valid CALL target or entry-point address in its own right, since nothing can address a location past $FFFF to call into.

A fixed jump table of twenty-one three-byte JP instructions at XBN_API ($BEC8), frozen from the first shipping release. The address never moves and existing rows never change signature or meaning - only new rows are ever added, at the end, with a version bump reported by SVC_VERSION. So code written against an older xbn.inc keeps calling the same rows on every later NextDAAD release; what CAN change between format versions is the file header, and it did at format 2 - a binary assembled against an older xbn.inc is reassembled against the current one to pick up the new header (see Header). This is the same frozen-entry-point discipline esxDOS and NextZXOS use for their own jump tables.

Error convention throughout is esxDOS style: carry flag set, error code in A. A row's Corrupts column is its contract; only the registers its Out column names carry a result. Every service preserves the caller's own MMU mapping across the call - your extern's bank is back under $C000 when a service returns, whatever paging it did internally.

The last column is the hook rule. Rows marked yes are the only services the #int hook may call (they touch resident memory only and never page); every other row is foreground-only, because it runs the print path, the file system, a window switch or the shared palette registers, none of which may be entered from interrupt context. See Externs.

SVC_GETMSG's buffer is interpreter-owned resident memory, shared with other machinery, and is only guaranteed valid until the next service call or the next save/load - see Externs.

SVC_RANDOM draws from the same stream as CHANCE and RANDOM. A draw from the hook consumes that stream at a time the game cannot predict, so a game that needs reproducible runs must not draw from the hook.

SVC_VOCFIND's HL points at exactly one word: a space or other punctuation counts as an ordinary character toward the five significant, so pass a single word, not a phrase. It is foreground-only like most of rows 1-19, but the rule is stricter than usual for it: never call it from the output hook either, even though the output hook is not the #int hook. The lookup reuses shared resident state that a print already in flight is also using.

Fixed addresses xbn.inc binds symbols to, none of which move between releases:

XBN_API grew to fifteen rows in format 2, to sixteen at API version 3 (SVC_PAIR), to twenty at format 3 (rows 16-19), and to twenty-one with SVC_FITWORD (row 20); rows 0-9 kept their addresses and signatures throughout.

• 16384 bytes ($4000) maximum, header included, for the whole GAME.XBN file.
• 256 bytes maximum for a single SVC_GETMSG result; longer messages are truncated, not rejected.
• One GAME.XBN per game. There is no per-part extern file - the same binary stays loaded across every part switch.

See Limits for these alongside the interpreter's other size ceilings.