User Tools

Site Tools


Automatic file mapping in PK3

Doomsday's pk3 reader supports several “shortcuts” that can be used to simplify the virtual directory stucture within a PK3. These automatic mappings allow for easy use of Doomsday's folder structure when making addons.

Automatic relocation by resource class

Files in the root direction of a PK3 are subject to automatic relocation according to the associated resource class.

Files with the following extensions are automatically mapped to data\<gamecomponent>\auto\

ded definitions are automatically mapped to defs\<gamecomponent>\auto\

Note: Automatically relocated root files are mapped to the same (virtual) directory appropriate for that class of resource. For example, given two archives “a.pk3” and “b.pk3” each containing the root file “myded.ded” only the last loaded definition file will be read (the later file overrides the earlier one).

Shortcut folders (1.9.x)

All files in the following virtual folders of a PK3 (including subfolders) are automatically moved to the correct (virtual) location in the file hierarchy by Doomsday. These shortcuts allow you to greatly simplify the folder structure of your mod/addon. For example instead of the virtual folder data/jdoom/textures/ you only need a folder named textures/.

  • flats/
  • fonts/
  • lightmaps/
  • models/ (1.9.7+)
  • music/
  • patches/
  • sfx/ (1.9.7+)
  • textures/

Manual "Auto" directory mapping

It is also possible to request the mapping of entire directories manually by adding a special prefix character to the name of a directory in the root of a PK3.

Prefix Virtual Directory
# (hash) data/<gamecomponent>/auto/
@ (at) defs/<gamecomponent>/auto/


Layout of myaddon.pk3 when loaded with the doom game component:

PK3 Directory Virtual Directory
#CoolStuff/ data/doom/auto/CoolStuff/
@CoolStuff/ defs/doom/auto/CoolStuff/


Addon example for a mod for Doom that makes use of the available virtual directory shortcuts to simplify the structure.

  • MyCoolLevel.PK3
    • textures/
      • Bigdoor1.png
      • Brick1.png
    • music/
      • romero.mp3
    • mycoolwad.wad
    • myded.ded

See also

modding/automatic_file_mapping_in_pk3.txt · Last modified: 2017-03-20 20:21 by skyjake