Dev Environment

This tutorial takes you through setting up a working NextDAAD developement environment setup: an editor that understands DAAD source, version control keeping a history of your work, the authoring kit, the tools it needs, and a starter game running in an emulator.

You do not need to know yet DAAD to follow it. At the end you will have built and played STARTER.DSF, the example that ships with the kit.

What you are building

NextDAAD is an interpreter for the ZX Spectrum Next: it reads a compiled DAAD adventure and plays it, with Layer 2 artwork, AY music, sampled sound and video cutscenes. You write your adventure as a plain text .DSF (DAAD Source File) file. The authoring kit turns that file, plus whatever artwork and audio you supply, into a folder you copy onto an SD card to put in your Next - or launch straight into an emulator.

You can write DAAD games in any text editor but here we're going to be using Visual Code Studio.

Five pieces make up the environment:

Windows is required. The kit's build scripts are Windows batch files.

Step 1: Install VS Code

Visual Studio Code is a free editor from Microsoft. Any text editor can write a .DSF file, but VS Code is the one the DAAD extension plugs into.

1. Go to https://code.visualstudio.com/ and click the big download button. It detects Windows on its own.
2. Run the downloaded installer, VSCodeUserSetup-x64-<version>.exe.
3. Accept the licence and keep clicking Next. On the "Select Additional Tasks" page, tick Add "Open with Code" action to Windows Explorer directory context menu. That gives you a right-click "Open with Code" on any folder, which you will use later.
4. Finish the install and let it launch VS Code.

First run shows a welcome tab. Three parts of the window matter for this tutorial:

• The Explorer icon at the top left of the sidebar, which lists the files in the folder you have open.
• The Source Control icon below it, a branching-lines symbol. That is Git's panel.
• The terminal, opened with Ctrl + ` (backtick) or from Terminal > New Terminal. It opens in whatever folder you have open.

Step 2: Install the DAAD VS extension

DAAD VS is an extension for the DSF source format. It colours the condacts, messages and object definitions, tells you what a flag or condact does when you hover over it, jumps to where a location is defined, draws a map preview of your adventure, and flags problems before you run a build.

It is not on the VS Code Marketplace yet, so you install it from a downloaded file.

1. Go to https://condact.xyz/daad-vs and download the release. You get a .vsix file, for example daad-dsf-0.1.0-beta.1.vsix.
2. In VS Code, click the Extensions icon in the sidebar (four squares).
3. Click the ... menu at the top of the Extensions panel and choose Install from VSIX....
4. Pick the .vsix file you downloaded and click Install.

Step 3: Install Git

Why bother

Git records the state of your source every time you ask it to, and lets you go back to any of those states later. Advantages of using git source history:

• You change a response, the game stops working, and you cannot remember what it used to say. Git shows you exactly which lines changed since your last save point, and puts them back if you want.
• You want to try restructuring a puzzle without losing the version that works. Commit first, experiment freely, and throw the experiment away if it goes nowhere.
• A .DSF file grows to thousands of lines. "What did I do yesterday" stops being answerable from memory.

Git is not required to build a game, but it can be very helpful in keeping track of changes and helping with debugging as your game grows.

Install it

1. Go to https://git-scm.com/download/win and download the 64-bit Windows installer.
2. Run it. The installer asks a lot of questions and the defaults are all fine - keep clicking Next.
3. One page worth a glance: "Choosing the default editor used by Git". Pick Use Visual Studio Code as Git's default editor if it is offered. It only matters in situations this tutorial does not reach.
4. Finish the install.

Tell Git who you are

Git stamps your name on every save point. Open a terminal in VS Code (Ctrl + `) and run these two lines, with your own details:

git config --global user.name "Your Name"
git config --global user.email "Turn on Javascript!"

You only ever do this once per machine. If VS Code was already open when you installed Git, close and reopen it so it picks Git up.

You will actually start tracking your adventure in Step 5, once there is something to track.

Step 4: Get the NextDAAD authoring kit

1. Go to https://condact.xyz/nextdaad and download the authoring kit, for example NextDAAD-AuthoringKit-v0.9.0.zip.
2. Right-click the zip and choose Extract All. Put it somewhere short and without spaces or accented characters in the path, such as C:\NextDAAD\MyGame or D:\Adventures\MyGame. Avoid OneDrive-synced folders: the sync client can lock files while a build is writing them.

What is in the folder

Open the extracted folder in VS Code: right-click it in Explorer and choose Open with Code, or use File > Open Folder in VS Code.

STARTER.DSF        The example adventure - your source file
BUILD.BAT          Compiles everything into RELEASE\
RUN.BAT            Launches the emulator on what is already built
CLEAN.BAT          Empties RELEASE\
CONFIG.BAT         Every build setting
nextdaad.nex       The interpreter itself
IMAGES\            Location artwork as PNGs
AUDIO\             Arkos music and .wav samples
VIDEO\             Cutscene sources as .mp4
RELEASE\           Build output - the SD card image (appears after a build)
docs\index.html    The full manual
tools\             Where the third-party tools go (Step 5)
externs\           The externs library
lib\               The compiler library files

Click STARTER.DSF in the Explorer sidebar to open it in VS Code.

When opening a DSF file you may need to enable the highlighing. To do so click Plain Text, then in the search bar at the top search DSF and select DAAD DSF.

The file comes up in colour rather than plain grey text, and hovering over a condact such as PRINT shows what it does.

Start tracking it with Git

Now that there is a folder to track, put it under version control. In VS Code's terminal, in the kit folder, run:

git init

Before your first save point, tell Git what to ignore. Build output and downloaded tools do not belong in your history - they are large, they change on every build, and they can be regenerated. Create a new file called .gitignore in the kit folder (in the Explorer sidebar, click the new-file icon and type the name including the leading dot) with this in it:

RELEASE/
tools/
lib/

Then make your first save point. Click the Source Control icon in the sidebar. It lists everything in the folder as a change. Type a message in the box at the top, such as Initial kit, and click the tick (Commit). If VS Code asks whether to stage all changes, say yes.

From now on, commit whenever you reach a state worth being able to return to.

Step 5: Download the extra tools

The kit ships the compiler and the interpreter, but three third-party tools are downloaded separatelye. All three are needed to build STARTER.DSF, because it has artwork, music and a video cutscene.

Everything goes into the kit's tools\ folder. tools\README.txt lists the same addresses if you need them later.

These are independent releases rather than signed commercial installers, so the first time you run one Windows may show a blue "Windows protected your PC" box. Click More info, then Run anyway.

CSpect - the emulator

This is what plays your game on your PC.

1. Download from https://mdf200.itch.io/cspect (click "Download Now", then "No thanks, just take me to the downloads").
2. Extract it so that CSpect.exe ends up at tools\CSpect\CSpect.exe.

Arkos Tracker 3 - the music tools

The build uses three of its command-line converters to turn Arkos .aks music into the format the interpreter plays.

1. Download from https://www.julien-nevo.com/arkostracker/index.php/download/ and pick the Windows build.
2. Extract or install it so that these exist:
   • tools\ArkosTracker3\tools\SongToAky.exe
   • tools\ArkosTracker3\tools\SongToSoundEffects.exe
   • tools\ArkosTracker3\tools\SongToYm.exe

Arkos Tracker is also the program you compose in, later on. The build only uses the converters in its tools\ subfolder.

ffmpeg - video decoding

Only used when a cutscene needs encoding, which STARTER.DSF does.

1. Download from https://www.gyan.dev/ffmpeg/builds/ and take the release essentials build.
2. Extract it so that ffmpeg.exe ends up at tools\ffmpeg\bin\ffmpeg.exe. The zip already has a bin\ inside it, so extract the archive's inner folder as tools\ffmpeg.

Check the layout

When you are done, these five paths must exist inside the kit folder:

tools\CSpect\CSpect.exe
tools\ArkosTracker3\tools\SongToAky.exe
tools\ArkosTracker3\tools\SongToSoundEffects.exe
tools\ArkosTracker3\tools\SongToYm.exe
tools\ffmpeg\bin\ffmpeg.exe

tools\gfx2next\gfx2next.exe should already be there - the picture converter ships with the kit, along with the video encoder.

Already have one of these?

CSpect, Arkos Tracker and ffmpeg are general-purpose tools, and there is no need for a second copy. Open CONFIG.BAT and set the matching directory to your existing install:

SET CSPECTDIR=C:\Emulators\CSpect
SET ARKOSDIR=C:\Program Files\Arkos Tracker 3
SET FFMPEGDIR=C:\ffmpeg

Point each at the folder the tool was installed into. Leave the rest blank and they still come from tools\, so you can mix the two freely. Paths with spaces are fine.

What about sjasmplus?

tools\README.txt also lists sjasmplus, a Z80 assembler. Skip it. It is only needed to modify an extern's assembly source, and every extern ships prebuilt. You can add it later if you ever need it.

Step 6: Build STARTER.DSF

Double-click BUILD.BAT in the kit folder. A console window opens and works through the stages: compiling the database, converting the pictures, converting the audio, encoding the video, staging the interpreter.

The first build is the slow one, because the video cutscenes have to be encoded. That result is cached, so later builds skip it unless you change the .mp4.

You are looking for this at the end:

BUILD OK: RELEASE\ is ready to copy to an SD card

RELEASE\ now holds the finished game: nextdaad.nex (the interpreter), GAME.DDB (your compiled adventure), and the converted pictures, audio and video beside them. Copying the contents of that folder to the root of an SD card is all it takes to run on real hardware.

If the build fails

The build stops at the first error and names the cause. The three a beginner usually meets:

required tool missing - the named path does not exist. Compare it against the five paths in Step 5. The usual culprit is an extra nested folder from the zip, for example tools\CSpect\CSpect_2_19_1_9\CSpect.exe. Move the contents up a level.

CSpect is running - close it before building - the emulator has the RELEASE\ files open. Close its window and build again.

set GAME in CONFIG.BAT - the kit folder holds no .DSF, or more than one. With exactly one there the build finds it by itself; otherwise open CONFIG.BAT and set SET GAME=STARTER (the base name, no extension).

The console window stays open on any of these, so you can read the message. It closes by itself only when the build succeeds.

The kit manual at docs\index.html has the full list of build messages under "Getting started", in the section "When the build fails".

Step 7: Run it

If CONFIG.BAT still has its shipped default of SET RUN=1, CSpect launched by itself as soon as the build succeeded. Otherwise, or any time afterwards, double-click RUN.BAT - it starts the emulator on whatever is already in RELEASE\, without rebuilding.

Press any key to exit the title screen and move into the game.

A few things to know about the emulator window:

• Close it with the window's close button, or Alt + F4. Esc does not quit: RUN.BAT launches CSpect with -esc, which hands the Escape key to the game instead of using it to exit.
• F1 opens CSpect's debugger. Press it again to leave. You will not need it for a while.
• The window opens at triple size, and RUN.BAT points the emulator's SD card at your RELEASE\ folder, so what you see is exactly what real hardware would load.

Things to try in STARTER

STARTER.DSF exists to demonstrate the Next-specific features. Type these at the prompt:

• HINT - pointers to everything the demo can do
• MUSIC, MUTE, TUNE - AY background music
• BLEEP, ZAP, SAMPLE - sound effects and sampled audio
• MOVIE, REEL - video cutscenes

Ordinary adventure verbs work as you would expect: LOOK, NORTH, EXAMINE, GET, INVENTORY.

You are set up

Commit your working state before you go any further. In the Source Control panel, type a message like Working build of STARTER and commit. That is the state you can always get back to.

Where to go next:

• The kit manual, docs\index.html in the kit folder. Start with "Getting started", then the pages for whatever you want to add: Graphics, Audio, Video, Fonts, Mouse.
• Learning DAAD itself. The manual covers what is specific to the Next, not the DAAD language. The DAAD Ready manual is the reference for the source format, the condact set and the system flags.

A working loop from here is short: edit the .DSF in VS Code, save, double-click BUILD.BAT, play the result, commit when it works.