1. Install Python 2.4, which can be downloaded from
  2. Extract the files in the Omgifol package into a directory named “omg” in pythondir/Lib/site-packages (replace pythondir with the directory where Python is installed).


  1. Install the Python Imaging Library. This is required to save or load images.
  2. Install Psyco This can make Omgifol quite a bit faster, typically 2-10x.

Using Omgifol

At the beginning of an interactive session, or as the first line in a Python script file, enter:

from omg import *

WAD objects

A WAD is an abstract representation of a WAD file. A WAD object can load content from a WAD file, or save content to a WAD file, but is entirely memory-resident.

Loading from WAD files

The following are all equivalent:

a = WAD('wadfile.wad')

a = WAD(from_file='wadfile.wad')

f = open('wadfile.wad', 'rb')
a = WAD(from_file=f)

a = WAD()

f = open('wadfile.wad', 'rb')
a = WAD()

You can load more than one file to the same object:

a = WAD()

In this case, lumps from file2 will overwrite those from file1 with the same name, etc.

Writing to WAD files

If a is a WAD instance:


Accessing lumps

Lumps are stored in groups. Each WAD holds a number of groups, representing different categories of lumps. Each group is an ordered dictionary; that is, it works just like a Python dict object but remembers in which order lumps were inserted

All lumps are instances of the Lump class; see below for its documentation

To retrieve the sprite called CYBR1A from the WAD object a, do:


And to replace it with some other lump object called some_lump:

a.sprites['CYBR1A'] = some_lump

To add a new lump, simply do as above with a lump name that does not yet exist.

Renaming and deleting is done as follows:

a.sprites.rename('CYBR1A', 'NEW_NAME')
del a.sprites['CYBR1A']

Lump groups

By default, WADs recognize the following lump groups:

Sprite graphics (between S and SS markers)
Wall graphics (between P and PP markers)
Flat graphics (between F and FF markers)
Boom colormaps (between C markers)
ZDoom textures (between TX markers)
Map data
GL nodes map data
Music (all lumps named D_*)
Sound effects (all lumps named DS* or DP*)
Titlepic, status bar, miscellaneous graphics
Everything else

This scheme can be modified if desired; refer to for the details.

The maps and glmaps are special. These do not contain lumps, but additional groups of lumps, one for each map. So if you access E1M1:


you will retrieve a group of lumps containing all the map’s data. To retrieve the individual lumps, do:




To merge two WADs a and b:

c = a + b

Note that (for efficiency reasons) this only copies references to lumps, which means that subsequent changes to lumps in a or b will affect the corresponding lumps in c. To give c its own set of lumps, do:

c = (a + b).copy()

When lumps in a and b have the same name, lumps from b will replace those from a.

It is also possible to merge individual sections:

a.sprites += b.sprites

Use with care for sections of different types.

Note that some sections do more than just copy over the list of lumps when they merge. For example, adding two txdefs sections together will automagically merge the TEXTURE1, TEXTURE2 and PNAMES lumps. txdefs also get merged this way when two WAD objects are merged on the top level.


The Lump class holds a single lump. The class provides the following data and methods:

The lump’s raw data as a string
Save from a file
Load from a file
Return a copy

Creating a new lump called ‘FOOF’ containing the text ‘Hello!’ and inserting it into a WAD w would be done as follows:['FOOF'] = Lump('Hello!')

Graphic lumps

There are subclasses of Lump for different types of lumps. Currently, only two of these provide special functionality: Graphic and Flat.

Graphic, used to represent Doom format graphics, provides the following settable attributes:

(x, y) offsets
x offset
y offset
(width, height)
width in pixels
height in pixels

Graphic defines the following methods in adddition to those defined by Lump:

Load from a raw image
Return the image converted to raw pixels
Load from a PIL Image instance
Return the image converted to a PIL image
Translate to another palette

For the argument lists used by these functions, refer to the code and the inline documenation in

Flat works similarly to Graphic, but handles format conversions slightly differently.


Editors are used to edit lumps or lump groups. They represent lump data with high-level objects and structures, and provide methods to modify the data. The following editors have been implemented so far:

  • Colormap for the COLORMAP lump
  • Playpal for the PLAYPAL lump
  • MapEditor for maps

All editors provide the following methods:


or, if the editor represents more than one lump:


In the latter case, the editor is initialized with a lump group instead of a single lump.

Map editor

Example (moving one vertex one unit):

m = MapEditor(wad.maps["E1M1"])
m.vertexes[103].x += 1
wad.maps["E1M1"] = m.to_lumps()

Refer to the source code for more information.