29 September 2012

Become a Software Engineer by modding Fallout 3 - Tutorial Part 1

I recently started modding Fallout 3 which is a lot of fun and a painful experience at the same time. But before I start to explain why there is so much pain when modding Fallout 3 let me tell you first what you may expect from this post.

I am no veteran in game modding. The Universal Whiz Perk is the very first mod I ever created. But I am a software engineer with more than 25 years of experience in software development and a passionate gamer.

This blog tries to explain in detail what I learned after creating my first mod, which tools I used and why they are helpful. Which concepts in Fallout 3 are related to concepts in object oriented or procedural programming and how to avoid the many traps found along the way when creating a mod. But most importantly: I will tell you a lot about principles and practices used today by professional software engineers.

If all this sounds interesting to you, you might enjoy the post. So keep reading. Otherwise the chances, you won't like the rest of this post and get bored soon, are high. It's up to you ... make your choice!

Where does all the pain come from?

If you work as a professional software engineer you are used to the comfort and feature richness modern IDEs like Eclipse, Visual Studio or IDEA provide. Don't expect anything close to it from your main modding tool G.E.C.K. (The Garden Eden Construction Kit). This tool is just as rudimentary as a minimal productive development tool could be. For example: there are some editor windows (not only one) used to edit scripts which do not resize their editing region when resized. Damn! That's horrible, isn't it?!

The scripting language used in modding Fallout 3 has been reduced to a bare minimum of commands, leading to lots of code duplication. There is no language construct for a loop! You can't define your own functions or procedures. I suggest you install FOSE (Fallout Script Extender) to enhance your modding experience. It adds the commands label and goto to the scripting language providing a way to define loops and mighty branching. But when overused it increases complexity and reduces readability instead of improving readability and reducing duplication of code, which you want to avoid as much as possible.

Refactoring, the act of renaming and restructuring source code, is not supported by the G.E.C.K., even so it has all information necessary to do it. Objects defined in the G.E.C.K. all have an Editor ID as well as a Form ID used as a handle. All objects know about other objects using them. But the only information shown when renaming the Editor ID of an object is a warning and the amount of objects potentially affected by the renaming. If you are lucky, the affected objects refer to the object to be renamed using its Form ID, leaving them unaffected. But if they refer to the object to be renamed using its Editor ID, like source code of a script mostly does, you are screwed!

But as I wrote before: creating a mod and watching it in action is still fun and I am already addicted. So lets get started creating a perk mod.

How should the perk mod behave?

The Universal Whiz Perk is the first perk mod I created. In this post I will use a slightly simplified variant of it to explain how modding in Fallout 3 can be done.

The Perk we are about to create should reward the player with one additional perk for every level. The additional perk should be granted when the player has collected at least half the amount of XPs required to reach the next level. The perk comes with a cost, the reduction of all XPs gained by 50%. It's an attempt to balance the power of the perk.

Now that we know what to expect from the perk mod the next question is: how to start putting things together? There are two popular approaches in software development we may choose from:

  • The Top-Down approach
  • The Bottom-Up approach

Let me quickly explain the trade-offs of both approaches:

Top-Down vs. Bottom-Up

We could start creating the object representing a Perk, give it a name, attach an image and provide a description. This perk would be immediately visible in the pipboy, even so it wouldn't do anything useful yet. This approach is called Top-Down. You always start with the top-most interface a user or system requires to interact with the software to be developed. Behavior is added piece by piece while making progress down the execution stack.

The positive aspect of using this approach is that you develop those requirements first, which you have the most complete understanding of. Furthermore you are able to inspect behavior added, by using the same interface you intend to be used when development has come to an end. A down-side of this approach is that you are likely to detect problematic issues, those that can't be implemented as envisioned, very late (most often the tricky technical details are found toward the bottom of the execution stack).

An alternative approach would be to first create the Script (an object type available in the G.E.C.K.), that brings the Perk-Selection-Menu up. For testing purposes we could trigger the execution of that script by attaching it to an Item (another object type available in the G.E.C.K.) and declare the block type of the script as OnAdd. This would trigger the execution of our script whenever the player would add such an item to his inventory. This approach is called Bottom-Up, always starting with functionality sitting immediately above functionality that already exists.

Obviously one of the positive aspects using this approach is, that verifying if a critical aspect (how to provide additional perks to the player) can be implemented as envisioned, is done early. If the proof fails and we can't find any other implementation, we wouldn't proceed developing more software leading to a dead end.

A negative side of this approach is that we have to guess how to provide early implemented functionality to not yet implemented functionality intended to use it. Its similar to start building the interior walls of a house before its exterior walls. Where will the front door be? Where the windows? To test this functionality we often have to implement software we do not need later on, which is a waste of time.

Which of those approaches should we use?

We will use both! The Top-Down approach is the one we favor whenever we feel to be in control of what to develop next. It avoids to make us guess how functionality not yet implemented will access functionality we are about to develop.

But when we are in doubt if a requirement is even realizable or how the collaboration structure of G.E.C.K. objects may look like, we switch to the Bottom-Up approach, explore a bit and collect enough information to become confident again that everything can be implemented as intended, switching back to our favored Top-Down approach.

It requires experience, talent and discipline to know when to switch from one approach to another. You have to practice it over and over again and have to avoid driving on autopilot. Stay aware of what you are currently doing and don't get tired asking yourself: Am I doing the right thing?

Setting up the development environment

Before we can start to develop anything we have to install the G.E.C.K. Many articles already exists describing how to solve problems that may arise on different operating systems. Therefore I avoid to repeat everything here and instead provide direction where you will find those valuable information.

  1. Download the G.E.C.K. and install it to the same folder where Fallout 3 is installed.
  2. Download and install the G.E.C.K. 1.5 Patch as well.

Now find the file GECK.exe inside your Fallout 3 installation folder and start it. If everything went fine the G.E.C.K. should startup. Make sure the version number is 1.5.0.19 by selecting the menu entry Help > About. In case the G.E.C.K. won't start up, try to find a solution at the G.E.C.K. wiki. Close the G.E.C.K. for now.

The last thing we need to do is download and install FOSE. It is provided as a 7-zip archive we must explode (if you don't have a file archiver, download 7-zip). Copy all files having an extensions of .exe or .dll into your Fallout 3 installation folder.

Create a windows shortcut pointing to the FOSE Launcher executable and pass in the argument -editor (see the screenshot on the left).

That's it! Start the G.E.C.K. using the windows shortcut just created. All functions as well as the commands label and goto provided by FOSE should be available in the G.E.C.K. now.

Creating the plug-in file

We have to create our plug-in file first. Hit the disc button or select File > Save from the menu. Name the mod file Extra Perk.esp (the G.E.C.K. will append the file extension .esp for Elder Scrolls Plugin by itself). We have created an empty Fallout 3 plug-in but currently all resources defined by Fallout 3 are not available in the G.E.C.K. To get access to those resources we need to load the Elder Scrolls Master file Fallout3.esm as well. Hit the folder button or select File > Data... from the menu.

Notice that our plug-in file Extra Perk.esp is already ticked and has the status Active File. This means that every changes we will make in the G.E.C.K. will alter the active file only when saving. It does protect us from accidentally altering files we never wish to change (like the Fallout3.esm). Add an author and description to the plug-in file. Tick the Fallout3.esm by double-clicking it and hit the OK button. Watch the status bar showing the progress of loading objects into memory (which may take a while).

Making the perk available in the pipboy

We will start using the Top-Down approach because we know what to do to make the perk visible in the game. By default you should find the Object Window on the left side of the G.E.C.K., where every object loaded from the files ticked (in our case the Fallout3.esm and Extra Perk.esp) can be accessed. You can filter objects by selecting the object category they belong to. If you do not know to which category an object belongs select the category labeled *All.

In addition the Object Window provides filtering of objects by their Editor ID. At the top left corner you can enter an infix into the field labeled Filter. All objects not matching the infix won't be shown.

Some advices about naming objects before we start to create our perk. It is a good idea to choose a (hopefully rare) prefix for all objects we are about to create to avoid naming conflicts with objects provided by Fallout 3 and other mods. It is an attempt to create an exclusive namespace wherein names defined by our mod are unlikely to conflict with names defined by other mods. This attempt does not guarantee to always avoid conflicts but it will reduce its likeliness. For all my tutorials we will use the prefix QWE which is a very selective prefix and easy to remember (look where the characters on your keyboard are located).

To create a new perk we have to select the Perk category, place the mouse into the right window and right-click. From the context menu select the menu entry New. The perk dialogue will show up where we define:

  • an unique editor ID used as a handle by objects referencing this perk
  • the perk Name as displayed in different views of the pipboy
  • the Perk Description as displayed in different views of the pipboy
  • a Perk icon as displayed in different views of the pipboy
  • the Level the player must have reached before he may pick the perk

Because the perk we are about to create is just an example, we may use an arbitrary perk icon. I found one which is free-to-use, provided by Bronod as part of his Perk Pack 1. I picked image 12.dds, renamed it to extra perk.dds and placed it into the folder <Fallout 3>\Data\Textures\Interface\Icons\Pipboyimages\Perks\QWE. As you can see it is a good practice to choose your own folder(s) for resources you provide as part of your mod. It makes it easier to identify to which mod resources belong.

It is relatively easy to create your own icons using GIMP and the DirectDraw Surface Plug-In. But I won't explain the how-to in this post, perhaps in an upcoming post. But feel free to find out by yourself, as I did.

The last thing we have to do is: save our changes! Before you start to test your mod, always check if you have to save first. The G.E.C.K. does indicate changes not yet saved by appending an asterisk to the file name of your mod displayed in the window title. Let's save

Installing the perk

Before we are able to see our perk in action we have to overcome some tricky technical issues.

First: we have to tell Fallout 3 to load our mod as well. To achieve this we can use the Fallout 3 Launcher or we edit the plugins.txt file (which enumerates all files to load and in which order) directly. The loading order can't be defined using the Fallout 3 Launcher. You can find the plugins.txt file on a Windows 7 Operating System at the path C:\Users\<Account>\AppData\Local\Fallout3. If you use some other Windows Operating System just search your drive for the plugins.txt file located inside a Fallout3 folder. Open the file with any ASCII editor (like Notepad) and add the name of our mod Extra Perk.esp to the bottom of the file.

Second: we have to force Fallout 3 to not only search for resources inside .bsa files (Bethesda Software Archives) but also from the Data folder where our mod Extra Perk.esp is located at. We have to edit the FALLOUT.INI file which on a Windows 7 Operating System can be found at C:\Users\<Account>\Documents\My Games\Fallout3. Open the file with an ASCII editor and change the line starting with bInvalidateOlderFiles from 0 to 1. Otherwise the pipboy will display an error message instead of the perk icon.

There is a good article about how Fallout 3 handles resources provided by mods. So if you are interested in a detailed discussion about this topic go and read the article .

Have you got the feeling all this configuration was very cumbersome? I would like to suggest you grab either Invalidation Invalidated which takes care about proper loading of resources provided by mods, regardless of if they do replace an existing or add a new resource. An even better choice in my opinion would be to install Fallout 3 Mod Manager instead. It contains Invalidation Invalidated already, provides a nice GUI to activate and define the load order of all mods you like to load. It detects the existence of FOSE automatically, using it instead of Fallout 3 Launcher to start Fallout 3.

Fallout 3 Mod Manager provides much more convenient features we are likely to use while developing our mod. Both tools are no must have. I will continue to explain how to achieve everything needed to create our mod even without those tools. But nevertheless they will make your life much easier, therefore worth your consideration.

Picking the perk In-Game

We are about to pick our yet-do-nothing-perk! Run Fallout 3 by using the FOSE Launcher (which is the fose_loader.exe located inside your Fallout 3 installation folder. Load a game where you already have completed the Vault 101 tutorial quest and have not yet reached the maximum player level (which is 20 for Fallout 3 and 30 with the DLC Broken Steel installed). Enter the in-game console and type advLevel. Here you go! After distributing your skill points you should see our perk in the list of available perks. Congratulations!

Conclusion

This is the end of the first part of my tutorial. We have implemented the bare minimum necessary to see something of value inside the game. Besides we set up the majority of tools required to develop Fallout 3 mods.

Part 2 of my tutorial will cover the scripting of the perk, adding behavior to it. In addition I like to introduce the use of a Source Code Management System helping us to manage a flawless history of all changes we make to our mod. It is capable to restore the mod to every state it was in the past. So stay tuned!

I hope you enjoyed the post so far. Feel free to contact me either by e-mail or leave a comment on the Fallout 3 Nexus Site. If you think this tutorial is worth to be recommended, please consider to endorse it.

Logged Off: Harmlezz