ModdingWiki - User contributions [en-gb]

Super 3-D Noah's Ark

2025-07-29T13:27:40Z

Congusbongus: Add music tables

{{Game Infobox
| Levels = Yes
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's [https://web.archive.org/web/20151003140316/www.wisdomtreegames.com/games/super3dnoahsark/ original homepage went down around 2015], but the game is still available [https://www.gog.com/en/game/super_3d_noahs_ark on GOG.com] and [https://wisdomtree.itch.io/s3dna itch.io].

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Contains sprites, textures and sounds at 11025 Hz
}}
{{EndGameFileList}}

=== Sounds ===

The following is a list of sounds in the VSWAP file

{| class="wikitable" style="margin:auto"
|-
! Index !! Notes
|-
| 0 || Antelope alert
|-
| 1 || Bear alert
|-
| 2 || Item pickup
|-
| 3 || Camel alert
|-
| 4 || Door close
|-
| 5 || Cantaloupe hit
|-
| 6 || Cantaloupe feeder shoot
|-
| 7 || Goat kick
|-
| 8 || ?
|-
| 9 || Animal falling asleep
|-
| 10 || Elephant alert
|-
| 11 || Life powerup
|-
| 12 || Super feeder shoot
|-
| 13 || Giraffe alert
|-
| 14 || Goat alert
|-
| 15 || Small feeder shoot
|-
| 16 || ?
|-
| 17 || Kangaroo alert
|-
| 18 || Level end
|-
| 19 || Hand feed
|-
| 20 || Monkey alert
|-
| 21 || Bear walk
|-
| 22 || Door open
|-
| 23 || Ostrich alert
|-
| 24 || Ox alert
|-
| 25 || Player hurt
|-
| 26 || Game over
|-
| 27 || Secret door
|-
| 28 || Sheep alert
|-
| 29 || Large feeder shoot
|-
| 30 || Animal spit
|-
| 31 || Watermelon hit
|-
| 32 || Watermelon feeder shoot
|}

=== Music ===

{| class="wikitable" style="margin:auto"
|-
! Index !! Name !! Used In
|-
| 0 || || Intro
|-
| 1 || ALLGOOD || End of game level
|-
| 2 || ||
|-
| 3 || ||
|-
| 4 || FEEDTIME || End of level
|-
| 5 || ||
|-
| 6 || || Boss levels
|-
| 7 || ||
|-
| 8 || || Menus
|-
| 9 || HAPPYSNG ||
|-
| 10 || || High scores
|}

{| class="wikitable" style="margin:auto"
|-
! Level !! Music
|-
| E1L1 || 0
|-
| E1L2 || 1
|-
| E1L3 || 6
|-
| E2L1 || 2
|-
| E2L2 || 0
|-
| E2L3 || 1
|-
| E2L4 || 6
|-
| E3L1 || 3
|-
| E3L2 || 2
|-
| E3L3 || 0
|-
| E3L4 || 6
|-
| E3L5 || 8
|-
| E4L1 || 5
|-
| E4L2 || 3
|-
| E4L3 || 1
|-
| E4L4 || 2
|-
| E4L5 || 6
|-
| E5L1 || 7
|-
| E5L2 || 0
|-
| E5L3 || 5
|-
| E5L4 || 3
|-
| E5L5 || 9
|-
| E5L6 || 6
|-
| E6L1 || 10
|-
| E6L2 || 1
|-
| E6L3 || 2
|-
| E6L4 || 7
|-
| E6L5 || 5
|-
| E6L6 || 6
|-
| End of game || 1
|}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = Read
| txt = No
| sav = No
| exe = No
| notes = Slade erroneously uses Wolf3D's sample rate of 7042Hz, instead of 11025Hz, so the sounds are too slow
}}
{{EndFileFormatTools}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

Super 3-D Noah's Ark

2025-07-28T13:13:14Z

Congusbongus: add itch link

{{Game Infobox
| Levels = Yes
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's [https://web.archive.org/web/20151003140316/www.wisdomtreegames.com/games/super3dnoahsark/ original homepage went down around 2015], but the game is still available [https://www.gog.com/en/game/super_3d_noahs_ark on GOG.com] and [https://wisdomtree.itch.io/s3dna itch.io].

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Contains sprites, textures and sounds at 11025 Hz
}}
{{EndGameFileList}}

=== Sounds ===

The following is a list of sounds in the VSWAP file

{| class="wikitable" style="margin:auto"
|-
! Index !! Notes
|-
| 0 || Antelope alert
|-
| 1 || Bear alert
|-
| 2 || Item pickup
|-
| 3 || Camel alert
|-
| 4 || Door close
|-
| 5 || Cantaloupe hit
|-
| 6 || Cantaloupe feeder shoot
|-
| 7 || Goat kick
|-
| 8 || ?
|-
| 9 || Animal falling asleep
|-
| 10 || Elephant alert
|-
| 11 || Life powerup
|-
| 12 || Super feeder shoot
|-
| 13 || Giraffe alert
|-
| 14 || Goat alert
|-
| 15 || Small feeder shoot
|-
| 16 || ?
|-
| 17 || Kangaroo alert
|-
| 18 || Level end
|-
| 19 || Hand feed
|-
| 20 || Monkey alert
|-
| 21 || Bear walk
|-
| 22 || Door open
|-
| 23 || Ostrich alert
|-
| 24 || Ox alert
|-
| 25 || Player hurt
|-
| 26 || Game over
|-
| 27 || Secret door
|-
| 28 || Sheep alert
|-
| 29 || Large feeder shoot
|-
| 30 || Animal spit
|-
| 31 || Watermelon hit
|-
| 32 || Watermelon feeder shoot
|}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = Read
| txt = No
| sav = No
| exe = No
| notes = Slade erroneously uses Wolf3D's sample rate of 7042Hz, instead of 11025Hz, so the sounds are too slow
}}
{{EndFileFormatTools}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

Crystal Caves Sound format

2025-03-09T05:56:40Z

Congusbongus: Fix order of data in info table

{{Sound Infobox
| Type = PC Speaker
| Count = 12
| NumChannels = 1
| Compressed = N
| Tags = None
| Games =
{{Game|Crystal Caves}}
}}

== Format ==

Files in [[Crystal Caves]] sound format do not contain a header or sound names, and sounds are of a fixed length. (610 bytes.)

The sounds are stored in the files <tt>CCx-y.SND</tt> (or <tt>SAMx0yE.SND</tt> for [[Secret Agent]]); 12 sounds to a file.

The sound data itself consists of an array of two-byte values each giving a tone frequency in Hertz. (Larger value, higher pitch.) with a value of -1 ending the sound. (There is one terminator at the sound play end and another at the sound data end, just to be sure.) The actual sound data takes up the first 600 bytes of the sound, the last 10 being a number of attributes as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[SINT16LE]][300] || data || Sound data (frequencies in Hertz)
|-
| [[UINT16LE]] || priority || Whether or not sound will be interrupted by another sound if said sound starts playing while the first is. Sounds can only be interrupted by sounds that have an equal or higher value of this.
|-
| [[UINT16LE]] || unknown || {{TODO|Unknown}}
|-
| [[UINT16LE]] || vibrate || A divider for the vibrate; this changes a sound's tone by periodicly switching off the PC speaker. (But at a more rapid rate than would be achieved by simply adding silences to the sound data.
|-
| [[UINT32LE]] || unknown2 || {{TODO|Unknown}}
|}

== Implementation ==

<source lang="pascal">
{Sound player for Crystal Caves and Secret Agent}
{Created by K1n9_Duk3 in January 2015, based on a partial disassembly}

program CCSASound;

uses Dos, Crt;

type
TSound = record
fData: array [1..300] of Word;
fPriority: Word;
fUnknown1: Word;
fVibrate: Word;
fUnknown2: Word;
fUnknown3: Word;
end;
TSoundFile = record
fSounds: array [1..12] of TSound;
end;
PSoundFile = ^TSoundFile;
PByte = ^Byte;

var
OldInt: Pointer;

SoundsOn, SoundIsPlaying: Boolean;
TickCount: Word;
sndIndex, sndNumberInFile, sndFileNumber: Word;
sndFiles: array [1..3] of PSoundFile;

procedure SoundService; interrupt;
begin
asm cli end;
if (SoundIsPlaying) then begin
Sound(sndFiles[sndFileNumber]^.fSounds[sndNumberInFile].fData[sndIndex]);
Inc(sndIndex);
if (sndIndex mod sndFiles[sndFileNumber]^.fSounds[sndNumberInFile].fVibrate <> 0)
then NoSound;
if (sndFiles[sndFileNumber]^.fSounds[sndNumberInFile].fData[sndIndex] = $FFFF) then begin
SoundIsPlaying := FALSE;
sndIndex := 1;
NoSound;
end;
end;
Inc(TickCount);
asm sti end;
end;

procedure PlaySound(soundNum:Word);
var oldFileNum, oldSndNumInFile:Word;
begin
oldFileNum := sndFileNumber;
oldSndNumInFile := sndNumberInFile;
if (SoundsOn) then begin
if (SoundIsPlaying) then begin
sndFileNumber := 1 + (soundNum-1) div 12;
sndNumberInFile := 1 + (soundNum-1) mod 12;
if (
sndFiles[sndFileNumber]^.fSounds[sndNumberInFile].fPriority
>=
sndFiles[oldFileNum]^.fSounds[oldSndNumInFile].fPriority
) then begin
sndIndex := 1;
SoundIsPlaying := TRUE;
end else begin
sndFileNumber := oldFileNum;
sndNumberInFile := oldSndNumInFile;
end;
end else begin
sndFileNumber := 1 + (soundNum-1) div 12;
sndIndex := 1;
SoundIsPlaying := TRUE;
sndNumberInFile := 1 + (soundNum-1) mod 12;
end;
end;
end;

procedure WaitSoundDone;
begin
while (SoundIsPlaying) do;
end;

procedure StartSoundService;
begin
SoundIsPlaying := FALSE;
GetIntVec($1c, OldInt);
SetIntVec($1c, Addr(SoundService));
asm
push bx
push ax
mov bx, 2147h
cli
mov al, 36h
out 43h, al
mov al, 0
mov al, bl
out 40h, al
mov al, bh
out 40h, al
sti
pop ax
pop bx
end;
end;

procedure StopSoundService;
begin;
SoundIsPlaying := FALSE;
SetIntVec($1c, OldInt);
asm
push ax
cli
mov al, 36h
out 43h, al
mov al, 0
out 40h, al
out 40h, al
sti
pop ax
end;
end;

var REV_TABLE: array[0..255] of byte;

procedure DecryptData(dataptr: PByte; size:Word);
const
XOR_KEY : array [0..27] of byte = ($43, $6F, $70, $79, $72, $69, $67, $68, $74, $20, $31, $39, $39, $31,
$20, $50, $65, $64, $65, $72, $20, $4A, $75, $6E, $67, $63, $6B, $00);
var
counter: byte;
i,b:Byte;
begin
if REV_TABLE[1] <> $80 then
for i:= 0 to 255 do begin
b := ((i and $0F) shl 4) or ((i and $F0) shr 4);
b := ((b and $33) shl 2) or ((b and $CC) shr 2);
b := ((b and $55) shl 1) or ((b and $AA) shr 1);
REV_TABLE[i] := b
end;
counter := 0;
while size > 0 do begin
dataptr^ := REV_TABLE[dataptr^] xor XOR_KEY[counter];
Inc(counter);
if counter = 28 then counter := 0;
Inc(dataptr);
Dec(size);
end
end;

procedure LoadSoundsSA;
var
source: file of TSoundFile;
name: string;
i: byte;
begin
name := 'SAM101E.SND';
for i := 1 to 3 do begin
sndFiles[i] := New(PSoundFile);
Assign(source, name);
Reset(source);
Read(source, sndFiles[i]^);
Close(source);
Inc(name[6]);
DecryptData(Addr(sndFiles[i]^), 7320);
end;
end;

procedure LoadSoundsCC;
var
source: file of TSoundFile;
name: string;
i: byte;
begin
name := 'CC1-1.SND';
for i := 1 to 3 do begin
sndFiles[i] := New(PSoundFile);
Assign(source, name);
Reset(source);
Read(source, sndFiles[i]^);
Close(source);
Inc(name[5]);
end;
end;

var i:Byte;
begin
LoadSoundsCC;
StartSoundService;
SoundsOn := TRUE;

for i:= 1 to 36 do begin
PlaySound(i);
writeln('Now playing sound #', i);
WaitSoundDone;
Delay(500);
end;

StopSoundService;
end.
</source>

Super 3-D Noah's Ark

2024-03-30T07:44:30Z

Congusbongus: fix some sounds

{{Game Infobox
| Levels = Yes
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's [https://web.archive.org/web/20151003140316/www.wisdomtreegames.com/games/super3dnoahsark/ original homepage went down around 2015], but the game is still available [https://www.gog.com/en/game/super_3d_noahs_ark on GOG.com].

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Contains sprites, textures and sounds at 11025 Hz
}}
{{EndGameFileList}}

=== Sounds ===

The following is a list of sounds in the VSWAP file

{| class="wikitable" style="margin:auto"
|-
! Index !! Notes
|-
| 0 || Antelope alert
|-
| 1 || Bear alert
|-
| 2 || Item pickup
|-
| 3 || Camel alert
|-
| 4 || Door close
|-
| 5 || Cantaloupe hit
|-
| 6 || Cantaloupe feeder shoot
|-
| 7 || Goat kick
|-
| 8 || ?
|-
| 9 || Animal falling asleep
|-
| 10 || Elephant alert
|-
| 11 || Life powerup
|-
| 12 || Super feeder shoot
|-
| 13 || Giraffe alert
|-
| 14 || Goat alert
|-
| 15 || Small feeder shoot
|-
| 16 || ?
|-
| 17 || Kangaroo alert
|-
| 18 || Level end
|-
| 19 || Hand feed
|-
| 20 || Monkey alert
|-
| 21 || Bear walk
|-
| 22 || Door open
|-
| 23 || Ostrich alert
|-
| 24 || Ox alert
|-
| 25 || Player hurt
|-
| 26 || Game over
|-
| 27 || Secret door
|-
| 28 || Sheep alert
|-
| 29 || Large feeder shoot
|-
| 30 || Animal spit
|-
| 31 || Watermelon hit
|-
| 32 || Watermelon feeder shoot
|}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = Read
| txt = No
| sav = No
| exe = No
| notes = Slade erroneously uses Wolf3D's sample rate of 7042Hz, instead of 11025Hz, so the sounds are too slow
}}
{{EndFileFormatTools}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

Super 3-D Noah's Ark

2024-03-29T02:23:42Z

Congusbongus: gameover sound

{{Game Infobox
| Levels = Yes
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's [https://web.archive.org/web/20151003140316/www.wisdomtreegames.com/games/super3dnoahsark/ original homepage went down around 2015], but the game is still available [https://www.gog.com/en/game/super_3d_noahs_ark on GOG.com].

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Contains sprites, textures and sounds at 11025 Hz
}}
{{EndGameFileList}}

=== Sounds ===

The following is a list of sounds in the VSWAP file

{| class="wikitable" style="margin:auto"
|-
! Index !! Notes
|-
| 0 || Antelope alert
|-
| 1 || ?
|-
| 2 || Item pickup
|-
| 3 || Camel alert
|-
| 4 || Door close
|-
| 5 || Cantaloupe hit
|-
| 6 || Cantaloupe feeder shoot
|-
| 7 || Goat kick
|-
| 8 || ?
|-
| 9 || Animal falling asleep
|-
| 10 || Elephant alert
|-
| 11 || Life powerup
|-
| 12 || Super feeder shoot
|-
| 13 || Giraffe alert
|-
| 14 || Goat alert
|-
| 15 || Small feeder shoot
|-
| 16 || ?
|-
| 17 || Kangaroo alert
|-
| 18 || Level end
|-
| 19 || Hand feed
|-
| 20 || Monkey alert
|-
| 21 || Bear alert
|-
| 22 || Door open
|-
| 23 || Ostrich alert
|-
| 24 || Ox alert
|-
| 25 || Player hurt
|-
| 26 || Game over
|-
| 27 || Secret door
|-
| 28 || Sheep alert
|-
| 29 || Large feeder shoot
|-
| 30 || Animal spit
|-
| 31 || Watermelon hit
|-
| 32 || Watermelon feeder shoot
|}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = Read
| txt = No
| sav = No
| exe = No
| notes = Slade erroneously uses Wolf3D's sample rate of 7042Hz, instead of 11025Hz, so the sounds are too slow
}}
{{EndFileFormatTools}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

Super 3-D Noah's Ark

2024-03-29T02:20:46Z

Congusbongus: /* Tools */

{{Game Infobox
| Levels = Yes
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's [https://web.archive.org/web/20151003140316/www.wisdomtreegames.com/games/super3dnoahsark/ original homepage went down around 2015], but the game is still available [https://www.gog.com/en/game/super_3d_noahs_ark on GOG.com].

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Contains sprites, textures and sounds at 11025 Hz
}}
{{EndGameFileList}}

=== Sounds ===

The following is a list of sounds in the VSWAP file

{| class="wikitable" style="margin:auto"
|-
! Index !! Notes
|-
| 0 || Antelope alert
|-
| 1 || ?
|-
| 2 || Item pickup
|-
| 3 || Camel alert
|-
| 4 || Door close
|-
| 5 || Cantaloupe hit
|-
| 6 || Cantaloupe feeder shoot
|-
| 7 || Goat kick
|-
| 8 || ?
|-
| 9 || Animal falling asleep
|-
| 10 || Elephant alert
|-
| 11 || Life powerup
|-
| 12 || Super feeder shoot
|-
| 13 || Giraffe alert
|-
| 14 || Goat alert
|-
| 15 || Small feeder shoot
|-
| 16 || ?
|-
| 17 || Kangaroo alert
|-
| 18 || Level end
|-
| 19 || Hand feed
|-
| 20 || Monkey alert
|-
| 21 || Bear alert
|-
| 22 || Door open
|-
| 23 || Ostrich alert
|-
| 24 || Ox alert
|-
| 25 || Player hurt
|-
| 26 || ?
|-
| 27 || Secret door
|-
| 28 || Sheep alert
|-
| 29 || Large feeder shoot
|-
| 30 || Animal spit
|-
| 31 || Watermelon hit
|-
| 32 || Watermelon feeder shoot
|}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = Read
| txt = No
| sav = No
| exe = No
| notes = Slade erroneously uses Wolf3D's sample rate of 7042Hz, instead of 11025Hz, so the sounds are too slow
}}
{{EndFileFormatTools}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

Super 3-D Noah's Ark

2024-03-29T02:09:49Z

Congusbongus: Add incomplete list of sounds

{{Game Infobox
| Levels = Yes
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's [https://web.archive.org/web/20151003140316/www.wisdomtreegames.com/games/super3dnoahsark/ original homepage went down around 2015], but the game is still available [https://www.gog.com/en/game/super_3d_noahs_ark on GOG.com].

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Contains sprites, textures and sounds at 11025 Hz
}}
{{EndGameFileList}}

=== Sounds ===

The following is a list of sounds in the VSWAP file

{| class="wikitable" style="margin:auto"
|-
! Index !! Notes
|-
| 0 || Antelope alert
|-
| 1 || ?
|-
| 2 || Item pickup
|-
| 3 || Camel alert
|-
| 4 || Door close
|-
| 5 || Cantaloupe hit
|-
| 6 || Cantaloupe feeder shoot
|-
| 7 || Goat kick
|-
| 8 || ?
|-
| 9 || Animal falling asleep
|-
| 10 || Elephant alert
|-
| 11 || Life powerup
|-
| 12 || Super feeder shoot
|-
| 13 || Giraffe alert
|-
| 14 || Goat alert
|-
| 15 || Small feeder shoot
|-
| 16 || ?
|-
| 17 || Kangaroo alert
|-
| 18 || Level end
|-
| 19 || Hand feed
|-
| 20 || Monkey alert
|-
| 21 || Bear alert
|-
| 22 || Door open
|-
| 23 || Ostrich alert
|-
| 24 || Ox alert
|-
| 25 || Player hurt
|-
| 26 || ?
|-
| 27 || Secret door
|-
| 28 || Sheep alert
|-
| 29 || Large feeder shoot
|-
| 30 || Animal spit
|-
| 31 || Watermelon hit
|-
| 32 || Watermelon feeder shoot
|}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = Read
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

Wolfenstein 3-D

2024-02-27T11:18:32Z

Congusbongus: add vswap file

{{Game Infobox
| Levels = Edit
| Tiles = Edit
| Sprites = Edit
| Fullscreen = Edit
| Sound = Edit
| Music = Edit
| Text = Edit
| Story = Edit
| Interface = Edit
}}

'''Wolfenstein 3-D''' is the game that brought world attention to first-person shooter games. It is considered the father of all modern 3D games.

The complete source code was released by id Software on July 21, 1995, only three years after the game's release. It can be downloaded from [ftp://ftp.idsoftware.com/idstuff/source/ id Software's FTP server]. This was the first in a long line of source-code releases by id, and paved the way for their later success by designing and selling game engines to other game developers.

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[TED5]]
| Platform = DOS
| grp = N/A
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
| notes = Editor used by id Software to create the original levels
}}
{{EndFileFormatTools}}

Many more tools can be found at [http://www.wolfenstein3d.co.uk/utilities.htm The Wolfenstein 3D Dome].
{{BeginGameFileList}}
{{GameFile
| Name = audiot.wl? audiohed.wl?
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. The game uses the uncompressed version of this format.
}}
{{GameFile
| Name = maptemp.wl? (v1.0) gamemaps.wl? (v1.1+) maphead.wl? (all versions)
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = VSWAP.WL?
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = *.exe
| Format = [[B800 Text]]
| KnownFormat = Yes
| Desc = There are a couple of text screens in the main .EXE file (including the text displayed on the screen when you quit)
}}
{{EndGameFileList}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]

Super 3-D Noah's Ark

2024-02-27T11:17:40Z

Congusbongus: Add VSWAP info

{{Game Infobox
| Levels = No
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's [https://web.archive.org/web/20151003140316/www.wisdomtreegames.com/games/super3dnoahsark/ original homepage went down around 2015], but the game is still available [https://www.gog.com/en/game/super_3d_noahs_ark on GOG.com].

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = Wolf3D VSWAP file
| KnownFormat = Yes
| Desc = Contains sprites, textures and sounds at 11025 Hz
}}
{{EndGameFileList}}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

Crystal Caves

2024-01-27T09:34:47Z

Congusbongus: Add note about MNI file trailing junk

{{Game Infobox
| Levels = Edit
| Tiles = Edit
| Sprites = Edit
| Fullscreen = Edit
| Sound = No
| Music = None
| Text = No
| Story = No
| Interface = No
}}

'''Crystal Caves''' is a platform game often noted for the smoothness of the game creature animations, due to the programmer deciding to use more animation frames than was typical at the time.

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| grp = N/A
| map = Edit
| gfx = Edit
| mus = N/A
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://sfprod.shikadi.net/old/games/crystalcaves.htm#tile_modifier CCmod]
| Platform = DOS
| grp = N/A
| map = No
| gfx = Edit
| mus = N/A
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

{{BeginGameFileList}}
{{GameFile
| Name = *.apg *.cdt *.end *.ttl
| Format = [[PCX Format]]
| KnownFormat = Yes
| Desc = 320×200 16-colour full screen images
}}
{{GameFile
| Name = *.gfx
| Format = [[ProGraphx Toolbox tileset format]]
| KnownFormat = Yes
| Desc = 16×16 16-colour sprites. The registered version contains three gfx files but they are identical.
}}
{{GameFile
| Name = *.mni
| Format = [[ProGraphx Toolbox tileset format]]
| KnownFormat = Yes
| Desc = 8×8 16-colour sprites, like the characters and icons on the status bar. Not to be confused with the MNI files from [[Cosmo's Cosmic Adventures]]. Note that the files contain a single 50-sprite chunk; there is junk trailing data after this chunk.
}}
{{GameFile
| Name = *.snd
| Format = [[Crystal Caves Sound format]]
| KnownFormat = Yes
| Desc = PC speaker sound effects (a modified form of [[Inverse Frequency Sound format]])
}}
{{GameFile
| Name = cc?.exe
| Format = [[Crystal Caves Map Format]]
| KnownFormat = Yes
| Desc = Game levels are stored inside the main game .exe
}}
{{EndGameFileList}}

== Trivia ==

* Episode 1, level 16 is made up primarily of green pipes. Two join types (left/right/top and left/open-down) were drawn and have usable level codes, however they were not used in the game.

[[Category:Apogee]]
[[Category:Sidescroller]]

PCX Format

2023-10-12T06:57:34Z

Congusbongus: /* Tools */ Add SDL_image

{{Image Infobox
| Hardware1 = CGA
| Hardware2 = EGA
| Hardware3 = VGA
| Depth = Multiple
| MinSize = 0×0
| MaxSize = 65536×65536 
| Palette = Internal (optional)
| NumPlanes = 1-255
| HasTransparency = No
| HasHitmap = No

| Games =
{{Game|Bubble Bobble featuring Rainbow Islands}}
{{Game|Command & Conquer}} (Win95 version only)
{{Game|Command & Conquer: Red Alert}}
{{Game|Crystal Caves}}
{{Game|F1 Manager Professional}}
{{Game|Halloween Harry}}
{{Game|Hocus Pocus}}
{{Game|Hugo's House of Horrors}}
{{Game|Hugo II, Whodunit?}}
{{Game|Hugo III, Jungle of Doom!}}
{{Game|Math Rescue}}
{{Game|The Oregon Trail}}
{{Game|Wacky Wheels}}
{{Game|Word Rescue}}
}}
The [[PCX Format]] is an image format used by many games, usually to store full screen (320x200) 16-colour EGA, and later 256-colour VGA (mode 13h), graphics. It was, for a time, also a general picture format like .bmp or .png, and was the primary format used by PC Paintbrush. It declined in popularity after support for 24-bit true colour images was added too late, by which time many people had switched to competing formats like .png and JPEG (the latter offering far better compression for photos.) It also lacks support for transparency, which resulted in it losing some ground to the GIF format which otherwise provided a similar feature set.

== Header ==

The PCX file is composed of two parts, the header and the image data, which is usually compressed. The header is as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT8]] || Manufacturer || Always 0x0A
|-
| [[UINT8]] || Version || PC Paintbrush version. Acts as file format version. 0 = v2.5 2 = v2.8 with palette 3 = v2.8 without palette 4 = Paintbrush for Windows 5 = v3.0 or higher
|-
| [[UINT8]] || Encoding || Should be 0x01 0 = uncompressed image (not officially allowed, but some software supports it) 1 = PCX run length encoding
|-
| [[UINT8]] || BitsPerPlane || Number of bits per pixel in each entry of the colour planes (1, 2, 4, 8, 24)
|-
| [[UINT16LE]] || WindowXmin ||rowspan=4| Window (image dimensions): ImageWidth = <tt>Xmax - Xmin + 1</tt> ImageHeight = <tt>Ymax - Ymin + 1</tt> Normally <tt>Xmin</tt> and <tt>Ymin</tt> should be set to zero. Note that these field values are valid rows and columns, which is why you have to add one to get the actual dimension (so a 200 pixel high image would have Ymin=0 and Ymax=199, or Ymin=100 and Ymax=299, etc.)
|-
| [[UINT16LE]] || WindowYmin
|-
| [[UINT16LE]] || WindowXmax
|-
| [[UINT16LE]] || WindowYmax
|-
| [[UINT16LE]] || VertDPI ||rowspan=2| This is supposed to specify the image's vertical and horizontal resolution in DPI (dots per inch), but it is rarely reliable. It often contains the image dimensions, or nothing at all.
|-
| [[UINT16LE]] || HorzDPI
|-
| [[UINT8]] || Palette[48] || Palette for 16 colors or less, in three-byte RGB entries. Padded with 0x00 to 48 bytes in total length. See below for more details on palette handling.
|-
| [[UINT8]] || Reserved || Should be set to 0, but can sometimes contain junk.
|-
| [[UINT8]] || ColorPlanes || Number of colour planes. Multiply by <tt>BitsPerPlane</tt> to get the actual colour depth.
|-
| [[UINT16LE]] || BytesPerPlaneLine || Number of bytes to read for a single plane's scanline, i.e. at least <tt>ImageWidth</tt> ÷ 8 bits per byte × <tt>BitsPerPlane</tt>. Must be an even number. Do '''not''' calculate from Xmax-Xmin. Normally a multiple of the machine's native word length (2 or 4)
|-
| [[UINT16LE]] || PaletteInfo || How to interpret palette: 1 = Color/BW 2 = Grayscale (ignored in PC Paintbrush IV and later)
|-
| [[UINT16LE]] || HorScrSize ||rowspan=2| Only supported by PC Paintbrush IV or higher; deals with scrolling. Best to just ignore it.
|-
| [[UINT16LE]] || VerScrSize
|-
| [[BYTE]][54] || Padding || Filler to bring header up to 128 bytes total. Can contain junk.
|}

== Image Data ==

Image data comes after the header (starting at offset 0x80 in a PCX file), and will be RLE compressed if the header indicated so. The way the data is stored depends on how many colour planes are specified. Each row has its color planes stored sequentially, similar to [[raw EGA data]].

For one plane of eight bits (256-colour), each byte will represent one pixel. For one plane of four bits (16-colour), each byte will represent two pixels. The bits within the byte are in big-endian order, so the most significant bit belongs to the left-most pixel. In other words, in two bits per pixel mode, a byte of value 0xE4 (binary 11 10 01 00) will have left-to-right pixel values of 3, 2, 1, 0.

EGA 16-colour images are often stored with four colour planes instead of one, with each plane being one-bit-per-pixel (think of four black and white images, one each for red, green, blue and intensity.) The planes are stored sequentially for each line (see [[Raw EGA data#Row-planar EGA data|Row-planar EGA data]] for the exact details), thus a 320x200 EGA image will store at least 40 bytes for each scanline's colour plane (320 pixels ÷ 8 bits per byte × 1 bit per pixel), with each scanline being at least 160 bytes long (320 pixels ÷ 8 bits per byte × 1 bit per pixel × 4 planes). Note that the scanline length can be larger than expected (40 bytes in this example), especially for images whose width is not a multiple of four. This is because each scanline in a plane is padded to a multiple of two or four bytes, depending on the architecture of the machine used to create the file. The actual size is stored in the <tt>BytesPerPlaneLine</tt> field in the header, which should always be used instead of calculating the value from the other image attributes.

True colour PCX files are not common, and could be either three planes (R, G and B) of eight bits each (24-bit RGB) or one plane of 24-bits. Technically, the same is applicable for alpha-capable 32-bit images (with four planes in planar mode), though no official format specs ever included such a thing.

The split into planes is generally governed by what is most convenient for the game at the time, which in turn depends on which video mode is being used to display the image. Since EGA video memory is split into planes, 16-colour PCX files are frequently split into matching planes so that no processing is required when loading an image directly into video memory.

=== RLE Compression ===

The PCX format uses a form of [[RLE Compression]] that is rather unique. It compresses on the byte level and uses a flag system, where the flag is the two highest bits of a byte. If this flag is set (i.e. the two upper bits are set, or in other words the value is >= 192) then the lower six bits are the number of times to repeat the following byte.

Thus, for a byte pair <tt>C7 28</tt>, the 0xC7 can be decomposed into the flag value 192 (128 + 64) plus 7, meaning the full byte pair means '7 bytes of 0x28'. So to get the amount, you subtract 192 from the flag, or, using faster logic operations, you can do <code>byte & 0x3F</code> to retain only the lowest six bits.

This means that the six-bit length values have a maximum of 63. It also means that any value larger than 191 ''must'' be stored as a length/value pair, which can actually ''increase'' the size of the file in some cases. For instance, if you have a single byte of color 192, then it must be represented by two bytes - one of 193 (C1, a repeat of one time) followed by one of 192 (C0, color byte 192).

It is also worth noting that the byte value C0 does not have a clearly defined effect. Depending on the implementation in the decoding program, this could do any of the following:

* treat <tt>C0</tt> as a literal byte.
* ignore <tt>C0</tt> and continue with the following byte.
* 'repeat the following byte zero times', effectively ignoring any byte following <tt>C0</tt>. This could conceivably be used to embed non-image data in the PCX file which would be ignored by any program displaying the image.
* 'repeat the following byte 65536 times', which is basically a bugged implementation using a "<tt>while (--count != 0)</tt>" style loop with a 16 bit variable/CPU register.

At any rate, the best way to handle a <tt>C0</tt> when encoding (compressing) is to write the sequence <tt>C1 C0</tt>. When decoding (decompressing), a value of <tt>C0</tt> almost always indicates an error in the file.

Note that each scanline is compressed independently - an RLE sequence may span multiple planes, but it will never span more than one row of pixels. Thus when decompressing an image, the RLE algorithm will produce at most <tt>BytesPerPlaneLine</tt> bytes at a time. Even where the RLE coding could have continued over to the next scanline, it will stop and start again fresh for each line.<ref>[http://www.drdobbs.com/pcx-graphics/184402396#01ED_0105 PCX Graphics | Dr Dobb's]</ref> For example, if the input image is 8×4 pixels EGA 16-colour, and the first two lines of pixels are black (color 0) and the last two are white (color 15), they must be compressed as <tt>C4 00 | C4 00 | C4 FF | C4 FF</tt> and not as <tt>C8 00 | C8 FF</tt>.

=== Palettes ===

Most of the game's supported formats are indexed, and thus require a colour palette. There are, however, three distinct ways of handling those palettes; CGA, EGA and VGA. For images with 16 colours or less, the palette is stored in the header. For images with more colours (i.e. 256-colour images) the header palette is ignored, and the 768-byte palette is stored after the image data. Some sources seem to indicate that there are formats where even the smaller palettes are added behind the image, so it is best to always check for it there. To determine if this is the case, check if the decompressed image data is followed by a <tt>0C</tt> byte, and if there is enough data left in the file behind that for the palette data.

As a general rule, the palettes are lists of 3-byte blocks. These blocks normally contain 8-bit RGB data, but even if they are used differently (as is the case for CGA palettes), they will still retain the 3-byte block structure.

It is difficult to correctly determine the palette for 1-bit and 2-bit images, since they can be stored either as CGA or as EGA, and there is no real way to identify which method to use. Some sources suggest checking for 640x200 dimensions on 1-bit images, or 320x200 on 2-bit, since those are standard CGA sizes for respectively its monochrome and 4-colour mode, but 320x200 is a very common size for non-CGA images as well, and there has most likely never been anything preventing people on CGA hardware from saving PCX images in different sizes than a full screen. It is also suggested, for two bit per pixel images, that those with a single 2-bit plane would use a CGA palette, while those with two 1-bit planes would use EGA<ref>[http://www.fysnet.net/pcxfile.htm PCX graphics files explained] - section "Interpretation of the PCX data"</ref>. All of this makes fully automatic identification for these image types very difficult.

==== CGA palette ====

CGA palette handling is a bit peculiar. As with other colour palettes, the data is seen as blocks of three bytes. However, in CGA mode, these blocks do not contain normal RGB colour data.

The first triplet contains a specifically-defined colour. Only the highest four bits of the first byte are used, meaning the actual colour value can be found by taking that byte and shifting it four bits to the right. The result is a value from 0..15, which matches [[EGA Palette|one of the standard CGA/EGA text-mode colours]].

For monochrome CGA images, this colour is put on index 1 on the palette, and index 0 is filled in with black (EGA palette entry #0).

For actual 4-colour palettes, this colour becomes the background colour at index 0. The other colours are determined by three status bits fed into the CGA hardware; <tt>ColorBurst</tt>, <tt>Palette</tt> and <tt>Intensity</tt>. For the full explanation on which colours this produces, see the [[CGA Palette]] article.

However, the way these three bits are determined changed in PC Paintbrush version IV, and this change is not reflected in a change in the <tt>Version</tt> value in the header. The only decent way to distinguish the files from before and after version IV is to check the <tt>PaletteInfo</tt> byte in the header, which is 0 on files using the old method, and filled in (with 1 or 2) on files using the new method.

===== Older method =====

In the original way the status bits were saved, the second palette entry's first byte (byte 3) contains the three status bits.<ref name="fileformat">[https://www.fileformat.info/format/pcx/egff.htm PCX specs on fileformat.info]</ref> They can be extracted by taking the highest three bits of that byte.

* Bit 8 (<tt>10000000</tt>) is <tt>ColorBurst</tt>.
* Bit 7 (<tt>01000000</tt>) is the <tt>Palette</tt>.
* Bit 6 (<tt>00100000</tt>) is the <tt>Intensity</tt>.

===== Newer method =====

For the newer files, with the <tt>PaletteInfo</tt> byte filled in, the following<ref>[https://github.com/samuel/go-pcx/blob/d9c017170db4e016377181263f7e4cbb6bf1d8cc/pcx/decoder.go#L299 PCX image encoder and decoder for Go] - ''PC Paintbush 4.0 encodes the CGA palettes differently than 3.0.''</ref><ref>[https://github.com/wjaguar/mtPaint/blob/3884b6d6ebc18511df7bf1485a19fe774dd61dcf/src/png.c#L5416 Mark Tyler's Painting Program] - ''CGA palette is evil: what the PCX spec describes is the way it was handled by PC Paintbrush 3.0, while 4.0 was using an entirely different, undocumented encoding for palette selection.''</ref> should be done to determine the palette:

* Take the green and blue values of the second palette entry. These are the bytes at index 4 and 5 in the palette data.
* If the green value is strictly-greater than the blue value, take Palette 0, otherwise take Palette 1.
* If the largest of these two values is greater than 200, the Intensity bit is enabled.

The new method seemed to have been intended to convert a fully-saved colour palette back to CGA status bits. Sadly, it seems people figured out exactly what it checked, and started writing PCX files which contained only exactly enough data to derive those bits instead of saving an actual full palette.

As a side effect of this, there is no real check for the color burst, meaning it is always considered to be enabled, and there is no support for palette 2. If an actual palette is saved in the file, such support ''could'' be added. A viable check for detecting palette 2 (meaning, a disabled colour burst bit) would be that the original logic matches palette 1, and the third entry's red value is greater than its blue value.

==== EGA palette ====

EGA images are those with eight or sixteen colours. Typically, they have <tt>BitsPerPlane</tt> set to 1 and <tt>ColorPlanes</tt> set to 3 or 4, though variations like two 2-bit planes or one 4-bit plane are possible as well. For these images, there are two ways of handling the colours:

* If the version in the header is 0 or 3, then the [[EGA Palette|standard EGA palette]] is used, since version 0 does not support a modified palette, and version 3 specifically indicates that no palette information is present in the file.<ref name="fileformat" />
* In any other version, the palette is read from the header. The data is structured the same way as [[VGA Palette#The_.22Modern.22_format|8-bit VGA palettes]], except that it's less long.

Most EGA images will be 4 bits per pixel, meaning the palette will be 16 colours long, but 3 bit per pixel planar format is supported as well. In that case, only 8 entries are read, or if it uses the default EGA palette, only the darker first eight colours will be available. 2 bit per pixel images could use EGA palette handling as well, but these are hard to distinguish from the CGA ones.

Note that technically, EGA images are limited to 2 bit colour components, meaning every component would need to be rounded to the nearest multiple of <tt>0x55</tt>, though, practically, there is little reason to not let the images retain the more accurate colours as they are specified in the palette.

==== VGA palette ====

For 8-bit images, the 256-colour palette can be found behind the image data. It is a [[VGA Palette#The_.22Modern.22_format|standard VGA palette in 8-bit RGB format]]. A single signature byte of <tt>0C</tt> is included before the palette data begins.

Some PCX readers simplify the start offset of the 256-colour palette to <code>EndOfFile - 768</code>, though technically, the correct way to find it is to take the offset you end up at after decompressing the image, checking for the <tt>0C</tt> byte after that, and then reading the 768-byte palette.

== Source Code ==

=== ASM ===

<syntaxhighlight lang="asm">
EXTERN kbdin, dosxit ; LIB291 functions

SEGMENT ScratchSeg
ScratchPad resb 65535

SEGMENT stkseg STACK
resb 64*8
stacktop:
resb 0

SEGMENT code

PCX1 db 'my_pcx1.pcx', 0 ; Filenames
PCX2 db 'my_pcx2.pcx', 0 ; (Must end with 0 byte)

..start:
mov ax, cs ; Set up data and stack segments
mov ds, ax
mov ax, stkseg
mov ss, ax
mov sp, stacktop

MAIN:
; Sets up mode 13h and clears screen
mov ax, 0013h
int 10h

mov dx, pcx1 ; Filename to display
call ShowPCX ; Display PCX file to screen

; Wait for keypress
call kbdin

; Go back to text mode
mov ax, 0003h
int 10h

; Return to DOS
call dosxit

;-----------------------------------------------------------------------------
; ShowPCX procedure by Brandon Long,
; modified by Eric Meidel and Nathan Jachimiec,
; converted to NASM, cleaned up, and better commented by Peter Johnson
; Inputs: DX has the offset of PCX filename to show.
; Output: PCX file displayed (all registers unchanged)
; Notes: Assumes PCX file is 320x200x256.
; Uses ScratchSeg for temporary storage.
; The PCX file must be in the same directory as this executable.
;-----------------------------------------------------------------------------
ShowPCX
push ax ; Save registers
push bx
push cx
push si
push di
push es

mov ax, 3D00h
int 21h ; Open file
jc .error ; Exit if open failed

mov bx, ax ; File handle
mov cx, 65535 ; Number of bytes to read
mov ax, ScratchSeg ; DS:DX -> buffer for data
mov ds, ax
mov dx, ScratchPad
mov si, dx
mov ah, 3Fh
int 21h ; Read from file

mov ax, 0A000h ; Start writing to upper-left corner
mov es, ax ; of graphics display
xor di, di

add si, 128 ; Skip header information

xor ch, ch ; Clear high part of CX for string copies

.nextbyte:
mov cl, [si] ; Get next byte
cmp cl, 0C0h ; Is it a length byte?
jb .normal ; No, just copy it
and cl, 3Fh ; Strip upper two bits from length byte
inc si ; Advance to next byte - color byte
lodsb ; Get color byte into AL from [SI]
rep stosb ; Store to [ES:DI] and inc DI, CX times
jmp short .tst

.normal:
movsb ; Copy color value from [SI] to [ES:DI]

.tst:
cmp di, 320*200 ; End of file? (written 320x200 bytes)
jb .nextbyte

mov cl, [si]
cmp cl, 0Ch ; Palette available?
jne .close

; Set palette using port I/O
mov dx, 3C8h
mov al, 0
out dx, al
inc dx ; Port 3C9h
mov cx, 256*3 ; Copy 256 entries, 3 bytes (RGB) apiece
inc si ; Skip past padding byte

.palette:
lodsb
shr al, 1 ; PCX stores color values as 0-255
shr al, 1 ; but VGA DAC is only 0-63
out dx, al
dec cx
jnz .palette

.close:
mov ah, 3Eh
int 21h ; Close file

.error:
pop es ; Restore registers
pop di
pop si
pop cx
pop bx
pop ax
ret
</syntaxhighlight>

== Tools ==

PCX files can be read, and occasionally converted by several programs, notably, the Microsoft Photo Editor included in Windows XP can do so.

{{BeginFileFormatTools|Type=image}}
{{FileFormatTool
| Name = [http://www.xnview.com XnView]
| Platform = Windows/MacOSX/Linux
| canView = Yes
| canExport = Yes
| canImport = Yes
| editHidden = N/A
| editMetadata = N/A
| notes = Freeware for private non-commercial or educational use.
}}
{{FileFormatTool
| Name = [http://www.imagemagick.com ImageMagick]
| Platform = Cross-platform
| canView = Yes
| canExport = Yes
| canImport = Yes
| editHidden = N/A
| editMetadata = N/A
| notes = Is unable to correctly write 16-colour PCX files.
}}
{{FileFormatTool
| Name = [http://www.gimp.org GNU Image Manipulation Program]
| Platform = Cross-platform
| canView = Yes
| canExport = Yes
| canImport = Yes
| editHidden = N/A
| editMetadata = N/A
| notes = Does not handle CGA or default-palette EGA images correctly.
}}
{{FileFormatTool
| Name = [[Engie File Converter]]
| Platform = Windows
| canView = Yes
| canExport = Yes
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Relies on common image dimensions for CGA detection. No save functionality so far.
}}
{{FileFormatTool
| Name = [https://github.com/libsdl-org/SDL_image SDL_image]
| Platform = Cross-platform
| canView = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes =
}}
{{EndFileFormatTools}}

== Useful links ==

* [http://bespin.org/~qz/pc-gpe/pcx.txt Official PCX documentation]
* [http://web.archive.org/web/20030111010058/http://www.nist.fss.ru/hr/doc/spec/pcx.htm Official PCX documentation in HTML (archived version)]
* [http://www.fileformat.info/format/pcx/egff.htm PCX at the File Format Encyclopaedia] - very detailed
* [http://fileformats.archiveteam.org/wiki/PCX PCX on the 'Just Solve the File Format Problem' wiki] - includes useful sample files.

== References ==
<references/>

Crystal Caves

2023-08-04T10:22:44Z

Congusbongus:

{{Game Infobox
| Levels = Edit
| Tiles = Edit
| Sprites = Edit
| Fullscreen = Edit
| Sound = No
| Music = None
| Text = No
| Story = No
| Interface = No
}}

[[Crystal Caves]] is a platform game often noted for the smoothness of the game creature animations, due to the programmer deciding to use more animation frames than was typical at the time.

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| grp = N/A
| map = Edit
| gfx = Edit
| mus = N/A
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://sfprod.shikadi.net/old/games/crystalcaves.htm#tile_modifier CCmod]
| Platform = DOS
| grp = N/A
| map = No
| gfx = Edit
| mus = N/A
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

{{BeginGameFileList}}
{{GameFile
| Name = *.apg *.cdt *.end *.ttl
| Format = [[PCX Format]]
| KnownFormat = Yes
| Desc = 320×200 16-colour full screen images
}}
{{GameFile
| Name = *.gfx
| Format = [[ProGraphx Toolbox tileset format]]
| KnownFormat = Yes
| Desc = 16×16 16-colour sprites. The registered version contains three gfx files but they are identical.
}}
{{GameFile
| Name = *.mni
| Format = [[ProGraphx Toolbox tileset format]]
| KnownFormat = Yes
| Desc = 8×8 16-colour sprites, like the characters and icons on the status bar. Not to be confused with the MNI files from [[Cosmo's Cosmic Adventures]]
}}
{{GameFile
| Name = *.snd
| Format = [[Crystal Caves Sound format]]
| KnownFormat = Yes
| Desc = PC speaker sound effects (a modified form of [[Inverse Frequency Sound format]])
}}
{{GameFile
| Name = cc?.exe
| Format = [[Crystal Caves Map Format]]
| KnownFormat = Yes
| Desc = Game levels are stored inside the main game .exe
}}
{{EndGameFileList}}

== Trivia ==

* Episode 1, level 16 is made up primarily of green pipes. Two join types (left/right/top and left/open-down) were drawn and have usable level codes, however they were not used in the game.

[[Category:Apogee]]
[[Category:Sidescroller]]

Super 3-D Noah's Ark

2023-03-02T06:04:42Z

Congusbongus: Add file formats and tools

{{Game Infobox
| Levels = No
| Tiles = No
| Sprites = No
| Fullscreen = No
| Sound = No
| Music = No
| Text = No
| Story = No
| Interface = No
}}

This is the PC version of the game '''Super 3D Noah's Ark''' by Wisdom Tree Games. It uses a modified (licensed) version of the [[Wolfenstein 3-D]] engine, with added support for textured floors and ceilings. Super 3D Noah's Ark's homepage is at [http://www.wisdomtreegames.com/games/super3dnoahsark/ http://www.wisdomtreegames.com/games/super3dnoahsark/], where it is still for sale.

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [http://hwolf3d.dugtrio17.com/index.php?section=hwe Havoc's Wolf3D Editor]
| Platform = Windows
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = No
| gfx = Edit
| mus = Edit
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

== File formats ==

As the game uses a licensed version of the [[Wolfenstein 3-D]] engine, it shares many of the same file formats, although some have been enhanced.

{{BeginGameFileList}}
{{GameFile
| Name = audiot.n3d audiohed.n3d
| Format = [[AudioT Format]], [[IMF Format]]
| KnownFormat = Yes
| Desc = Archive storing sound effects and music. Note however the files are empty, as the game stores Ogg Vorbis music in a WAD file
}}
{{GameFile
| Name = maphead.n3d
| Format = [[GameMaps Format]]
| KnownFormat = Yes
| Desc = Levels
}}
{{GameFile
| Name = noah3d.pk3
| Format = PK3 file (ZIP)
| KnownFormat = Yes
| Desc = Contains mainly formatted text files of actor parameters, level parameters, strings and quiz questions.
}}
{{GameFile
| Name = noah3d.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive containing Ogg Vorbis music files
}}
{{GameFile
| Name = vswap.n3d
| Format = ?
| KnownFormat = Yes
| Desc = Contains sprites and textures
}}
{{EndGameFileList}}

[[Category:Apogee]]
[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Wolfenstein 3-D]]

GameMaps Format

2023-02-25T10:16:52Z

Congusbongus: add header for noah's ark

{{Map Infobox
| Type = 2D tile-based
| Layers = 3
| Viewport = ''Varies by game''
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Catacomb Abyss}}
{{Game|Commander Keen Dreams}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Dangerous Dave 3}}
{{Game|Dangerous Dave 4}}
{{Game|Super 3-D Noah's Ark}}
{{Game|Operation Body Count}}
{{Game|Rescue Rover 2}}
{{Game|Spear of Destiny}}
{{Game|Wolfenstein 3-D}}
}}

The '''GameMaps Format''' stores levels in a number of [[:Category:id Software]] games. The filenames and compression varies somewhat across different games but all files stored in this format were produced by the [[TED5]] level editor.

There are three main varieties of the file format. The most basic version is just [[RLEW compression|RLEW compressed]], the other two are either [[Carmack compression|carmackized]] or [[Huffman Compression|Huffman compressed]] on top of the RLEW compression. Each variation has its own file naming scheme and pattern of external/internal files.

There are two main components to the format. The game maps proper, which contain the actual level data, and the map headers, which contain both the location of each level's data within the game maps file, and the tile info for the game.

== Variants ==

{|class="wikitable"
! Game !! RLEW !! Carmackization !! Huffman !! Head || Gamemaps || Notes
|-
| Bio Menace || Yes || No || No || maphead.bm[123] || maptemp.bm[123] || gamemaps.bm[123] and mapthead.bm[123] are present but not used
|-
| Blake Stone: Aliens of Gold || Yes || No || No || maphead.bs[16] || maptemp.bs[16] ||
|-
| Blake Stone: Planet Strike || Yes || No || No || maphead.vsi || maptemp.vsi ||
|-
| Catacomb 3-D || Yes || Yes || No || Inside .exe || gamemaps.c3d ||
|-
| Catacomb Abyss || Yes || Yes || No || Inside .exe || gamemaps.abs ||
|-
| Catacomb Apocalypse || Yes || Yes || No || Inside .exe || gamemaps.apc ||
|-
| Catacomb Armageddon || Yes || Yes || No || Inside .exe || gamemaps.arm ||
|-
| Commander Keen Dreams || Yes || No || Yes || Inside .exe || gamemaps.kdr (v1.00), kdreams.map (v1.01+) ||
|-
| Commander Keen 4-6 || Yes || Yes || No || Inside .exe || gamemaps.ck[456] ||
|-
| Corridor 7 Alien Invasion || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Dangerous Dave 3 || Yes || No || Yes || Inside .exe || gamemaps.dav ||
|-
| Dangerous Dave 4 || Yes || No || Yes || Inside .exe || gamemaps.dav ||
|-
| Super 3-D Noah's Ark || Yes || Yes || No || maphead.n3d || gamemaps.n3d ||
|-
| Operation Body Count || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Rescue Rover 2 || Yes || Yes || No || Inside .exe || gamemaps.rr2 ||
|-
| Spear of Destiny || Yes || Yes || No || maphead.sod || gamemaps.sod ||
|-
| Wolfenstein 3-D (v1.0) || Yes || No || No || maphead.wl1 || maptemp.wl1 ||
|-
| Wolfenstein 3-D (v1.1 and above)|| Yes || Yes || No || maphead.wl[16] || gamemaps.wl[16] ||
|}

The games that use Huffman compression will have a MAPDICT (embedded in the game's main executable). Those missing the map dictionary are not Huffman encoded.

To work out whether Carmackization is used, read the first UINT16LE in a map plane (the field storing the decompressed size). If the value matches the expected size of the plane (i.e. width * height * 2), then only RLEW compression is used. If it doesn't match, check the second UINT16LE in the file (which will become the first UINT16LE once Carmackization has been removed). If this matches the expected plane size then the plane must first have Carmackization removed followed by removal of RLEW. The exception to this rule are plane sizes that have either 0xA7 or 0xA8 as the high byte (i.e. any value from 0xA700 to 0xA8FF), as those values would have been encoded differently by the [[Carmack compression]] algorithm.

== Data structures==

The map data is split into two files: The map header (<tt>MAPHEAD.xxx</tt>) and the main map file (usually <tt>MAPTEMP.xxx</tt> or <tt>GAMEMAPS.xxx</tt>). The map header may be embedded in the game's main executable.

<tt>MAPTEMP.xxx</tt> is the working format saved by [[TED5]] when maps are being edited and can be directly accessed and edited by this utility, allowing changes to be made to the game. Note that if the MAPHEAD file exists as an external file, the game always reads it from a file named named <tt>MAPHEAD.xxx</tt> for both the <tt>GAMEMAPS.xxx</tt> and the <tt>MAPTEMP.xxx</tt> variation. TED5 also saves a <tt>MAPTHEAD.xx</tt> file when editing maps, but that file is only used by TED5 and usually omitted from any game release.

The maps were often compressed even further for the public release versions of the games. This more compressed version of the map file was saved as <tt>GAMEMAPS.xxx</tt> by TED5. Later releases would omit the additional compression layer and ship with the <tt>MAPTEMP.xxx</tt> file instead. One possible reason for this could be that the size of the games grew to the point where they would no longer fit onto and be playable from a single floppy disk, and therefore the additional compression was no longer worth the amount of time it took to compress the maps and re-compile the code.

=== Map headers (MAPHEAD) ===

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[UINT16LE]] || magic || Magic word signalling [[RLEW compression]]
|-
| 2 || [[INT32LE]][100] || ptr || 100 pointers to start of level 0-99 data in the game maps file
|-
| 402 || {{TODO|Unknown}} || tileinfo || Optional tileinfo data
|}

The map header file (MAPHEAD) is of varying length and contains three main types of data.

* The first is the magic word or flag used for RLEW compression, which is almost always $ABCD in the original files. It could be changed to any other value if necessary.

* The second is 100 level pointers which give the location of the start of level data in the GAMEMAPS file, relative to the start of that file. A value less than 1 indicates no level (generally 0, but occasionally -1 (0xFFFFFFFF) is used). Using -1 should be preferred over 0, as the pre-Wolf3D version of the engine will treat any negative value as "a non existant map" [sic!] and quit with an appropriate error message, while 0 will cause it to try reading a level header at offset 0 (where the "TED5v1.0" string is usually stored), which will cause all kinds of errors as there is clearly no valid level header at that offset.

* The third is the tileinfo data, which contains tile properties for each tile used in level creation. (These are masked and unmasked and either 8x8, 16x16 or 32x32.)

Many programs treat the tileinfo as a separate file from the MAPHEAD and it is possible to modify a game in this manner. Indeed, some games such as Wolfenstein 3-D do not have any tileinfo data at all in the map header file (giving a total file length of 402 bytes.) However TED5 works with any tileinfo data in the MAPHEAD.

=== Map data (GAMEMAPS) ===

The GAMEMAPS file consists of the string "TED5v1.0" and a number of compressed chunks of varying length. Each level in the file will have from two to four chunks (usually four) depending on the game, with all levels in a given game having the same number of chunks. These are the level header and 1-3 planes (foreground, background and sprite/info.) The chunks are in no particular order and it is possible to read through the entire file decompressing chunks as they're found.

Chunks are ordered by the MAPHEAD file, which will point to the GAMEMAPS level header chunks which in turn contain pointers to the other GAMEMAPS chunks used by that level.

All level data is in the form of [[UINT16LE]] values (or in the case of pointers, [[UINT32LE]].)

==== Level headers ====

The header for each level inside the GAMEMAPS file (which is pointed to by MAPHEAD) is 38 bytes long and ''never'' RLEW compressed. If the GAMEMAPS file is using Huffman compression, the level header itself is Huffman-compressed. In that case, the size of the compressed level header can be found in the MAPHEAD file. Since the uncompressed level header always has a size of 38 bytes, that size is not stored at the beginning of the compressed data. The header is sometimes followed by a signature "!ID!" string, which would give the header a total size of 42 bytes, but that string is not part of the actual level header.

The expanded size of each map plane is the size of a word ([[UINT16LE]]) times the width times the height. This is the final, expected size and can be precomputed even if there are two layers of compression.

Plane 0 is background using unmasked tiles, plane 1 is foreground and uses masked tiles, and plane 2 is sprite/info. Levels must contain a background plane and usually an infoplane.

For the compressed size of each level plane, a value of 0 indicates the plane does not exist. The offset value for unused planes appears to be set to a random number with the most significant byte set to 0xFF, making it either a negative number or an offset close to the 4 gigabyte range. The games only check the compressed size and ignore the offset if the size is 0.

Note that Wolf3D is hard-coded to always load the first two planes, even if the compressed size of a plane is 0. Wolf3D also ignores the width and height stored in the level header and just assumes the level is 64x64 tiles. This also applies to Blake Stone and probably any other game based on the Wolf3D code.

All versions of the "Id Software Caching Manager" ignore the expanded size value at the beginning of the RLEW data and just assume that the size is the same as the size of the plane (width * height * 2).

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[INT32LE]] || offPlane0 || Offset in GAMEMAPS to beginning of compressed plane 0 data (or <= 0 if plane is not present)
|-
| 4 || INT32LE || offPlane1 || Offset in GAMEMAPS to beginning of compressed plane 1 data (or <= 0 if plane is not present)
|-
| 8 || INT32LE || offPlane2 || Offset in GAMEMAPS to beginning of compressed plane 2 data (or <= 0 if plane is not present)
|-
| 12 || UINT16LE || lenPlane0 || Length of compressed plane 0 data (in bytes)
|-
| 14 || UINT16LE || lenPlane1 || Length of compressed plane 1 data (in bytes)
|-
| 16 || UINT16LE || lenPlane2 || Length of compressed plane 2 data (in bytes)
|-
| 18 || UINT16LE || width || Width of level (in tiles)
|-
| 20 || UINT16LE || height || Height of level (in tiles)
|-
| 22 || char[16] || name || Internal name for level (used only by editor, not displayed in-game. null-terminated)
|}

Note that for Wolfenstein 3D, a 4-byte signature string ("!ID!") will normally be present directly after the level name. The signature does not appear to be used anywhere, but is useful for distinguishing between v1.0 files (the signature string is missing), and files for v1.1 and later (includes the signature string).

== Carmack compression ==

[[Carmack compression]] is the method used to compress later ''id Software'' games, when file size was still a concern. It is the most efficient and complex compression method and was created specifically to work with the 16-bit word structure of the GameMaps file. The compression is detailed on its [[Carmack compression|own page.]]

Carmackized game maps files are external <tt>GAMEMAPS.xxx</tt> files and the map header is usually (but not always) stored internally in the executable. The map header must be extracted and the game maps decompressed before TED5 can access them. TED5 itself can produce carmackized files and external <tt>MAPHEAD.xxx</tt> files. Carmackization does not replace the RLEW compression used in uncompressed data, but compresses this data, that is, the data is doubly compressed.

Note that for Wolfenstein 3D v1.0, map files are not carmackized, only RLEW compression is applied.

== Huffman compression ==

[[Huffman Compression]] was probably used by earlier versions of TED5 (but possibly not TED5 at all) before carmackization was introduced. It uses the same method to compress its data as is used by ''id Software'' games to compress their graphics and sounds. Again this compression method works with RLEW compressed data and has its [[Huffman Compression|own page.]]

Huffman compression is easily detected since it works on the bit level and thus disrupts the word structure of the game data. This is easily seen in a hex editor. Compressed data will not contain the string $00 $00 or indeed even $00 very often. (In contrast, even carmackized data contains both strings hundreds of times.)

There will be two internal files for this format: the map header and the Huffman dictionary (which is always the first dictionary in the executable.) The map header format is also slightly different, being 502 bytes long, the extra 100 bytes being the length of the compressed level headers in the game maps data, which occur immediately after the normal level header offsets and before the tileinfo. Each entry is one octet indicating the decompressed header length in bytes or zero if the level does not exist. (These can be ignored when decompressing since Huffman data can be read until the decompressed level header's fixed size is reached, but if they are omitted when writing the MAPHEAD, the game may experience a buffer overflow when reading the maps.)

== Location of internal files ==

The GAMEMAPS file itself is always external, but in the case of compression, the MAPHEAD is stored internally in the main .exe file. Executables are themselves compressed with either with LZEXE or PKLite. Once the .exe has been decompressed it is a trivial task to find the MAPHEAD as it will start with the UINT16LE value $ABCD (i.e. the byte $CD followed by the byte $AB.) For level editing purposes only the first 402 (or 502) bytes of the file need to be extracted, though it is possible to read the MAPHEAD file to calculate its length.

The following table lists the offsets of the MAPHEAD file for various games, relative to the start of the decompressed game .exe file.

{{TODO|TODO: Add all known versions of all games}}

{|class="wikitable"
! Game !! Version !! Location !! Filename !! Offset !! Notes
|-
| [[Bio Menace]] || Freeware || External || <tt>MAPHEAD.BM[123]</tt> || - ||
|-
|rowspan=2| [[Blake Stone]]: Aliens of Gold || Shareware || External || <tt>MAPHEAD.BS1</tt> || - ||
|-
| Registered|| External || <tt>MAPHEAD.BS6</tt> || - ||
|-
| [[Blake Stone]] 2: Planet Strike || All || External || <tt>MAPHEAD.VSI</tt> || - ||
|-
| [[Catacomb 3-D]] (3) || 1.00 || Internal || <tt>CAT3D.EXE</tt> || $1C570 || After UNLZEXE
|-
| [[Catacomb Abyss]] (4) || 1.13 || Internal || <tt>CATABYSS.EXE</tt> || $1C510 || After UNLZEXE
|-
| [[Catacomb Armageddon]] (5) || 1.01a || Internal || <tt>CATARMA.EXE</tt> || $1D900 || After UNLZEXE
|-
| [[Catacomb Apocalypse]] (6) || 1.00b || Internal || <tt>CATAPOC.EXE</tt> || $1DD50 || After UNLZEXE
|-
|rowspan=3| [[Corridor 7 Alien Invasion]] || Demo || External || <tt>MAPHEAD.DMO</tt> || - ||
|-
|| CD || Internal || <tt>CORR7CD.EXE</tt> || $30D50 || File is not compressed
|-
| Floppy || Internal || <tt>C7.EXE</tt> || $24BF0 || File is not compressed
|-
|rowspan=2| [[Commander Keen 4-6|Keen 4]] || Special Demo || ? || ? || ? || File is PKLite compressed
|-
| 1.4 EGA || Internal || <tt>KEEN4E.EXE</tt> || $24830 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 5]] || 1.4 EGA || Internal || <tt>KEEN5E.EXE</tt> || $25990 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 6]] || 1.4 EGA || Internal || <tt>KEEN6.EXE</tt> || $25080 || After UNLZEXE
|-
| [[Commander Keen Dreams]] || 1.13 || Internal || ? || $1FA50 || After UNLZEXE
|-
| [[Super 3-D Noah's Ark]] || All || External || <tt>maphead.n3d</tt> || - ||
|-
| [[Operation Body Count]] || All || External || <tt>MAPHEAD.BC</tt> || - ||
|-
| [[Spear of Destiny]] || All || External || <tt>MAPHEAD.SOD</tt> || - ||
|-
|rowspan=2| [[Wolfenstein 3-D]] || Shareware || External || <tt>MAPHEAD.WL1</tt> || - ||
|-
| Registered || External || <tt>MAPHEAD.WL6</tt> || - ||
|}

== Utilities ==

* [[TED5]] can edit the <tt>GAMEMAPS</tt> format of any games that use it. It is the original editor used to create these files.

== Credits ==

This file format was reverse engineered by Andrew Durdin (adurdin). If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

GameMaps Format

2022-11-30T01:47:08Z

Congusbongus: /* Location of internal files */ add bs aog registered to table

{{Map Infobox
| Type = 2D tile-based
| Layers = 3
| Viewport = ''Varies by game''
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Catacomb Abyss}}
{{Game|Commander Keen Dreams}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Dangerous Dave 3}}
{{Game|Dangerous Dave 4}}
{{Game|Super 3-D Noah's Ark}}
{{Game|Operation Body Count}}
{{Game|Rescue Rover 2}}
{{Game|Spear of Destiny}}
{{Game|Wolfenstein 3-D}}
}}

The '''GameMaps Format''' stores levels in a number of [[:Category:id Software]] games. The filenames and compression varies somewhat across different games but all files stored in this format were produced by the [[TED5]] level editor.

There are three main varieties of the file format. The most basic version is just [[RLEW compression|RLEW compressed]], the other two are either [[Carmack compression|carmackized]] or [[Huffman Compression|Huffman compressed]] on top of the RLEW compression. Each variation has its own file naming scheme and pattern of external/internal files.

There are two main components to the format. The game maps proper, which contain the actual level data, and the map headers, which contain both the location of each level's data within the game maps file, and the tile info for the game.

== Variants ==

{|class="wikitable"
! Game !! RLEW !! Carmackization !! Huffman !! Head || Gamemaps || Notes
|-
| Bio Menace || Yes || No || No || maphead.bm[123] || maptemp.bm[123] || gamemaps.bm[123] and mapthead.bm[123] are present but not used
|-
| Blake Stone: Aliens of Gold || Yes || No || No || maphead.bs[16] || maptemp.bs[16] ||
|-
| Blake Stone: Planet Strike || Yes || No || No || maphead.vsi || maptemp.vsi ||
|-
| Catacomb 3-D || Yes || Yes || No || ? || ? ||
|-
| Catacomb Abyss || Yes || Yes || No || ? || ? ||
|-
| Catacomb Apocalypse || Yes || Yes || No || ? || ? ||
|-
| Catacomb Armageddon || Yes || Yes || No || ? || ? ||
|-
| Commander Keen Dreams || Yes || No || Yes || ? || ? ||
|-
| Commander Keen 4-6 || Yes || Yes || No || Inside .exe || gamemaps.ck[456] ||
|-
| Corridor 7 Alien Invasion || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Dangerous Dave 3 || Yes || No || Yes || ? || ? ||
|-
| Dangerous Dave 4 || Yes || No || Yes || ? || ? ||
|-
| Super 3-D Noah's Ark || Yes || Yes || No || maphead.n3d || gamemaps.n3d ||
|-
| Operation Body Count || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Rescue Rover 2 || Yes || Yes || No || ? || ? ||
|-
| Spear of Destiny || Yes || Yes || No || ? || ? ||
|-
| Wolfenstein 3-D (v1.0) || Yes || No || No || maphead.wl1 || maptemp.wl1 ||
|-
| Wolfenstein 3-D (v1.1 and above)|| Yes || Yes || No || maphead.wl[16] || gamemaps.wl[16] ||
|}

The games that use Huffman compression will have a MAPDICT (embedded in the game's main executable). Those missing the map dictionary are not Huffman encoded.

To work out whether Carmackization is used, read the first UINT16LE in a map plane (the field storing the decompressed size). If the value matches the expected size of the plane (i.e. width * height * 2), then only RLEW compression is used. If it doesn't match, check the second UINT16LE in the file (which will become the first UINT16LE once Carmackization has been removed). If this matches the expected plane size then the plane must first have Carmackization removed followed by removal of RLEW. The exception to this rule are plane sizes that have either 0xA7 or 0xA8 as the high byte (i.e. any value from 0xA700 to 0xA8FF), as those values would have been encoded differently by the [[Carmack compression]] algorithm.

== Data structures==

The map data is split into two files: The map header (<tt>MAPHEAD.xxx</tt>) and the main map file (usually <tt>MAPTEMP.xxx</tt> or <tt>GAMEMAPS.xxx</tt>). The map header may be embedded in the game's main executable.

<tt>MAPTEMP.xxx</tt> is the working format saved by [[TED5]] when maps are being edited and can be directly accessed and edited by this utility, allowing changes to be made to the game. Note that if the MAPHEAD file exists as an external file, the game always reads it from a file named named <tt>MAPHEAD.xxx</tt> for both the <tt>GAMEMAPS.xxx</tt> and the <tt>MAPTEMP.xxx</tt> variation. TED5 also saves a <tt>MAPTHEAD.xx</tt> file when editing maps, but that file is only used by TED5 and usually omitted from any game release.

The maps were often compressed even further for the public release versions of the games. This more compressed version of the map file was saved as <tt>GAMEMAPS.xxx</tt> by TED5. Later releases would omit the additional compression layer and ship with the <tt>MAPTEMP.xxx</tt> file instead. One possible reason for this could be that the size of the games grew to the point where they would no longer fit onto and be playable from a single floppy disk, and therefore the additional compression was no longer worth the amount of time it took to compress the maps and re-compile the code.

=== Map headers (MAPHEAD) ===

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[UINT16LE]] || magic || Magic word signalling [[RLEW compression]]
|-
| 2 || [[INT32LE]][100] || ptr || 100 pointers to start of level 0-99 data in the game maps file
|-
| 402 || {{TODO|Unknown}} || tileinfo || Optional tileinfo data
|}

The map header file (MAPHEAD) is of varying length and contains three main types of data.

* The first is the magic word or flag used for RLEW compression, which is almost always $ABCD in the original files. It could be changed to any other value if necessary.

* The second is 100 level pointers which give the location of the start of level data in the GAMEMAPS file, relative to the start of that file. A value less than 1 indicates no level (generally 0, but occasionally -1 (0xFFFFFFFF) is used). Using -1 should be preferred over 0, as the pre-Wolf3D version of the engine will treat any negative value as "a non existant map" [sic!] and quit with an appropriate error message, while 0 will cause it to try reading a level header at offset 0 (where the "TED5v1.0" string is usually stored), which will cause all kinds of errors as there is clearly no valid level header at that offset.

* The third is the tileinfo data, which contains tile properties for each tile used in level creation. (These are masked and unmasked and either 8x8, 16x16 or 32x32.)

Many programs treat the tileinfo as a separate file from the MAPHEAD and it is possible to modify a game in this manner. Indeed, some games such as Wolfenstein 3-D do not have any tileinfo data at all in the map header file (giving a total file length of 402 bytes.) However TED5 works with any tileinfo data in the MAPHEAD.

=== Map data (GAMEMAPS) ===

The GAMEMAPS file consists of the string "TED5v1.0" and a number of compressed chunks of varying length. Each level in the file will have from two to four chunks (usually four) depending on the game, with all levels in a given game having the same number of chunks. These are the level header and 1-3 planes (foreground, background and sprite/info.) The chunks are in no particular order and it is possible to read through the entire file decompressing chunks as they're found.

Chunks are ordered by the MAPHEAD file, which will point to the GAMEMAPS level header chunks which in turn contain pointers to the other GAMEMAPS chunks used by that level.

All level data is in the form of [[UINT16LE]] values (or in the case of pointers, [[UINT32LE]].)

==== Level headers ====

The header for each level inside the GAMEMAPS file (which is pointed to by MAPHEAD) is 38 bytes long and ''never'' RLEW compressed. If the GAMEMAPS file is using Huffman compression, the level header itself is Huffman-compressed. In that case, the size of the compressed level header can be found in the MAPHEAD file. Since the uncompressed level header always has a size of 38 bytes, that size is not stored at the beginning of the compressed data. The header is sometimes followed by a signature "!ID!" string, which would give the header a total size of 42 bytes, but that string is not part of the actual level header.

Plane 0 is background using unmasked tiles, plane 1 is foreground and uses masked tiles, and plane 2 is sprite/info. Levels must contain a background plane and usually an infoplane.

For the compressed size of each level plane, a value of 0 indicates the plane does not exist. The offset value for unused planes appears to be set to a random number with the most significant byte set to 0xFF, making it either a negative number or an offset close to the 4 gigabyte range. The games only check the compressed size and ignore the offset if the size is 0.

Note that Wolf3D is hard-coded to always load the first two planes, even if the compressed size of a plane is 0. Wolf3D also ignores the width and height stored in the level header and just assumes the level is 64x64 tiles. This also applies to Blake Stone and probably any other game based on the Wolf3D code.

All versions of the "Id Software Caching Manager" ignore the expanded size value at the beginning of the RLEW data and just assume that the size is the same as the size of the plane (width * height * 2).

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[INT32LE]] || offPlane0 || Offset in GAMEMAPS to beginning of compressed plane 0 data (or <= 0 if plane is not present)
|-
| 4 || INT32LE || offPlane1 || Offset in GAMEMAPS to beginning of compressed plane 1 data (or <= 0 if plane is not present)
|-
| 8 || INT32LE || offPlane2 || Offset in GAMEMAPS to beginning of compressed plane 2 data (or <= 0 if plane is not present)
|-
| 12 || UINT16LE || lenPlane0 || Length of compressed plane 0 data (in bytes)
|-
| 14 || UINT16LE || lenPlane1 || Length of compressed plane 1 data (in bytes)
|-
| 16 || UINT16LE || lenPlane2 || Length of compressed plane 2 data (in bytes)
|-
| 18 || UINT16LE || width || Width of level (in tiles)
|-
| 20 || UINT16LE || height || Height of level (in tiles)
|-
| 22 || char[16] || name || Internal name for level (used only by editor, not displayed in-game. null-terminated)
|}

Note that for Wolfenstein 3D, a 4-byte signature string ("!ID!") will normally be present directly after the level name. The signature does not appear to be used anywhere, but is useful for distinguishing between v1.0 files (the signature string is missing), and files for v1.1 and later (includes the signature string).

== Carmack compression ==

[[Carmack compression]] is the method used to compress later ''id Software'' games, when file size was still a concern. It is the most efficient and complex compression method and was created specifically to work with the 16-bit word structure of the GameMaps file. The compression is detailed on its [[Carmack compression|own page.]]

Carmackized game maps files are external <tt>GAMEMAPS.xxx</tt> files and the map header is usually (but not always) stored internally in the executable. The map header must be extracted and the game maps decompressed before TED5 can access them. TED5 itself can produce carmackized files and external <tt>MAPHEAD.xxx</tt> files. Carmackization does not replace the RLEW compression used in uncompressed data, but compresses this data, that is, the data is doubly compressed.

Note that for Wolfenstein 3D v1.0, map files are not carmackized, only RLEW compression is applied.

== Huffman compression ==

[[Huffman Compression]] was probably used by earlier versions of TED5 (but possibly not TED5 at all) before carmackization was introduced. It uses the same method to compress its data as is used by ''id Software'' games to compress their graphics and sounds. Again this compression method works with RLEW compressed data and has its [[Huffman Compression|own page.]]

Huffman compression is easily detected since it works on the bit level and thus disrupts the word structure of the game data. This is easily seen in a hex editor. Compressed data will not contain the string $00 $00 or indeed even $00 very often. (In contrast, even carmackized data contains both strings hundreds of times.)

There will be two internal files for this format: the map header and the Huffman dictionary (which is always the first dictionary in the executable.) The map header format is also slightly different, being 502 bytes long, the extra 100 bytes being the length of the compressed level headers in the game maps data, which occur immediately after the normal level header offsets and before the tileinfo. Each entry is one octet indicating the decompressed header length in bytes or zero if the level does not exist. (These can be ignored when decompressing since Huffman data can be read until the decompressed level header's fixed size is reached, but if they are omitted when writing the MAPHEAD, the game may experience a buffer overflow when reading the maps.)

== Location of internal files ==

The GAMEMAPS file itself is always external, but in the case of compression, the MAPHEAD is stored internally in the main .exe file. Executables are themselves compressed with either with LZEXE or PKLite. Once the .exe has been decompressed it is a trivial task to find the MAPHEAD as it will start with the UINT16LE value $ABCD (i.e. the byte $CD followed by the byte $AB.) For level editing purposes only the first 402 (or 502) bytes of the file need to be extracted, though it is possible to read the MAPHEAD file to calculate its length.

The following table lists the offsets of the MAPHEAD file for various games, relative to the start of the decompressed game .exe file.

{{TODO|TODO: Add all known versions of all games}}

{|class="wikitable"
! Game !! Version !! Location !! Filename !! Offset !! Notes
|-
| [[Bio Menace]] || Freeware || External || <tt>MAPHEAD.BM[123]</tt> || - ||
|-
|rowspan=2| [[Blake Stone]]: Aliens of Gold || Shareware || External || <tt>MAPHEAD.BS1</tt> || - ||
|-
| Registered|| External || <tt>MAPHEAD.BS6</tt> || - ||
|-
| [[Blake Stone]] 2: Planet Strike || All || External || <tt>MAPHEAD.VSI</tt> || - ||
|-
| [[Catacomb 3-D]] (3) || 1.00 || Internal || <tt>CAT3D.EXE</tt> || $1C570 || After UNLZEXE
|-
| [[Catacomb Abyss]] (4) || 1.13 || Internal || <tt>CATABYSS.EXE</tt> || $1C510 || After UNLZEXE
|-
| [[Catacomb Armageddon]] (5) || 1.01a || Internal || <tt>CATARMA.EXE</tt> || $1D900 || After UNLZEXE
|-
| [[Catacomb Apocalypse]] (6) || 1.00b || Internal || <tt>CATAPOC.EXE</tt> || $1DD50 || After UNLZEXE
|-
|rowspan=3| [[Corridor 7 Alien Invasion]] || Demo || External || <tt>MAPHEAD.DMO</tt> || - ||
|-
|| CD || Internal || <tt>CORR7CD.EXE</tt> || $30D50 || File is not compressed
|-
| Floppy || Internal || <tt>C7.EXE</tt> || $24BF0 || File is not compressed
|-
|rowspan=2| [[Commander Keen 4-6|Keen 4]] || Special Demo || ? || ? || ? || File is PKLite compressed
|-
| 1.4 EGA || Internal || <tt>KEEN4E.EXE</tt> || $24830 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 5]] || 1.4 EGA || Internal || <tt>KEEN5E.EXE</tt> || $25990 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 6]] || 1.4 EGA || Internal || <tt>KEEN6.EXE</tt> || $25080 || After UNLZEXE
|-
| [[Commander Keen Dreams]] || 1.13 || Internal || ? || $1FA50 || After UNLZEXE
|-
| [[Noah's Ark 3D]] || All || External || ? || - ||
|-
| [[Operation Body Count]] || All || External || <tt>MAPHEAD.BC</tt> || - ||
|-
| [[Spear of Destiny]] || All || External || <tt>MAPHEAD.SOD</tt> || - ||
|-
|rowspan=2| [[Wolfenstein 3-D]] || Shareware || External || <tt>MAPHEAD.WL1</tt> || - ||
|-
| Registered || External || <tt>MAPHEAD.WL6</tt> || - ||
|}

== Utilities ==

* [[TED5]] can edit the <tt>GAMEMAPS</tt> format of any games that use it. It is the original editor used to create these files.

== Credits ==

This file format was reverse engineered by Andrew Durdin (adurdin). If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

GameMaps Format

2022-11-30T01:45:10Z

Congusbongus: Undo revision 10826 by Congusbongus (talk)

{{Map Infobox
| Type = 2D tile-based
| Layers = 3
| Viewport = ''Varies by game''
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Catacomb Abyss}}
{{Game|Commander Keen Dreams}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Dangerous Dave 3}}
{{Game|Dangerous Dave 4}}
{{Game|Super 3-D Noah's Ark}}
{{Game|Operation Body Count}}
{{Game|Rescue Rover 2}}
{{Game|Spear of Destiny}}
{{Game|Wolfenstein 3-D}}
}}

The '''GameMaps Format''' stores levels in a number of [[:Category:id Software]] games. The filenames and compression varies somewhat across different games but all files stored in this format were produced by the [[TED5]] level editor.

There are three main varieties of the file format. The most basic version is just [[RLEW compression|RLEW compressed]], the other two are either [[Carmack compression|carmackized]] or [[Huffman Compression|Huffman compressed]] on top of the RLEW compression. Each variation has its own file naming scheme and pattern of external/internal files.

There are two main components to the format. The game maps proper, which contain the actual level data, and the map headers, which contain both the location of each level's data within the game maps file, and the tile info for the game.

== Variants ==

{|class="wikitable"
! Game !! RLEW !! Carmackization !! Huffman !! Head || Gamemaps || Notes
|-
| Bio Menace || Yes || No || No || maphead.bm[123] || maptemp.bm[123] || gamemaps.bm[123] and mapthead.bm[123] are present but not used
|-
| Blake Stone: Aliens of Gold || Yes || No || No || maphead.bs[16] || maptemp.bs[16] ||
|-
| Blake Stone: Planet Strike || Yes || No || No || maphead.vsi || maptemp.vsi ||
|-
| Catacomb 3-D || Yes || Yes || No || ? || ? ||
|-
| Catacomb Abyss || Yes || Yes || No || ? || ? ||
|-
| Catacomb Apocalypse || Yes || Yes || No || ? || ? ||
|-
| Catacomb Armageddon || Yes || Yes || No || ? || ? ||
|-
| Commander Keen Dreams || Yes || No || Yes || ? || ? ||
|-
| Commander Keen 4-6 || Yes || Yes || No || Inside .exe || gamemaps.ck[456] ||
|-
| Corridor 7 Alien Invasion || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Dangerous Dave 3 || Yes || No || Yes || ? || ? ||
|-
| Dangerous Dave 4 || Yes || No || Yes || ? || ? ||
|-
| Super 3-D Noah's Ark || Yes || Yes || No || maphead.n3d || gamemaps.n3d ||
|-
| Operation Body Count || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Rescue Rover 2 || Yes || Yes || No || ? || ? ||
|-
| Spear of Destiny || Yes || Yes || No || ? || ? ||
|-
| Wolfenstein 3-D (v1.0) || Yes || No || No || maphead.wl1 || maptemp.wl1 ||
|-
| Wolfenstein 3-D (v1.1 and above)|| Yes || Yes || No || maphead.wl[16] || gamemaps.wl[16] ||
|}

The games that use Huffman compression will have a MAPDICT (embedded in the game's main executable). Those missing the map dictionary are not Huffman encoded.

To work out whether Carmackization is used, read the first UINT16LE in a map plane (the field storing the decompressed size). If the value matches the expected size of the plane (i.e. width * height * 2), then only RLEW compression is used. If it doesn't match, check the second UINT16LE in the file (which will become the first UINT16LE once Carmackization has been removed). If this matches the expected plane size then the plane must first have Carmackization removed followed by removal of RLEW. The exception to this rule are plane sizes that have either 0xA7 or 0xA8 as the high byte (i.e. any value from 0xA700 to 0xA8FF), as those values would have been encoded differently by the [[Carmack compression]] algorithm.

== Data structures==

The map data is split into two files: The map header (<tt>MAPHEAD.xxx</tt>) and the main map file (usually <tt>MAPTEMP.xxx</tt> or <tt>GAMEMAPS.xxx</tt>). The map header may be embedded in the game's main executable.

<tt>MAPTEMP.xxx</tt> is the working format saved by [[TED5]] when maps are being edited and can be directly accessed and edited by this utility, allowing changes to be made to the game. Note that if the MAPHEAD file exists as an external file, the game always reads it from a file named named <tt>MAPHEAD.xxx</tt> for both the <tt>GAMEMAPS.xxx</tt> and the <tt>MAPTEMP.xxx</tt> variation. TED5 also saves a <tt>MAPTHEAD.xx</tt> file when editing maps, but that file is only used by TED5 and usually omitted from any game release.

The maps were often compressed even further for the public release versions of the games. This more compressed version of the map file was saved as <tt>GAMEMAPS.xxx</tt> by TED5. Later releases would omit the additional compression layer and ship with the <tt>MAPTEMP.xxx</tt> file instead. One possible reason for this could be that the size of the games grew to the point where they would no longer fit onto and be playable from a single floppy disk, and therefore the additional compression was no longer worth the amount of time it took to compress the maps and re-compile the code.

=== Map headers (MAPHEAD) ===

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[UINT16LE]] || magic || Magic word signalling [[RLEW compression]]
|-
| 2 || [[INT32LE]][100] || ptr || 100 pointers to start of level 0-99 data in the game maps file
|-
| 402 || {{TODO|Unknown}} || tileinfo || Optional tileinfo data
|}

The map header file (MAPHEAD) is of varying length and contains three main types of data.

* The first is the magic word or flag used for RLEW compression, which is almost always $ABCD in the original files. It could be changed to any other value if necessary.

* The second is 100 level pointers which give the location of the start of level data in the GAMEMAPS file, relative to the start of that file. A value less than 1 indicates no level (generally 0, but occasionally -1 (0xFFFFFFFF) is used). Using -1 should be preferred over 0, as the pre-Wolf3D version of the engine will treat any negative value as "a non existant map" [sic!] and quit with an appropriate error message, while 0 will cause it to try reading a level header at offset 0 (where the "TED5v1.0" string is usually stored), which will cause all kinds of errors as there is clearly no valid level header at that offset.

* The third is the tileinfo data, which contains tile properties for each tile used in level creation. (These are masked and unmasked and either 8x8, 16x16 or 32x32.)

Many programs treat the tileinfo as a separate file from the MAPHEAD and it is possible to modify a game in this manner. Indeed, some games such as Wolfenstein 3-D do not have any tileinfo data at all in the map header file (giving a total file length of 402 bytes.) However TED5 works with any tileinfo data in the MAPHEAD.

=== Map data (GAMEMAPS) ===

The GAMEMAPS file consists of the string "TED5v1.0" and a number of compressed chunks of varying length. Each level in the file will have from two to four chunks (usually four) depending on the game, with all levels in a given game having the same number of chunks. These are the level header and 1-3 planes (foreground, background and sprite/info.) The chunks are in no particular order and it is possible to read through the entire file decompressing chunks as they're found.

Chunks are ordered by the MAPHEAD file, which will point to the GAMEMAPS level header chunks which in turn contain pointers to the other GAMEMAPS chunks used by that level.

All level data is in the form of [[UINT16LE]] values (or in the case of pointers, [[UINT32LE]].)

==== Level headers ====

The header for each level inside the GAMEMAPS file (which is pointed to by MAPHEAD) is 38 bytes long and ''never'' RLEW compressed. If the GAMEMAPS file is using Huffman compression, the level header itself is Huffman-compressed. In that case, the size of the compressed level header can be found in the MAPHEAD file. Since the uncompressed level header always has a size of 38 bytes, that size is not stored at the beginning of the compressed data. The header is sometimes followed by a signature "!ID!" string, which would give the header a total size of 42 bytes, but that string is not part of the actual level header.

Plane 0 is background using unmasked tiles, plane 1 is foreground and uses masked tiles, and plane 2 is sprite/info. Levels must contain a background plane and usually an infoplane.

For the compressed size of each level plane, a value of 0 indicates the plane does not exist. The offset value for unused planes appears to be set to a random number with the most significant byte set to 0xFF, making it either a negative number or an offset close to the 4 gigabyte range. The games only check the compressed size and ignore the offset if the size is 0.

Note that Wolf3D is hard-coded to always load the first two planes, even if the compressed size of a plane is 0. Wolf3D also ignores the width and height stored in the level header and just assumes the level is 64x64 tiles. This also applies to Blake Stone and probably any other game based on the Wolf3D code.

All versions of the "Id Software Caching Manager" ignore the expanded size value at the beginning of the RLEW data and just assume that the size is the same as the size of the plane (width * height * 2).

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[INT32LE]] || offPlane0 || Offset in GAMEMAPS to beginning of compressed plane 0 data (or <= 0 if plane is not present)
|-
| 4 || INT32LE || offPlane1 || Offset in GAMEMAPS to beginning of compressed plane 1 data (or <= 0 if plane is not present)
|-
| 8 || INT32LE || offPlane2 || Offset in GAMEMAPS to beginning of compressed plane 2 data (or <= 0 if plane is not present)
|-
| 12 || UINT16LE || lenPlane0 || Length of compressed plane 0 data (in bytes)
|-
| 14 || UINT16LE || lenPlane1 || Length of compressed plane 1 data (in bytes)
|-
| 16 || UINT16LE || lenPlane2 || Length of compressed plane 2 data (in bytes)
|-
| 18 || UINT16LE || width || Width of level (in tiles)
|-
| 20 || UINT16LE || height || Height of level (in tiles)
|-
| 22 || char[16] || name || Internal name for level (used only by editor, not displayed in-game. null-terminated)
|}

Note that for Wolfenstein 3D, a 4-byte signature string ("!ID!") will normally be present directly after the level name. The signature does not appear to be used anywhere, but is useful for distinguishing between v1.0 files (the signature string is missing), and files for v1.1 and later (includes the signature string).

== Carmack compression ==

[[Carmack compression]] is the method used to compress later ''id Software'' games, when file size was still a concern. It is the most efficient and complex compression method and was created specifically to work with the 16-bit word structure of the GameMaps file. The compression is detailed on its [[Carmack compression|own page.]]

Carmackized game maps files are external <tt>GAMEMAPS.xxx</tt> files and the map header is usually (but not always) stored internally in the executable. The map header must be extracted and the game maps decompressed before TED5 can access them. TED5 itself can produce carmackized files and external <tt>MAPHEAD.xxx</tt> files. Carmackization does not replace the RLEW compression used in uncompressed data, but compresses this data, that is, the data is doubly compressed.

Note that for Wolfenstein 3D v1.0, map files are not carmackized, only RLEW compression is applied.

== Huffman compression ==

[[Huffman Compression]] was probably used by earlier versions of TED5 (but possibly not TED5 at all) before carmackization was introduced. It uses the same method to compress its data as is used by ''id Software'' games to compress their graphics and sounds. Again this compression method works with RLEW compressed data and has its [[Huffman Compression|own page.]]

Huffman compression is easily detected since it works on the bit level and thus disrupts the word structure of the game data. This is easily seen in a hex editor. Compressed data will not contain the string $00 $00 or indeed even $00 very often. (In contrast, even carmackized data contains both strings hundreds of times.)

There will be two internal files for this format: the map header and the Huffman dictionary (which is always the first dictionary in the executable.) The map header format is also slightly different, being 502 bytes long, the extra 100 bytes being the length of the compressed level headers in the game maps data, which occur immediately after the normal level header offsets and before the tileinfo. Each entry is one octet indicating the decompressed header length in bytes or zero if the level does not exist. (These can be ignored when decompressing since Huffman data can be read until the decompressed level header's fixed size is reached, but if they are omitted when writing the MAPHEAD, the game may experience a buffer overflow when reading the maps.)

== Location of internal files ==

The GAMEMAPS file itself is always external, but in the case of compression, the MAPHEAD is stored internally in the main .exe file. Executables are themselves compressed with either with LZEXE or PKLite. Once the .exe has been decompressed it is a trivial task to find the MAPHEAD as it will start with the UINT16LE value $ABCD (i.e. the byte $CD followed by the byte $AB.) For level editing purposes only the first 402 (or 502) bytes of the file need to be extracted, though it is possible to read the MAPHEAD file to calculate its length.

The following table lists the offsets of the MAPHEAD file for various games, relative to the start of the decompressed game .exe file.

{{TODO|TODO: Add all known versions of all games}}

{|class="wikitable"
! Game !! Version !! Location !! Filename !! Offset !! Notes
|-
| [[Bio Menace]] || Freeware || External || <tt>MAPHEAD.BM[123]</tt> || - ||
|-
| [[Blake Stone]]: Aliens of Gold || Shareware || External || <tt>MAPHEAD.BS1</tt> || - ||
|-
| [[Blake Stone]] 2: Planet Strike || All || External || <tt>MAPHEAD.VSI</tt> || - ||
|-
| [[Catacomb 3-D]] (3) || 1.00 || Internal || <tt>CAT3D.EXE</tt> || $1C570 || After UNLZEXE
|-
| [[Catacomb Abyss]] (4) || 1.13 || Internal || <tt>CATABYSS.EXE</tt> || $1C510 || After UNLZEXE
|-
| [[Catacomb Armageddon]] (5) || 1.01a || Internal || <tt>CATARMA.EXE</tt> || $1D900 || After UNLZEXE
|-
| [[Catacomb Apocalypse]] (6) || 1.00b || Internal || <tt>CATAPOC.EXE</tt> || $1DD50 || After UNLZEXE
|-
|rowspan=3| [[Corridor 7 Alien Invasion]] || Demo || External || <tt>MAPHEAD.DMO</tt> || - ||
|-
|| CD || Internal || <tt>CORR7CD.EXE</tt> || $30D50 || File is not compressed
|-
| Floppy || Internal || <tt>C7.EXE</tt> || $24BF0 || File is not compressed
|-
|rowspan=2| [[Commander Keen 4-6|Keen 4]] || Special Demo || ? || ? || ? || File is PKLite compressed
|-
| 1.4 EGA || Internal || <tt>KEEN4E.EXE</tt> || $24830 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 5]] || 1.4 EGA || Internal || <tt>KEEN5E.EXE</tt> || $25990 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 6]] || 1.4 EGA || Internal || <tt>KEEN6.EXE</tt> || $25080 || After UNLZEXE
|-
| [[Commander Keen Dreams]] || 1.13 || Internal || ? || $1FA50 || After UNLZEXE
|-
| [[Noah's Ark 3D]] || All || External || ? || - ||
|-
| [[Operation Body Count]] || All || External || <tt>MAPHEAD.BC</tt> || - ||
|-
| [[Spear of Destiny]] || All || External || <tt>MAPHEAD.SOD</tt> || - ||
|-
|rowspan=2| [[Wolfenstein 3-D]] || Shareware || External || <tt>MAPHEAD.WL1</tt> || - ||
|-
| Registered || External || <tt>MAPHEAD.WL6</tt> || - ||
|}

== Utilities ==

* [[TED5]] can edit the <tt>GAMEMAPS</tt> format of any games that use it. It is the original editor used to create these files.

== Credits ==

This file format was reverse engineered by Andrew Durdin (adurdin). If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

Id Software RLEW compression

2022-11-30T01:43:47Z

Congusbongus: Add finalLength table

{{DISPLAYTITLE:id Software RLEW compression}}
{{Compression Infobox
| Type = Stream
| UnitSize = 2-byte
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Catacomb Abyss}}
{{Game|Catacomb Apocalypse}}
{{Game|Catacomb Armageddon}}
{{Game|Commander Keen 1-3}}
{{Game|Commander Keen Dreams}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Dangerous Dave 2}}
{{Game|Dangerous Dave 3}}
{{Game|Dangerous Dave 4}}
{{Game|Hovertank 3-D}}
{{Game|Super 3-D Noah's Ark}}
{{Game|Operation Body Count}}
{{Game|Rescue Rover}}
{{Game|Rescue Rover 2}}
{{Game|Shadow Knights}}
{{Game|Slordax}}
{{Game|Spear of Destiny}}
{{Game|Wolfenstein 3-D}}
}}

'''id Software RLEW compression''' was used in a number of id's early games. It is an [[RLE Compression]] algorithm that works at the word level, where each word is a group of two bytes (16 bits). The algorithm is used on files that themselves use 16-bit words as their basic units, such as game levels, where a single 16-bit value such as "12 34" might be repeated multiple times in a row. A byte-level RLE algorithm would not be able to compress this data at all, as each byte is different to the previous, however the same RLE algorithm operating at the 16-bit word level can achieve good compression.

The use of 16-bit values over 8-bit also yields other benefits, such as the maximum repetition count increasing from around 256 to 65,536, allowing even greater compression of data with large numbers of repeated values. The RLE code word can also be chosen to be less likely to appear in the data, minimising the number of escapes required. While 8-bit RLE has a 1 in 256 chance of a given byte needing to be escaped, 16-bit RLE reduces that to 1 in 65,536.

RLEW compression is almost exclusively used to compress level data. Most revisions of the early game engines by id Software used arrays of 16 bit values to store the level data.

== Algorithm ==

The algorithm is very straightforward. Every 16-bit value is passed through unchanged until an RLE code value is encountered. Typically this is 0xFEFE or 0xABCD (the latter stored as the two bytes 0xCD 0xAB in little-endian order). When this code word is read, instead of writing it out like the other values, two further words are read. The first is the number of times to repeat the word, and the second is the value to be repeated.

All 16-bit words are in little-endian order, although in practice only the code word and the repeat count need to be treated as little-endian. The other values can be read in either endian so long as they are read and written unchanged.

Data is usually read from the start of a file to the end, but many implementations have the size of the decompressed data as a [[UINT16LE]] at the beginning of the file. This should be used where possible so that trailing data at the end of the file does not inadvertently get read as input data.

A simple algorithm for decompressing this format is as follows;

<ol>
<li>If implemented, get the first word in the file (here called <tt>finalLength</tt> - see table)</li>
<li>While the length of the output data is less than <tt>finalLength</tt>:
<ol style="list-style-type:lower-alpha">
<li>Read a word from the input data</li>
<li>Is this word the RLE code word? (e.g. 0xFEFE)
<ul>
<li>If yes;
<ol style="list-style-type:lower-roman">
<li>Get the next two words, the first as <tt>Count</tt> and the second as <tt>Value</tt>.</li>
<li>Write Value as a word, <tt>Count</tt> times.</li>
<li>Move forward three words and go to 2.</li>
</ol>
</li>
<li>If no;
<ol style="list-style-type:lower-roman">
<li>Write the word to the output.</li>
<li>Move forward a word and go to 2.</li>
</ol>
</li>
</ul>
</ol>
</li>
</ol>

{|class="wikitable"
! Game !! finalLength
|-
| Blake Stone: Aliens of Gold || No (use 64x64 words as finalLength)
|-
| Spear of Destiny || Yes
|-
| Wolfenstein 3-D (v1.0) || Yes
|-
| Wolfenstein 3-D (v1.1 and above) || Yes
|}

=== Minimal compression ===

As only the code word needs to be handled specially, a quick compression function can be implemented by passing through all values as-is, and if the code word has just been written then it is followed by the additional words 0x0001 and the code word again. For example if the code word is 0xFEFE, then it will end up in the output as <tt>FEFE 0001 FEFE</tt>, meaning "RLE sequence begins: write 0xFEFE once".

=== Inefficiencies and hidden data ===

It is interesting to note that as only the RLEW code word needs to be escaped, no other word would ever need to be repeated only once. This means the escape sequence <tt>FEFE 0001 FEFE</tt> could have been shortened to <tt>FEFE 0001</tt> by omitting the field containing the word to repeat, with the assumption that the only word ever written just once is the RLEW code word itself.

Furthermore, the <tt>Count</tt> field in the RLE sequence is set to 1 to write the word once. This means it can be set to 0 to write the word zero times, effectively discarding that word. In theory this could allow "hidden" data to be embedded in the compressed data stream that would be skipped over by the decompressor and not affect the output decompressed data.

Most RLE algorithms avoid this inefficiency by adding 1 (or more) to the count value before using it, meaning a count of 0 writes the word once, a count of 1 writes it twice, and so on. In this case, as the RLE sequence takes up three words, no space is saved until at least four words are converted into an RLE code. This means adding 3 to the count would have been most efficient, with a count of 0 reserved as a special case for handling the escaping of the code word itself. Thus 0 would write the code word, 1 would repeat the word 4 times, 2 would repeat it 5 times, and so on. Words appearing 2 or 3 times in a row would be written out as-is without incurring any space penalty, with the sole exception of the RLEW code word appearing 2 or 3 times in a row, which would incur a small space penalty.

=== RLEB compression ===

This is almost exactly the same as RLEW compression. The only difference is that it operates on bytes instead of words. The flag value for this compression is $FE in most cases.

[[Dangerous Dave 2]], [[Rescue Rover]] and [[Shadow Knights]] use this method to compress some of their full-screen images. [[Rescue Rover]] and [[Shadow Knights]] also use this method to compress the game's sprite graphics.

=== Example code ===

* Javascript: the [https://github.com/camoto-project/gamecompjs/blob/master/formats/cmp-rlew-id.js cmp-rlew-id] algorithm in gamecomp.js (full compression and decompression)

GameMaps Format

2022-11-30T01:09:03Z

Congusbongus: blake stone is carmackized

{{Map Infobox
| Type = 2D tile-based
| Layers = 3
| Viewport = ''Varies by game''
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Catacomb Abyss}}
{{Game|Commander Keen Dreams}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Dangerous Dave 3}}
{{Game|Dangerous Dave 4}}
{{Game|Super 3-D Noah's Ark}}
{{Game|Operation Body Count}}
{{Game|Rescue Rover 2}}
{{Game|Spear of Destiny}}
{{Game|Wolfenstein 3-D}}
}}

The '''GameMaps Format''' stores levels in a number of [[:Category:id Software]] games. The filenames and compression varies somewhat across different games but all files stored in this format were produced by the [[TED5]] level editor.

There are three main varieties of the file format. The most basic version is just [[RLEW compression|RLEW compressed]], the other two are either [[Carmack compression|carmackized]] or [[Huffman Compression|Huffman compressed]] on top of the RLEW compression. Each variation has its own file naming scheme and pattern of external/internal files.

There are two main components to the format. The game maps proper, which contain the actual level data, and the map headers, which contain both the location of each level's data within the game maps file, and the tile info for the game.

== Variants ==

{|class="wikitable"
! Game !! RLEW !! Carmackization !! Huffman !! Head || Gamemaps || Notes
|-
| Bio Menace || Yes || No || No || maphead.bm[123] || maptemp.bm[123] || gamemaps.bm[123] and mapthead.bm[123] are present but not used
|-
| Blake Stone: Aliens of Gold || Yes || Yes || No || maphead.bs[16] || maptemp.bs[16] ||
|-
| Blake Stone: Planet Strike || Yes || Yes || No || maphead.vsi || maptemp.vsi ||
|-
| Catacomb 3-D || Yes || Yes || No || ? || ? ||
|-
| Catacomb Abyss || Yes || Yes || No || ? || ? ||
|-
| Catacomb Apocalypse || Yes || Yes || No || ? || ? ||
|-
| Catacomb Armageddon || Yes || Yes || No || ? || ? ||
|-
| Commander Keen Dreams || Yes || No || Yes || ? || ? ||
|-
| Commander Keen 4-6 || Yes || Yes || No || Inside .exe || gamemaps.ck[456] ||
|-
| Corridor 7 Alien Invasion || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Dangerous Dave 3 || Yes || No || Yes || ? || ? ||
|-
| Dangerous Dave 4 || Yes || No || Yes || ? || ? ||
|-
| Super 3-D Noah's Ark || Yes || Yes || No || maphead.n3d || gamemaps.n3d ||
|-
| Operation Body Count || Yes || No || No || ? || ? || Uses MAPTEMP.xxx (only RLEW compression)
|-
| Rescue Rover 2 || Yes || Yes || No || ? || ? ||
|-
| Spear of Destiny || Yes || Yes || No || ? || ? ||
|-
| Wolfenstein 3-D (v1.0) || Yes || No || No || maphead.wl1 || maptemp.wl1 ||
|-
| Wolfenstein 3-D (v1.1 and above)|| Yes || Yes || No || maphead.wl[16] || gamemaps.wl[16] ||
|}

The games that use Huffman compression will have a MAPDICT (embedded in the game's main executable). Those missing the map dictionary are not Huffman encoded.

To work out whether Carmackization is used, read the first UINT16LE in a map plane (the field storing the decompressed size). If the value matches the expected size of the plane (i.e. width * height * 2), then only RLEW compression is used. If it doesn't match, check the second UINT16LE in the file (which will become the first UINT16LE once Carmackization has been removed). If this matches the expected plane size then the plane must first have Carmackization removed followed by removal of RLEW. The exception to this rule are plane sizes that have either 0xA7 or 0xA8 as the high byte (i.e. any value from 0xA700 to 0xA8FF), as those values would have been encoded differently by the [[Carmack compression]] algorithm.

== Data structures==

The map data is split into two files: The map header (<tt>MAPHEAD.xxx</tt>) and the main map file (usually <tt>MAPTEMP.xxx</tt> or <tt>GAMEMAPS.xxx</tt>). The map header may be embedded in the game's main executable.

<tt>MAPTEMP.xxx</tt> is the working format saved by [[TED5]] when maps are being edited and can be directly accessed and edited by this utility, allowing changes to be made to the game. Note that if the MAPHEAD file exists as an external file, the game always reads it from a file named named <tt>MAPHEAD.xxx</tt> for both the <tt>GAMEMAPS.xxx</tt> and the <tt>MAPTEMP.xxx</tt> variation. TED5 also saves a <tt>MAPTHEAD.xx</tt> file when editing maps, but that file is only used by TED5 and usually omitted from any game release.

The maps were often compressed even further for the public release versions of the games. This more compressed version of the map file was saved as <tt>GAMEMAPS.xxx</tt> by TED5. Later releases would omit the additional compression layer and ship with the <tt>MAPTEMP.xxx</tt> file instead. One possible reason for this could be that the size of the games grew to the point where they would no longer fit onto and be playable from a single floppy disk, and therefore the additional compression was no longer worth the amount of time it took to compress the maps and re-compile the code.

=== Map headers (MAPHEAD) ===

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[UINT16LE]] || magic || Magic word signalling [[RLEW compression]]
|-
| 2 || [[INT32LE]][100] || ptr || 100 pointers to start of level 0-99 data in the game maps file
|-
| 402 || {{TODO|Unknown}} || tileinfo || Optional tileinfo data
|}

The map header file (MAPHEAD) is of varying length and contains three main types of data.

* The first is the magic word or flag used for RLEW compression, which is almost always $ABCD in the original files. It could be changed to any other value if necessary.

* The second is 100 level pointers which give the location of the start of level data in the GAMEMAPS file, relative to the start of that file. A value less than 1 indicates no level (generally 0, but occasionally -1 (0xFFFFFFFF) is used). Using -1 should be preferred over 0, as the pre-Wolf3D version of the engine will treat any negative value as "a non existant map" [sic!] and quit with an appropriate error message, while 0 will cause it to try reading a level header at offset 0 (where the "TED5v1.0" string is usually stored), which will cause all kinds of errors as there is clearly no valid level header at that offset.

* The third is the tileinfo data, which contains tile properties for each tile used in level creation. (These are masked and unmasked and either 8x8, 16x16 or 32x32.)

Many programs treat the tileinfo as a separate file from the MAPHEAD and it is possible to modify a game in this manner. Indeed, some games such as Wolfenstein 3-D do not have any tileinfo data at all in the map header file (giving a total file length of 402 bytes.) However TED5 works with any tileinfo data in the MAPHEAD.

=== Map data (GAMEMAPS) ===

The GAMEMAPS file consists of the string "TED5v1.0" and a number of compressed chunks of varying length. Each level in the file will have from two to four chunks (usually four) depending on the game, with all levels in a given game having the same number of chunks. These are the level header and 1-3 planes (foreground, background and sprite/info.) The chunks are in no particular order and it is possible to read through the entire file decompressing chunks as they're found.

Chunks are ordered by the MAPHEAD file, which will point to the GAMEMAPS level header chunks which in turn contain pointers to the other GAMEMAPS chunks used by that level.

All level data is in the form of [[UINT16LE]] values (or in the case of pointers, [[UINT32LE]].)

==== Level headers ====

The header for each level inside the GAMEMAPS file (which is pointed to by MAPHEAD) is 38 bytes long and ''never'' RLEW compressed. If the GAMEMAPS file is using Huffman compression, the level header itself is Huffman-compressed. In that case, the size of the compressed level header can be found in the MAPHEAD file. Since the uncompressed level header always has a size of 38 bytes, that size is not stored at the beginning of the compressed data. The header is sometimes followed by a signature "!ID!" string, which would give the header a total size of 42 bytes, but that string is not part of the actual level header.

Plane 0 is background using unmasked tiles, plane 1 is foreground and uses masked tiles, and plane 2 is sprite/info. Levels must contain a background plane and usually an infoplane.

For the compressed size of each level plane, a value of 0 indicates the plane does not exist. The offset value for unused planes appears to be set to a random number with the most significant byte set to 0xFF, making it either a negative number or an offset close to the 4 gigabyte range. The games only check the compressed size and ignore the offset if the size is 0.

Note that Wolf3D is hard-coded to always load the first two planes, even if the compressed size of a plane is 0. Wolf3D also ignores the width and height stored in the level header and just assumes the level is 64x64 tiles. This also applies to Blake Stone and probably any other game based on the Wolf3D code.

All versions of the "Id Software Caching Manager" ignore the expanded size value at the beginning of the RLEW data and just assume that the size is the same as the size of the plane (width * height * 2).

{|class="wikitable"
! Offset !! Type !! Name !! Description
|-
| 0 || [[INT32LE]] || offPlane0 || Offset in GAMEMAPS to beginning of compressed plane 0 data (or <= 0 if plane is not present)
|-
| 4 || INT32LE || offPlane1 || Offset in GAMEMAPS to beginning of compressed plane 1 data (or <= 0 if plane is not present)
|-
| 8 || INT32LE || offPlane2 || Offset in GAMEMAPS to beginning of compressed plane 2 data (or <= 0 if plane is not present)
|-
| 12 || UINT16LE || lenPlane0 || Length of compressed plane 0 data (in bytes)
|-
| 14 || UINT16LE || lenPlane1 || Length of compressed plane 1 data (in bytes)
|-
| 16 || UINT16LE || lenPlane2 || Length of compressed plane 2 data (in bytes)
|-
| 18 || UINT16LE || width || Width of level (in tiles)
|-
| 20 || UINT16LE || height || Height of level (in tiles)
|-
| 22 || char[16] || name || Internal name for level (used only by editor, not displayed in-game. null-terminated)
|}

Note that for Wolfenstein 3D, a 4-byte signature string ("!ID!") will normally be present directly after the level name. The signature does not appear to be used anywhere, but is useful for distinguishing between v1.0 files (the signature string is missing), and files for v1.1 and later (includes the signature string).

== Carmack compression ==

[[Carmack compression]] is the method used to compress later ''id Software'' games, when file size was still a concern. It is the most efficient and complex compression method and was created specifically to work with the 16-bit word structure of the GameMaps file. The compression is detailed on its [[Carmack compression|own page.]]

Carmackized game maps files are external <tt>GAMEMAPS.xxx</tt> files and the map header is usually (but not always) stored internally in the executable. The map header must be extracted and the game maps decompressed before TED5 can access them. TED5 itself can produce carmackized files and external <tt>MAPHEAD.xxx</tt> files. Carmackization does not replace the RLEW compression used in uncompressed data, but compresses this data, that is, the data is doubly compressed.

Note that for Wolfenstein 3D v1.0, map files are not carmackized, only RLEW compression is applied.

== Huffman compression ==

[[Huffman Compression]] was probably used by earlier versions of TED5 (but possibly not TED5 at all) before carmackization was introduced. It uses the same method to compress its data as is used by ''id Software'' games to compress their graphics and sounds. Again this compression method works with RLEW compressed data and has its [[Huffman Compression|own page.]]

Huffman compression is easily detected since it works on the bit level and thus disrupts the word structure of the game data. This is easily seen in a hex editor. Compressed data will not contain the string $00 $00 or indeed even $00 very often. (In contrast, even carmackized data contains both strings hundreds of times.)

There will be two internal files for this format: the map header and the Huffman dictionary (which is always the first dictionary in the executable.) The map header format is also slightly different, being 502 bytes long, the extra 100 bytes being the length of the compressed level headers in the game maps data, which occur immediately after the normal level header offsets and before the tileinfo. Each entry is one octet indicating the decompressed header length in bytes or zero if the level does not exist. (These can be ignored when decompressing since Huffman data can be read until the decompressed level header's fixed size is reached, but if they are omitted when writing the MAPHEAD, the game may experience a buffer overflow when reading the maps.)

== Location of internal files ==

The GAMEMAPS file itself is always external, but in the case of compression, the MAPHEAD is stored internally in the main .exe file. Executables are themselves compressed with either with LZEXE or PKLite. Once the .exe has been decompressed it is a trivial task to find the MAPHEAD as it will start with the UINT16LE value $ABCD (i.e. the byte $CD followed by the byte $AB.) For level editing purposes only the first 402 (or 502) bytes of the file need to be extracted, though it is possible to read the MAPHEAD file to calculate its length.

The following table lists the offsets of the MAPHEAD file for various games, relative to the start of the decompressed game .exe file.

{{TODO|TODO: Add all known versions of all games}}

{|class="wikitable"
! Game !! Version !! Location !! Filename !! Offset !! Notes
|-
| [[Bio Menace]] || Freeware || External || <tt>MAPHEAD.BM[123]</tt> || - ||
|-
| [[Blake Stone]]: Aliens of Gold || Shareware || External || <tt>MAPHEAD.BS1</tt> || - ||
|-
| [[Blake Stone]] 2: Planet Strike || All || External || <tt>MAPHEAD.VSI</tt> || - ||
|-
| [[Catacomb 3-D]] (3) || 1.00 || Internal || <tt>CAT3D.EXE</tt> || $1C570 || After UNLZEXE
|-
| [[Catacomb Abyss]] (4) || 1.13 || Internal || <tt>CATABYSS.EXE</tt> || $1C510 || After UNLZEXE
|-
| [[Catacomb Armageddon]] (5) || 1.01a || Internal || <tt>CATARMA.EXE</tt> || $1D900 || After UNLZEXE
|-
| [[Catacomb Apocalypse]] (6) || 1.00b || Internal || <tt>CATAPOC.EXE</tt> || $1DD50 || After UNLZEXE
|-
|rowspan=3| [[Corridor 7 Alien Invasion]] || Demo || External || <tt>MAPHEAD.DMO</tt> || - ||
|-
|| CD || Internal || <tt>CORR7CD.EXE</tt> || $30D50 || File is not compressed
|-
| Floppy || Internal || <tt>C7.EXE</tt> || $24BF0 || File is not compressed
|-
|rowspan=2| [[Commander Keen 4-6|Keen 4]] || Special Demo || ? || ? || ? || File is PKLite compressed
|-
| 1.4 EGA || Internal || <tt>KEEN4E.EXE</tt> || $24830 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 5]] || 1.4 EGA || Internal || <tt>KEEN5E.EXE</tt> || $25990 || After UNLZEXE
|-
| [[Commander Keen 4-6|Keen 6]] || 1.4 EGA || Internal || <tt>KEEN6.EXE</tt> || $25080 || After UNLZEXE
|-
| [[Commander Keen Dreams]] || 1.13 || Internal || ? || $1FA50 || After UNLZEXE
|-
| [[Noah's Ark 3D]] || All || External || ? || - ||
|-
| [[Operation Body Count]] || All || External || <tt>MAPHEAD.BC</tt> || - ||
|-
| [[Spear of Destiny]] || All || External || <tt>MAPHEAD.SOD</tt> || - ||
|-
|rowspan=2| [[Wolfenstein 3-D]] || Shareware || External || <tt>MAPHEAD.WL1</tt> || - ||
|-
| Registered || External || <tt>MAPHEAD.WL6</tt> || - ||
|}

== Utilities ==

* [[TED5]] can edit the <tt>GAMEMAPS</tt> format of any games that use it. It is the original editor used to create these files.

== Credits ==

This file format was reverse engineered by Andrew Durdin (adurdin). If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)