| 1 |
<html> |
| 2 |
<style> |
| 3 |
.tocindent { margin-left: 20px; } |
| 4 |
</style> |
| 5 |
<body> |
| 6 |
|
| 7 |
<h1>Omgifol manual</h1> |
| 8 |
|
| 9 |
<p><em>Note: this is ridiculously incomplete.</em> |
| 10 |
</p> |
| 11 |
<table border="0" id="toc"><tr id="toctitle"><td align="center"> |
| 12 |
<b>Table of contents</b> <script type="text/javascript">showTocToggle("show","hide")</script></td></tr><tr id="tocinside"><td> |
| 13 |
<div class="tocline"><a href="#Installation">1 Installation</a><br /></div> |
| 14 |
|
| 15 |
<div class="tocline"><a href="#Using_Omgifol">2 Using Omgifol</a><br /></div> |
| 16 |
<div class="tocline"><a href="#WAD_objects">3 WAD objects</a><br /></div> |
| 17 |
<div class="tocindent"> |
| 18 |
<a href="#Loading_from_WAD_files">3.1 Loading from WAD files</a><br /> |
| 19 |
<a href="#Writing_to_WAD_files">3.2 Writing to WAD files</a><br /> |
| 20 |
<a href="#Accessing_lumps">3.3 Accessing lumps</a><br /> |
| 21 |
<div class="tocindent"> |
| 22 |
<a href="#Lump_groups">3.3.1 Lump groups</a><br /> |
| 23 |
</div> |
| 24 |
<a href="#Merging">3.4 Merging</a><br /> |
| 25 |
</div> |
| 26 |
<div class="tocline"><a href="#Lumps">4 Lumps</a><br /></div> |
| 27 |
<div class="tocindent"> |
| 28 |
<a href="#Graphic_lumps">4.1 Graphic lumps</a><br /> |
| 29 |
</div> |
| 30 |
<div class="tocline"><a href="#Editors">5 Editors</a><br /></div> |
| 31 |
<div class="tocindent"> |
| 32 |
<a href="#Map_editor">5.1 Map editor</a><br /> |
| 33 |
<a href="#UDMF_map_editor">5.2 UDMF map editor</a><br /> |
| 34 |
|
| 35 |
</div> |
| 36 |
</td></tr></table> |
| 37 |
<a name="Installation"></a><h2>Installation</h2> |
| 38 |
<ol><li> Install Python 3, which can be downloaded from <a href="https://python.org" title="https://python.org">https://python.org</a> |
| 39 |
</li><li> Use pip to install Omgifol: <tt>pip install omgifol</tt> |
| 40 |
</li><li> Or, if pip is unavailable, extract the "omg" directory in the Omgifol package into <em>pythondir</em>/Lib/site-packages (replace <em>pythondir</em> with the directory where Python is installed). |
| 41 |
</li></ol> |
| 42 |
<p>Optionally: |
| 43 |
|
| 44 |
</p> |
| 45 |
<ol><li> Install the <a href="https://python-pillow.github.io" class="external" title="https://python-pillow.github.io">Pillow library</a><span class="urlexpansion"> (<i>https://python-pillow.github.io</i>)</span>. This is required to import or export images. |
| 46 |
</li> |
| 47 |
<li> Install the <a href="https://pysoundfile.readthedocs.io" class="external" title="https://pysoundfile.readthedocs.io">PySoundFile library</a><span class="urlexpansion"> (<i>https://pysoundfile.readthedocs.io</i>)</span>. This is required to import or export sound files. |
| 48 |
</li> |
| 49 |
</ol> |
| 50 |
|
| 51 |
<a name="Using_Omgifol"></a><h2>Using Omgifol</h2> |
| 52 |
<p>At the beginning of an interactive session, or as the first line in a Python script file, enter |
| 53 |
</p> |
| 54 |
<pre> from omg import * |
| 55 |
</pre> |
| 56 |
<a name="WAD_objects"></a><h2>WAD objects</h2> |
| 57 |
<p>A <tt>WAD</tt> is an abstract representation of a WAD file. A <tt>WAD</tt> object can load content from a WAD file, or save content to a WAD file, but is entirely memory-resident. |
| 58 |
|
| 59 |
</p> |
| 60 |
<a name="Loading_from_WAD_files"></a><h3>Loading from WAD files</h3> |
| 61 |
<p>The following are all equivalent: |
| 62 |
</p> |
| 63 |
<pre> a = WAD('wadfile.wad') |
| 64 |
|
| 65 |
a = WAD(from_file='wadfile.wad') |
| 66 |
|
| 67 |
f = open('wadfile.wad', 'rb') |
| 68 |
a = WAD(from_file=f) |
| 69 |
|
| 70 |
a = WAD() |
| 71 |
a.from_file('wadfile.wad') |
| 72 |
|
| 73 |
f = open('wadfile.wad', 'rb') |
| 74 |
a = WAD() |
| 75 |
a.from_file(f) |
| 76 |
</pre> |
| 77 |
<p>You can load more than one file to the same object: |
| 78 |
</p> |
| 79 |
<pre> a = WAD() |
| 80 |
a.from_file(file1) |
| 81 |
a.from_file(file2) |
| 82 |
a.from_file(file3) |
| 83 |
</pre> |
| 84 |
<p>In this case, lumps from <em>file2</em> will overwrite those from <em>file1</em> |
| 85 |
|
| 86 |
with the same name, etc. |
| 87 |
</p> |
| 88 |
<a name="Writing_to_WAD_files"></a><h3>Writing to WAD files</h3> |
| 89 |
<p>If <em>a</em> is a <tt>WAD</tt> instance: |
| 90 |
</p> |
| 91 |
<pre> a.to_file('some_wad.wad') |
| 92 |
</pre> |
| 93 |
<a name="Accessing_lumps"></a><h3>Accessing lumps</h3> |
| 94 |
|
| 95 |
<p>Lumps are stored in <em>groups</em>. Each <tt>WAD</tt> holds a number of groups, representing different categories of lumps. Each group is an ordered dictionary; that is, it works just like a Python <tt>collections.OrderedDict</tt> object. |
| 96 |
</p><p>All lumps are instances of the <tt>Lump</tt> class; see below for its documentation. |
| 97 |
|
| 98 |
</p><p>To retrieve the sprite called <tt>CYBR1A</tt> from the <tt>WAD</tt> object <em>a</em>, do: |
| 99 |
</p> |
| 100 |
<pre> a.sprites['CYBR1A'] |
| 101 |
</pre> |
| 102 |
<p>And to replace it with some other lump object called <tt>some_lump</tt>: |
| 103 |
</p> |
| 104 |
|
| 105 |
<pre> a.sprites['CYBR1A'] = some_lump |
| 106 |
</pre> |
| 107 |
<p>To add a new lump, simply do as above with a lump name that does not yet exist. |
| 108 |
</p><p>Renaming and deleting is done as follows: |
| 109 |
</p> |
| 110 |
<pre> a.sprites.rename('CYBR1A', 'NEW_NAME') |
| 111 |
del a.sprites['CYBR1A'] |
| 112 |
</pre> |
| 113 |
<a name="Lump_groups"></a><h4>Lump groups</h4> |
| 114 |
<p>By default, WADs recognize the following lump groups: |
| 115 |
</p> |
| 116 |
<pre> sprites Sprite graphics (between S and SS markers) |
| 117 |
patches Wall graphics (between P and PP markers) |
| 118 |
flats Flat graphics (between F and FF markers) |
| 119 |
colormaps Boom colormaps (between C markers) |
| 120 |
ztextures ZDoom textures (between TX markers) |
| 121 |
maps Map data |
| 122 |
udmfmaps Map data (UDMF) |
| 123 |
glmaps GL nodes map data |
| 124 |
music Music (all lumps named D_*) |
| 125 |
sounds Sound effects (all lumps named DS* or DP*) |
| 126 |
txdefs TEXTURE1, TEXTURE2 and PNAMES |
| 127 |
graphics Titlepic, status bar, miscellaneous graphics |
| 128 |
data Everything else |
| 129 |
</pre> |
| 130 |
<p>This scheme can be modified if desired; refer to wad.py for the details. |
| 131 |
|
| 132 |
</p><p>The <tt>maps</tt> and <tt>glmaps</tt> are special. These do not contain lumps, but additional groups of lumps, one for each map. So if you access E1M1: |
| 133 |
</p> |
| 134 |
<pre> a.maps['E1M1'] |
| 135 |
</pre> |
| 136 |
<p>you will retrieve a group of lumps containing all the map's data. To retrieve |
| 137 |
the individual lumps, do: |
| 138 |
</p> |
| 139 |
<pre> a.maps['E1M1']['SIDEDEFS'] |
| 140 |
</pre> |
| 141 |
<p>etc. |
| 142 |
|
| 143 |
</p> |
| 144 |
<a name="Merging"></a><h3>Merging</h3> |
| 145 |
<p>To merge two <tt>WAD</tt>s <em>a</em> and <em>b</em>: |
| 146 |
</p> |
| 147 |
<pre> c = a + b |
| 148 |
</pre> |
| 149 |
<p>Note that (for efficiency reasons) this only copies references to lumps, |
| 150 |
which means that subsequent changes to lumps in <em>a</em> or <em>b</em> will affect the |
| 151 |
corresponding lumps in <em>c</em>. To give <em>c</em> its own set of lumps, do: |
| 152 |
|
| 153 |
</p> |
| 154 |
<pre> c = (a + b).copy() |
| 155 |
</pre> |
| 156 |
<p>When lumps in <em>a</em> and <em>b</em> have the same name, |
| 157 |
lumps from <em>b</em> will replace those from <em>a</em>. |
| 158 |
</p><p>It is also possible to merge individual sections: |
| 159 |
|
| 160 |
</p> |
| 161 |
<pre> a.sprites += b.sprites |
| 162 |
</pre> |
| 163 |
<p>Use with care for sections of different types. |
| 164 |
</p><p>Note that some sections do more than just copy over the list of lumps |
| 165 |
when they merge. For example, adding two <em>txdefs</em> sections together |
| 166 |
will automagically merge the <tt>TEXTURE1</tt>, <tt>TEXTURE2</tt> and <tt>PNAMES</tt> lumps. <tt>txdefs</tt> |
| 167 |
|
| 168 |
also get merged this way when two <tt>WAD</tt> objects are merged on the top level. |
| 169 |
</p> |
| 170 |
<a name="Lumps"></a><h2>Lumps</h2> |
| 171 |
<p>The <tt>Lump</tt> class holds a single lump. The class provides the following data and methods: |
| 172 |
</p> |
| 173 |
<pre> .data The lump's raw data as a string |
| 174 |
.to_file(<em>filename</em>) Save from a file |
| 175 |
.from_file(<em>filename</em>) Load from a file |
| 176 |
.copy() Return a copy |
| 177 |
|
| 178 |
</pre> |
| 179 |
<p>Creating a new lump called 'FOOF' containing the text 'Hello!' and inserting it into a <tt>WAD</tt> <em>w</em> would be done as follows: |
| 180 |
</p> |
| 181 |
<pre> w.data['FOOF'] = Lump('Hello!') |
| 182 |
</pre> |
| 183 |
<a name="Graphic_lumps"></a><h3>Graphic lumps</h3> |
| 184 |
<p>There are subclasses of <tt>Lump</tt> for different types of lumps. Currently, only these provide special functionality: <tt>Graphic</tt>, <tt>Flat</tt>, and <tt>Sound</tt>. |
| 185 |
|
| 186 |
</p><p><tt>Graphic</tt>, used to represent Doom format graphics, provides the following settable attributes: |
| 187 |
</p> |
| 188 |
<pre> .offsets (x, y) offsets |
| 189 |
.x_offset x offset |
| 190 |
.y_offset y offset |
| 191 |
.dimensions (width, height) |
| 192 |
.width width in pixels |
| 193 |
.height height in pixels |
| 194 |
</pre> |
| 195 |
<p><tt>Graphic</tt> defines the following methods in adddition to those defined by <tt>Lump</tt>: |
| 196 |
</p> |
| 197 |
<pre> .from_raw Load from a raw image |
| 198 |
.to_raw Return the image converted to raw pixels |
| 199 |
.from_Image Load from a PIL Image instance |
| 200 |
.to_Image Return the image converted to a PIL image |
| 201 |
.translate Translate to another palette |
| 202 |
</pre> |
| 203 |
<p>For the argument lists used by these functions, refer to the code and the inline documentation in lump.py. |
| 204 |
</p><p><tt>Flat</tt> works similarly to <tt>Graphic</tt>, but handles format conversions slightly differently. |
| 205 |
|
| 206 |
</p><p><tt>Sound</tt>, used to represent Doom format sounds, provides the following settable attributes: |
| 207 |
</p> |
| 208 |
<pre> .format Sound effect format (0-3) |
| 209 |
.length Length of sound in samples |
| 210 |
.sample_rate Sample rate for digitized sounds (defaults to 11025) |
| 211 |
.midi_bank MIDI patch bank number (formats 1-2 only) |
| 212 |
.midi_patch MIDI patch number (formats 1-2 only) |
| 213 |
</pre> |
| 214 |
<p><tt>Sound</tt> defines the following methods in adddition to those defined by <tt>Lump</tt>: |
| 215 |
</p> |
| 216 |
<pre> .from_raw Load from a raw sound file |
| 217 |
.to_raw Return the sound file converted to raw samples |
| 218 |
.from_file Load from a sound file |
| 219 |
.to_file Save the sound to a file |
| 220 |
</pre> |
| 221 |
|
| 222 |
|
| 223 |
</p> |
| 224 |
<a name="Editors"></a><h2>Editors</h2> |
| 225 |
<p><em>Editors</em> 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: |
| 226 |
</p> |
| 227 |
<ul><li> <tt>Colormap</tt> for the COLORMAP lump |
| 228 |
</li><li> <tt>Playpal</tt> for the PLAYPAL lump |
| 229 |
</li><li> <tt>Textures</tt> for TEXTURE1/TEXTURE2/PNAMES |
| 230 |
|
| 231 |
</li><li> <tt>MapEditor</tt> for maps |
| 232 |
</li><li> <tt>UMapEditor</tt> for maps in UDMF format |
| 233 |
</li></ul> |
| 234 |
<p>All editors provide the following methods: |
| 235 |
</p> |
| 236 |
<pre> .to_lump |
| 237 |
.from_lump |
| 238 |
</pre> |
| 239 |
<p>or, if the editor represents more than one lump: |
| 240 |
</p> |
| 241 |
<pre> .to_lumps |
| 242 |
.from_lumps |
| 243 |
</pre> |
| 244 |
<p>In the latter case, the editor is initialized with a lump group instead of a single lump. |
| 245 |
</p> |
| 246 |
|
| 247 |
<a name="Map_editor"></a><h3>Map editor</h3> |
| 248 |
<p>Example (moving one vertex one unit): |
| 249 |
</p> |
| 250 |
<pre> m = MapEditor(wad.maps["E1M1"]) |
| 251 |
m.vertexes[103].x += 1 |
| 252 |
wad.maps["E1M1"] = m.to_lumps() |
| 253 |
</pre> |
| 254 |
|
| 255 |
<a name="UDMF_map_editor"></a><h3>UDMF map editor</h3> |
| 256 |
<p><tt>UMapEditor</tt> works similarly to <tt>MapEditor</tt>, except the attributes of map data are named based on how they appear in the <tt>TEXTMAP</tt> lump itself. See the <a href="https://www.doomworld.com/eternity/engine/stuff/udmf11.txt">UDMF specification</a> for examples. |
| 257 |
</p> |
| 258 |
<p><tt>UMapEditor</tt> can also import non-UDMF maps, and line specials will automatically be translated to their UDMF equivalents when necessary: |
| 259 |
</p> |
| 260 |
<pre> # Load and automatically convert a Doom-format map |
| 261 |
m = UMapEditor(wad.maps["E1M1"]) |
| 262 |
|
| 263 |
# Load a UDMF-format map |
| 264 |
m = UMapEditor(wad.udmfmaps["MAP01"]) |
| 265 |
</pre> |
| 266 |
<p>Refer to the source code for more information.</p> |
| 267 |
</body> |
| 268 |
</html> |