NextDAAD Extern Library Documentation
Ready-to-use XBN externs for NextDAAD games. Every folder here is self-contained: the assembly source, a prebuilt GAME.XBN you can copy straight to your card, a README.md with the DSF lines that drive it, and a build.ps1 to rebuild after editing.
To use one: copy its GAME.XBN next to your GAME.DDB and add the DSF lines from its README. No assembler needed unless you change the source.
| Extern | What it does | fn codes | Flags used |
|---|---|---|---|
playername/ |
Asks for the player's name and keeps it with the game: captures the typed line, prints it back, and tests it against a message. Kept in the extern state area (offsets 111-127), so SAVE and LOAD carry it. Needs API 3 |
20 capture the last typed line, 21 print, 22 no name yet, 23 name equals message p | - |
ticker/ |
Types or scrolls a database message in a field you place, size and colour - typewriter, marquee once or looping marquee | 30 arm, 31 stop (p = 1 clears), 32 row, 33 column, 34 width, 35 ink, 36 paper, 37 mode, 38 speed, 39 type message at cursor | - |
fade/ |
Fades the Layer 2 picture to any RRRGGGBB colour and back - fade to black for a scene change, change the picture, fade up again. Transparent regions stay transparent; a completed fade-in restores the palette bit for bit | 40 fade out, 41 fade in, 42 re-snapshot after a picture change, 43 wait for the fade | 240 done, 241 speed |
hints/ |
Prints hint text served from an SD card file (GAME.HNT), so a game can ship a large hint book without spending DAAD message slots or interpreter RAM |
50 print hint, 51 level count, 52 preflight, 53 clear progress | 242 level override, 243 level count |
clock/ |
An in-game clock advanced from the frame hook, with hour carry and an author-driven advance for sleeping or travelling | 60 arm and start, 61 stop, 62 advance p minutes | 224 hours, 225 minutes, 226 running, 227/228 rate, 244 days |
timer/ |
Three independent countdown timers, counting real seconds or in-game minutes, that expire into a flag your process table can test | 63 arm, 64 stop all three, 65 arm slot p as an in-game-minute deadline | 229-234 remaining (3 pairs), 235-237 state; an armed in-game-minute slot also READS the clock's 224, 225 and 244 |
realtime/ |
Reads the Next's real-time clock: date and time fields for the game to print or test, and day stamps kept in GAME.HST beside the database so a game can tell how long it has been since the last visit |
66 refresh, 67 field, 68 stamp, 69 days since | 238 result, 239 available |
toolkit/ |
Decimal printing, 16-bit flag-pair arithmetic, object queries, a random-without-repeat picker and time formatting. No hook - every function runs to completion inside the EXTERN that calls it; fns 76 and 84 keep their state in the extern state area, restored by LOAD | 70-84: 70 print flag as decimal, 71 print pair as decimal, 72-75 16-bit arithmetic, 76/77 picker, 78-81 object queries, 82 HH:MM, 83 MM:SS, 84 print target window | 248 width, 249 operand, 250 fn 79's high byte, 251 result |
transcript/ |
Records every typed line, and optionally everything printed, to TRANS.TXT beside the database - a walkthrough recorder, or a bug report that writes itself. Needs a v0.10.1 interpreter (format 3 header, line and output hooks) - an older interpreter loads the game with the module off. NOT in all/ - see below |
90 start recording (mode bitmask), 91 stop, 92 condition, 93 write message n as a label line, 94 restrict to window w | - |
all/ |
every extern in this collection EXCEPT transcript, in one binary | all of the above except transcript | all of the above except transcript |
A game uses ONE GAME.XBN. You do not have to merge anything by hand: the all/ folder ships every extern here except transcript, built into one binary, so copy that GAME.XBN and use whatever functions you want. Function codes and flags are disjoint across the collection, and a module stays inert until the game invokes it - an arming call for the modules that use one, or simply never being EXTERNed for the ones that don't - so an unused module costs you neither.
Transcript is not in all/: the loader arms the output tap for any binary whose header names an outEntry at all, so a binary with an output hook pays a per-character cost whether or not it is recording. Copy transcript/GAME.XBN on its own, or fold it into a smaller EXTERNS.BAT build, when a game actually wants to record.
If you want a smaller binary with only the modules you use, run EXTERNS.BAT from the kit root:
EXTERNS.BAT ticker fade
This writes GAME.XBN to the kit root, beside BUILD.BAT. Copy it next to your GAME.DDB the same as any other extern binary. That needs a Z80 assembler. Download sjasmplus from https://github.com/z00m128/sjasmplus and extract it into tools\sjasmplus\, or point SJASMPLUSDIR in CONFIG.BAT at an install you already have. You do not need it otherwise: every extern here ships a prebuilt GAME.XBN, and all/ ships one containing every module except transcript.
Your own modules combine the same way - name the folder that holds one:
EXTERNS.BAT fade ..\mymods\doors
A relative path counts from the folder you ran EXTERNS.BAT in. The shape your module needs is in the manual, docs\externs.html, under "Your own modules in a subset".
CALL targets are slots in a fixed jump table at $C00E - slot n is at $C00E + 3n - never routine addresses, which differ between the standalone, combined and subset builds.
Community externs are welcome. The submission requirements and process are in CONTRIBUTING.md at the repository root - in short: the four files above, fn codes 16+ documented in your README, the extern rules from the manual's externs chapter obeyed, and tests\audit-externs.ps1 passing locally before you open the PR.