A BRIEF GUIDE TO MAKING NEW NETHACK LEVELS Version 1.0 Jan 11, 2003 Rob Ellwood rob.ellwood@shaw.ca This is a short version of "Making New Levels". The full writeup assumes that you barely know how to edit a text file. This one assumes that you know your way around a computer. The section numbers here match those of the full writeup. If you need more details on something, go to the full writeup. 1.0 Stuff to download: Get the full writeup of "Making New Levels" from my site. I refer to sections of it. (If I copicd all the background info to here, the two files would soon get out of sync.) http://members.shaw.ca/rob.ellwood/ You need the existing .des files (level design files), plus dungeon.def (which says where each special level goes). Download the source at: http://nethack.org/ You're only interested in the /dat/ folder and maybe the /doc/ folder. You need four programs to add new levels: lev_comp.exe Compiles your level design files. makedefs.exe Makes minor changes to dungeon.def. dgn_comp.exe Compiles the changed dungeon.def. dlb_main.exe Combines data files into one big file. I've got precompiled versions of these for the Official DOS and Windows binaries at my site. lev_comp *must* match whichever version of Nethack you're using. Put the programs in the /dat/ folder. 2. General info: Look at a random .des file. o Lines starting with # are comments. o Ignore levels starting with "LEVEL:"; only look at levels which start with "MAZE:" and have ASCII maps. ("LEVEL:" means that it's a room-type level. These are hard to build.) o The ASCII maps define the walls, non-secret doors, and a few other things. o Next, there's a long list of commands, placing all the objects, monsters, and a few other things. o (0,0) is the upper left corner of the map. In a map, if the first character of a line is a number, it's ignored. This lets you number each line, which is easier than counting line numbers every time you add a command. 3. Making a level: You'll usually add your level to an existing .des file. Grab the template map from appendix 3 of the full writeup. Above and below the template map are the usual commands. The commands above the map have to go *before* the map, in the order given. To get you started, section 2.4.1 of the full writeup has some example commands. For full details on a command, see appendix 7. (Things in square brackets, like [lighting], are defined in appendix 6.) Appendix 5 has tables and lists: 5.1 Terrain symbols 5.2 Object symbols 5.3 Monster symbols 5.4 Types of traps 5.5 Types of rooms 4. Compiling the .des file: Open a DOS window. Move to the /dat/ folder. To confirm that everything is OK, enter: lev_comp barb.des You should now have several bar*.lev files. Try compiling the .des file you edited. You'll almost certainly get some error messages for trivial errors. Fix them and recompile. (The first time, I found this painfully tedious, but straightforward.) Section 4.4 of the full writeup explains what causes the most common errors. Section 7.1 lists some more errors (and I should combine it with 4.4). 5. Telling Nethack where your level goes: Edit dungeon.def. 5.1.1 If You Changed An Old Level Jump ahead to section 6. 5.1.2 If You Added A Variant Of An Old Level RNDLEVEL: "bigrm" "B" @ (10, 3) 40 5 The very last number is the number of versions of the file. If you created a "bigrm-6", increase the number from 5 to 6. If the level originally only had one version, and you're adding two more, you change a LEVEL command to RNDLEVEL: LEVEL: "juiblex" "J" @ (4, 4) becomes: RNDLEVEL: "juiblx" "J" @ (4, 4) 3 The .lev file names can only be 8 characters long, so "juiblex" was changed to "juiblx". In the .des file, change the name of the original level from "juiblex" to "juiblx-1". The new levels will be "juiblx-2" and "juiblx-3". 5.1.3 If You Added A New Level LEVEL: [level name prototype] [special letter of bones files] '@' '(' [earliest level] [range of levels it can be on] ')' ...or RNDLEVEL if you already have more than one version of your new level. The special level for bones files must be unique for the dungeon that the level belongs in. As of 3.4.0, the main dungeon uses "R", "O", and "B". 5.1.4 If You Added A New Branch A branch is a complete set of levels. The Gnomish Mines is a branch. The quest levels are branches. See section 8 of the full writeup. 5.2 Run makedefs makedefs -e ...and you should now have a new dungeon.pdf file. (If your folder isn't named \dat, you get an error message: "../dat/dungeon.def: No such file or directory (ENOENT)" ) 5.3 Run dgn_comp dgn_comp dungeon.pdf ...and you should get a new dungeon file: a file called "dungeon" with no extension. (If you get an error message, ignore the line number. It claims the first non-comment line contains the error, which is rarely true. Just check the line you changed for typos.) 6.0 Adding your level to Nethack dlb_main (or dlb for unix) is the data librarian. It collects a lot of small data files into one big file, called "nhdat". I've got a collection of add-on levels called New Toys. If your copy of Nethack has a version of New Toys from 2003 or later, just copy your new *.lev and "dungeon" files over to your Nethack folder and you're done. Otherwise: 6.2 Test dlb_main Your Nethack folder has a file called "nhdat". Put a copy of it in the \dat folder, then: dlb_main tv Several screens of information should flash by. The last screen should show the names of some of the files in the \dat folder. The very last line should look something like: Revision:1 File count:129 String size:1667 If you get something close to this, continue to the next step. 6.3 Getting Ready Background: the data librarian needs a file DLB.LST, which lists all of the files stored in nhdat. An old DLB.LST is no good, because you've probably added levels, which adds new .lev files. This setup procedure creates a new DLB.LST file. Once you've done this step, you only have to repeat it if you add a new level to a .des file (which lev_comp turns into a new .lev file). 1. Create a new folder under \dat called dlb. (If you already have it, delete everything in it, just to be safe.) 2. Copy nhdat and dlb_main.exe to the new folder. 3. Go into the new folder and enter this command: dlb_main x About 100 files will show up. (Your windows folder won't show them until you use View Refresh.) 4. Copy your new .lev files into the new folder. You'll have one new .lev file for every level you added. 5. Delete nhdat and dlb_main.exe from the new folder. 6. Enter this command: dir /b > ..\DLB.LST Confirm that the \dat folder now have a DLB.LST file. 7. Copy DLB.LST and dlb_main.exe to the new folder. 6.4 Procedure 1. If you've created any new levels since you did the "getting ready" procedure in section 6.3, then go back to 6.3 and do it again. 2. You probably changed dungeon.def back in section 5. If so, then copy your new dungeon file into the \dlb folder. (That file is "dungeon", without a filename extension.) 3. Copy any new or changed .lev files into the \dlb folder. (Reminder: every level you worked on gets a .lev file. If you worked on three levels in the same .des file, you will have three .lev files to copy, not just one.) 4. Enter this command: dlb_main cI DLB.LST Confirm that you have a nhdat file with today's date. It should be a bit over half a megabyte. 4. Copy the new nhdat file over to whatever directory you play Nethack out of. 7.0 Testing your level The main writeup explains wizard mode, if you haven't already used it. After fixing errors in the .des file, recompile, then go to step 3 of section 6.4. If you fix up your .des file, come back, and the errors are still there, you probably forgot one of these steps: o Run lev_comp. If there are errors, fix them and try again. o Copy the new .lev file to \dlb. o Enter dlb_main c to get a new nhdat file. o Copy nhdat to your Nethack directory. 10.0 Tricks and ideas In the full writeup. I suggest ignoring it until you've built at least one level.