Getting started
The authoring kit turns your DAAD source into a folder you copy straight onto an SD card. It compiles the database, converts your artwork and audio, stages the interpreter beside them, and can launch an emulator (CSpect, or jNext) on the result. There is nothing to assemble by hand.
The kit runs on Windows and on Linux. The build scripts, the compiler and the picture converter ship in the kit; the emulator, the music converters, ffmpeg and the assembler are third-party downloads. Pick your platform below, then read Already have some of these?.
On either platform, keep the kit folder on a local drive: NTFS on Windows; ext4, btrfs or xfs on Linux. A FAT or exFAT USB stick, a network share or a Docker bind mount cannot keep the precise file times the incremental build relies on, and the build refuses to run there.
Windows 10 or 11. Windows PowerShell, which is part of Windows, runs the build; nothing else needs installing for a text-only game.
The interpreter, nextdaad.nex, and the DAAD compiler, NDRC, as lib\ndrc.exe, are in the kit. Gfx2Next and the video encoder are too. Download the rest and extract each into the kit's tools\ folder at the path shown:
| Tool | Provides | Extract into | Needed |
|---|---|---|---|
| Arkos Tracker 3 | SongToAky.exe, SongToSoundEffects.exe, SongToYm.exe |
tools\ArkosTracker3\tools\ |
only with .aks audio |
| CSpect | emulator, to play the result without hardware | tools\CSpect\ |
to run the build |
| jNext | optional second emulator that also plays cutscenes and streamed sound | tools\jnext\ |
to run the build in jNext |
| ffmpeg | reads your video sources | tools\ffmpeg\ |
only when encoding an .mp4 cutscene |
| sjasmplus | Z80 assembler | tools\sjasmplus\ |
only to rebuild an extern with EXTERNS.BAT |
tools\README.txt lists the download addresses and the exact executable paths the build checks for.
Double-click BUILD.BAT to build, RUN.BAT to play the result in CSpect (or jNext, see EMULATOR), CLEAN.BAT to start over. DEBUG.BAT builds and plays the game in the debugger. On a fresh kit the first build makes the starter game; read Where your files go before you start your own.
x86_64 Linux with glibc 2.34 or newer: Ubuntu 22.04, Debian 12, Fedora 36 and later. Follow the steps below in order, in a terminal. First the programs the later steps use:
sudo apt install unzip wget ca-certificates
Then install PowerShell 7.4 or newer (pwsh), which runs the build scripts. Microsoft publishes packages for every major distribution: https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-linux
Unzip the kit into its own folder and go into it. Every command from here on runs in that folder:
unzip NextDAAD-AuthoringKit-<version>-linux.zip -d NextDAAD-AuthoringKit
cd NextDAAD-AuthoringKit
The interpreter, the compiler (lib/ndrc) and Gfx2Next (tools/gfx2next/gfx2next) ship in the Linux kit. A tool that is on your PATH is found without any setting; a tool under tools/ is found there; CONFIG.BAT points anywhere else. Install only the optional tools your game uses:
- Arkos Tracker 3 Linux release from https://www.julien-nevo.com/arkostracker/, for
.aksmusic only. Extract the Arkos zip intotools/: its own top folder isArkosTracker3/, givingtools/ArkosTracker3/tools/SongToAky. Or setARKOSDIR. - ffmpeg from your distribution (
sudo apt install ffmpeg), for video cutscenes andMUSIC PCMintros only. - CSpect Linux build from https://mdf200.itch.io/cspect plus mono (
sudo apt install mono-devel), to play the result. Extract intotools/CSpect/;run.shstarts it asmono CSpect.exe, or setCSPECTCMDinCONFIG.BATto run it some other way (Linux only, ignored on Windows). - jNext, optional, runs natively on Linux (no mono). See Running in jNext.
- sjasmplus, only to rebuild an extern with
externs.sh: a distribution package where one exists (sudo apt install sjasmpluson Debian), otherwise build it from https://github.com/z00m128/sjasmplus. - Python 3.10 or newer with
Pillowandnumpy, for video cutscenes only, in a virtual environment - see below.
Debian and Ubuntu do not allow pip to install into the system Python, and python3 -m venv needs the python3-venv package, so create a virtual environment once, from inside the kit folder:
sudo apt install python3 python3-venv
python3 -m venv ~/nextdaad-venv
~/nextdaad-venv/bin/pip install -r lib/requirements.txt
. ~/nextdaad-venv/bin/activate # optional: only to run python3 yourself
lib/requirementstxt pins the Pillow and numpy versions the kit is tested with. The scripts find ~/nextdaad-venv on their own, so activating it is optional; a python3 on your PATH that already has the packages is used first.
The video tuning window (./vidtune.sh) also needs PySide6. Install it into the same venv, from inside the kit folder:
~/nextdaad-venv/bin/pip install -r lib/requirements-vidtune.txt
A minimal install may lack the system libraries Qt needs; on Debian and Ubuntu, add them with:
sudo apt install libgl1 libegl1 libxkbcommon0 libfontconfig1 libdbus-1-3 libglib2.0-0
Then build and play:
chmod +x build.sh run.sh clean.sh externs.sh vidtune.sh lib/ndrc tools/gfx2next/gfx2next # only if your unzip dropped the execute bits
./build.sh
./run.sh
The shipped CONFIG.BAT has RUN=1, so until CSpect is installed each build ends with ERROR: CSpect not found after the build succeeds; set RUN=0 to build without an emulator.
On a fresh kit the first build makes the starter game; read Where your files go before you start your own.
build.sh, run.sh, clean.sh, externs.sh, vidtune.sh and debug.sh are the Linux names of the six .BAT launchers and take the same arguments.
Two things differ from Windows:
- File names are case-sensitive. Use the names this manual shows:
IMAGES/,AUDIO/,VIDEO/,001.png,STARTER.DSF,FONT.CHR. An#includeor#incbinin your source must match the file's case exactly and use/between folders. CONFIG.BATkeeps its name. It is a plain settings file ofSET NAME=valuelines that the scripts read; nothing executes it. Paths in it may use/.
Arkos Tracker, CSpect and ffmpeg are general-purpose tools you may well have installed already, and there is no need for a second copy. There is a directory setting per tool - ARKOSDIR, CSPECTDIR, FFMPEGDIR, GFXDIR, SJASMPLUSDIR, JNEXTDIR - and each one you set in CONFIG.local.BAT is used instead of the folder under TOOLSDIR. Anything you leave blank still comes from TOOLSDIR, so mixing the two is fine: keep the small stuff in tools\ and point the big installs wherever they already are. Absolute paths, including ones with spaces, are fine:
SET CSPECTDIR=C:\Emulators\CSpect
SET ARKOSDIR=C:\Program Files\Arkos Tracker 3
SET FFMPEGDIR=/usr/bin
Point each at the folder the tool was installed into. Arkos Tracker and ffmpeg keep their programs in a subfolder (tools\ and bin\); either the install root or that subfolder is accepted. If you keep every tool somewhere else, point TOOLSDIR at that folder instead.
This manual covers what is specific to the Next: the kit, the build, and how each condact behaves on this target. It does not teach the DAAD language. For that:
- The DAAD Ready manual covers the DSF source format, the condact set, the system flags and the symbol tables. It is the go-to reference to write your adventure against.
- The original DAAD manual is in the
Docsfolder of the DAAD project (or a hardcopy is available here), it is the fuller treatment of the language, worth reading once you know your way around the DAAD Ready manual.
The kit compiles your DSF with its own bundled NDRC (Next DAAD Reborn Compiler). If a CONFIG.local.BAT from an older kit still sets DAADDIR or DRCDIR, it is safe to delete those lines - neither setting is read any more since it migrated from DRC to NDRC.
Any text editor can write a .DSF file, but a few tools make the job easier:
- VS Code is a good general-purpose editor for DAAD source - free, cross-platform, and with an extension marketplace covering the two tools below.
- DAAD-DSF is a VS Code extension for the DSF source format: syntax highlighting for the condact set, messages and object definitions, plus checking that flags potential compiler and structural problems before you run a build. Install it from Github releases page in the repository above.
- git tracks changes to your source as you write it, giving you a history to fall back on and, if you keep it on GitHub or similar, a backup off your own machine. In VS Code's terminal type
git initinitialise the tracking.
None of this is required - the build only reads the files described below, however they were written.
Each game lives in its own folder inside the kit folder, called its game folder. The folder and the game's source file share one name: the game MYGAME is MYGAME\MYGAME.DSF. One kit can hold any number of games side by side, and you tell the build which one to work on (see Choosing the game).
The kit ships one game folder, STARTER\, holding the starter game. On a fresh kit with nothing configured, BUILD.BAT builds it and runs it, so you can check your setup before you write anything.
Copy STARTER\ before you write your game. Every kit update replaces STARTER\ completely, so anything you change inside it is lost at the next update. To start from the starter game, copy it to a game folder of your own first, then edit and build the copy, never STARTER\STARTER.DSF itself. While STARTER\ is the game being built, the build reminds you of this every time:
WARNING: STARTER\ is replaced by every kit update - copy it to your own game folder before writing a game (see Getting started).
The build still succeeds. A game folder named STARTER is always treated as the shipped starter - the warning prints and vidtune will not save there - so give your own game any other name.
Everything the build reads for a game is inside its game folder:
<GAME>.DSF- your adventure. Files it#includes or#incbins are looked up inside the game folder too.<GAME>.CFG- this game's own settings (see Configuration). Optional.IMAGES\- location pictures as001.png,002.pngand so on, plusDAAD.pngfor a title screen. See Graphics for the art rules.AUDIO\- Arkos.aksmusic and effects, and.wavsamples. See Audio.VIDEO\- cutscene sources as001.mp4or001.mkv(or a pre-encoded001.vid). See Video.- Ready-made files in the game folder itself - a
FONT.CHRcustom font (see Fonts) or aPOINTER.SPRmouse pointer (see Mouse), or already-converted title art. These are copied through untouched. INTRO.TXT,HINTS.TXT,GAME.XBN,PART2\toPART9\- a loader intro, hints and other externs, and the extra parts of a multi-part game, when your game has them.
A pure-text game needs only its .DSF. Graphics, audio and video are all optional and the build skips whatever is absent. A game folder is self-contained: the build never looks in the kit folder or in another game folder for a file your game is missing, so a new game cannot pick up the starter's pictures or tunes by accident.
Everything else in the kit folder - the launchers, CONFIG.BAT, lib\, docs\, externs\, tools\ and the rest - belongs to the kit. Updating the kit lists what an update replaces.
- Copy the
STARTER\folder to a new folder named after your game, sayMYGAME\. In the copy, renameSTARTER.DSFtoMYGAME.DSF,STARTER.CFGtoMYGAME.CFG,AUDIO\STARTER.akstoAUDIO\MYGAME.aksandAUDIO\STARTER_FX.akstoAUDIO\MYGAME_FX.aks. The build takes a game's music and sound effects from the.aksfiles named after the game, so without the last two renames the copy builds with no music and no sound effects. - Copy
CONFIG.local.BAT.samplein the kit folder toCONFIG.local.BAT, open it, and add the lineSET GAME=MYGAME. - Put your game's own settings in
MYGAME\MYGAME.CFG. Leave the kit'sCONFIG.BATalone. - Edit
MYGAME\MYGAME.DSFand build it withBUILD.BAT. Do not edit the files inSTARTER\.
The starter's pictures, audio and video come along in the copy. Keep what you want and delete or replace the rest. MYGAME.CFG holds VIDOPTS_001 and VIDOPTS_002 lines tuned for the starter's two demo clips; delete them when you replace those clips with your own.
Name the game to build in CONFIG.local.BAT, one SET GAME= line per game you have, with all but one turned off by REM:
REM SET GAME=MYGAME1
SET GAME=MYGAME2
To switch games, move the REM. GAME is the name of the game folder (and of the .DSF inside it), with no extension.
When GAME is blank, the build looks for something it can pick without being told:
- if the kit folder itself holds exactly one
.DSF, it builds that game in the old single-game layout (see Updating the kit); - otherwise, if the kit folder holds no loose
.DSFand exactly one game folder exists, it builds that one - on a fresh kit that isSTARTER\; - otherwise it stops with
set GAME in CONFIG.local.BAT.
So once you have copied the starter to your own folder there are two game folders, and you need the SET GAME= line. The folders PART2\ to PART9\ hold the extra parts of a multi-part game and are never taken for game folders.
CONFIG.BAT in the kit folder holds every setting with its default value and a note on what it does. It belongs to the kit and every update replaces it, so do not edit it. Change a setting by copying its line into one of the two files below and editing the copy:
<GAME>\<GAME>.CFG- settings that belong to one game:COLS,COMPRESS, the video options, and so on. Each game keeps its own, so two games never share settings by accident.CONFIG.local.BATin the kit folder - settings that belong to your machine, such as tool folders andRUN, plus theGAMEselector. Create it fromCONFIG.local.BAT.samplethe first time.
Your own game's .CFG and CONFIG.local.BAT are never shipped with the kit (only the starter's STARTER.CFG is), so an update never touches them. Both use the same SET NAME=value lines as CONFIG.BAT, and a line starting REM is ignored, so a line copies between the three files unchanged. The build only reads these files; it never runs them.
The settings:
| Setting | Meaning |
|---|---|
GAME |
The game to build: the name of its game folder. Set it in CONFIG.local.BAT. Blank = pick one automatically, see Choosing the game. |
COMPRESS |
1 = ZX0-compress pictures (smaller files); 0 = raw. |
RUN |
1 = launch the emulator chosen by EMULATOR after a successful build; 0 = build only. |
EMULATOR |
The emulator RUN launches: cspect (blank means this) or jnext. See Running in jNext. |
COLS |
Text columns your game is authored for. Blank = 80 (the default), or 40 for the double-width 40-column mode. Sets the compiler's -cols option - the interpreter still boots at 80, so a 40-column game must issue GFX 1 18 in its init process. See Graphics. |
TOOLSDIR |
Folder holding the tools above. Default tools. |
GFXDIR, ARKOSDIR, CSPECTDIR, FFMPEGDIR |
Where each individual tool lives. Blank means "the folder under TOOLSDIR", so leave them alone for the simple layout and set only the ones you keep elsewhere. See What you need. |
JNEXTDIR |
The folder holding jnext.exe, only for EMULATOR=jnext. Blank means tools\jnext\; on Linux, blank finds jnext on your PATH. |
JNEXT |
The full path to the jNext program itself, only for EMULATOR=jnext. Overrides JNEXTDIR; set it when the program is not named jnext or jnext.exe, as with a Flatpak launcher. |
JNEXTIMG |
The SD-card image jNext downloaded on its first run. Blank means jNext's own copy in your home folder (.jnext\sdcard\). The kit copies it and never changes it. |
VIDTOOLSDIR |
Same, for the folder holding videnc.exe and vidtune.exe, which the kit ships. You should not need to set this. On Linux the encoder runs from lib\videnc.py and this setting is unused. |
NDRCVER |
Normally unset: the compiler version the kit was tested against is pinned in lib\toolversions.txt and the build refuses any other. Set it only alongside your own NDRC override. |
NEXFILE |
The interpreter file to ship. Default nextdaad.nex. The build stages it under your game's name - see What comes out. |
NEXTDAWDIR |
Your NextDAW install, only for MUSIC NDR in a loader intro. |
INTRONEX |
The loader intro launcher to ship. Default intro.nex. |
VIDASPECT, VIDFPS, VIDOPTS, VIDOPTS_NNN |
Cutscene encoding - see Video. |
Local overrides. The build reads three files in turn, and a later file wins:
CONFIG.BAT- the kit's defaults.<GAME>\<GAME>.CFG- the selected game's own settings.CONFIG.local.BAT- your machine's settings.
Every key works the same way: the last file to set it wins, and an empty SET NAME= clears the value. A line in CONFIG.BAT is masked while the same key is set in either of the other two. GAME is the one exception - a game's own .CFG cannot choose a different game, so a GAME line there is ignored, with a warning naming the file.
Copy only the lines you change. Never copy the whole of CONFIG.BAT into CONFIG.local.BAT or a .CFG. A full copy pins every default - the compiler version, file names, tool folders - and from then on hides any change a kit update makes to them.
vidtune saves its per-video VIDOPTS_NNN settings in the game's <GAME>.CFG, so each game keeps its own tuning and kit updates keep it. See Video.
BUILD.BAT(Linux:./build.sh) - compiles the database, converts graphics and audio, encodes any new video, copies the interpreter, and launches the emulator ifRUN=1. It finishes withBUILD OK: RELEASE\MYGAME\ is ready - copy the contents of RELEASE\ to the root of an SD card, naming your game.RUN.BAT(./run.sh) - launches the emulator chosen byEMULATOR(CSpect unless you say otherwise) on the game already built inRELEASE\<GAME>\, without rebuilding. CSpect sees that folder as its SD card, the same shape as the folder you copy to a real card; jNext gets a card image with the game added, see Running in jNext.CLEAN.BAT(./clean.sh) - emptiesRELEASE\<GAME>\for the selected game only; other games' output is left alone. It also deletesCACHE\jnext\, the jNext card copy. The next build then converts everything from scratch.
All three work on the game GAME selects (see Choosing the game). Each launcher is a few lines that start the matching script in lib\ (build.ps1, run.ps1, clean.ps1); the build itself is the same code on both platforms.
The build stops at the first error, with a message naming the cause.
Pictures, sprite sets, sounds, tunes and video are only converted or copied when their source has changed since the last build. Everything else in RELEASE\<GAME>\ is left as it is, so a game with hundreds of pictures rebuilds in seconds. A file counts as changed when its size or modified time differs, including a file replaced by an older copy. Updating the kit or a conversion tool also converts everything again. The build deletes the output of any picture or tune you remove from the game folder, so nothing lingers on the card from an earlier build.
Your database is compiled as DAAD version 3. If you are bringing in a game written for version 2, three behaviours change silently - see DAAD V3.
jNext is an optional second emulator. CSpect cannot play video cutscenes and stops a long streamed sound after about a second and a half; jNext plays both. CSpect stays the default.
- Download jNext 1.1.87 or later from https://github.com/jorgegv/jnext/releases. On Windows, extract the x64 zip into
tools\jnext\. On Linux, install the.debor.rpmpackage, which putsjnexton your PATH. A Flatpak install is untested and may not see the kit's folders; if you use one, addSET JNEXT=<launcher>toCONFIG.local.BAT. - Start jNext once by itself and let it download its SD-card image (about 1 GB, kept in
.jnext\sdcard\in your home folder). Close it again. - Add
SET EMULATOR=jnexttoCONFIG.local.BAT.
From then on RUN.BAT (and a RUN=1 build) copies that card image to CACHE\jnext\card.img, adds your game to the copy, and boots NextZXOS, which starts the game. It takes a few seconds longer than CSpect. Your own copy of the card is never changed. The copy, about 1 GB, stays in CACHE\jnext\ between runs until CLEAN.BAT removes that folder.
- Saves made in jNext are lost on the next RUN, because every run starts from a fresh copy of the card.
- Close jNext before the next RUN; the kit will not start it twice.
- A jNext run is still an emulator. Check cutscenes and sound on a real Next before you release.
Each game builds into its own folder, RELEASE\<GAME>\. Copy the contents of RELEASE\ (not the RELEASE folder itself) to the root of the SD card, and each game arrives in a folder of its own. A built game holds exactly two things:
<GAME>.NEX- the file you launch.DATA\- everything else the game reads.
Without a loader intro, <GAME>.NEX is the interpreter itself. With one, <GAME>.NEX is the intro launcher, and the interpreter it starts is DATA\nextdaad.nex. Launch <GAME>.NEX either way.
DATA\ holds:
GAME.DDB- your compiled adventure.0.XMB- external message text, if your game uses XMESSAGE or XMES. It must stay besideGAME.DDB; without it those messages silently print nothing.NNN.NX2/NNN.NXI- converted location pictures,NNN.NX3for a positioned picture, andDAAD.NX2/DAAD.NXIfor a title screen (with a.zx0suffix whenCOMPRESS=1).GAME.AKY,NNN.AKY,NNN.AYS,GAME.SFB,NNN.WAV- converted and copied audio.NNN.VID- encoded cutscenes.FONT.CHR,POINTER.SPR- your custom font and pointer, if you supplied them.GAME.XBN,GAME.HNT- externs and hints, if your game has them.nextdaad.nexandINTRO\- the interpreter and the intro's own files, only when the game has a loader intro.PART2\toPART9\andGAME2.DDBonwards - the extra parts of a multi-part game.
DATA\ is also where the game writes while it is played: save games, and the files externs keep, such as GAME.HPR (hint progress), GAME.HST (high scores) and TRANS.TXT (a transcript), all land in <GAME>\DATA\ on the card.
Games built by kits before v0.12.0 put every file loose at the card root. The interpreter still runs a game laid out that way: it looks for GAME.DDB in the game's folder first and then in DATA\, so do not leave an old GAME.DDB in the root of a game folder.
STARTER\ ships with the kit, holding STARTER.DSF along with example graphics, audio and video, so a first build works before you have written anything. It shows the Next-specific condacts in use - PICTURE/DISPLAY for location art, SFX for music and effects, BEEP for tones, GFX for cutscenes. Try the verbs MUSIC, MUTE, TUNE, BLEEP, ZAP, SAMPLE, MOVIE and REEL. To build on it, copy it first - see Starting a new game.
When the build fails
| Message | What to do |
|---|---|
set GAME in CONFIG.local.BAT (found ... .DSF files and ... game folders here, need exactly one) |
GAME is blank and the build cannot pick a game by itself: there is more than one game folder, or none, or more than one loose .DSF in the kit folder. Add SET GAME= with your game folder's name to CONFIG.local.BAT - see Choosing the game. |
MYGAME\ has no MYGAME.DSF / MYGAME.DSF not found in MYGAME\ or this folder |
GAME names a game that is not there. The folder and the .DSF inside it must both carry the name GAME gives. |
WARNING: STARTER\ is replaced by every kit update |
You are building the shipped starter. Fine for a first try; to write a game, copy it first - see Starting a new game. |
WARNING: AUDIO\STARTER.aks is not used / WARNING: AUDIO\STARTER_FX.aks is not used |
Your game folder is a copy of the starter and its music or sound effects still carry the starter's name, so the build leaves them out. Rename them to AUDIO\<GAME>.aks and AUDIO\<GAME>_FX.aks - see Starting a new game. |
WARNING: GAME in ... .CFG is ignored |
A game's .CFG cannot select the game. Move the SET GAME= line into CONFIG.local.BAT. |
WARNING: RELEASE\ holds ... item(s) from an older kit build |
Files left loose in RELEASE\ by a kit before v0.12.0. Delete them - see Updating the kit. |
differ only by case - keep one |
Two files in the kit folder have names that differ only in letter case. Windows treats them as one file and Linux as two; rename one. |
does not keep sub-microsecond file times |
The kit folder is on a FAT, exFAT, network or bind-mounted drive. Move it to a local NTFS or ext4 folder. |
required tool missing |
The named path does not exist. Install that tool there, or fix TOOLSDIR / NEXFILE. |
wrong DAAD compiler version |
The banner lib\ndrc.exe prints does not match the version pinned in lib\toolversions.txt. This should not happen with the kit as shipped; if you have replaced ndrc.exe yourself, set NDRCVER in CONFIG.local.BAT to match. |
CSpect is running - close it before building |
CSpect holds the RELEASE\ files open. Close it and build again. |
ERROR: EMULATOR=... - use cspect or jnext |
EMULATOR holds something else. Set it to cspect or jnext, or leave it blank for CSpect. |
ERROR: jNext not found at ... |
Install jNext 1.1.87 or later at the path shown, or set JNEXTDIR in CONFIG.local.BAT. On Linux, installing the .deb or .rpm package puts jnext on your PATH. See Running in jNext. |
ERROR: no jNext SD-card image at ... |
Start jNext once and let it download its SD-card image, or set JNEXTIMG in CONFIG.local.BAT. |
ERROR: jNext is running - close it before running the game |
Close jNext and run again. |
ERROR: jNext could not write the SD-card image (step N, exit CODE) |
The kit could not add your game to its copy of the SD card. Step 1 adds AUTOEXEC.BAS; steps 2 and 3 add your game. Look up CODE in the list below the table. |
ndrc failed compiling |
The compiler rejected your source. Its own output above the message names the line. |
WARNING: ... -> on disk as ... (case differs; Linux cannot open it) / WARNING: ... -> uses \ (Linux needs /) |
An #include or #incbin line names a file whose name on disk is spelled with different capitals, or separates folders with \. Windows builds it anyway; on Linux the same line is an ERROR: and the build stops. Match the case and use /. |
GAME.DDB is N bytes, over the 65535 limit |
The database is too large. 64K is the format's own ceiling - see Limits, which suggests where to cut. |
uses #classic, which NextDAAD does not support |
Remove the #classic line from your source. It tells the compiler to imitate the original pre-DRC DAAD compiler, for the benefit of interpreters that cannot read a NextDAAD database in any case; here it only makes the database bigger. |
gfx2next not found |
Install Gfx2Next, or fix TOOLSDIR. |
expected a 320 or 256 wide PNG |
Resize the named image to exactly 320 or 256 pixels wide. |
must be a paletted 8-bit PNG |
Export the image again as an indexed-colour PNG. Truecolour is rejected. |
GAME.AKY is N bytes, over the 10208 song limit |
The tune does not fit the song slot. Shorten it, reduce channels, or stream it - see Audio. |
SongToAky not found / SongToYm not found |
Install Arkos Tracker 3, or fix TOOLSDIR. |
this encode cannot stream / cannot play at rate |
No encode of that clip fits the playback budget. Use a smaller shape, a lower frame rate, or a shorter clip - see Video delivery. |
audio bytes/frame ... exceeds |
The frame rate is below the floor sound needs. Raise VIDFPS. |
over the NXV player's ... ceiling |
The clip is too big or too long to play. The message names the longest clip your shape and frame rate allow. |
The jNext card-write error ends with the code jNext gave back:
exit 1- jNext is older than 1.1.87. Update jNext.exit 2- jNext could not read a file it was asked to add. Close any program holding the file; antivirus software scanning a new file is a common cause. Run again.exit 3- a file or folder name in your game folder cannot be stored on an SD card, or two names differ only in capitals. Rename it.exit 4- the file already exists on the card. RunCLEAN.BATand run again.exit 5- the card copy inCACHE\jnext\is damaged or could not be written. RunCLEAN.BAT, check there is free disk space, and run again.exit 6- the card is full. Your game folder is too big for it.
Warnings are different from errors. Anything about the sound-effects bank, or about picture transparency, is advisory - the build carries on and the game still ships.
A build that finished can still fail on the card. These are the interpreter's own messages. Each one paints a magenta bar right across the top row of the screen and prints itself into it in white, so it is legible whatever the game had drawn - and it appears in a release build as readily as a debug one. All of them stop the interpreter; reset or power-cycle to try again.
| Message | What to do |
|---|---|
NextDAAD: DDB missing - E1 |
There is no GAME.DDB beside the interpreter, or the card could not be read at all. The interpreter looks in the DATA\ folder next to the <GAME>.NEX you launched, so keep the game's folder whole: copy the contents of RELEASE\ to the card root, which puts <GAME>.NEX and its DATA\ together in the game's own folder. |
NextDAAD: DDB oversize - E2 |
GAME.DDB is larger than the interpreter will load. See Limits. |
NextDAAD: DDB bad header - E3 |
The file is there but is not a database this build can load - a truncated or corrupted copy, most often. Rebuild and copy it again. |
NextDAAD: DDB wrong machine - E4 |
GAME.DDB is a perfectly good database, but it was compiled for a different computer - CPC, C64, MSX, PC or another. Recompile it for the Spectrum: the kit's own build already does, so this normally means a .DDB arrived from somewhere else. Spanish and English databases are both fine; it is the machine that is wrong, not the language. |
NextDAAD: RUNTIME ERROR - E<n> |
The engine hit a fault while running your game. The digit names it: 1 is an invalid location and 4 a nested DOALL, both covered in Known differences and Platform notes; 5 is a version 3 opcode in a version 2 database, see DAAD V3. |
NextDAAD: RD STACK - E9 |
The text reader ran out of nesting depth. This should not happen with a database this kit compiled - if it does, it is worth reporting. |
Once a build runs, the game itself may still behave differently from how it did on another DAAD interpreter. Platform notes is the place to look first.
To update, unzip the new kit over your existing kit folder and let it replace files. Moving up from v0.11.x or earlier is the one exception: see Moving from v0.11 to v0.12.0 below.
An update replaces the kit's own files and leaves yours alone.
Replaced by every update (the kit's files):
CONFIG.BATandCONFIG.local.BAT.sample- the launchers:
BUILD.BAT,RUN.BAT,CLEAN.BAT,EXTERNS.BAT,VIDTUNE.BAT(Linux:build.sh,run.sh,clean.sh,externs.sh,vidtune.sh) - the folders
lib\,docs\,externs\and.agents\ AGENTS.md,README.txt,xbn.inc,xbnmod.incnextdaad.nexandintro.nextools\gfx2next\andtools\vidtools\STARTER\, the starter game
Never shipped, so never touched (your files):
CONFIG.local.BAT- every game folder of your own, including any extern module sources you keep inside it
RELEASE\- the other tools you installed under
tools\(Arkos Tracker, CSpect, ffmpeg, sjasmplus)
Where your settings belong:
| Setting | File |
|---|---|
A game's own settings (COLS, COMPRESS, intro and video options, VIDOPTS_NNN) |
<GAME>\<GAME>.CFG |
Machine settings (TOOLSDIR, tool folders, RUN) and the GAME selector |
CONFIG.local.BAT |
| Nothing | CONFIG.BAT - the update replaces it |
Do not edit anything in STARTER\: copy it (see Starting a new game).
A game still in the old layout. A game whose .DSF sits loose in the kit folder, as every game did before v0.12.0, still builds. But its pictures, audio and other files sit in the kit folder too, among the kit's own files, and any setting you changed in CONFIG.BAT is lost at the next update. The safe course is to move the game into a game folder of its own, and any VIDOPTS_NNN lines into its .CFG, before you rely on updates - the steps below do exactly that.
The build also warns when RELEASE\ still holds loose files from a build made by an older kit:
WARNING: RELEASE\ holds 12 item(s) from an older kit build (001.NX2, 002.NX2, 003.NX2, FONT.CHR, GAME.AKY and 7 more) - delete them; each game now builds into RELEASE\MYGAME\
The build never deletes them for you. Delete them yourself, so they do not end up on your card.
Do this one update into a new, empty folder, not over the old kit. Unzipped over a v0.11 kit, v0.12.0 would leave the old starter files (STARTER.DSF, IMAGES\ and the rest) loose in the kit folder, and with GAME blank a loose .DSF makes the build use the old layout.
- Unzip v0.12.0 into a new folder beside your old kit.
- In the new kit folder, make a folder named after your game, matching its
.DSF- forMYGAME.DSF, makeMYGAME\. From the old kit folder, copy into it: the.DSFand any source files it includes,IMAGES\,AUDIO\,VIDEO\,INTRO.TXT,HINTS.TXT, theDAAD.*title files, theFONT*andPOINTER*files,GAME.XBN, and anyPART2\toPART9\folders. Copy only the ones your game has. - Compare your old
CONFIG.BATwith theCONFIG.BATfrom the v0.11 kit zip as it was shipped (re-download the v0.11 kit zip from the releases page if you no longer have it), and copy across only the lines you changed. Game settings (COLS,COMPRESS, intro and video options) go into a newMYGAME\MYGAME.CFG. Machine settings (TOOLSDIR, the tool folders,RUN) go into a newCONFIG.local.BAT, made fromCONFIG.local.BAT.sample. The v0.11CONFIG.BATshippedVIDOPTS_001andVIDOPTS_002lines for the starter's demo clips; leave those behind unless your game uses them. - From your old
CONFIG.local.BAT, if you had one: theVIDOPTS_NNNlines go intoMYGAME\MYGAME.CFG, and machine settings go into the newCONFIG.local.BAT. Then addSET GAME=MYGAMEto the newCONFIG.local.BAT. - Copy across the tools you installed under the old kit's
tools\folder (Arkos Tracker, CSpect, ffmpeg, sjasmplus), unless they live somewhere else andCONFIG.local.BATpoints at them. - Build. The video encode cache is kept in
VIDEO\beside your clips (NNN.vidwith itsNNN.vid.args), so it moved withVIDEO\in step 2: your cutscenes do not re-encode, as long as theVIDOPTS_NNNlines you moved give the same encoder settings. - On the SD card, delete your game's old loose files from the card root, then copy the new
MYGAME\folder fromRELEASE\. Save games made with the old layout go intoMYGAME\DATA\to stay loadable. - Once the new kit builds and runs your game, you can retire the old kit folder.
If you would rather keep your game in the old layout, do step 2 without the game folder: copy the same loose game files straight into the new kit folder. Skip steps 3 and 4 and keep every setting you changed in CONFIG.local.BAT, the one settings file an update leaves alone. It still builds, but moving the game into its own folder is the better choice.