Mod Switch – Introduction & First Steps

UT3 LogoEpic’s 1.3 update to Unreal Tournament 3 finally opened a door for mod developers, relieving us of having to worry about things such as accidentally overwriting another mods packages or having our mods packages overwritten, mod distribution, localization and so forth. This update is called a mod switch. There have already been a few attempts to get this working, but by and large they are just not filling the holes that we developers have. It was pretty clear that a better understanding, and as such a better tutorial, was needed and I hope that I have provided that here.

First we need to know what it is we are doing and why, so we don’t get caught up in doing something that is wholly unnecessary for our mod. The mod switch provides a mechanic that allows mods to have their own directory to store their game and its related packages. It is an organizational structure. It is a way to avoid overwriting the UT3.exe configuration – which a number of early distributors did in error. We can put our localization, configuration, screenshots, and many other parts of this version of the game into our own directory, segregating it. The benefits are innumerable and are not going to be discussed here. If your mod needs these options you should be reading further. If it doesn’t then you should probably just get back to work.

The directory structure that I will be referring to will be identical to that of the UTGame directory, and this is on purpose. So far, mods and mutators and mappers have been sticking to this directory structure. Changing it just to be changing it is really a shame and I hope you take offense to my saying that you deserve to fail if you work that way. Making systematic and organizational changes like this are really unnecessary ways that can make your mod difficult to contribute to and will cause your team undue stress. I am currently working with my leads to come up with a structure that will be easy to understand and cause the smallest impact when upgrading packages.

It needs to be clear that this tutorial is not for the faint of heart. You will need to have an understanding of Unreal Script, How to navigate around the editor, its general browser, the UIScene Editor, the class tree as well as kismet. I will be walking you through each step in the process, but I will be assuming a basic level of understanding of these things. There are already tutorials around, via 3dBuzz and on ModDB, which will hold your hand and get you up to speed on the basic elements of the tools. If you have not already figured out how to work in the UIScene Editor I suggest you look at my code for the configurable mutators and see how we ultimately bound the elements of the scene to the classes within the mutator.

It is mandatory that you have already installed the 1.3 patch to UT3. Without it your command line arguments will be ignored and you will end up staring at the default UT3 scenes. With a little work you can easily replace these scenes, if anything you should probably just theme them, and you will be free to go about your business as you wish. There are many aspects of UT3 that are built to be modified easily, providing the freedom for you to simply supply the class or UIScene name for your next scene and avoid having to rebuild entire branches of the code hierarchy.

In a moment I will be walking through the elements that will need to be modified or created to allow you to create the mod switch. Your first step, however should be to create the directory structure that will allow you to start off on the right foot. I have called my mod End3r and will be referring to it in two ways. One is the full path to my mod, which all the other directories are descendent from, and the second is the source directory. When I refer to the path of my mod I will put brackets around it, [End3r], and when I refer to my source code directory I will be referring to it as [Source]. For the record, the full path to my mod is going to be as follows:

My Documents/My Games/Unreal Tournament 3/End3r/

And my source directory is here

[End3r]/Src/End3r/Classes

These two directories are extremely important. The following table is a list of directories and their shorthand names I will be using when referring to them throughout the tutorial.

Directory Path Short Description Shorthand Name
[End3r]/Config/ Config [Config]
[End3r]/Src/End3r/Classes/ Source [Source]
[End3r]/Unpublished/CookedPC/CustomMaps/ Maps [Maps]
[End3r]/Unpublished/CookedPC/Localization/INT/ English Localization [Localization]
[End3r]/Unpublished/CookedPC/Packages/ Packages [Packages]
[End3r]/Unpublished/CookedPC/Script/ Script Output [Script]

When I make reference to these directories I will be using the shorthand bracketed version. There are a number of directories that you can create at this time, but these are the ones that I found mandatory. Below is a full listing of directories you should create for a new mod. I have also created these scripts (Perl, Ruby, Python, Batch) that you can use to create these directories without need to right click, click, click the thirty times.

[End3r]/Config/
[End3r]/Screenshots/
[End3r]/Src/
[End3r]/Src/End3r/
[End3r]/Src/End3r/Classes/
[End3r]/Unpublished/
[End3r]/Unpublished/CookedPC/
[End3r]/Unpublished/CookedPC/CustomChars/
[End3r]/Unpublished/CookedPC/CustomMaps/
[End3r]/Unpublished/CookedPC/Localization/
[End3r]/Unpublished/CookedPC/Localization/DEU/
[End3r]/Unpublished/CookedPC/Localization/ESN/
[End3r]/Unpublished/CookedPC/Localization/FRA/
[End3r]/Unpublished/CookedPC/Localization/INT/
[End3r]/Unpublished/CookedPC/Localization/ITA/
[End3r]/Unpublished/CookedPC/Packages/
[End3r]/Unpublished/CookedPC/Script/

Do note that I have called my package and mod the same thing. In Project: White we are experimenting with a few standards that will help organize our packages to improve our distribution and code location oversight, but that is still in the boiler. I will be sharing our thoughts as time allows.

There are many parts to the manifest for a mod switch and what it will be looking for, with this configuration. Many people are trying to do simple things like remove a single item from the main menu or update the configuration of their mod in some creative way. It may not be entirely necessary to have you ruin your day trying to redo all of the underlying configuration menus and so forth. You can still leverage the defaults, especially at this point in time where no mod is going to be far enough along to justify the time and energy expenditures.

This tutorial will begin at the bottom, classes that will be needed and or replaced, and work up to the UIScene and its associated datastores. You will need to create a new map to trigger your UIScene, Name neutral as far as I know. You will need to create at least two UIScenes in order to replace the main menu, because of how the menu is triggered.

As a final note, I will say that there are many points of failure within this tutorial. They range from skipping a menu to typos, and all of them carry with them a certain level of hazard. The things within this walkthrough are put there to help you and your distribution of your mod. Make sure you read the terms of use or you may end up breaking them. I would not be surprised if Epic updates their EULA in the next couple months, but be warned.

I am going to get back to work on the rest of the tutorial. Expect them to be out in installments of similar length to this one, each focusing on the next step of the process.

  • Bob

    Below is a short batch script that you can use to create the directories. You simply execute it within your base directory (My Documents/My Games/Unreal Tournament 3/End3r) and it will create all of the directories mentioned above.

    mkdir "Config"
    mkdir "Screenshots"
    mkdir "Src/MyMod/Classes"
    mkdir "Unpublished/CookedPC/CustomChars"
    mkdir "Unpublished/CookedPC/CustomMaps"
    mkdir "Unpublished/CookedPC/Localization/DEU"
    mkdir "Unpublished/CookedPC/Localization/ESN"
    mkdir "Unpublished/CookedPC/Localization/FRA"
    mkdir "Unpublished/CookedPC/Localization/INT"
    mkdir "Unpublished/CookedPC/Localization/ITA"
    mkdir "Unpublished/CookedPC/Packages"
    mkdir "Unpublished/CookedPC/Script"
  • If you prefer using a more organized file structure opposed to lumping all of your packages into “Unpublished/CookedPC/Packages” like me, then the following setup works as well.

    mkdir “Config”
    mkdir “Screenshots”
    mkdir “Src/MyMod/Classes”
    mkdir “Unpublished/CookedPC/Chars”
    mkdir “Unpublished/CookedPC/Editor”
    mkdir “Unpublished/CookedPC/Effects”
    mkdir “Unpublished/CookedPC/Environments”
    mkdir “Unpublished/CookedPC/Localization/DEU”
    mkdir “Unpublished/CookedPC/Localization/ESN”
    mkdir “Unpublished/CookedPC/Localization/FRA”
    mkdir “Unpublished/CookedPC/Localization/INT”
    mkdir “Unpublished/CookedPC/Localization/ITA”
    mkdir “Unpublished/CookedPC/Maps”
    mkdir “Unpublished/CookedPC/Script”
    mkdir “Unpublished/CookedPC/Sounds”
    mkdir “Unpublished/CookedPC/Temporary”
    mkdir “Unpublished/CookedPC/UI”
    mkdir “Unpublished/CookedPC/Weapons”

  • Bob

    Make sure you follow the tutorials all the way through to the very end, otherwise you will end up screwing something up. This is especially necessary with the 2.0 patch installed as many things have changed since i wrote this tutorial and how it works now.

  • Casey

    Hi. Whenever I run the editor with my mod switch (editor +mod..CnRConfig) after setting up my directories un the DefaultEditor.ini, the editor still defaults the open/save paths etc. to my game folder rather than mod folder. What am I doing wrong?

  • Bob

    @Casey
    First things first, make sure you read the changes to the mod switch by the 2.0 patch. There may be some things that are important. Second i don’t know what kind of impact switching the sign on the arguments will have. I would suggest using -mod just because that is their convention.

    If you are having issues with this beyond that i would suggest you join me on IRC and we can discuss it in much more detail.

  • Rob

    I didn’t see you overtly say it anywhere so I’m going to ask. Is this a tutorial for a total conversion? Such as it has it’s own executable and everything?

    • Bob

      There is no such thing. A mod is a mod in UT3, and there is no mechanic for having your own executable.