Dungeon Master: Swoosh Construction Kit - A data extractor




"Oh, wow--that totally rocks!
Thanks a million. You've saved me an incredible amount of work."

Mon Ful Ir, Aug 29 2008

"So I checked out the XSLT converter and my goodness: this is an amazing piece of work!
It's fantastic that you can convert DUNGEON.DAT into XML because this info can be used by anyone now (well, anyone who knows how to use XML files).
Excellent work!"

Gambit, Feb 13 2008

"Greatstone's work looks interesting."
Paul Stevens, Feb 14, 2008

i'm gathering info enough to render complete dungeon viewport (DM snes style) in some ways: (i) using sck (swoosh construction kit) to extract viewport information. it includes decoder for "558 item", very excellent!
Kentaro, Mar 11 2007


Tutorial - sck FAQ
What is necessary to be able to extract dungeon master files?

A working Java environment.
Java 1.4 and Windows XP is the test platform.
Java 1.5 and 1.6 are also supported as well as Windows Vista/Seven.
Any system able to launch Java 1.4+ programs can potentially run the sck tool, including any unix/linux systems.

How to extract items from any dungeon master files?

java -jar sck.jar extract <file_path_to_be_extracted>

How to extract main graphics from dungeon master?

Short answer:

java -jar sck.jar extract graphics.dat

How to extract dungeon maps?

First, locate the file where is stored the dungeon.
Depending of the version of the game, the file name can be:
dungeon.dat, dungeonf.dat, dungeong.dat, dungeon.game, dungeon.bonus, etc.
Next read task "How to extract items from a dungeon.dat file?".

How to extract items from a dungeon.dat file?

Short answer:

java -jar sck.jar extract dungeon.dat

Long answer:
Java must be available as a valid command in your environnement.
you can use full paths if necessary:

<java_path>\java -jar <sck_path>\sck.jar extract <dungeon_path>\dungeon.dat

Example:

C:\Program Files\Java\jre1.6.0_03\bin\java -jar C:\Projects\sck\bin\sck.jar extract C:\DM\amiga_36\dungeon.dat

How to extract content from an animation file?

Short answer:

java -jar sck.jar extract <animation_file>

Long answer:
Java must be available as a valid command in your environnement.
you can use full paths if necessary:

<java_path>\java -jar <sck_path>\sck.jar extract <animation_path>\<animation_file>

Example:

C:\Program Files\Java\jre1.6.0_03\bin\java -jar C:\Projects\sck\bin\sck.jar extract C:\DM\amiga_36\anim.dat

How to extract content from a savegame file?

Short answer:

java -jar sck.jar extract <savegame_file>

Long answer:
Java must be available as a valid command in your environnement.
you can use full paths if necessary:

<java_path>\java -jar <sck_path>\sck.jar extract <savegame_path>\<savegame_file>

Example:

C:\Program Files\Java\jre1.6.0_03\bin\java -jar C:\Projects\sck\bin\sck.jar extract C:\CSB\amiga_utility_fr\minif.dat

What is the simplest way to extract data?

Short answer:

java -jar sck.jar

Long answer:
Use the provided GUI (graphical user interface) where all the batch commands are automatized for you.


Is sck able to deal with signed dungeon and/or compressed dungeon?

Yes. signature and compression is automatically detected and decompression is done if necessary before any extraction. The sck is also able to deal with little-endian and big-endian dungeon format.
Moreover, extracting items from the SNES rom will create a "dungeon.dat" file that can be extracted as a regular dungeon.

There is a strange error when decoding CSBWin dungeon, saying that this is not a dungeon? Is sck able to deal with encrypted CSBWin dungeon?

Well... CSBWin dungeon can be encrypted by the author and it will prevent sck to be able to decode it.
In such case, ask the author for a non-encrypted version, is possible.

Where are extracted the items?

If nothing is specified to the sck, an output directory is automatically built using the path of the source file.

Example:

java -jar sck.jar extract C:\DM\amiga_36\dungeon.dat

items will be extracted in the following directory:

C:\DM\amiga_36\dungeon.dat_out

You can also specify this output directory:

java -jar sck.jar extract -outputdir C:\tmp C:\DM\amiga_36\dungeon.dat

items will be extracted in the directory C:\tmp.

What are all the possible parameters of the "extract" command?

You can launch the extraction without any parameters to have the full list.

java -jar sck.jar extract

Here is a summary of the main parameters:

-raw: all items are extracted in their known format if any AND as raw (useful to debug, investigate, etc.
-outputdir <dir>: all items are extracted in <dir>.
-cleanoutputdir: remove all files in the outputdir before extracting items.
-map <mapfile>: the mapfile used to extract all items.
-external_resource '<id>=<path>,<map>': allow to specify external resource necessary to extract the main resource.
ex: some graphics.dat need to have palettes extracted from kaos.ftl resource to extract their own images
id = id used in the main resource mapfile
path = path of the external resource. optional if present in the same directory than the main resource and named like the id
map = path of the external resource mapfile. optional if mapfile is already known by sck or named as <path>.map
-strings <path>: allow to specify an external xml file where user friendly items descriptions are stored (currently used only to extract dungeon.dat).

How this tool knows how to extract items from a specific file?

The sck relies on "description" on each known dungeon master files.
These descriptions are stored directly inside the sck.jar archives.
To be able to pick the good "description" for a specific file, the sck computes a signature (MD5 hash code) of the file and check in its own internal repository if this signature is already associated with a description.
As the sck doesn't have all the signatures of the existing dungeon master files, you must sometimes force a specific map file yourself.
You can copy an existing description file (*.map file in the sck.jar archive) and easily force the detection of this description with your own specific dungeon master file.
You can also create or customize a new description file and use it.
to do that, you can copy it near the source file using the name of this file with the ".map" extension.

Example:

java -jar sck.jar extract C:\DM\amiga_36\dungeon.dat

it will automatically search for the description file C:\DM\amiga_36\dungeon.dat.map
You can also specify the "description" file path:
Example:

java -jar sck.jar extract -map C:\TEMP\dm.map C:\DM\amiga_36\dungeon.dat

For a customized dungeon master file, is it possible to force the sck to use a specific map file?

Yes. Use ever the "-map" parameter or copy a "<your_file_name>.map" description file in the same directory.
The content of the description file can be taken from the sck.jar archive (*.map files) with your own modifications.
You can also create a completly new description file.

How to view/play DM/CSB/DM2 animation files?

java -jar sck.jar view <file_path_to_be_viewed>

What are all the possible parameters of the "view" command?

-fs: fullscreen.
-spd : force a specific speed at the start.

How to play animation when sck says "Out of Memory" error?

It means that the animation is too big to be extracted in memory using the standard amount of memory reserved for the java heap.
You need to specify the required memory to be used. Here is a working proposal:

java -Xmx256m jar sck.jar view <file_path_to_be_viewed>

Tutorial - sck graphical user interface
Available commands

There is now a graphical interface for the sck to easily achieved items extraction from Dungeon Master resources:

java -jar sck.jar

All the following batch commands are moore or less available through this GUI.

Tutorial - sck batch commands
Available commands

The main sck command is the "extract" one, to extract items from Dungeon Master resources:

java -jar sck.jar extract <file_path_to_be_extracted>

But the sck can do more than the extraction of items.
Uncompress dungeon (if compressed :) ):

java -jar sck.jar uncompressDungeon [-outpudir <directory>] <dungeon_path>

Compress dungeon:

java -jar sck.jar compressDungeon [-outpudir <directory>] [-word <4 bits hexa; ex: 0x0008>] <dungeon_path>

Uncompress PAK Atari format:

java -jar sck.jar uncompressPak [-outpudir <directory>] <pak_path>

It is also possible to play animations files:

java -jar sck.jar view <file_path_to_be_viewed>

Tutorial - sck Extra pack batch commands
Goal

The sck Extra Pack is devoted to the transformation of data already extracted by the sck.

The sck can extract known items from original dungeon master data.
An xml file is produced and related images, sounds and texts.

Then the sck Extra Pack takes this xml and images/sounds/texts to produce a Web version: html with images as png, sounds as mp3, etc.

Example:

dungeon.dat + sck -> dungeon.xml
dungeon.xml + sck extra pack -> dungeon.html

To use the extra pack, you must know first the type of data to convert.

Dungeon maps

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\sck\extra
  @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

Now, if you want to customize the strings used to describe the items, you can add:
  @REM For Chaos Strikes Back
  set DUNGEON_STRINGS="file:///%SCKEXTRA_PATH%\dungeon\strings\csb_en.xml"
  @REM For Dungeon Master (default)
  set DUNGEON_STRINGS="file:///%SCKEXTRA_PATH%\dungeon\strings\dm_en.xml"

*.ftl files

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\sck\extra
  @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=_SWSH.FTL [Amiga program].xml
  set OUTPUT_PATH=C:\tmp\dm_extracted_data_web\dm_amiga_36
  set OUTPUT_NAME=swsh.ftl.html
@REM User customization - End
call "%SCKEXTRA_PATH%/_bat/ftl_web.bat"
@REM Script end

graphics.dat files

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\sck\extra
  @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=_graphics.dat.xml
  set OUTPUT_PATH=C:\tmp\dm_extracted_data_web\dm_amiga_36
  set OUTPUT_NAME=graphics.dat.html
@REM User customization - End
call "%SCKEXTRA_PATH%/_bat/mapfile_web.bat"
@REM Script end

"single" files

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\sck\extra
  @REM INPUT_PATH must contain the data already extracted previously by the sck
  set INPUT_PATH=C:\tmp\csb_extracted_data\csb_utilitydisk
  set OUTPUT_PATH=C:\tmp\csb_extracted_data_web\csb_utilitydisk
  set OUTPUT_NAME=sound.html
@REM User customization - End
call "%SCKEXTRA_PATH%/_bat/single_web.bat"
@REM Script end

Oracle HTC files

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\sck\extra
  @REM INPUT_PATH must contain the data already extracted previously by the sck
  set INPUT_PATH=C:\tmp\csb_extracted_data\csb_utilitydisk
  set XML_NAME=HCSB.HTC.xml
  set OUTPUT_PATH=C:\tmp\csb_extracted_data_web\csb_utilitydisk
  set OUTPUT_NAME=hcsb.htc.html
@REM User customization - End
call "%SCKEXTRA_PATH%/_bat/htc_web.bat"
@REM User customization - Begin
  set OUTPUT_NAME=hcsb.htc.all.html
@REM User customization - End
call "%SCKEXTRA_PATH%/_bat/htc_all_web.bat"
@REM Script end