Note: this is ridiculously incomplete.
| Table of contents |
Optionally:
At the beginning of an interactive session, or as the first line in a Python script file, enter
from omg import *
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.
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()
a.from_file('wadfile.wad')
f = open('wadfile.wad', 'rb')
a = WAD()
a.from_file(f)
You can load more than one file to the same object:
a = WAD() a.from_file(file1) a.from_file(file2) a.from_file(file3)
In this case, lumps from file2 will overwrite those from file1 with the same name, etc.
If a is a WAD instance:
a.to_file('some_wad.wad')
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 collections.OrderedDict object.
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:
a.sprites['CYBR1A']
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']
By default, WADs recognize the following lump groups:
sprites Sprite graphics (between S and SS markers) patches Wall graphics (between P and PP markers) flats Flat graphics (between F and FF markers) colormaps Boom colormaps (between C markers) ztextures ZDoom textures (between TX markers) maps Map data udmfmaps Map data (UDMF) glmaps GL nodes map data music Music (all lumps named D_*) sounds Sound effects (all lumps named DS* or DP*) txdefs TEXTURE1, TEXTURE2 and PNAMES graphics Titlepic, status bar, miscellaneous graphics data Everything else
This scheme can be modified if desired; refer to wad.py 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:
a.maps['E1M1']
you will retrieve a group of lumps containing all the map's data. To retrieve the individual lumps, do:
a.maps['E1M1']['SIDEDEFS']
etc.
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:
.data The lump's raw data as a string .to_file(filename) Save from a file .from_file(filename) Load from a file .copy() 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:
w.data['FOOF'] = Lump('Hello!')
There are subclasses of Lump for different types of lumps. Currently, only these provide special functionality: Graphic, Flat, and Sound.
Graphic, used to represent Doom format graphics, provides the following settable attributes:
.offsets (x, y) offsets .x_offset x offset .y_offset y offset .dimensions (width, height) .width width in pixels .height height in pixels
Graphic defines the following methods in adddition to those defined by Lump:
.from_raw Load from a raw image .to_raw Return the image converted to raw pixels .from_Image Load from a PIL Image instance .to_Image Return the image converted to a PIL image .translate Translate to another palette
For the argument lists used by these functions, refer to the code and the inline documentation in lump.py.
Flat works similarly to Graphic, but handles format conversions slightly differently.
Sound, used to represent Doom format sounds, provides the following settable attributes:
.format Sound effect format (0-3) .length Length of sound in samples .sample_rate Sample rate for digitized sounds (defaults to 11025) .midi_bank MIDI patch bank number (formats 1-2 only) .midi_patch MIDI patch number (formats 1-2 only)
Sound defines the following methods in adddition to those defined by Lump:
.from_raw Load from a raw sound file .to_raw Return the sound file converted to raw samples .from_file Load from a sound file .to_file Save the sound to a file
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:
All editors provide the following methods:
.to_lump .from_lump
or, if the editor represents more than one lump:
.to_lumps .from_lumps
In the latter case, the editor is initialized with a lump group instead of a single lump.
Example (moving one vertex one unit):
m = MapEditor(wad.maps["E1M1"]) m.vertexes[103].x += 1 wad.maps["E1M1"] = m.to_lumps()
UMapEditor works similarly to MapEditor, except the attributes of map data are named based on how they appear in the TEXTMAP lump itself. See the UDMF specification for examples.
UMapEditor can also import non-UDMF maps, and line specials will automatically be translated to their UDMF equivalents when necessary:
# Load and automatically convert a Doom-format map m = UMapEditor(wad.maps["E1M1"]) # Load a UDMF-format map m = UMapEditor(wad.udmfmaps["MAP01"])
Refer to the source code for more information.