Getting Started with GZDoom Modding

Let us unpack what is happening here. You ran GZDoom with two files: freedoom2.wad and my_first_mod.zip. The first one is the IWAD, meaning the file that contains the base game. The second one is what is called a PWAD (short for patch WAD). The IWAD contained a texture lump (will explain later) named AQRUST08, and a map lump (among others) named MAP01, and instructions inside the map lump for the engine to paint that texture on a specific bunch of walls (with some offsets, lighting effects, etc.). This is what happens when you run GZDoom with just the IWAD freedoom2.wad by itself. But when you run the IWAD with this PWAD, which contains its own copy of the AQRUST08 texture (we’ll get into how I knew that later), the engine replaces all instances of that texture with the one from your PWAD. This is also why it was important to name the file exactly right. If you load two PWADs that both replace the same texture like so:

./gzdoom -iwad freedoom2.wad -file mod1.pk3 -file mod2.pk3

then the replacement texture from the last PWAD (mod2.pk3) will be used. Think of it as if the replacement instructions are executed serially, in the sequence of the files specified. For the rest of this guide, we will be naming the zip-archive file my_first_mod.pk3, but always remember that under the hood it is merely a zip file.

This is one reason I illustrated the command line method of launching GZDoom. Selecting multiple mod files and dragging-and-dropping them onto the GZDoom executable does not give you control over the mod load order. People routinely play games on GZDoom with 5-15 mods loaded at once, often in a specific order. Don’t worry. No one is actually typing out long commands. They are using launcher programs like ZDL or DoomRunner. I myself am partial to DoomRunner. Pick one and stick to it.

Most launcher programs allow saving of presets for various mod and order combinations. On first launch, they typically ask you to select engine executables, a list of IWADs, and the usual location for various kinds of PWADs like map packs. So you don’t have to put files in your GZDoom folder, or any other specific location. You should feel free to organize your files on your computer any way you see fit. Here is a view of my DoomRunner front page:

As you can see, I have highlighted a preset that I have named “Elementalism” that is using the GZDoom executable, the doom2.wad IWAD file, and a whole bunch of PWADs in a particular order. The lights.pk3 file from the GZDoom install is for dynamic lights (it doesn’t get loaded by default for performance reasons). Elementalism is an ambitious map pack, and Hellrider Vengeful is a weapons and player-movement mod. Here, I am adding a mod called Flashlight++ even though Hellrider already comes with a flashlight, because the maps in Elementalism have all been programmed to strip the player of all inventory items and pistol-start every level. And the flashlight in Flashlight++ happens to be unclearable using that method. If I were to try and and another mod that modifies weapons, like Beautiful Doom to this list, then the conflict with Hellrider will cause all weapons to be replaced by one mod and ammunition pickups be of the other. So not all mods are designed to go together. I mostly ignore DoomRunner’s separate map pack subwindow and load map-pack mods as regular mods, with full control over load order.

For the rest of this guide, I recommend picking a launcher program and launching GZDoom with my_first_mod.pk3 and freedoom2.wad just to develop good habits. Under the hood, all these Lauchers are just constructing and executing lengthy commands like the ones above.

Remember that my_first_mod.pk3 is really just a zip file. The file extension doesn’t matter, and only exists to help you. Modern GZDoom PWADs are named *.pk3 and IWADs are named *.ipk3 (we’ll get there). You might recall that the engine’s internal files that came with the GZDoom download (lights.pk3, brightmaps.pk3, game_support.pk3, etc.) are also *.pk3 files. These are the only ones that should not be moved out of the GZDoom executable’s folder.

Older mods, and mods made to be interoperable with source ports other than GZDoom aren’t zip files, but are instead of the WAD format. While GZDoom can read WAD files (the IWAD freedoom2.wad is a WAD file, after all), the best practice is to make mods as *.pk3 files (which are secretly zip files). Only levels/maps need to be in the old WAD format. More on that later.

Let us go through the contents of the ZSCRIPT.zsc file to see how this is achieved. The first line reads version "4.14". This is a necessary clause at the beginning of the ZSCRIPT lump, and signals a minimum version that your mod can now be run in. If you try and load my_first_mod.pk3 in GZDoom 4.13.2 with the ZSCRIPT.zsc file in, it should throw an error. This facility exists to ensure that mods that use new, advanced ZScript features don’t get accidentally launched by older versions of the engine, which would result in a crash.

Looking further down, even if you have no experience with programming, you can notice the pairs of curly brackets encapsulating content, which has been formatted with TAB-indentations for clarity. There is a master-pair of curly brackets “open” after the line that starts with the term “class”, and encapsulate everything else. This “everything else” is in the “class” “block”, or belongs to the “class”. Within the class, there are two other blocks: the Default block, and the States block. All of these are reserved keywords that the engine assigns special meaning to.

Classes are a very common structure within programming languages, and their complete definition is beyond the scope of this guide. But in this limited context, a class is a … well … class of entity that can exist in the game’s simulation. A class can be of various types: inventory item, monster, the player’s character (called a PlayerPawn), a flying rocket, a falling rain drop, or even an invisible “thinker”. Every entity within the game is an instantiation of some class. The engine “ticks” about 35 times every second, and during each “tick” it runs through the list of entities on the map and runs some standard “Tick()” functions belonging to their class definitions. There is a little more to that, but this is basically how the game runs. Physics collisions, actors interacting with each other and the map, etc., all happen in “ticks”, and there’s 35 of them in about a second.

If the last paragraph was hard to understand, that is okay. The most important thing about classes is that you can inherit properties from a parent class and then modify them. For the purposes of modding, the syntax for declaring a class object is:

class <NEW-CLASS-NAME> : <PARENT-CLASS-NAME> [ replaces <SOME-OTHER-CLASS-NAME> ]

The part between the square brackets [ & ] is optional (the square brackets themselves shouldn’t be typed). A new class doesn’t have to replace an existing class. The new definition can exist and operate independently. To use our own example, the line reads:

class MFM_Elixir : HealthBonus replaces HealthBonus

Here we have defined a new class with the name MFM_Elixir. The prefix MFM_ stands for “My first Mod” (the name of your mod). It is good practice to add a unique prefix to all new class definitions. That way, there will be no conflict when your mod is loaded along with another mod that might happen to have its own elixir class, since that is a common word. Anyway, this new class is of the type HealthBonus which plays the role of the parent class that all properties can be inherited from. This HealthBonus class is an existing class that is defined inside the engine itself. You can take a look at its definition in GZDoom’s source code here. The class HealthBonus has the class Health as its parent class (further down in the same file, you can see the definition for the StimPack class, which also has Health as a parent class). You can find the same class definition inside the gzdoom.pk3 file that came with the engine download. Find it using SLADE (zscript->actors->doom->doomhealth.zs), but remember the rule: do not modify the file. GZDoom automatically loads gzdoom.pk3 when you run it (which is why it should always be present the same folder as the executable).

Looking at the first few lines of class HealthBonus, you can see its Default and States blocks. We inherit these properties, and change some values within the Default block of our MFM_Elixir class definition. Namely, we changed something called Inventory.Amount from 1 to 5 (to make it give you 5 health points on pickup), and changed some other internal rendering properties like RenderStyle and StencilColor which affects how its sprites are rendered. And lastly, the States block is meant to contain the actor’s state labels, which contain a state sequence. And each state in the sequence is specified by the sprite to display, the time (in “ticks”) to remain in this state for, and any other functions that need to be run. In our example, MFM_Elixir class’s States block has a single state label (Spawn) just like its parent HealthBonus class. This marks the state sequence that all actors first enter when they are spawned on the map. The sequence line reads:

BON1 ABCDCB 3;

This tells the engine to display the sprites BON1A0, BON1B0, BON1C0, BON1D0, BON1C0, and BON1B0 again in that order, each for 3 ticks. The Loop; statement in the next line causes this sequence to repeat indefinitely. You can find these sprites inside freedoom2.wad using SLADE. The original HealthBonus class displayed each of these sprites for 6 ticks, which is why it was flashing at half the speed of MFM_Elixir.

Lastly, the replace HealthBonus clause instructed the engine to replace all instances of the HealthBonus item on any loaded map with MFM_Elixir. The replaced class doesn’t have to be the same as the parent class. You could, if you wanted to, replace all instances of the Zombieman class with MFM_Elixir. You can test the replacement effect by using console commands. Open the console while playing Freedoom 2 (by hitting the tilde “~” key below the Escape-key on your keyboard). This should pause the game and give you a command prompt. In it, type “summon MFM_Elixir” (without quotes) and hit ENTER. Now close the console by hitting the “~” key again. Provided that there is enough space in front of your player character, an instance of MFM_Elixir will have been spawned in front of you and will have fallen to the ground. If you repeat the exercise and try to summon HealthBonus instead, the replacement clause will cause another instance of MFM_Elixir to fall at your feet.

Let us remove the replacement clause by either deleting the words replace HealthBonus or by commenting them out by prefixing a double-slash like so:

class MFM_Elixir : HealthBonus // replaces HealthBonus

All text in a line that follows a double-slash “//” is treated as non-existent by the engine. So this is a great way to leave comments or notes-to-self all over your ZScript code to help yourself (and others) understand the code better. After doing this, you should be able to summon HealthBonus and summon MFM_Elixir via the console and watch both items flashing next to each other like so:

Let us leave the mod in a state where MFM_Elixir is NOT replacing HealthBonus for now, as we will be using this to learn something new in the “Basics of mapping” section later.

The sprites that we have explored so far: STIMA0, and the BON1[ABCD]0, all share a common feature. They all end in a “0”. The sprite names start with a 4-character string, followed by a single-character frame ID, and then a number. The two items that these sprites depict: StimPack and HealthBonus, both look the same from all directions. But we have seen sprited objects/actors in this game that look different from different angles (like the Zombieman). Let us try and understand how this is done. Let us replace the MFM_Elixir sprite sequence with another set of sprites from freedoom2.wad that also have the [ABCD] frames, but do not end with a “0” character. Replace the state-sequence line with:

HEAD ABCDCB 3;

Get back into the game and summon MFM_Elixir in a brightly lit region. Now walk around it and see how the sprite changes based on the angle. To make it clearer to see, comment out the RenderStyle line in the Default block and use a single sprite frame to keep it from animating:

HEAD A 1;

Now actually read the Angles and Mirroring sections from the Sprites wiki page. Look up the names of all the sprite lumps that start with the characters HEADA (there should be five of them). See if the names make sense in terms of in-game viewing angle. Do not proceed further until you have understood how sprite-naming convention can affect sprite rotations. You can get pretty close to smooth rotations if you use all 16-rotation characters, but at that point, especially if you have a lot of animations, you are better of learning to use 3D models.

Before proceeding, I want to confirm that you are not modifying the internal contents of my_first_mod.pk3 archive file using SLADE, but are directly modifying the files outside in your project folder and re-compressing the zip archive. The importance of this habit will become clear later.

For starters, do not click anything. Save the blank map inside the maps subfolder in your mod’s project folder. Give it a name like myfirstmap.wad. The top title of the UDB window should now say “myfirstmap.wad (MAP01)”. Now let us learn our first hotkeys. Press the L-key on your keyboard. The broad, bottom bar should now read Linedefs Mode instead of Vertices Mode. You can get back into Vertices Mode by pressing V. Pressing S should swap you to Sectors Mode, and hitting T will take you to Things Mode. Just practice changing between these various modes. What your left-click or right-click is able to do depends on what mode you are in. To draw or select lines, you will have to be in Linedefs Mode. To draw/select sectors, be in Sectors Mode, and so on. You can, of course, switch between these same modes by clicking on the appropriate button on the left panel. But I want you to get used to using hotkeys. By the end of year-two of Doom mapping, I want you to be able to match Bridgeburner’s hotkey prowess from this video. Write them down in a cheatsheet if you have to. You can, of course, change the default hotkeys to your preferred bindings later.

Right. Now let’s focus on the blank grid expanse in the center of the screen. This grid presents a top-down plan view of your map (which is empty right now). Here, you can use the mouse’s scroll wheel to zoom in and out. And if you hold down the spacebar-key, your mouse movements will cause the grid to pan. It might be hard to tell with the only fixed-point of reference being the plus-sign at the center/origin. So let’s create a point of reference by drawing a rectangular room somewhere. Press Ctrl + Shift + D to enter the Draw Rectangle Mode. Now left click somewhere in the blank grid a little bit to the top-left of center. Let go of the mouse button. Now move the mouse pointer towards the bottom-right until the rectangle being dragged open is a decent size (something over 256 \(\times\) 256 is good). Left click again. This should materialize the rectangle and kick you out of the Draw Rectangle Mode.

You are looking at the top-down view of your first room. All you can see is its floor texture (there is a button that switches it to show the ceiling texture in the top-down view, but I won’t tell you where it is!). This room has one Sector, four Vertices and four Lines. The Lines have a little notch at the center pointing inwards into the room. This notch tells you where the “front-side” of the line is. These four Lines are single-sided lines since their backs are facing the void. Now if you switch to Sectors Mode (S) and left-click on the room’s floor anywhere, you will “select” the sector. Press the C-key to cancel the selection. Switch to Linedefs Mode (L) and you will be able to select the lines by left-clicking on them. You can select multiple lines by drag selecting, or clicking on multiple of them in sequence. Again, hit the C-key to clear the selection. The C-key is your best friend.

When in any of these modes, if you right-click on the appropriate entity (and not in the void or empty region), you will bring up a window for its properties. If you had multiple entities selected before you right-clicked on one of them, the properties will collectively apply to all of them. If you accidentally right-click in the void (or within a Sector while in Linedefs Mode), you will start drawing lines. Hit the Escape-key to snap out of it. The Escape-key is your other best friend. If you right-click on a Line while in Vertices Mode you will create a new Vertex and split the Line into two Lines there. Hit Ctrl + Z to undo that action. Or select that Vertex while in Vertices Mode and Delete it.

Now, get into Linedefs Mode (L) and right-click on the top (North) Line of your room. It should bring of a properties window with tabs in a top row. Click on the Front tab (remember, this line is one-sided and doesn’t really have a Back-side). To the right you will see a column of three gray squares, with the middle square displaying a texture and a name like STARTAN1 or STARTAN2 (these are just the UDB defaults). Left-click on the middle square to bring up another window that allows you to select some other texture. It will show you all the available textures to choose from based on the resource files (freedoom2.wad, gzdoom.pk3, and my_first_mod.pk3) that you specified in the Game Configuration setting.

Scroll down until you see my_first_mod.pk3 in the list. Selecting it and then All will bring up three textures. If you recall, I used a custom image (of John Romero’s forehead) called John_Romero.png and then created a virtual texture lump in the TEXTURES.lmp patch called BIGDOOR1. The both of these, as well as our modified AQRUST08 texture are showing up as selectable options. Note that only the first-eight DOS-friendly characters of John_Romero.png show up. Let us select our modified AQRUST08 and apply it to the middle-texture slot of the Line. As far as playing is concerned, it doesn’t matter whether you use the AQRUST08 texture lump from freedoom2.wad or my_first_mod.pk3 here, as the mod ensures that the replacement gets applied in GZDoom. But for UDB to visually display the right one within its views, we might as well use our modified lump.

There is a checkbox for “Long Texture Names” in the Browse texture window. NEVER turn that on. It will store the absolute file-path to your texture file in the map wad instead of the short-lump name. It is better to use the lump names, as this keeps your mod … well … mod-able (both by yourself and others). If someone in the future makes a replacement mod that, say, replaces AQRUST08 with a higher-resolution version with PBR-material shaders for realistic lighting and reflections, that replacement won’t take effect on your map if it isn’t just using the simple lump name AQRUST08.

Okay great. We have a room with one wall painted with our modified texture. To actually make this map playable, we need to add a player-start Thing. Enter Things Mode (T) and right-click anywhere inside the room. This should, by default, place a Player 1 start “Thing” on the map and bring up its properties window. Here you can set the starting Angle you want the player to face and hit OK. If you accidentally placed additional Things, select them in Things Mode by left-clicking them and hit Delete (or use Ctrl + Z a bunch to undo recent steps).

Now just an empty room (albeit with some art on one of the walls) is boring. Let’s add some other Things for the player to interact with. While still in Things Mode, right-click at some corner of the room and expand the Monsters folder in the Things selection panel. You should be able to select an entry called $FN_ZOMBIE. Normally, this would have said “Former Human”. But since we added a class-replacement clause in our ZScript file for the ZombieMan class, UDB doesn’t know which resource file to prioritize. So it is trying to display a Tag Name, but is running into a LANGUAGE lump substitution bug (don’t worry about it, it might have gotten fixed by the time you read this). Anyway, select $FN_ZOMBIE and make sure that his Angle is facing away from the Player 1 start Thing so that he doesn’t get alerted as soon as the game starts. When you launch the game with your mod, the class replacement will automatically kick in, and you will be fighting an MFM_InviZombie. Similarly, scroll down to find the Health Bonus Thing and place it somewhere else in the room.

Now you might be wonder, how do we place our shiny MFM_Elixir Thing into the map. Even though we defined it, we removed the replacement clause (like I asked you to!). So it exists as a separate independent entity that can be summoned in the game from the console (and by killing the MFM_InviZombie class with weak bullets). But it is not available in this list for pre-placement on the map. To fix this, we have to give it an Editor Number. Leave UDB open in the background (minimize it or switch to a different workspace if your OS allows it). Now create a new file in your mod’s project folder called MAPINFO.lmp. In it, put the following text:

DoomEdNums
{
  20001 = "MFM_Elixir"
}

Map wad files aren’t storing Things in them by their entire definition. It only stores a Thing’s editor number (along with some map properties like starting angle). Most standard Things have a standard editor number that all Doom source ports and map editors respect (more or less). For GZDoom, as of this writing, all editor numbers between 11,000 to 14,000, and between 14,166 to 31,999 are available to modders for custom classes. Here, we have assigned the number 20001 to our custom MFM_Elixir class in a new (reserved name) lump file MAPINFO.lmp. Now re-zip the archive:

zip -r my_first_mod.pk3 textures/ TEXTURES.lmp sprites/ ZSCRIPT.zsc MAPINFO.lmp

I understand that this zip command is getting a bit long. I will present my solution to this problem later. For now, it is important to know what is (and what is not) going into the pk3. For example, I am still leaving out the maps folder that I had you create a while back in this section. Also, since we are editing these files, the editing software can sometimes create temporary or permanent backup copies of the files (usually with the same names and a tilde “~” character appended in the end). Make sure that you don’t accidentally zip those into the pk3 file.

Now return to UDB, navigate to the Tools popup menu and reload resources (F8-key) from your resource files (freedoom2.wad, etc.). Right-clicking in Things Mode again should allow you to scroll down to the User-defined folder and place the MFM_Elixir class in your map. The display sprite for it in UDB will be the same as that of the Health Bonus since we didn’t actually change its Spawn state sprite. We merely changed the rendering style, which is an engine thing, not a UDB thing.

The room is going to be fun for a while. But eventually, the player will want to leave it. Let’s add an exit button. Switch to Vertices Mode (V). Right click at two places on the northern Line of the room again to place two Vertices exactly 64 map-units apart (it should be easy if the grid-spacing is set to 32 mp at the bottom right). This splits the northern Line into three. Switch to Linedefs Mode (L) and right-click on the middle Line as shown to bring up its properties window. In the Front tab again, change the middle texture to a switch texture like SW1COMP (you can type it below the gray square without bringing up the Browse texture window). Any switch texture that is 64 units wide or greater is good here. Hit OK.

The switch is just a texture painted on the wall. You can’t activate it yet. Before we learn to make it do that, I want to introduce you to the visual mode in UDB. So far, we have been looking at our level in the top-down “plan” view. Here, we could switch amongst a bunch of “modes” and operate on the map. But you can look at your map in a 3D perspective from within UDB. Move your mouse cursor somewhere close to or inside the room, and hit the Q-key. Now look around using the mouse. Do you see your room? Don’t click on anything. Hit Q again to return to the “plan” view. Move the mouse cursor over to a different location and enter visual mode again (Q) to spawn your viewpoint at that new location.

In visual mode, you can actually fly the viewpoint through the map using the E-S-D-F keys by default (these are shifted by one key over to the right from the standard W-A-S-D movement keys for FPS games). While in visual mode, the “modes” have no meaning. The map-entity (walls, floors, ceilings, or Things) that the central cursor is pointing at will be highlighted with a pulsating orange glow, unless highlighting has been toggled off with the H-key. Anything you do (like hit keys or scroll the mouse wheel) will affect the entity highlighted, even if the highlighting effect has been visually turned off (hit H to turn it back on again). Like pressing the arrow-keys (with or without the Shift-key pressed) while a wall or floor is highlighted will offset its texture. The arrow-keys can move locations of highlighted Things. And the mouse wheel can raise or lower a highlighted floor or ceiling. People, epecially newcomers, find this behavior very frustrating. The way to avoid this problem is to actually select the entities you want to manipulate by left-clicking them (yes, while in visual mode). Selected objects pulsate in red, and you can selected multiple entities by sequential clicking on them (press your best friend the C-key to clear selection). When one or more entities are selected, hitting keys or scrolling the mouse wheel will now only manipulate the selected entities. Let’s practice doing it this way.

Find the middle-segment of the northern wall with the switch texture. Unless you really lucked out with your room Vertices location, it will most likely be misaligned as shown. Left-click on it while still in visual mode so that it pulsates with a red highlight instead of orange. Now use Shift plus the left or right arrow keys to change the texture offsets until you are satisfied with the alignment. Hit C to clear the selection and then Q to exit back to the “plan” view mode.

Now, to make the switch actually usable, we have to give that middle Line an action special. From Linedefs Mode, right-click on that line, and in the Properties tab, in the Action panel, you can click on the list icon to the right of the wide bar and search for the End Normal action special (or just type the number 243 in the smaller leftward box as shown). Then in the Activation panel, click on the “When player presses use” checkbox to tick it on. Hit OK. Now your Line will execute the action special End Normal defined in the UDMF map standard when the player presses the USE key while facing it (and is close enough). Note that we assigned this to the Line, and not the switch texture. That whole wall is technically the switch, and can be activated from any height (like from a ledge or ladder). That picture of that switch at the bottom is just for show. This is just how Doom works. If you want a height restriction, you will have to do something clever like a lowered ceiling and a recessed sector.

Save your map (Ctrl + S). Now to play it, I already committed to not showing you how to do it from within UDB. So we use the launcher program and add the map file myfirstmap.wad (it was saved in the maps subfolder of your mod’s project folder) to the list of mods in our preset. Then launch the game. You can (in my experience) do this while the map file is open in UDB. If you want to launch from a terminal command prompt instead, the command would be:

./gzdoom -iwad freedoom2.wad -file <PATH-TO-PROJECT-FOLDER>/my_first_mod.pk3 <PATH-TO-PROJECT-FOLDER>/maps/myfirstmap.wad

Voila. You are playing your map in the game. There is the MFM_Elixir, and the MFM_InviZombie. And that tempting switch. If you rush forward and hit it, the level MAP01 will end and the game will show you the intermission screen, and then load MAP02 for you.

You might have noticed that when you hit the level-exit switch, the level just ends. The switch didn’t actually visually flip, and there was no switching sound made. While this is okay for a level-exit switch (after all, there is no time for the sound to play), it will become problematic if you want to use that switch texture for other things (like opening doors) in other places on the map. Side-note: Typically, you are supposed to have a distinctive looking special switch for level exits that don’t look like other switches that do other things. A game-design aspect of visual clarity. But let’s leave that aside for now.

When I introduced the TEXTURES lump, I promised to show you how to slap a switch onto any wall texture. The switch textures on offer from freedoom2.wad (browse through them through UDB now instead of SLADE) all come with background wall textures, and none of them are on AQRUST08. Let’s fix that. In our TEXTURES.lmp file, we can define two new texture lumps by combining our modified AQRUST08.png file and two internal switch lumps called SW1S0 and SW1S1 from inside freedoom2.wad like so:

Texture MYSW1, 64, 128
{
  Patch "textures/AQRUST08.png", 0, 0
  Patch SW1S0, 16, 82
}

Texture MYSW1ON, 64, 128
{
  Patch "textures/AQRUST08.png", 0, 0
  Patch SW1S1, 16, 82
}

I have called these new virtual texture lumps MYSW1 and MYSW1ON, and their overall sizes are 64 \(\times\) 128 pixels. The patches are applied in the order they are specified, and I have carefully chosen the patch offsets to put the switch at the bottom center. Now, we create a new file with yet another reserved lump name: ANIMDEFS.lmp (be sure to not type “anime” by mistake). Its contents should be:

switch MYSW1 on sound Switch1 pic MYSW1ON tics 0
switch MYSW1ON off sound Switch2 pic MYSW1 tics 0

This is invoking internal sound lumps named Switch1 and Switch2 from inside freedoom2.wad, and telling the engine to treat our two new virtual textures as switches that are complementary states of each other. Now zip-up the whole thing again:

zip -r my_first_mod.pk3 textures/ TEXTURES.lmp sprites/ ZSCRIPT.zsc MAPINFO.lmp ANIMDEFS.lmp

In UDB, you can reload the resource files (F8) and change that one Line’s texture to the newly available MYSW1. Go into the visual mode and align the texture of that middle wall (and/or neighboring walls). Come out of visual mode. Save (Ctrl + S). Now launch the game again with your map. This time, assuming that your framerate is high enough, you should see the switch change states (and briefly hear the Switch1 sound effect) as the level ends.

Practice a small set of hotkeys over and over again until you get the hang of them. Then add one new hotkey for every new feature you learn. To review, watch this. And this and this.

Now let’s do some experiments. Open the launcher program again, and this time launch your mod with freedoom1.wad as the IWAD (I hope you didn’t delete that one after the download!). You will note that the game does not start you off on your custom map. It just starts you off in Freedoom 1’s regular maps, no matter which of the four “Episodes” you start with. In fact, you can play through the whole of Freedoom 1 and never encounter your map.

That is because Freedoom 1 instructs the engine to follow a different set of map lump naming conventions. If you start with Episode 1, the engine starts you off in map lump E1M1. The next map in the sequence is called E1M2. And so on. You can still tell the engine to force you into the map though. Launch with freedoom1.wad as the IWAD again, and this time, run `changemap MAP01` in the console. If you hit the level exit switch though, it will take you to the end credits sequence, since the IWAD freedoom1.wad doesn’t tell the engine what the next lump after MAP01 should be.

You can define your own sequence of maps and map lumps in your MAPINFO.lmp file. This is also where you would specify the level soundtracks, what sky texture to use for each level, give them fancy nicknames like “Hanger Base”, and so on. I won’t show you how, but know that this exists. And it doesn’t have to be a linear sequence of maps (with or without episodes) either. You can even specify clusters, with a central hub map and several “spoke” maps that you can travel to and return from. Godless Night is my favorite example of this structure. We will see an example PWAD that does this later.

Open myfirstmap.wad in SLADE. It can do it. It is a WAD file after all. You should see its insides:

It is simple, as it should be. Maps can get a little heavier that that later on, when you add more complicated things to your map, like ACS scripts, and Dialogue lumps. Remember that rule I had about not modifying anything through SLADE? This is where we break that rule. Rename the first marker lump from MAP01 to MAP02. Save. Do not change the actual WAD file name. Now launch the game again with freedoom2.wad. This time, you will have to play through the entire first level of the base game before it plops you into your custom map, which now has the lump name MAP02. And after you hit the exit switch in that, the engine will load MAP03 for you. You could have named it E1M1 and launched it with freedoom1.wad as well. Now change the name back to MAP01 again through SLADE (hit save before closing).

So far we have some texture/sprite replacements, and custom classes mod in a pk3 file (my_first_mod.pk3), and a map in a wad file (myfirstmap.wad). But can we smoosh them together? The pk3 format already has a way to do that. First, rename myfirstmap.wad to map01.wad (the file name has to match the lump name for this method). Then, just add the map file (along with the maps subfolder) to the zip archive:

zip -r my_first_mod.pk3 textures/ TEXTURES.lmp sprites/ ZSCRIPT.zsc MAPINFO.lmp ANIMDEFS.lmp maps/map01.wad

And you are done. Note that I specified the file name maps/map01.wad in full in the command instead of just the subfolder name maps/. This is because if you look inside the subfolder, you will see a lot of backup files that got created by UDB and SLADE when we opened the file in them. We don’t want these files ending up in our pk3 file. I could have specified a regular expression like maps/*.wad too to catch only the files that end in a .wad. In the end, the structure of your full my_first_mod.pk3 should be:

Now if you launch the game with just freedoom2.wad (or Doom2.wad) as the IWAD, and your mod my_first_mod.pk3 as the PWAD. No extra map file needed. You should be playing your mod in your map. You can create more maps, name them MAP02, MAP03, and so on, and package them all inside the maps subfolder in your pk3 file. There is some more work to be done if you want to make your own standalone IWAD. We will analyze some publicly available IWADs in SLADE later. But for all intents and purposes, you are now a certified doom modder. Now go create something!

The OTEX textures are a wildly popular option for modern megawads and mappacks. They are created by the veteran texture artist Ola “Ukiro” Björling, who has also made some famous Doom maps back in the day, and dabbles in music. If you’ve played through either of the Eviternity megawads, you’ve seen these textures. You can get them from this forum post on Doomworld. It links to a downloads’ page on Ukiro’s on website, wherein you can read his permissions text, and download links to both the *.wad and *.pk3 versions. Download the pk3 file and open it in SLADE. You should see this simple file structure inside:

All three folder names are reserved names, as is ANIMDEFS. The README.txt file contains the credits list, the redistribution permissions, a changelog, and some useful information about creating new textures using the png images inside the patches folder. You would do what you learnt regarding the TEXTURES lump in making the level-exit switch for you first map. Ukiro has been kind enough to not just share finished textures, but to make the raw patches public to allow anyone to mix and mash them into new textures.

The ANIMDEFS lump contains a short list of switches, just like we defined in the mapping segment for the level exit. Further down, it contains a bunch of texture sequences meant for animations:

For example, the first line is instructing the engine to animate the texture lumps OROCKO2A, OROCKO2B, OROCKO2C, and OROCKO2D by sequentially replacement every 4 ticks (remember that there are 35 ticks per second, see the wiki for the syntax). You can find these textures in the Textures folder and cycle through them to see how they animate. They constitute a pulsing, glowing, solidified lava surface. Further down in ANIMDEFS.txt you will find the line:

Flat	Optional	0ICYWA01	Range	0ICYWA08	Tics 5

The texture lumps 0ICYWA0x (x goes from 1 through 8) simulate an icy water surface (you can find these in the Flats folder). This is a great way to animate liquid-surface textures like water, nukage, lava, blood, or sewage goop. Every frame of these liquid textures is designed to tile seamlessly with themselves, so you can cover arbitrary shapes and sizes of contiguous areas with them.

If you are getting into mapping, adding the OTEX pk3 as a staple resource file (along with the UDB config on Ukiro’s website that helps arrange the textures into subcategories) will offer a great many inspiring set of textures to play with. Just be sure to include the pk3 file in your launcher too!

The IDKFA album (named after one of the cheat codes from the original Doom release) is a modern, metal reimagining of Bobby Prince’s original Doom 1 soundtrack. It was created by Andrew Hulshult, who has a lot of music credits in commercial games you may have heard of. The zip-download on the modDB page is around 720 MB large, but it includes the music in *.flac and *.mp3 format for your enjoyment outside of the engine. The actual IDKFAv2.wad file within is only 87 MB large. If you open this in SLADE, you will only find sound lumps with very specific names. These are the default soundtrack lump names from Doom 1 (and not Doom 2), and this is a simple lump-replacement wad. In case you don’t have Doom 1, you can play this with freedoom1.wad too, since the whole point of the FreeDoom project is to use all the same lump names.

If you open gzdoom.pk3 in SLADE and navigate to mapinfo->doom1.txt, below the GameInfo block and the episode definitions (Doom 1 and Freedoom 1 both arrange their levels into episodes), you will see the map definitions like so:

The music for map E1M1 is defined as the variable $MUSIC_E1M1, which is in turn defined in the language.def lump in the root directory. As a homework assignment, look up both mapinfo->doom2.txt and the language.def file for what to rename the first soundtrack in IDKFAv2.wad so that it plays on MAP01 in Doom 2 or Freedoom 2, even with your my_first_mod.pk3 (don’t forget the “D_” prefix).

Next we will look at a small weapon mod by Gothic. This pk3 file can be download from Realm667.com, which is a long-running repository of sorts for community creations. Before opening the mod in SLADE, I suggest just playing it in Freedoom 1 or 2 to get an idea of what is being implemented. Put the pk3 in you launcher mod list and start the game. Open the console and run summon bow. It should spawn a bow with ten arrows that you can collect (sits in weapon-slot 3). Now, if you press-and-hold the primary fire button, the bow gets drawn and remains drawn. If you let go, the arrow flies (and sticks to the wall for some time before disappearing). Run give arrowammo or summon arrowammo in the console if you run out of arrows. If you press-and-hold the alt-fire button (typically bound to the mouse right-click button), your screen gets an overlay like so:

Using the W-A-S-D movement keys while the alt-fire button is still pressed lets you select between four types of arrows. Letting go of the button will play a weapon-sprite animation and change your arrow type. The fire arrows explode, and the frost arrow freezes its target. You can then walk up to it and punch it to pieces!

This is obviously a fairly complex weapon. Analyzing the code for it will also be difficult with our current skill level. Luckily, Gothic has also included code for a simplified version of the weapon called BowSimple. You can summon this in the game by running give bowsimple. This gives you a simplified bow with no alt-fire magic abilities. This one hasn’t been bound to a weapon slot so don’t deselect the weapon!

Now we can open Bow.pk3 in SLADE. The file structure should look like so:

The big thing to point out here is the lump named DECORATE.txt. This is the older scripting language that ZScript has since superseded. You should learn and stick to ZScript, since it is more powerful and will see continuous development. But some of the older mods still have a lot of DECORATE code in them, and it is good to know how to look at it and parse it well enough. If you look at the contents of the DECORATE.txt file, you will see a definition for the Bow class at the top. But the syntax is very different from ZScript! The class-definition line is different, there is no Default block, and where are the semicolons!!

Let us skip past the Bow class and scroll down to line 212. Here is the code:

////Simplified Bow, if you just want a regular bow
Actor BowSimple : Weapon
{
  Inventory.PickUpMessage "Bow"
  Weapon.AmmoUse 1
  Weapon.AmmoGive 10
  Weapon.AmmoType "ArrowAmmo"
  Tag "Bow"
  //+WEAPON.NOALERT
  States
  {
  Spawn:
    BWPU A -1
    Stop
  Select:
    TNT1 A 0 A_ZoomFactor(1.0,ZOOM_INSTANT)
    DBOW A 1 A_Raise
    Loop
  Deselect:
    TNT1 A 0 A_ZoomFactor(1.0,ZOOM_INSTANT)
    DBOW A 1 A_Lower
    Loop
  Ready:
    DBOW A 1 A_WeaponReady
    Loop
  Fire:
    DBOW B 4
    DBOW C 4 A_StartSound("Bow/Hold",CHAN_WEAPON,CHANF_OVERLAP)
    Goto Hold
  Hold:
    DBOW D 1
    {
      if(GetPlayerInput(INPUT_BUTTONS) & (BT_ZOOM)) { A_ZoomFactor(4.0); }
      else { A_ZoomFactor(1.0); }
    }
    TNT1 A 0 A_Refire
    DBOW E 3 { A_ZoomFactor(1.0); A_Overlay(7,""); A_StartSound("Bow/Shoot",CHAN_WEAPON); A_FireProjectile("ArrowProj",0,true); }
    DBOW FBA 3
    Goto Ready
  }
}

The state block is using some standard state labels for weapons: Spawn, Select, Deselect, Ready, Fire, and Hold. You can guess what these standard states correspond to by their names (you can look up the sprites being used for some contextual help). The Fire state sequence is obviously entered when the fire button is pressed. The weapon then runs through the DBOWB0 and DBOWC0 sprites for 4-ticks each and plays the “Bow/Hold” sound lump, and transitions to the Hold state sequence. Here, there is an additional test to check if the zoom-in button is pressed (you can bind this to something like the Z-key from the options menu). And then there is a call to A_Refire(), a built-in action function that checks if the fire button is still being pressed, and returns the actor to the start of the Hold state sequence if so. This is the loop the weapon gets stuck in (with the bow drawn, held in DBOWD0 sprite) for as long as the fire button is pressed-and-held. But once it is released, the A_Refire check will fall through to the next line, where a sound lump (“Bow/Shoot”) is played and A_FireProjectile() is called with the projectile type “ArrowProj” (defined further down in the file, from line 255 onwards). The weapon turns through a three-sprite-frame run-down animation and returns to the Ready state sequence.

If you move the TNT1 A 0 A_Refire line to the end of the Hold state block just above the Goto Ready line, then the BowSimple weapon will lose its press-and-hold-fire-to-keep-bow-drawn property and instead fire a rapid succession of arrows (you can increase the number of ticks for one of the earlier sprite frames in the Hold block to drop the fire rate). You can even replace the projectile type to one of the predefined ones in gzdoom.pk3, like PlasmaBall, to have the bow fire that. A good exercise might be to move both the BowSimple and ArrowProj class definitions to your ZScript lump in my_first_mod.pk3 and convert the syntax over to ZScript to make it work with just your mod. You’ll need to modify the starting class-definition lines, add Default blocks, and throw in a whole bunch of semicolons. The GetPlayerInput(INPUT_BUTTONS) & (BT_ZOOM) check is also done differently in ZScript (player.cmd.buttons & BT_ZOOM). You could even add a slot number to the weapon in its Default block. Don’t forget to copy the sprites and sounds over (and credit Gothic). Note the two new (to you) built-in class types: Weapon and Projectile.

I had you skip the regular magic Bow class definition at the beginning of the file because it is more complicated. Feel free to glance at it. It has a whole bunch of non-standard custom state labels. And it uses a lot of dummy inventory items as tokens to keep track of what magic-arrow “mode” you are in, and do the conditional thing. DECORATE was really limited when it came to custom variables and functions, so giving and taking inventory tokens (and checking for their presence/absence) used to be the only way to institute conditional logic back in the day. We can look at a slightly simpler example of that concept in this next mod.

Now for some shameless self-promotion: we can analyze one of my own template mods. You can read my description of it from the forum post, but it is better to just play it (with freedoom2.wad). There is a 3D-model canoe in the starting level (in every level really) that you can “talk” to by pressing the “use” key in front of it. If you haven’t collected the world map (or the partial world map), it won’t give you any options. But if you had either of the maps, it should let you travel to any of the other levels shown in the map. I made four small template maps out of OTEX textures, and threw in some public-domain ambient soundscapes to sell the location.

I’ve hijacked the built-in character conversation/dialogue system (originally invented for Strife) that allows you to converse through dialogue trees with any actor. The maps have some interesting things too. If you open them in UDB and right-click on the lines at the edge of the sea, you’ll see the Line Horizon property being used, making the horizon look infinitely far away. Some other lines have the Block players flag on. Additionally, the sectors representing the floating ice sheets have the floor waggle function being called on them via ACS scripting (something we didn’t go over in this guide). And lastly, all the levels are setup to be in a hub cluster. This means that changes made to the level are persistent even if you leave them and return, even through saving and loading. You can test this by destroying the explosive barrels placed in some levels or writing your name in charred decals on the wall (use give plasmarifle and give cell in the console).

Let’s open the pk3 in SLADE and look inside. The file structure looks like so:

First, look into the mapinfo.lmp file. The block

clusterdef 1
{
  hub
}

declares the cluster “1” as a “hub” type. The four map blocks further below have all been assigned cluster = 1. The map blocks also have a “next =” line that has some other map assigned to each. I am not really using this feature, but this dictates the next map that the game would have loaded had I executed a line special like End Normal, just like you learned to do in the Basics of mapping section.

Next, look at the zscript.zc file in the root directory. It has the version string and two #include lines for two other ZScript files in some subfolders: zscript/fasttravelzc/CustomActors.zc and zscript/fasttravelzc/EventHandlers.zc. This is a great way to organize ZScript code into separate files instead of dumping it all into a single lump. I won’t go over the EventHandlers.zc file (it contains some code that dictates when, which, and how to draw the world-map images to the screen). Let’s look at the contents of CustomActors.zc. It opens with a class definition called Canoe of the type Actor. Within this, besides the Default block and the States block, there is a block we haven’t seen before:

override void Tick()
{
  Super.Tick();
  Vel.Z = 0.03*Sin(10*Level.Maptime);
}

This is “overriding” a virtual function called Tick() that was inherited from the parent class (Actor). This Tick() function gets called every tick by the engine (35 times a second). Inside it, I am running Super.Tick(), which basically runs the Tick() function from the parent, just to make sure nothing important gets missed. Then I am modulating the vertical velocity of the Canoe sinusoidally to simulate the boat bobbing in the water. I could have gotten some default bobbing behavior by flipping the “+FLOATBOB” flag in the Default block, but this approach gave me more control.

Further down the file, starting from line 29, I define a class named WorldMaps of type Inventory. It has some lengthy definition that we can skip past. Starting from line 91 onwards, I’ve defined two classes named WorldMapPartial and WorldMapFull, both of type WorldMaps (meaning they inherit all that lengthy definition that we skipped analyzing). They both sport a couple of custom Default block lines, and a couple of overrides for standard Inventory item functions. The HandlePickup() overrides make sure that WorldMapFull replaces WorldMapPartial in the inventory when picked up, and that WorldMapPartial cannot be picked up if the toucher already possesses an instance of WorldMapFull. The TryPickup() overrides are actually giving the toucher additional inventory items. The WorldMapPartial comes packaged with a FortBluePass item and a BrickPortPass item. WorldMapFull also awards those, along with an additional WasteProcPass item, and an ArcticBasePass item.

You might have noticed that these items bare the short-hand names of the four levels in this hub. Lines 145-170 show that these are dummy inventory tokens of a custom type: “Passport”. These are used by the canoe actor in deciding what options to make available to the player based on what passports the player has in their possession. More on that later.

Line 172 starts a lengthy definitions for yet another custom Inventory type class named FastTravelTicket. The code handles a screen fade on a timer, followed by a call to level.ChangeLevel(). Below this are four quick tickets defined (one for each level), all of type FastTravelTicket (and thus, inheriting its parent-class properties). These inventory items will begin a level-transition sequence as soon as they enter the player’s inventory, and destroy themselves once the transition is triggered. You can test this in the game. In the opening area, run give BrickPortTicket in the console to immediately begin transitioning into MAP02. These inventory items can even be placed/summoned into the map. They will be invisible since their Spawn state labels lack a sprite assignment, but if you run summon WasteProcTicket instead of give WasteProcTicket and then walk forward, you will “pick” the ticket up and transition to MAP03.

Lastly, let’s address the conversation/dialogue system. The detailed wiki article is pretty good, but the video tutorial by Chubz is more instructive. Towards the end, he introduces a shopkeeper mechanic and shows how the player’s inventory can be scanned for conditions (presence of a particular gun type or certain amount of currency) and conditionally display specific dialogue options based off of that. I have exploited this mechanic to check for possession of world map items (and passports), and conditionally display options to go to specific levels. You can look at the dialogue lump within, say, MAP01.wad in this pk3 by either opening it in UDB, or double-clicking on MAP01.wad in SLADE and having it open in a separate tab like so:

The Universal Strife Dialogue Format has its own unique syntax, but the terms use words from natural language in an intuitive manner. Terms such as link, ifitem, choice, require, and giveitem explain themselves.

To close this section off, let’s cover at least one IWAD (*.ipk3). Nash Muhandes is part of the engine Dev team, and has a big catalog of GZDoom projects. His MyStandaloneGame became the base template for a multitude of projects (it even got linked to on the wiki). It is launched by itself with GZDoom (meaning not with Freedoom 2 or Doom 2). Meaning:

./gzdoom -iwad MyStandaloneGame.ipk3

Judging by the version number in line 1 of the zscript.zc lump, this was originally created for GZDoom version 3.3.2. So launching it in modern GZDoom will throw out some warnings about the defcvars.txt lump trying to set some engine CVars that no longer exist. But the game will still launch. Among the new lumps in the root directory, the iwadinfo.lmp and the playpal.lmp lumps are the necessary ones for the engine to be able to recognize it as an IWAD. The playpal reserved name is meant for a palette lump. Since we have been using truecolor png files for textures and sprites, the playpal.lmp file can just be a dummy placeholder.

Inside the file zscript->MyStandaloneGamePlayer->MyStandaloneGamePlayer.zc is the definition of a class named MyStandaloneGamePlayer of type PlayerPawn. This is a special class for the actor that the player controls, and gets really complicated the more you dig into it. Nash has used his minimalist sprites to populate a whole bunch of standard state labels, which the engine will automatically transition the player into when certain conditions are met. And then the line in mapinfo.lmp that goes

PlayerClasses = "MyStandaloneGamePlayer"

assigns this PlayerPawn class to your player in this IWAD. You can actually play through MAP01 of Freedoom 2 as this player by running:

./gzdoom -iwad MyStandaloneGame.ipk3 -file freedoom2.wad

where freedoom2.wad is being interpreted as a PWAD despite being an IWAD. What happens when you get to the end of MAP01 and hit the exit switch? Can you think of the smallest change necessary to mapinfo.lmp that would let you transition from MAP01 to MAP02 of freedoom2.wad on level exit, instead of going to the end-credits? Try adding Next = "MAP02" (with the quotes) to the MAP block.

Try running:

./gzdoom -iwad MyStandaloneGame.ipk3 -file freedoom1.wad

Why didn’t the game start you in the starting level of Freedoom 1? Try running changemap E1M1 in the console. Does that reveal the problem? Now what about treating this ipk3 as a PWAD?

./gzdoom -iwad freedoom2.wad -file MyStandaloneGame.ipk3

What does the above command do? Or how about:

./gzdoom -iwad freedoom1.wad -file MyStandaloneGame.ipk3 -file freedoom2.wad

Watch out! The enemies and pickups now exist but your PlayerPawn doesn’t start with a weapon. Quick, run give shotgun in the console!

Much like in gaming, working consists of several nested state-loops operating over various timescales. And tiny discomforts or frustrations in the smallest loop can snowball over time into unpleasantness, and can cause us to not want to start/continue working without realizing why. It is important for the steps that are the smallest but are also repeated the most often to be as stress-free as possible. All micro-stressors should be eliminated. Just arranging your dedicated workstation at a comfortable desk and chair, and mounting the screen at mid-eye level while maintaining good posture can have a huge impact on your productivity. Have drinking water available on a different and/or lower platform to avoid spilling. If making/editing maps, drop the in-game music volume to zero and play some instrumental soundtracks in the background on your computer, so that it keeps playing constantly as you go back-and-forth between UDB and the engine. Reduced brightness and a low contrast between background and text also goes a long way when working with text.

Almost never having to move your arms maintains a low-latency between the act of desiring something of the computer and having it fullfilled. So avoid moving one hand to the mouse and back, or scanning and navigating popup menus, whenever possible. The OS-specific keyboard shortcuts for switching between windows (typically Alt + Tab and Shift + Alt + Tab) or switching workspaces (Ctrl + Alt + Arrow Keys) are a must if you are new to them. Much like web browsers, certain terminal programs support multiple tabs within the same window, which can be switched between with, typically, Alt + Number Key. Most terminals and command prompt programs also remember the history of commands, which can be revisited or cycled through by hitting the UP-Arrrow Key (or Ctrl + P if you are on Linux). Similarly, I use keyboard shortcuts to (a) move the cursor to the start/end of the line, (b) move cursor forward/backward by whole words, (c) delete rest of the word/command to the right of the cursor, (d) delete one word at a time, (c) hit Tab a bunch of times after having typed a “word” partially to either autocomplete it, or list available valid autocompletions. That Tab-completion trick is great for file-system navigation and typing out long file names. So I never find typing out commands frustrating. I can revisit a previously executed malformed command, navigate to the mistake, fix it and re-execute it with very few key presses without moving either of my wrists.

If you are new to coding, I suggest looking into IDEs. ZScript is not a complicated language, and you will never generate too many libraries and #include clauses but a good IDE can still be helpful. It’ll give you syntax highlighting, auto-indentation, code folding and fast intra- and inter-file navigation, and popup hints for function arguments/definitions and possible completions as you type them. Power-coders in the community swear by VSCode and have some extant packages available to configure it for ZScript. Someone even made a ZScript syntax highlighter for notepad++. I myself use Emacs on Linux. Text search/navigation and mass-text manipulation, managing multiple buffers and sub-windows, running a Bash terminal within Emacs, and setting it up to open *.zsc files in c-mode gives me most of what I need. With a little extra work, Emacs can be turned into a full IDE. Hell, this guide was written in Emacs (in org-mode markup and then a modified ox-tufte.el script with custom css headers for export to html, but I digress).

And get a good, wired, mechanical keyboard.

Throughout this guide, I have had you manually executing the zip command to generate the pk3 archive. You technically didn’t need to generate said archive, as GZDoom can work with whole folders. My purpose was two-fold: (a) most people, especially when new, conceptualize a mod as a single, share-able file. And (b) I didn’t want to bring up temporary backup files that programs like UDB, SLADE, and text editors (even Emacs) generate when working on files, which can duplicate code and throw errors. So a tool like zip was used to generate the archive with just the necessary, base files. However, the command kept getting longer and more complicated as we added more files and subfolders to the project. While you could create a shell-script or a *.bat file with the zip command in it, and run that every time, a better option is to use a makefile.

Linux comes built-in with a command line tool called make. On Windows, there are a bunch of routes to get it working. So I never run zip on my doom modding projects. After I make additions/changes to the code and assets, I run the make command from the project-folder location. The tool then looks for a file named makefile at that location, and executes the instructions therein. To illustrate with a real-world example, take a look at the project files in one of my publicly shared mods, an IWAD template for isometric-viewpoint games in GZDoom. Its makefile has the following contents:

BUILDDIR=build
ZIP=zip
ZIPFLAGS=-r -FS
ZIPEXCLUDES=-x '**~' 'build/*' '.*' 'makefile' '**.dbs' '**.backup*' '**.bak' '**.autosave*'
ZIPTARGET=$(BUILDDIR)/$(notdir $(CURDIR)).ipk3

TARGETS=$(BUILDDIR) $(ZIPTARGET)

.phony: all debug clean
all: $(TARGETS)

debug:
  @echo $(BUILDDIR)
  @echo $(ZIPTARGET)
  @echo $(ZIPEXCLUDES)

$(BUILDDIR):
  mkdir $(BUILDDIR)

$(ZIPTARGET) : *.* */*.obj */*.lmp */*.png */*.wav */*/*.png maps/*.wad *.zc */*/*.zc | $(BUILDDIR)
  $(ZIP) $(ZIPFLAGS) $(ZIPTARGET) * $(ZIPEXCLUDES)

Without knowing much about makefile syntax, you can kind-of guess what it is doing. There are a whole bunch of variables (all capitalized) at the start. The variable BUILDDIR is set to the text-string “build”. And there is a variable named ZIPEXCLUDES that lists a bunch of regular expressions for files to exclude from the archive (including makefile and the contents of the build subfolder). And there is a variable named ZIPTARGET which is using some internal make variables like CURDIR (stands for “current directory”). With this makefile in my project’s root folder, I can type make or make all to have the build subfolder automatically created if it didn’t exist, and execute the zip command for all of those file-types in the second-to-last line (with the excludes). make also keeps track of what files have changed since it last ran, so running make twice will not regenerate the archive (unlike a zip command), and only files that have been changed will get added to the archive. I can run make clean to delete the archive in case I need a fresh one built, and I use make debug to make sure that I have assigned the variables correctly (by having them printed out). I always start with a simple makefile in all of my projects and slowly grow its complexity with the project over time. If you want, you can even have make launch GZDoom and run your archive after it builds it. Some work will be needed to hide your local file structure from the makefile if you end up sharing your source code.

The commit history (which is stored in a very efficient, differences-only format by git) is collectively called a “repository” (or “repo” for short). The real power of version control starts to shine when you start using remote repositories. Meaning storing your project on a remote server that is accessible from any computer connected to the internet. That doesn’t necessarily mean that it is public, as you can have a private remote repo that requires a password or a cryptographic key. Famous public git repo servers that offer free accounts are Bitbucket, Gitlab, and the one this website is hosted on: Github. These are private companies (Github was acquired by Microsoft a while ago) that don’t have anything to do with the open-source software called git, though their employees might be developers. You could get a private repo going on Github if you get a paid account.

You can view the repo hosting this website by visiting https://github.com/dileepvr/gzdoom_modding_101. It is a barebones repo with very few files (the README.org file is a symbolic link to index.org) and one subfolder for images. The .gitignore file has only one line in it. To view the commit history with the dates, messages, and the last few characters of the hashes, click on “commits” below the green “code” button, or simply visit this link. This is just a linear chain with only the “master” branch, but you can checkout this repository and view earlier versions of the guide to see how it has evolved over time.

So to work on this website, my workflow is only slightly different from the one above. When I start, I run:

git pull
git checkout

before I begin. The git pull command pulls all the changes that the remote repo as accrued (very useful if you have multiple collaborators). After I am done for the day, I run the commit command, and then run:

git push

to push my latest commits to the remote repo. When I start working on it from, say, one of my other computers (like the laptop while traveling), I can git pull the changes that I pushed from my desktop earlier and continue working. I just need to remember to git push after I am done! If I want to start working in it on an entirely new computer that didn’t have the project repo to begin with, I run:

git clone git@github.com:dileepvr/gzdoom_modding_101.git

to clone the repo on my local machine, and then start cracking. You can clone any publicly available repo, by the way. You just won’t be able to push changes to it if you don’t have write-access.

The Github docs page contains instructions for starting a new repo. You can either create it on the website and clone locally, or start git init on the local machine and then push the first commit to your Github account. You may either use the website’s GUI, the git program’s GUI, or the command line to manage remote repos. You don’t have to push everything you commit either. You can have local branches that don’t get pushed to the remote repo (useful for clean, collaborative projects). When trying to merge two branches that have diverged too much, git can report a “merge conflict” and will create diffs inside files, giving you the opportunity to resolve the conflicts by making choices about which conflicting blocks of text to keep or discard. But that is an advanced topic.

The isometric-camera IWAD template that I mentioned earlier is also hosted on Github. This one has a “license.txt” file in addition to a “readme.org” file. Its commit history is also linear with no branches, but it has a couple of “tags” named “v1.0” and “v1.1” that I’ve designated as “Release candidates” using Github’s facility for the same. These were particularly stable commits that I was happy with. There is a “Releases” tab in the right-panel on the repo’s home page. The .gitignore file in this repo has a few more lines to cover the backup files created by programs like UDB and Slade.

Lastly, GZDoom itself is hosted on and actively developed on Github. It has over a hundred branches and tags (some of which are release versions). You can click on the “master” pull-down button to the top left in the home page to see some of the branch names. In the right-panel, you can see a list of the major contributors, some of whom can push to the repo directly. They have the keys to the engine source and make the major decisions. In the top, there is a tab for “Issues.” This is where anyone can report bugs or make feature requests that is visible to the public (and anyone can contribute to the discussion). Right next to it, there is a tab called “Pull Requests”, where contributions from third-party people like myself (who can’t push to the repo directly) are staged before they are either accepted or rejected. This is a Github feature (not a git feature), and other repo servers have similar collaborative tools. The work flow is:

1. “Fork” the GZDoom repo.
2. Clone the fork on my local machine.
3. Start a new branch and commit some work.
4. Push the branch to my forked repo.
5. Create a “pull request” to the main GZDoom repo on Github’s page.

At the time of writing, there are 581 forks of GZDoom. Most of them are likely just experiments from the past that have been abandoned by various people. But engine dev is sort of irrelevant to modding. I caught the GZDoom repo home page a few hours after one of my minor pull requests (“PR” for short) had been accepted. So the latest commit briefly showed my name: