1. 8-Bit Compatibility Mode

Adventuron games can be auto-translated so that they can run on 8-bit microcomputers via pre-existing engines - as long as they adhere to rules highlighted in this section.

Games are exported to use either the DAAD engine (text, or text and graphics) or PAW (not yet documented but available via menu). These engines cover a majority of popular 8-bit machines.

As of this first release only ZX Spectrum Next and ZX Spectrum +3 are supported with graphics.

1920px ZX Spectrum Plus3
Figure 1. ZX Spectrum +3, public domain image (Wikipedia)
snext
Figure 2. ZX Spectrum Next, image from https://www.specnext.com (Copyright fair use)

Amstrad PCW is additionally supported without graphics.

pcw
Figure 3. Amstrad PCW, image by Marcin Wichary (CC 2.0 license)

Adventuron contains a lot of features that are not compatible with the DAAD engine, or would be problematic to map. Games targetting 8-bit in Adventuron must be built from the ground up with exporting in mind.

Authors should enable the 8-bit-compatibility mode within Adventuron and develop your game with this toggle switched on, only using only compatible features, see the 8 Bit Compatible Features section to understand what is permitted and what is not.

If you want to add 8-bit compatible graphics, then it is important that you select your target platform (for graphics) prior to developing your game. See the 8-Bit Graphics section for more information on the limitations you should bear in mind when making graphics.

This section contains a sample game to test then copy and paste "The Cave of Magic" from here.

Warning
The 8-bit compatibility mode is not guaranteed to work in all cases. It’s quite possible that an exported game won’t fit in DAAD. Regular exports are recommended.

2. Step By Step Guide

Warning
This tutorial assumes that you are writing games from the ground-up to target 8-bit, rather than trying to export an existing game. Exporting an existing game will difficult if not impossible.

2.1. Preparing Adventuron

Navigate your desktop browser to:

Click the "Menu" button at the bottom right of the text editor, and clear the editor by selecting the "Start Coding" option.

Click the "Menu" button at the bottom right of the text editor, and click the "8-Bit Compatible" option (should show a check next to the option when selected).

This will enable Adventuron to become more picky about the features it permits you to use (so as to be compatible with the target game engines).

2.2. Preparing The DAAD Ready ! Environment

Before you can port your games to ZX Next / ZX +3, you will need to install the DAAD Ready ! package (Windows Only currently).

The DAAD Ready! package is a collection of tools and emulators to help you build and test games with the next generation DAAD tooling (DRC Compiler + Maluva plugin).

The Adventuron to DAAD / PAW converter (including graphics converters) runs entirely in the browser and is OS independent, but (currently) the DAAD Ready ! package is Windows Only.

Note
Read more about DAAD Ready !, DAAD, PAW, Inpaws, and the Maluva plugin later in the section.

2.2.1. Installing DAAD Ready

Warning
DAAD Ready is currently only available on Windows operating systems.
  1. Download the DAAD Ready Zipfile (English language), from here : http://ngpaws.com/downloads/DAAD/DAADReady/

  2. Unzip the zipfile to C:\utils\DAADNX

2.2.2. DAAD Ready!

(Every time you want to re-build, you need this window open.)

  1. Open a command prompt, by typing cmd (in your start menu) then pressing ENTER.

  2. In the command prompt window, type C:

  3. In the command prompt window, type cd \utils\DAADNX

2.3. Exporting

  1. Click MENU, and confirm that 8-bit compatibility mode is switched on (this should be have been switched on from the moment you were developing your game). If not, then click it.

  2. Press CONTROL + S to save your game.

  3. Confirm there are no errors (the header bar is not red).

  4. Now click "MENU / Export DAAD" or "MENU / Export DAAD (+ Graphics).

8bit a
Note
Selecting the option without graphics will use full screen. Selecting the option with graphics will reserve the top 80 pixels for graphics (ZX Next and ZX Plus 3).
  1. A zipfile should have been downloaded in the default download folder for your browser. Locate the zipfile, and unzip the contents into the Daad Ready! folder we set up earlier. This will overwrite TEST.DSF, so make sure you have a backup if it is important.

Note
This procedure will be simplified in a later release.
  1. In the command window for DAADNX, type ZXNEXT.BAT to test your game.

Warning
Please note that there is no guarantee that the exported source code will be 100% compatible with DAAD Ready. There are a number of issues, including gamesize that may make the exported file not able to be compiled by the DRC (DAAD Reborn Compiler).
com zxnext 1
Figure 4. Cave of Magic running under ZEsarUX (ZX Spectrum Next Emulator)
  1. In the command window for DAADNX, type ZXPLUS3.BAT to build a ZX Spectrum +3 disk image and test your game in an emulator (or PCW.BAT to build for PCW - text only).

com zxp3 1
Figure 5. Cave of Magic running under ZEsarUX (ZX Spectrum +3)
Note
You should choose a target platform and design your graphics for that platform. See the graphics section for more information. The ZX Next graphics for example are incompatible with +3 so any attempt to port a game with graphics will end up with very badly formatted graphics.
  1. Your build gamefiles will now be stored in the RELEASE/ZXNEXT folder underneath your DAADNX folder. You can zip up these files, and add a readme.txt to distribute your game.

  1. In the command window for DAADNX, type ZXTAPE.BAT to build a ZX Spectrum tape image (without graphics) and test your game in an emulator. Please note that if you want to build the tape version of the game, then you should export with graphics switched off, otherwise the top part of the screen will be reserved for graphics.

2.4. End of Tutorial

Thank you for following this tutorial.

3. Compatibility

Not all Adventuron features work with the 8-bit export option. In fact most do not. This section details the features are are available to you when you target 8-bit.

3.1. Graphics

You can customize graphics for multiple platforms from the output of this tool, but you can only currently target either ZX Spectrum Next, or ZX Spectrum +3 at the moment.

All graphics (to be mapped) should be in PNG format.

Location graphics (graphic dimensions and colour palette must be compatible with target platform). If the graphics are in PNG format and adhere to the rules as shown below, then the graphics will be converted and exported automatically by the "Export to DAAD (+ graphics)" option.

ZX NEXT

ZX Next location (or incidental) graphics should be 255 colours or less, and be 256 pixels by 80 pixels.

com lakeside
Figure 6. A ZX Spectrum Next compatible image (3.20 : 1 aspect ratio, 128 x 40)

Loading screen should be 255 colours of less and 256 x 192 pixels.

com loading screen
Figure 7. A ZX Spectrum Next compatible loading screen (3.20 : 1 aspect ratio, 128 x 96)

You as an author should make sure that you use 255 or less colours, and be careful about very smooth gradients.

Stick to pixel art, with approimately 8, 9 or 12 bit palettes and it will be mostly fine.

Don’t worry about the loss of some colour precision in your image. The ZX Next only has a 256 colour palette, so this is natural. The DAAD Ready! PCX to Next image converter takes care of colour assignment.

ZX SPECTRUM +3 / ESDOS

ZX Spectrum graphics should be a maximum of 15 colours, and adhere to the ZX Spectrum attribute colour rules (no more that 2 colours in each 8x8 tile).

Location graphics should be 256 x 80 pixels.

birwood 1
Figure 8. A ZX Spectrum compatible image (3.20 : 1 aspect ratio, 256 x 80)

Loading screen graphic should be 256 x 192 pixels (or 128 x 96).

dino load
Figure 9. A ZX Spectrum compatible image (3.20 : 1 aspect ratio, 256 x 192)

Drawing ZX Spectrum graphics is very difficult for the newcomer. It really helps to use a tool like multipaint to help you, as it is aware.

If you want to manually test your ZX Spectrum PNG file for compatibility before importing your images into Adventuron, then Retronator png to scr by Matej Jan will let you know if your image is compliant.

retronator
Figure 10. Retronator PNG to SCR (ZX Spectrum Compliant PNG Checking tool)

3.2. Mapped Boolean Expressions

Adventuron has a powerful expression format that allows use of ands ors and not operations. These are largely supported by the 8-bit exporter.

chance

has_not_created

has_visited

is_at

is_beside

is_carried

is_exists

is_mobile()

is_present

is_worn

is_within_direct

! (NOT)

&& (AND)

|| (OR)

P1 == P2

P1 != P2

P1 < P2

P1 ⇐ P2

P1 > P2

P1 >= P2

VARIABLE_ID

Note
is_mobile() will always resolve to a true value when exporting to 8-bit.

3.2.1. Type Support

The 8-bit exporter supports integer and boolean variables only, not string variables.

Dynamic variables are not supported (dynamic_string, dynamic_integer, dynamic_boolean).

3.3. Theme Support

The vast majority of theme related features are not mapped. The "set_theme" command is not mapped.

The colors for the default theme are mapped (only for the PAW exporter, and only if they use 0 - 15 as colour codes, with the default ZX Spectrum palette).

Inline text colouring is supported on PAW, but not on the DAAD export.

3.4. Mapped Commands

The following commands are compatible with the 8-bit export feature:

Table 1. Mapped Commands

add

beep

clear_screen

create

decrement

destroy

done

door_operation

drop

else

get

goto

if

if_else

increment

inventory

lose_game

match

ok

pause

pocket

press_any_key

print

print_graphic

redescribe

return

set_false

set_graphic

set_integer

set_true

store_random

swap

turns

win_game

3.5. Match statement compatibility

An outer match and inner matches are supported, but only if an outer match ONLY contains inner matches.

// Good
: match "examine _" {

   : match "examine hat" {
      // Content
   }

   : match "examine lamp" {
      // Content
   }
}
// Bad
: match "examine _" {
   if (is_awake) {
       : match "examine hat" {
          // Content
       }

       : match "examine lamp" {
          // Content
       }
   }
}

3.6. Local Event Handlers

Only the on_describe local event handler is compatible with 8-bit compatible mode.

Warning
Other local event handlers (event handlers underneath a location) are NOT yet mapped. These handlers should be placed in the global event handler sections.
start_at = hut
locations {
    hut : location "You are in a hut." {
       on_describe {
          : if (chance(50)) {
             : print "You feel a breeze.";
          }
       }
    }
}

3.7. If statement compatibility

If statements are mapped up to a level of 4 depth. else_if statement and else statements attached to an if do not increment the depth counter.

As else statements are not supported in DAAD or PAW, then the code that is output for if then else statements will be a little noisy in DAAD / PAW.

If you don’t need an else, don’t use an else.

: match "examine hat" {

    // Level 0

    : if (a) {
       // Level 1
       : if (b) {
          // Level 2
          : if (c) {
             // Level 3
             : if (d) {
                // Level 4
             }
             : else if (e) {
                // Level 4
             }
             : else if (f) {
                // Level 4
             }
             : else {
                // Level 4
             }
          }
          : else_if (g) {
             // Level 3
          }
          : else {
             // Level 3
          }
       }
       : else {
          // Level 2
       }
    }
    : else {
      // Level 1
    }

    // Level 0

    : if (h) {
       // Level 1
    }
    : else {
       // Level 1
    }

    // Level 0

    : if (i) {
       // Level 1
    }
    : else if (j) {
       // Level 1
    }
    : else {
       // Level 1
    }

    // Level 0

}

3.7.1. Detecting if running in 8-bit

If you define the following boolean variables, then they will return true or false values depending on the platform.

These are NOT special Adventuron functions, you need to add these as variables with these exact names, and the converter will take care of the rest.

booleans {
   is_paw          : boolean "false" ;
   is_daad         : boolean "false" ;
   is_paw_or_daad  : boolean "false" ;
}

If you can use this expression to gate off commands that are incompatible with the 8-bit export function.

   : if (is_paw) {
      : print "PAW Version";
   }

   : if (is_daad) {
      : print "DAAD Version";
   }

   : if (is_paw_or_daad == false) {
      : print "Adventuron version";
   }
Warning
Never use else or else if with respect to these variables.

3.8. TROUBLESHOOTING: NOUN OVERLAP and VERB OVERLAP

DAAD only supports parsing the first 5 letters of words in its parser. This was very common back in the 80s, and it helped to reduce the overall memory footprint of the parser.

In 8-bit compatibility mode, this limitation is artificially imposed on Adventuron, so that the exported game will run on the DAAD engine.

As such, you may notice errors such as this (hover over the header of the editor for full message):

NOUN COLLISION DETECTED (CHOPPED TO 5 LETTERS): WATER

When this happens, use CONTROL + F to look for all instances of WATER in your game. What you are looking for is object nouns (usually the object id or scenery id in the objects table) that start with WATER, and also look for NOUNS in the : match commands, that start with water.

In our hypothetical example, we may find that we defined an object called water (which automatically associates a noun called 'WATER'), and we may discover there is also an object called 'WATERFALL'. Now in Adventuron, these are different words entirely, but in DAAD, there is an overlap.

There are two ways to resolve this, either change the name of one of the objects (or match nouns), or make WATER and WATERFALL synonyms.

It is strongly recommended to avoid the synonym approach if it is possible to have parser ambiguity, and to simply rename your object, but if you want to try the synonym approach, the following code will make WATER, and WATERFALL essentially the same token in the output source, and remove the error messages.

There are issues with this approach that if typing EXAMINE WATER in the same location as the WATER and the WATERFALL, which will be examined first.

start_at = lake

locations {
   lake   : location "You are by a lake" ;
}

objects {
   water      : object "some water (in the beaker)" at = "lake" ;
   waterfall  : scenery "a waterfall" at = "lake";
}

vocabulary {
   # Creates a noun synonym for water and waterfall.
   : noun / aliases = [water, waterfall]
}

3.9. Additional Compatible Features

3.9.1. Darkness (NEW)

Darkness is now supported (DAAD Only Export).

3.9.2. Treasure Hunt Mode (NEW)

Treasure Hunt Mode is now compatible.

3.9.3. Status Bar (NEW)

The status bar will now be enabled (text only export mode only).

Table 2. Regular Status Bar

Location Header

Game Name

Table 3. Treasure Hunt Mode Header

Location Header

Treasure Deposited Tally

Note
Game name is extracted from the game_information {} section.

3.9.4. Auto Redescribe mode (Beta)

Warning
This feature has not been tested very much.

Auto-redescribe mode is a mode that refreshes the screen when the object state of the screen changes.

This mode can give an impression of statefulness to the game, as it reduces the number of times that "LOOK" has to be typed. It is very useful for object-centric adventure games.

For games that enable auto-describe mode, you need to call : success at the end of any code block that creates or destroys an object in the current location.

Adventuron is a little more sophisticated as it works out if something changes automatically, but such code is memory hungry, and a waste of RAM on 8-bit.

In 8-bit compatibility mode, adventuron will automatically refresh the screen when you use a : success command.

Get and Drop handlers will be automatically added.

Barriers

All three types of barrier are compatible with the 8-bit export.

block

block_path

door

Warning
In 8-bit compatibility mode 'block_when' and 'block_when_not' cannot reference a dynamic boolean variable (referencing regular boolean variables is fine).

3.10. Randomness

There are two ways to implement randomness into your 8-bit compatible game.

Either use the chance(x) integer function along with a comparitor ( = , >, <, <=, or >=).

Or use the store_random command. Both methods are demonstrated below.

start_at = my_location

locations {
   my_location : location "You are in a room." ;
}

​integers {
   // Only required if you are using store_random
   randomvar : integer ;
}

​on_tick {
   // GOTCHA NOTICE -- Chance is (currently) not working with its parameter in double quotes.
   //                  Use as listed here. This is on the bug list.
   : if (chance (50)) {
      // Will print hello 50 percent of the time
      : print "HELLO" ;
   }

   // Stores the random result in randomvar
   : store_random var = "randomvar" ;

   : if (randomvar < 33) {
      // Will print GOODBYE 33 percent of the time
      : print "GOODBYE" ;
   }
}

3.11. Non-Compatible Features

If the feature isn’t listed under compatible features, then assume that the feature is not compatible.

  • The use of STRING type variables is not supported in 8-bit compatibility mode at all (not supported by DAAD).

  • Non conspicious objects are not supported in 8-bit compatibility mode.

  • Almost all mathematical expressions are not supported in compatibility mode.

  • The % operator is not supported in compatibility mode.

  • Dynamic print statements are only supported in the form {("Some string = " + some_integer variable + " some string " + some integer variable.)

  • Gamebook mode, choice based commands and string variables or functions are explicitly not compatible, but neither is any other feature that is not explicitly whitelisted in this section.

3.11.1. Word Trim Collisions

Warning
Adventuron currently won’t warn about word collisions but the DAAD Ready Compiler (DRC) will inform you if there is an issue. In future versions of 8-bit compatibility mode, you will be informed in the Adventuron editor itself.

Adventuron supports parsing words precisely, but in the 1980s, memory was at a premium, and engines often discarded a little bit of precision to save memory.

DAAD can only detect word uniqueness up to a maximum of 5 letters.

Your game may have issues if you have two words that are the same when looking at the first 5 letters.

  • Example 1 : closet, and close.

  • Example 2 : sauce and saucer.

The best solution is to rename objects / verbs that collide.

3.11.2. Verb / Noun collisions

To be completed.

4. Sample Code

Here we will list a few simple Adventuron games / files that are compatible with the converter. This will be useful to test out the feature / setup.

4.1. The Cave of Magic

This version of the cave of magic includes some text colour codes. These codes are ignored for DAAD, but will be used for the PAW export feature.

start_at = lakeside

locations {
   lakeside     "You are by the side of a <beautiful lake<13>>." ;
   forest       "You are on the <forest path<12>>.\nTall trees tower over you on both sides." ;
   outside_cave "You are standing outside the <cave of magic<11>>." ;
   inside_cave  "You are inside the <cave of magic<14>>." ;
}

connections {

   from, direction, to = [
      lakeside,     north,        forest,
      forest,       north,        outside_cave,
      outside_cave, north_oneway, inside_cave,
   ]
}

objects {
   troll          : scenery "<an enormous troll (guarding cave to north)<10>>" at = "outside_cave" ;
   sleeping_troll : scenery "an enormous troll (sleeping)" ;
   apple          : object  "<an apple<12>>" ;
   treasure       : object  "<a pile of treasure<14>>" at = "inside_cave" ;
}

barriers {
   block_cave : block {
      location               = inside_cave
      message                = THE TROLL IS GUARDING THE CAVE.
      block_when_exists      = troll
   }
}

on_startup {
   : print "You must find the treasure in the cave of magic.";
   : press_any_key ;
}

on_describe {

   : if (is_present "troll") {
      : print "The troll says, \"THE CAVE IS MINE, GO AWAY\"." ;
   }

   : if (is_at "inside_cave" ) {
      : print "CONGRATULATIONS !" ;
      : print "YOU WON THE GAME !" ;
      : print "YOUR RANKING IS : JUNIOR ADVENTURER !" ;
      : press_any_key ;
      : clear_screen;
      : win_game ;
   }
}

on_command {

   : match "examine trees"  {
      : if (is_at "forest") {
         : print "Apple trees." ;
      }
   }

   : match "pick apple;get apple"  {
      : if (is_at "forest" && has_not_created "apple") {
        : print "You take an <APPLE<12>> from one of the trees." ;
        : pocket "apple";
      }
   }

   : match "examine troll;talk troll"  {
      : if (is_present "troll") {
         : clear_screen;
         : print "\"I'M SO HUNGRY\", says the enormous TROLL in the deepest possible voice." ;
         : press_any_key ;
         : redescribe;
      }
   }

   : match "give apple"  {
      : if (is_present "troll" && is_carried "apple") {
         : print "The troll grabs the apple from you hungrily. Unfortunately (for the troll), the apple is an <ENCHANTED APPLE<12>>, and sends the troll directly to sleep." ;
         : destroy "apple" ;
         : swap o1 = "troll"  o2 = "sleeping_troll" ;
         : press_any_key ;
         : redescribe;
      }
   }

}

4.2. Dog And Castle

An ultra-small game that is really just an even smaller version of "The Cave of Magic" is "Dog And Castle".

To add graphics to the game, select the MENU / Import option, to import graphics into the game. Graphics should be named xxxxxx.png, and be 256 pixels by 80 pixels (or 128 x 40), and the xxxxxxx part should correspond to the identifier of the location.

After (optionally adding graphics),to export the game to the ZX Spectrum or ZX Spectrum Next, follow the "Export To 8-bit Platforms" tutorial.

#########################################################
## Dog And Castle - By Chris Ainsley (CC0, Public Domain)
#########################################################

start_at   = forest
redescribe = auto_beta

locations {
   hut    : location "You are in the wizard's hut." ;
   forest : location "You are in the forest." ;
   castle : location "You are in the castle." ;
}

connections {
   from, direction, to = [
      hut,    west,  forest,
      forest, north, castle
   ]
}

objects {
   bone     : object  "a bone"         msg = "A fibula.";
   cupboard : scenery "a cupboard"     msg = "Empty."               at = "hut" ;
   dog      : scenery "a fierce doggy" msg = "A serious chihuahua." at = "forest" ;
}

on_startup {
   : print "Reach the castle!" ;
   : press_any_key ;
}

barriers {
   block_castle : block {
      location            = castle
      message             = The doggy will not allow it.
      block_when_exists   = dog
      show_blocked_exit   = true
   }
}

on_command {
   : match "open cupboard; examine cupboard"  {
      : if (is_beside "cupboard" && has_not_created "bone") {
         : print "You find something ..." ;
         : create "bone" ;
      }
   }
   : match "give bone; throw bone"  {
      : if (is_beside "dog" && is_carried "bone") {
         : print "The doggy approves of your offering and salutes you with a paw before fading into nothingness." ;
         : destroy "dog" ;
      }
   }
}

on_tick {
   : if (is_at "castle") {
      : print "You have reached the castle! Well done." ;
      : win_game ;
   }
}

4.3. Customising The Export

There a few different parameters that can be changed for your 8-bit export, and Adventuron provides a mechanism for including these features. To specify these options, use the "daad_exporter_tags" attribute inside game_settings {}.

game_settings {
   daad_exporter_tags = [
      "status_bar = 10",
      "extra_rows = 1"
   ]
}

4.3.1. Extra rows

Specifies how many extra rows will be added between either the bottom of the graphic, or the bottom of the status bar, and the start of the location description text (usually 1).

extra_rows = [0 .. 10]

4.3.2. Status bar

Specifies what kind of status bar to display.

status_bar = [0 .. 10]

status_bar

Description

0

No status bar (default).

1

Top left = TURNS, Top right = NOTHING

2

Top left = NOTHING, Top right = TURNS

3

Top left = GAME TITLE, Top right = LOCATION HEADER

4

Top left = GAME TITLE, Top right = TURNS

5

Top left = GAME TITLE, Top right = TREASURES

6

?????

7

Top left = LOCATION HEADER, Top right = TURNS

8

Top left = LOCATION HEADER, Top right = EXITS

9

Top left = LOCATION HEADER, Top right = GAME TITLE

10

Top-left = Heading, Top-right=Treasure count

4.4. Multiple Choice In 8-Bit Compatibility Mode

Adventuron has convenient commands for adding dynamic choices to a game. Unfortunately, DAAD does not have the same commands, but it is possible to add multiple choice handler to your game in a limited way, albeit with a little bit more code overhead.

See the following snippet for a 'game' that shows a dynamic set of choices to the player.

This snippet is 8-bit mode compatible

start_at = hut

locations {
   hut : location "You are in a hut.";

   // The location is just for displaying choices.
   // As these are all dynamic, there is no location text.
   choice_dialog_1 : location "";
}

objects {
   // The breadcrumb is used as a marker for the location to return to (at the end of choices)
   breadcrumb : object "a breadcrumb" ;
   man        : scenery "a man" start_at = "hut" ;
}


integers {
   // Used to track how many choices are available.
   // Always add a failsafe choice to return to the breadcrumb
   num_choices_displayed : integer "0" ;
}

booleans {

   display_choice_rhino : boolean "true" ;
   display_choice_aardvark : boolean "true" ;
   display_choice_sorcerer : boolean "true" ;

}

on_describe {

   // To let the 'player' how to select choices.
   // You can trigger choices however you like in your
   // own game.

   : if (is_present "man") {
      : print "Type CHOICES says the man." ;
   }

   // If at the choice dummy location 'choice_dialog_1'
   // Then show the context of the question, and the choices
   // available.

   : if (is_at "choice_dialog_1") {
      : set_integer var = "num_choices_displayed" value = "0" ;

      : print "The man says ... make your choices ...";

      : if (display_choice_rhino) {
          : increment "num_choices_displayed";
          : print "Type 'rhino' to do something.";
      }
      : if (display_choice_aardvark) {
         : increment "num_choices_displayed";
         : print "Type 'aardvark' to do something.";
      }
      : if (display_choice_sorcerer) {
          : increment "num_choices_displayed";
          : print "Type 'sorcerer' to do something.";
      }

      // Always add a failsafe choice to return to the breadcrumb
      : if (num_choices_displayed == 0) {
         : print "No more choices remain. Type 'return' to leave the choice selection dialog.";
      }
   }
}

on_command {

   : match "choices _"  {
      // Creates the breadcrumb object in the current location.
      : create "breadcrumb" ;
      : goto "choice_dialog_1" ;
      : redescribe;

   }

   // NOTE: You can't put an 'if' directly underneath 'on_command'
   //       in 8-bit compatibility mode.

   // All choices need to be placed at top level of the on_command block
   // This isn't perfect, but it is all that is available for now.
   // I'll work on local on_command handlers at location level which should tidy this up a bit.

   : match "rhino _"  {
      // Always have to duplicate the logic
      // from the choice display section (on_describe)
      : if (is_at "choice_dialog_1" && display_choice_rhino) {
         : set_false "display_choice_rhino" ; // Removes the choice dynamically
         : print "You chose rhino (rhino will no longer be a choice)." ;
         : press_any_key ;
         : gosub "return_to_breadcrumb" ;
      }
   }

   : match "aardvark _"  {
      : if (is_at "choice_dialog_1" && display_choice_aardvark) {
         : set_false "display_choice_aardvark" ; // Removes the choice dynamically
         : print "You chose aardvark (aardvark will no longer be a choice).";
         : press_any_key ;
         : gosub "return_to_breadcrumb" ;

      }
   }
   : match "sorcerer _"  {
      : if (is_at "choice_dialog_1" && display_choice_sorcerer) {
         : set_false "display_choice_sorcerer" ; // Removes the choice dynamically
         : print "You chose sorcerer (sorcerer will no longer be a choice)." ;
         : press_any_key ;
         : gosub "return_to_breadcrumb" ;
      }
   }

   : match "return _"  {
      // Always add a failsafe choice to return to the breadcrumb
      : if (is_at "choice_dialog_1" && num_choices_displayed == 0) {
         : gosub "return_to_breadcrumb";
      }
   }

}

subroutines {
   return_to_breadcrumb : subroutine {
      : goto "breadcrumb" ;
      : destroy "breadcrumb" ;
      : redescribe;
   }
}

5. Supporting Tools

5.1. PAW

PAW (or PAWS) is a text-adventuring authoring tool and engine created by Gilsoft in 1986.

PAW is an evolution of Gilsoft’s earlier tool "The Quill", written by Graeme Yeandle, with a lot of added features.

PAW supports vector graphics (Adventuron does not currently leverage the vector art format support by PAW), better compressed text, and carries forward a lot of support for coloured text formatting features / user defined graphics.

5.2. InPaws (for PAW)

Inpaws is a source code based compiler that can create .tap (virtual tape) files usable in PAW under an emulator.

Inpaws only currently runs under Windows, and only supports 48K game output at present (can’t utilize 128K mode yet). There exists an experimental tool to help use InPaws to create 128K games, but this is outside the scope of this document.

5.3. DAAD

DAAD is a text adventure engine developed by Tim Gilberts for Spanish development studio Aventuras AD in the late 1980s.

Two years ago, DAAD was placed into the public domain by the ex-owner Aventuras AD, Andrés Samudio.

DAAD was used to write commercial text adventures and contains interpreters for almost all popular 8-bit platforms and also platforms such as Amiga, MS Dos, and Atari ST. It is a very portable adventure game engine.

DAAD uses a very similar syntax to QUILL / PAW albeit with greater flexibility at the expense of greater complexity. DAAD also loses a number of features that were troublesome to span across all the target platforms. Embedding text colouring information in messages (supported by QUILL and PAW) is gone, but colours can be changes at per-message granularity.

DAAD (on Spectrum) also supported a custom font rendering routine which meant that 30% more text could fit on the screen (glyphs could be 6 x 8 instead of 8 x 8). DAAD also supported multiple gameplay windows (PAW supported vertical splits).

Text heavy games feel better on DAAD than on PAW, and DAAD is undoubtedly more flexible with the exception of granular text colouring and the lack of > 64K support (which Maluva mitigates to a large degree).

5.4. Maluva

Maluva is an extension for DAAD that adds a number of features including the streaming of messages from disk storage (for larger adventures), and the streaming of bitmap graphics from disk storage.

Maluva loads graphics in different formats for different hardware platforms based on the graphic constraints of the platform.

Maluva is developed by @UtoDev.

5.5. DAAD Reborn Compiler

DRC is short for the DAAD Reborn Compiler. This compiler will compile .DSF files (why not DRC I do not know) into the intermediary format required by DAAD. It adds a lot of nice features to the DAAD format whilst not requiring a modification to the DAAD runtime environment.

DRC is developed by @UtoDev.

5.6. DAAD Ready!

DAAD Ready! is a collection of tools (arranged by Uto Dev), that are required to build a DAAD game for the most popular DAAD platforms.

DAAD Ready! packages the DAAD interpreters, the DRC compiler, the Maluva plugins (per platform), and provides convenient build scripts for building all these platforms.

7. Licenses & Acknowledgements

7.1. Licenses

The 8-bit export feature is provided without guarantee or warranty of any kind. The author shall not be held liable for loss or failure of this software.

  • PAW is not public domain. If you plan to release commercial software with PAW, then please contact Tim Gilberts for a license.

  • Adventuron 2 PAW does NOT embed the PAW utility or the PAW runtime.
    It is down to the implementer to ensure they have a valid license to use PAW when distributing a game using the game engine.

  • DAAD binaries have been released into the public domain by Andrés Samudio.

  • You can release release commercial software running under the DAAD interpreter free of charge.

  • Maluva has its own license, which is generally speaking commercial-use friendly. Anyone distributing games compiled with DAAD Ready! should investigate the Maluva license themselves as I’m not a legal expert.

7.2. Acknowledgements

  • Thank you to Uto Dev for his assistance, and for creating the DAAD Ready ! package, which was essential in keeping the complexity of this guide to a minimum

  • Thanks to Uto Dev for the wondering DAAD Reborn Compiler, which brought DAAD compilation back to modern operating systems.

  • Thanks to Uto Dev for the wonderful Maluva plugin which added bitmap graphic support, external messages, and modern storage access to DAAD (and more!).

  • Thanks to Stefan Vogt & Tim Gilberts for recovering the English language version of DAAD .

  • Thanks to Andrés Samudio for placing DAAD into the public domain.

  • Thanks to Gareth Pitchford for his testing of earlier versions of this feature.

  • The InPaws exporter uses various fonts (including Plotter Bold) from the ZX Origins collection, authored by Damien Guard. These fonts have been marked as free for all uses including commercial,and free to redistribute, as long as the font is not redistributed in isolation.

7.3. End of Tutorial

Click here to return to the Adventuron User Guide.