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 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:

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, CLEAN.BAT to start over.

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 .aks music only. Extract the Arkos zip into tools/: its own top folder is ArkosTracker3/, giving tools/ArkosTracker3/tools/SongToAky. Or set ARKOSDIR.
• ffmpeg from your distribution (sudo apt install ffmpeg), for video cutscenes and MUSIC PCM intros only.
• CSpect Linux build from https://mdf200.itch.io/cspect plus mono (sudo apt install mono-devel), to play the result. Extract into tools/CSpect/; run.sh starts it as mono CSpect.exe, or set CSPECTCMD in CONFIG.BAT to run it some other way (Linux only, ignored on Windows).
• sjasmplus, only to rebuild an extern with externs.sh: a distribution package where one exists (sudo apt install sjasmplus on Debian), otherwise build it from https://github.com/z00m128/sjasmplus.
• Python 3.10 or newer with Pillow and numpy, 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.

build.sh, run.sh, clean.sh, externs.sh and vidtune.sh are the Linux names of the five .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 #include or #incbin in your source must match the file's case exactly and use / between folders.
• CONFIG.BAT keeps its name. It is a plain settings file of SET NAME=value lines 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. CONFIG.BAT has a directory setting per tool - ARKOSDIR, CSPECTDIR, FFMPEGDIR, GFXDIR, SJASMPLUSDIR - and each one you set 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 Docs folder 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 init initialise the tracking.

None of this is required - the build only reads the files described below, however they were written.

Everything the build reads lives in the kit folder:

• Your adventure, as a single .DSF file in the kit folder. With exactly one there, the build finds it by itself; otherwise name it in GAME in CONFIG.BAT (base name, no extension).
• IMAGES\ - location pictures as 001.png, 002.png and so on, plus DAAD.png for a title screen. See Graphics for the art rules.
• AUDIO\ - Arkos .aks music and effects, and .wav samples. See Audio.
• VIDEO\ - cutscene sources as 001.mp4 (or a pre-encoded 001.vid). See Video.
• Ready-made files in the kit folder itself - a FONT.CHR custom font (see Fonts) or a POINTER.SPR mouse pointer (see Mouse), or already-converted title art. These are copied through untouched.

A pure-text game needs none of these folders. Graphics, audio and video are all optional and the build skips whatever is absent.

CONFIG.BAT holds every setting:

Local overrides. If a file named CONFIG.local.BAT sits beside CONFIG.BAT, it is loaded straight after it, so anything it sets wins. Put settings that belong to your machine rather than to the game there - a different TOOLSDIR, or RUN=0 for an unattended build - and CONFIG.BAT stays as the settings you would hand to someone else along with the game.

• BUILD.BAT - double-click it. It compiles the database, converts graphics and audio, encodes any new video, copies the interpreter, and launches CSpect if RUN=1. It finishes with BUILD OK: RELEASE\ is ready to copy to an SD card.
• RUN.BAT - launches CSpect on whatever is already in RELEASE\, without rebuilding.
• CLEAN.BAT - empties RELEASE\ and clears the compiler's staged intermediates. The next build then converts everything from scratch.

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\ 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 kit 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.

RELEASE\ is the finished SD card image. Copy its contents (not the folder) to the root of the card. It holds:

• nextdaad.nex - the interpreter, the file you launch.
• <GAME>.NEX and INTRO\ - the loader intro, when you ship one; launch <GAME>.NEX instead. See Loader intro.
• GAME.DDB - your compiled adventure.
• 0.XMB - external message text, if your game uses XMESSAGE or XMES. It must stay beside GAME.DDB; without it those messages silently print nothing.
• NNN.NX2 / NNN.NXI - converted location pictures, and DAAD.NX2 / DAAD.NXI for a title screen (with a .zx0 suffix when COMPRESS=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.

STARTER.DSF ships with the kit 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.

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.

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.