Skip to content

Home

Jump to bottom
Uto edited this page Mar 9, 2020 · 29 revisions

INDEX

Preface

DRC is the new DAAD (Diseñador de Aventuras de Aventuras AD - Aventuras AD adventure designer) compiler, DRC stands for "DAAD Reborn Compiler" and it has two parts:

  • The front-end, which takes a .DSF file (DAAD Source File), a format very similar to SCE but not the same, and generates a .json file which contains all the information of the game.

  • The back-end, which takes the .json file and generates the .DDB file.

Other tools

The package also includes the following tools:

  • DAADMAKER, a tool which will help you easily create TAP and DSK files for ZX Spectrum.
  • MCRF, a native (Windows, Linux, OSX) replacement for original DAAD MCRF for CPC, which had to be run in CP/M.

License & copyright

The compiler is (C) Uto 2018 and it's distributed under the GPL v3 license. Some parts have been greatly inspired in Jose Manuel Ferrer's python interpreter.

Downloads

Find latest version at DRC Releases site, make sure you pick the version with the more recent date.

Why should you use DRC?

There are four main reasons:

  • It's native to your OS, no more DOSBOX windows
  • It applies some specific optimizations, not related to text compressions, which makes the DDB file smaller
  • You will be able to write messages directly instead of having to create message in MTX section and then refer it by number in processes. Example:
MESSAGE "Blah blah blah"

You can still use numbered messages if it's more convenient at some point though.

  • It transparently integrates with MALUVA, a DAAD addon providing very interesting features. You can use the X condacts (XMESSAGE, XPICTURE, XPLAY, etc.) instead of using more complicated EXTERN calls.

The DSF format

DRC uses a source format very similar to the original SCE format used by original DAAD compiler (DC), but there are some changes:

  • Character encoding is ISO-8859-1 (Latin1), but is also compatible with Windows-1252. It's a quite more common encoding today, and much preferred over the very old CP437 (DOS) encoding.
  • #define symbols can have any length, DC was cutting them after 15 characters.
  • STX/MTX/LTX/OTX sections should have the message written between quotes (it doesn't matter if single or double quotes while you use the same at both sides)

Examples:

\0 "It's dark"
\1 'You are carrying: '

Any quote similar to those at the sides of the string, which are inside the string, should be escaped with a backlash. For English it's highly recommended to use double quotes for strings, so you can write "It's OK" instead of 'It's OK'.

Actually, DRC is able to detect a non escaped quote and fix it, so this is actually possible:

\0 'It's dark'

A side effect of that support is DRF will just understand anything between the first quote in the line and the last one is a string, so this:

\0 'It's dark' ; 'Not really'

would get this as the string, ignoring the comment:

>>>It's dark' ; 'Not really<<<
  • Escape codes use sharp character (#) instead of backslash. For instance you write #k instead of \k. Due to some lucky side effect, \n will still work, but it's the only one (and #n works as well).

Examples:

/58 "Disk or drive full.#k#n"

Please notice escape codes that used to be a blank space are not really required with the double quotes delimiters, but anyway they still work.

  • The following compiler directives are supported

#define xxxxx [value|identifier|expression]

#define fPlayer 38
#define Columns COLS
#define fTurnsHi "fTurns+1"

Please notice expressions should be placed in between quotes, just like in last example above.

**#ifdef/#ifndef "xxxxx" **

#ifdef "zx"
#ifndef "8bit"

Please notice #ifdef can be replaced with #if too, but DC expressions like '#IF !zx' are not valid. Use #ifndef instead.

**#endif **

Just as for DC

**#else **

You can do:

#ifdef "zx"
<do something>
#else
<do something else>
#endif

**#extern, #sfx and #int **

#extern "MLV_MSX.BIN"

#incbin, #hex, #dw/#defw and #db/#defb

#incbin "somefile.bin"
#hex "AF89F5EA"
#dw 7
#db COLS
#db "COLS/2"

(please notice in expressions, results will be truncated to the previous integer value, so if in last example COLS equals 21, them 10 will be the result in the #db)

#classic (will be explained later)

**#echo **

#echo "Hello world!"

** #include

#include includefile.dsf

Please notice #include should be at the start of a line, and file name is not in between quotes.

Nested includes are not allowed.

#debug (will explain later too)

  • DSF format doesn't have a /TOK section
  • In DSF files processes, indirection is marked with @ sign, that is @Player instead of [Player]
  • You can write messages directly like this

MESSAGE "Hello World!" SYSMESS "Help" DESC "You are in hole"

The compiler will find a place for that message in a message table, and assign the number automatically. You can still create and use messages the old way if you want.

  • DSF files have /END mark at the end of last process
  • Processes entries should have a preceding > sign , see below.
  • Processes Syntax is more flexible all these options are possible (some are quite weird, but possible anyway):
; All in one line
> _ _ AT 7 CARRIED 2 LET 127 12 MESSAGE 15 CREATE 2 DONE

; ngPAWS/Superglus/NMP style
> _ _
 AT 7
 CARRIED 2
 LET 127 12
 MESSAGE 15
 CREATE 2
 DONE

; DC Style
> _ _     AT 7
        CARRIED 2
        LET 127 12
        MESSAGE 15
        CREATE 2 
        DONE

; Obfuscated DAAD
> 
_ 
_  AT 7 
 CARRIED 
 2 LET 127 12 MESSAGE ; comment
 15 CREATE ; comment
 2 DONE
  • The compiler directive #debug will make the compiler accept a new condact named DEBUG. If #debug is not present DEBUG condacts will be just ignored. DEBUG condact is a fake condact that will you game reset unless you are running under ZesarUX ZX Spectrum emulator with DAAD debug active. ZesarUX emulator detects that fake condact, and enters step by step debugging at that point. You can add as many DEBUG condacts as you want, for debugging purposes, just remember to remove the #debug directive before generating production version of your game.
  • The compiler directive #classic affects both backend and front end. By default the new compiler makes several optimizations which at the moment are experimental.

Those optimizations include mainly two tasks:

  1. Optimizations to save space (make a smaller database), not related to text compressing.
  2. Automation which makes the compiler be clever enough to put a message in STX or LTX tables when the MTX table is full and another MESSAGE "a message" condact appears.

In classic mode, none of those advantages take place.

  • DRC supports synonym sentences, which mean you can write this:
> UNLOCK GATE
> OPEN DOOR
   AT lGatesOfDoom
   NOTCARR oKey
   MESSSAGE "You don't have the key."
   DONE

and have the same result than writing this:

> UNLOCK GATE
   AT lGatesOfDoom
   NOTCARR oKey
   MESSSAGE "You don't have the key."
   DONE

> OPEN DOOR
   AT lGatesOfDoom
   NOTCARR oKey
   MESSSAGE "You don't have the key."
   DONE

It doesn't only save space in your source file, but also in the final DDB, as DRC is able to detect two entries with same condacts and re-use the code.

You can add as many sentences as you want:

>UNLOCK GATE
>OPEN DOOR
>OPEN GATES
>PUSH DOOR
 <condacts>

How to compile

  1. First we have to call the front end (drf). Syntax is:

DRF [subtarget] <file.DSF> [output.json]

can be zx, cpc, msx, c64, amiga, pcw, st, pc or msx2.

machine is automatically created as a #define, so if you call the compiler with "c64" then [#ifdef "C64"] would be a successful condition.

DRF will also create "bit8" or "bit16" symbols depending on target machine, so you can also use [#ifdef/#ifndef "bit8"]

DRF will also automatically create the symbol COLS as DC does, depending on target, but will also create the ROWS symbol, which DC doesn't create.

DRF will also create the symbols LAST_OBJECT, LAST_LOCATION, NUM_OBJECTS and NUM_LOCATIONS

[subtarget] is only required if target is PC (options accepted are VGA, CGA, EGA and TEXT), MSX2 (oprtions accepted are 5_6,5_8,6_6,6_8,7_6,7_8,8_6 and 8_8, or Spectrum (options accepted are esxdos, plus3 and next)

[output.json] is the output file name, if missing , same name of the .DSF file will be used, with JSON extension.

Please notice MSX2 target is a new target for a new interpreter being developed at the moment (April, 2018).

Examples:

drf msx mygame.dsf
drf zx plus3 mygame.dsf
drf c64 mygame.dsf
drf pc vga mygame.dsf someother.json
drf msx2 5_8 mygame.dsf
  1. Then we have to call the backend, that is made like this:

drb [subtarget] <fichero.json> [output.ddb]

and [subtarget] are just like in the front end, and language can be "es" or "en" (for Spanish and English)

Once again, last parameter is optional, if you don't provide an output file name, the same name of the json file will be chosen, and extension changed to DDB.

Examples:

drb c64 en mygame.json
drb pc vga es mygame.json
drb msx en mygame.json final.ddb

Fake Condacts

DRC supports several fake condacts when using MALUVA extension. Please check MALUVA documentation for better understanding.

Hey! There is no DRB executable!

You are right, drb is not an executable file, is a PHP script, so you have to call it with php. See below about how to install PHP in your OS.

So you actually have to call drb like this:

php drb.php zx plus3 en mygame.json
php drb.php pc vga es mygame.json
php drb.php msx en mygame.json final.ddb

Installing PHP

  • OSX: since a long time ago php is installed de-facto in all OSX versions, I have checked it was already on Mavericks, so anything newer than that, including latest High Sierra and Mojave include php.

  • Linux: install the following packages with your favorite package manager: "php" and "php-xml"

  • Windows: go this URL (https://www.php.net/downloads.php), click on "Windows Downloads" (at the bottom of first block). Download the newest zip and extract it wherever you prefer. After that you either add that folder to the PATH, or you will have to call php using the full path, so instead of

php drb.php msx en mygame.json final.ddb

ou will have to write

C:\path\to\your\php\installation\php.exe drb.php msx en mygame.json final.ddb

Obviously, adding php folder to the path will make your life easier in the long term.

Compiler parameters

For DRF

Apart of the parameters detailed before, DRF can accept several options and symbol definition. Any parameter after the JSON file may be an option (starting with a hyphen) or a symbol list.

A symbol list is a way to #define from command line. So if you add a parameter like this (without the quotes): "test,over" it's just like if you add this to the beginning of the code:

#define test 1
#define over 2

Make sure you make a comma separated list without spaces in between. If only a symbols is to be defined, just write the symbol.

Example:

drf msx game.dsf game.json test
drf msx game.dsf test
drf msx game.dsf test,over

Also, there are several options that can be added:

  • -verbose : will force verbose output
  • -no-semantic: DRF makes some check so the parameters of a condact has some meaning, for instance if you type CARRIED 10, it will check if there is an object with #10, and fail otherwise. This parameters makes DRF ignore those cases and continue. Please notice there is likely the interpreters fail with a runtime error in those cases.
  • -semantic-warnings : similar to the previous one, DRF won't fail on semantic errors, but will warn about them.
  • -force-normal-messages: this parameter will make all XMESSAGE/XMES (check MALUVA) to be converted to MESSAGE/MES.

For DRB

DRB supports several options after last parameter:

  • -v : verbose output
  • -ch : Prepend C64 header to DDB file (ch stands for 'Commodore header')
  • -3h : Prepend +3 header to DDB file (3h stands for 'Three header')
  • -c : Forced classic mode
  • -d : Forced debug mode
  • -np : Forced no padding on padding platforms
  • -p : Forced padding on non padding platforms

Examples:

php drb zx plus3 es game.json -3h
php drb c64 en game.json mygame.ddb -ch
php drb pc vga en game.json mygame.ddb -c -v

Important note

Many of you will tend to include DRF and DRB calls in a batch file, please make sure that batch file checks DRF exit errorlevel, cause if it fails, you would probably running DRF on the previous version of the JSON file generated by DRC, so it will be successful but very confusing.

In Linux, MSYS and probably in OSX, adding this after the call to DRF will do the trick:

rc=$?; if $rc != 0; then exit $rc; fi

In Windows I believe you have to put this after DRF call:

IF ERRORLEVEL 1 EXIT

Hey! What about text compression?

The backend compiler includes the tokens included in the default databases for both English and Spanish, so you don't have to care about that. I've worked a bit trying to get better tokens for the current messages, but didn't get any results. Still, DRC saves space compared with DC, but it's because of other optimizations not related with text compression. DRC always applies compression to MTX and STX sections, in case you don't want that, edit drb.php file and in the line where you can see "advanced" replace that with "basic".

If you need to get the better tokens for a given title you can use DRT by Jose Manuel Ferrer, a nice tokenizer for DAAD texts which will get the best compression.

DAADMAKER

DAADMaker will help you create a .TAP file, and even a .DSK file for your Spectrum. You will need at least the DDB file created by DRC (or DC) and the chosen interpreter (DS48IS.P3F for Spanish, DS48IE.P3F for English).

You can also add (optional):

  • A graphics+charset database, created by DG, in .SDG format. If you don't provide one, daadmaker will add one with no graphics, and with default charset.
  • A loading screen in .SCR format. If you don't provide one the game won't have a loading screen but will work anyway.
  • A custom loader. If you don't like the BASIC loader daadmaker provides, just create one and save a TAP file with it, and tell daadmaker to use it. Make sure the custom loader contains three LOAD""CODE, or four in case you add a loading screen.

For instance, you can do:

daadmaker OUTPUT.TAP DS48IE.P3F GAME.DDB GAME.SDG PANTALLA.SRC   --> Creates OUTPUT.TAP with GAME.DDB, GAME.SDG and GAME.SCR
daadmaker OUTPUT.TAP DS48IE.P3F GAME.DDB --> Creates OUTPUT.TAP with GAME.DDB, default font, no graphics and no loading screen.
daadmaker OUTPUT.TAP DS48IE.P3F GAME.DDB GAME.SCR --> Creates OUTPUT.TAP with GAME.DDB, default font, no graphics and GAME.SCR as loading screen.
daadmaker OUTPUT.TAP DS48IE.P3F GAME.DDB GAME.SDG GAME.SRC MYLOADER.TAP  --> Creates OUTPUT.TAP with GAME.DDB, GAME.SDG and GAME.SCR, using MYLOADER.TAP as BASIC loader.

This package does also include TAP2DSK.TAP, a custom loader which when used your generated tap file is a tap file that , when loaded in a Spectrum +3 (real or emulated), will save the game to disc instead of running the game. Use it to create .DSK file. Please notice this custom loader assumes the game has a loading screen, won't work otherwise.

DAADMAKER does also now support changing the game character font. You will need a 2048 bytes file, 8 bytes per character, 256 characters. Please take in mind DAAD in the Spectrum uses a 6x8 character set, so despite each of your characters has 8 bits per scanline to define, make sure you don't use the two rightmost ones (and even the third rightmost one if you want to have some space between characters). This feature is experimental.

MCRF

MCRF is described in DAAD's manual , section "4.2.2 The CPC". The version provided in DRC package is just a DOS/LINUX/OSX executable, instead of a CP/M one, which makes things easier.

Apart of what is described there, the new MCRF supports an additional parameter: a CHR file can be specified in order to replace the charset. A CHR file must be a 2048 bytes long file, using 8 bytes per each 256 chars. Spanish characters are located from character 16 to 31.

Building DRC

To compile just download freepascal and run:

fpc drf.pas

In case you need to change the lexer file (DSF.l) delete file lexer.pas and update it by running:

plex DSF.l lexer.pas

Plex is usually included with freepascal. Make sure you have installed both fpc and fpc-src packages.

Support me

Well, honestly I do this for fun, so I don't really need support. I enjoy every minute I work in these kind of tools, and when I don't enjoy it, I just don't do it. If anyway you want to support me somehow you can send me a copy of your games (either digital or physical), or as last option, just buy me a beer via paypal donation.

Clone this wiki locally