Ruby-DOOM

If you want to generate a DOOM map, you need to use a level editor and manually create the map, either from scratch, or from a template. Although this works well for most map creation scenarios, it would be nifty if maps could be generated programmatically. This would allow maps to be generated for Cougaar agent community visualization, or PMD problem visualization, or from a floor plan.

Thus, Ruby-DOOM provides a scripting API for creating DOOM maps. It also provides higher-level APIs to make map creation easier.

Here's an example of what you can do with Ruby-DOOM:

User documentation

You'll need a couple of things to generate and play DOOM maps using Ruby-DOOM:

There are two ways to generate a map - both ways involve writing a small script in Ruby. This script will call various functions in the Ruby-DOOM API that will set up your map - walls, player position, etc. There are some examples in the examples.rb script in the release, but here are some more details.

Here's a script which will create a map from a monochrome uncompressed bitmap:

The important part is the Path.new line - that's where the map outline is specified using a series of directions and lengths separated by slashes - i.e., east 600, north 200, and so on. Note that the path needs to run clockwise, it must be a closed path (i.e., the last leg should stop at the starting point), and it can't cross back on itself.

After you've generated a map (i.e., a ".wad" file), you need to run it thru the aforementioned node builder. With DOOMBSP, this is as simple as:

./bsp new.wad -o out.wad

That's it! Your new map is ready to play - go shoot those barrels!

To make it easier to prototype stuff, you can also render small maps using a Nethack-style renderer, i.e.:

All long integers are 32 bit unsigned longs in little-endian format (shorts are signed, 16 bits, little-endian as well). So the byte sequence 212 2 0 0 is really 0 0 2 212 which translates to 724 decimal. I'm using the following Ruby snippet to do this transformation:

bytes.pack("C4").unpack("V")[0]

Also, I'm a bit of a dolt, so I had to do this to understand this byte packing order. 0 0 2 212 converted to binary is 00000000 00000000 00000010 11001010. So the 1 is in the 512 place, so 512 + 212 = 724.

Credits

John Carmack, John Romero and many other folks at Id Software for writing and then open sourcing DOOM

Matthew Fell - wrote the Unofficial DOOM specification

Alina Copeland - discussions of polygon types and structure

Legal

This section has been copied almost verbatim from the UDS. They put things so well there it seems a shame not to reuse their efforts. So, here we go:

Please make sure you have read id Software's LICENSE.DOC and README files that came with DOOM. Pertinent portions of those files are repeated here.

The LICENSE.DOC says:

"You shall not: rent, lease, sell, distribute for money or other consideration, modify, translate, disassemble, decompile, reverse engineer, or create derivative works based upon the Software. Notwithstanding the foregoing, you may create a map editor, modify maps and make your own maps (collectively referenced as the "Permitted Derivative Works") for the Software. You may not sell or distribute any Permitted Derivative Works but you may exchange the Permitted Derivative Works at no charge amongst other end-users. In order to commercially distribute any such map editor or data utility you must first sign id's Data Utility License and id reserves the right to deny authorization to commercial distribute the any such map editor or data utility. You may request a copy of the Data Editor License from id."

"(except for backup purposes) You may not otherwise reproduce, copy or disclose to others, in whole or in any part, the Software."

The README says:

"id Software respectfully requests that you do not modify the levels for the shareware version of DOOM. We feel that the distribution of new levels that work with the shareware version of DOOM will lessen a potential user's incentive to purchase the registered version."

"If you would like to work with modified levels of DOOM, we encourage you to purchase the registered version of the game."

If you are making add-ons, plan on them not working on the shareware game, and plan on including statements about the trademarks and copyrights that id Software owns, as well as disclaimers that they won't support your add-on product, nor will they support DOOM after it has been modified.