Dungeon Master: Swoosh Construction Kit

Technical documentation - Dungeon in HTML

How to convert dungeon.dat to XML and HTML

The primary goal of the sck is to extract all data from DM/CSB files in user-friendly (or at least computer-friendly) formats.The first targets were images, sounds, graphics.dat, etc. files. A big challenge was remaining: the dungeon.dat format itself.
Based on the brilliant specification of the dungeon published in the Encyclopaedia web site, the sck is now able to read the dungeon.dat file.In this preliminary step, the savegame, containing a similar description of the dungeon is not yet supported.So, the dungeon can now be decoded and extracted in the more friendly/known XML format.

sck schema

It is now easier to:

compare/see differences between multiple DM releases,
see the pseudo-random decorations (some fountains and others),
see the corrections, additions done in later releases,
understand internal mecanisms, like actuators,
convert the dungeon format to you own format, with the help of XSL templates.

As usual, sck will take care of the endian mode, the compression, if any, the pseudo-random decoration items (like fountains) and consequently is able to decode all the known releases of DM/CSB, even the SNES releases as we already know where is located the dungeon.dat in the ROM. The SNES mapfiles available in the sck package itself have been updated to reflect this.
An interesting thing to do is to compare SNES maps with the other platforms: there are a lot of differences and even forgotten items in unaccessible parts of the SNES dungeon; the SNES dungeon have been copied from another platform and tweaked a lot.

To be automatically identified as a dungeon.dat format, your dungeon must be named:
* dungeon.dat, dungeonf.dat, dungeong.dat, dungeon.bonus, dungeon.game, mini.dat, minif.dat, minig.dat.

sck command example:

java -jar sck.jar extract "<path>\dungeon.dat"

Then, you will find the result in:

<path>\out_DUNGEON.DAT\0000.DUNGEON [Dungeon].xml

XML dungeon content example:

<dungeon seed="99"
         maps_data_size="12366"
         number_of_maps="14"
         unused1="0"
         texts_data_size="1749"
         start_x="1"
...
<text>WELCOME BACK
BRAVE
ADVENTURERS.</text>
    <text>TURN BACK</text>
    <text>INVOKE FUL
FOR A MAGIC
TORCH</text>
...
<door index="48"
            type="1"
            ornate="0"
            opening="Vertical"
            button="0"
            fireball="1"
            force="1"
            bits_9_15="0"/>
...
<creature index="12"
            type="16"
            number_of_creatures="2"
            position_1="3"
            position_2="2"
            hit_point_1="22"
            hit_point_2="23"
            facing="North"
...
<!-- Wall (9;0) -->
<tile index="9"
      type="0"
      has_objects="1"
      allow_decoration_east="0"
      allow_decoration_north="0"
      allow_decoration_south="0"
      allow_decoration_west="0">
  <items>
    <actuator index="553" position="2">
      <!-- Wall actuator: 10 - Double magic missile shooter -->
      <type>10</type>
      <data>0</data> <!-- missile identifier: Fireball -->
      <graphic>6</graphic> <!-- 0 = invisible -->
      <action_target>local</action_target>
      <delay>1</delay>
      <has_sound>0</has_sound>
      <has_revert>0</has_revert>
      <action_type>Set</action_type>
...

So, it is now possible to write an XSL file to convert the XML dungeon to another format.
To show the possibilities of the XML extraction, we provide also an additional download:

the sck "extra-pack"

This extra package will allow you to automatically create HTML maps of any releases of DM and CSB (tested with Firefox 2.0 and IE 6).

sckExtraPack schema

sck "extra-pack" command example:
  unzip the sckExtraPack archive
  read the README file
  Create an empty ms-dos batch file on windows (similar unix shell scripts can easily be written).
  Open this batch file and write the following lines, with your own customizations for the paths:

@REM Script beginning
@REM User customization - Begin
  set SCK_PATH=C:\tmp\sck\sck.jar
  set SCKEXTRA_PATH=C:\tmp\_sckExtraPack
  @REM INPUT_PATH must contain the data already extracted previously by the sck
  set INPUT_PATH=C:\tmp\dm_extracted_data\dm_amiga_36
  set XML_NAME=0000.DUNGEON [Dungeon].xml
  set OUTPUT_PATH=C:\tmp\dm_extracted_data_web\dm_amiga_36
@REM User customization - End
 call "%SCKEXTRA_PATH%/_bat/dungeon_web.bat"
@REM Script end

run it

The resulting Web maps are available in the "Games" section.

Here are some screenshots:
map 1

Note that these maps have been automatically generated from the original dungeon.dat files, without any manual addition.
I don't try to use custom dungeon but if they use the original FTL dungeon.dat format, it should be possible to obtain quickly a good result, with perhaps some rewrite in the "extra-pack" (images, names, xsl, css), depending of the modifications done. The goal here is to provide a way to just change names, images and/or css resources to be able to generate custom maps, without having to understand the original FTL format (compression, endian-mode, specification, etc.).

The support of DM2 is very limited, mainly because of the number of new actuators versus DM/CSB.

map 4

Credits

Christophe Fontanel, for the dungeon.dat format described on dmweb.free.fr.
Kentaro, for specific DM2 explanation.

History

1.0 (17 March 2007): initial release.