Mod Switch – Configuration Walkthrough

UT3 Logo In the previous installment we took the time to get our directory structure set up and orient ourselves toward creating a stand-alone mod. We discussed some guidelines and described many of the standards that will be used throughout this guide. If you need to brush up before we get too far into this please do so now. This stage in the guide is going to take things a step further as we begin filling in the directories with the details that allow our mod to be executed and cleanly executed using the mod switch.

One thing standing between us and a mod switch is the configuration directory. When you use the Mod-switch you are actually just giving UT3 a few new configuration files and from there it goes nuts. You could literally have your packages and maps strewn throughout your hard drives if you chose to. I would strongly urge you to keep things simple, sticking instead to the structure dictated in the previous post, but for now I am going to try to get your mod directory setup.

We need to begin with creating three files, DefaultEngine, DefaultGame, and DefaultEditor which serve as a filter for unreal to create the underlying UTEngine, UTGame, and UTEditor files. UT3 reads these in and overwrites the files that we choose to base them upon to create them for our own mod. The implication here, which needs to be clear, is that the changes you make to these files is only used by ut3 when you are first creating the UT files. After this has completed the Default files are ignored entirely, and only the changes made to the UT files will be used. This is fundamental to this section of the tutorial because each of the steps may require you to tweak the values for your own mod, and confusion will probably result if you are unable to see what is going on behind the scenes here.

Our goals with this stage are to…

  • Be able to build our scripts, outputting the compiled .u file into the proper directory
  • Properly setup our paths so that we load all of our content with the minimal expense
  • Setup UnrealEd to run our mod with our game type when we run in the editor
  • Configure the default directory locations for UnrealEd
  • Minimize the number of instructions we have to provide by choosing the best ini to derive from
  • Setup the default player properties
  • Remove the unnecessary movie entries and possibly add our own intro movies

Go ahead and create the three files.

[End3r]/Config/DefaultEditor.ini
[End3r]/Config/DefaultEngine.ini
[End3r]/Config/DefaultGame.ini

Within each we are going to put a very important pair of lines, allowing ut3 to know where we are getting our initial values from. Unfortunately my testing has led me to believe that the only file it will let you derive from is another Default of the same name. The reason I bring this up is your CD Key. With the current patched version of the mod switch you are forced to input your CD Key when you first start up with the Default ini’s. If we could derive from the UTEngine.ini in the UTGame directory this would be a moot discussion because it already contains the CD Key. What this means to you is that you can/should not pass around the UT Ini files, because doing so will make it possible for others to use your CD Key. Your Default ini’s will serve as place holders for all of your changes to UT and its editor, and will be distributed to your fans as such.
[Config]/DefaultEditor.ini

[Configuration]
BasedOn=..UTGameConfigDefaultEditor.ini

[Config]/DefaultEngine.ini

[Configuration]
BasedOn=..UTGameConfigDefaultEngine.ini

[Config]/DefaultGame.ini

[Configuration]
BasedOn=..UTGameConfigDefaultGame.ini

Our first step is going to be script compilation. We have the three files in a useable state, but now we need to let Make know where our scripts are hidden and where to put its output. At the same time we can add a couple entries to make working in the editor a little easier – directing it to the proper directories for our map assets. I’ll show you and then we are going to walk through the settings.
[Config]/DefaultEditor.ini

[Configuration]
BasedOn=..UTGameConfigDefaultEditor.ini

[ModPackages]
ModPackagesInPath=..End3rSrc
ModOutputDir=..End3rUnpublishedCookedPCScript
ModPackages=End3r

[Directories]
UNR=..End3rUnpublishedCookedPCCustomMaps
BRUSH=..End3rUnpublishedCookedPC
COLLADAAnim=..End3rUnpublishedCookedPC
GenericImport=..End3rUnpublishedCookedPC
GenericExport=..End3rUnpublishedCookedPC
GenericOpen=..End3rUnpublishedCookedPC
GenericSave=..End3rUnpublishedCookedPC

We started out with just the configuration block, but have added two further sections. The first new section is ModPackages, which lets Make know where our source code is located, as well as the directory to throw our script into when it has completed compiling it. You can configure this to meet the needs of your mod, but do note the relative paths. Version 1.3 of ut3 does not yet support full paths everywhere, so when you do link to anything it will be in your interest to keep it on the same drive as either your system or wherever you installed UT3 initially. The path that I have provided here will cause Make to look in [Source] and compile any .uc or .uci files it finds there. Please refer back to the previous section of the tutorial if you need to be reminded of the standards I will be following with the naming conventions.

Below this section you will see a number of directory entries that may be of note. UNR is the Unreal maps directory, on down to the Generic directories which are each configurable. There are a couple others that you can add into this section but I am primarily interested in getting you rolling over anything else. Tweaking and further personalization can be handled on your own end at a later time.

The next file in line is the Engine file. In here we are going to be designating a couple of very important items; in particular we are letting UT3 know what directories to search through for our files. SeekFreePaths are recursively searched through to find our packages, maps, compiled code and so forth. As stated previously you can configure this as you wish. This is also a good time to note a couple other fixes you can make to your engine defaults to make your life a little more manageable. First, and foremost, This is the file that you can use to set the pruning length for your log files. Secondarily you can take a load off of your mappers and allow them to test their maps from within the editor. You can edit these lines with the standard URL styles entries.
[Config]/DefaultEngine.ini

[Configuration]
BasedOn=..UTGameConfigDefaultEngine.ini

[Core.System]
+SeekFreePCPaths=..End3rCookedPC

[LogFiles]
PurgeLogsDays=5

[Editor.EditorEngine]
InEditorGameURLOptions=?quickstart=1?numplay=1?game=End3r.EGame?mutator=End3r.EFreezeGun_Mutator

[UTEditor.UTUnrealEdEngine]
InEditorGameURLOptions=?quickstart=1?numplay=1?game=End3r.EGame?mutator=End3r.EFreezeGun_Mutator

When you have completed this you can go ahead and make entries below this to include a few further options, like removing and adding introductory movies, setting up the default URL entries, setting up the localization, screenshot or saved game paths and ultimately the details for your game. You are now cooking with gas.

You may have noticed that the directory paths aren’t lining up entirely. I make reference to the path ../Ender/CookedPC and disregard the /Published/ or /Unpublished/ parts of the paths here on purpose. When you are working in the code you have the option to pass -useunpublished as a command line flag that will toggle to the Unpublished directory. This is extremely useful for development and allows you some developmental freedom. I keep my releasable mod content in published, art assets and UI for instance, and keep demo maps and code in the unpublished directory, a make shift Dev/QA setup for UT3.

Now we need to update one last file, once this is complete we can simply drop a dummy class into our [Source] directory and execute UT3 Make to ensure that it is properly configured and we are done. Lets move into DefaultGame.ini. All you need to do is update it to contain the following entries and it will be complete.
[Config]/DefaultGame.ini

[Configuration]
BasedOn=..UTGameConfigDefaultGame.ini

[DefaultPlayer]
Name=Ender Wiggins
team=255

Go ahead and create a file in your [Source] directory, it should be a valid UScript file since we are going to compile it, but the contents are completely arbitrary. It is only important that it compiles. I have created EGame.uc and it contains the following.

class EGame extends UTTeamGame config( End3r );

You should then be able to run UT3 Make and see something comparable to the following output. You should note the –mod=../End3r/Config is the relative path to your Config directory. In a later tutorial I will be showing you how to create the necessary shortcuts to allow your mod to be run from the desktop.

C:UsersBob_2>ut3 make -mod=../End3r/Config
Init: Version: 3601
Init: Epic Internal: 0
Init: Compiled: Jul 31 2008 05:26:15
Init: Command line:  -mod=../End3r/Config
Init: Base directory: D:GamesUnrealUT3Binaries
Init: Character set: Unicode
Log: Executing Class Editor.MakeCommandlet
--------------------Core - Release--------------------
--------------------Engine - Release--------------------
--------------------GameFramework - Release--------------------
--------------------Editor - Release--------------------
--------------------UnrealEd - Release--------------------
--------------------UnrealScriptTest - Release--------------------
--------------------IpDrv - Release--------------------
--------------------OnlineSubsystemGameSpy - Release--------------------
--------------------OnlineSubsystemLive - Release--------------------
--------------------UTGame - Release--------------------
--------------------UTEditor - Release--------------------
--------------------UTGameContent - Release--------------------
--------------------UWeb - Release--------------------
--------------------End3r - Release--------------------
Analyzing...
Parsing EGame
Compiling EGame
Importing Defaults for EGame
Scripts successfully compiled - saving package 'C:UsersBob_2DocumentsMy GamesUnreal Tournament 3Binaries..End3rUnpublishedCookedPCScriptEnd3r.u'
Updating UTMutator_Arena's menu information in UTGame.ini
Updating EGame's menu information in UTEngine.ini

Success - 0 error(s), 0 warning(s)

Execution of commandlet took:  12.70 seconds

At this point it is important that you don’t get over zealous. Because we have only configured things to a degree to make code compilation work, which is our next order of business mind you, you will be unsuccessful in executing UT3 with your mods contents. There are a number of things that we will need to step through in the code that are not yet in scope. Rest assured that the next step is going to be more involved.

12 thoughts on “Mod Switch – Configuration Walkthrough”

  1. As a quick addition to this, if you are so inclined you can remove the intro videos and individual map videos with this block added to your DefaultEngine.ini file.

    [FullScreenMovie]
    -StartupMovies=Copyright_PC
    -StartupMovies=EpicLogo
    -StartupMovies=MidwayLogo
    -StartupMovies=UE3_logo
    -StartupMovies=Nvidia_PC
    -StartupMovies=Intel_Duo_Logo
    -StartupMovies=UT_loadmovie1
    -LoadMapMovies=UT_loadmovie1
    -LoadMapMovies=UT_loadmovie2
    -LoadMapMovies=UT_loadmovie3
    -LoadMapMovies=UT_loadmovie4
    -LoadMapMovies=UT_loadmovie5
    -LoadMapMovies=UT_loadmovie6
    -LoadMapMovies=UT_loadmovie7
    -LoadMapMovies=UT_loadmovie8
    bShouldStopMovieAtEndOfLoadMap=TRUE

    If you want to add your own video to the startup listing you can do so with the following command

    +StartupMovies=End3rsIntro

    The format is Bink, you can find more about it here: http://www.radgametools.com/bnkmain.htm
    Your videos, i think, are to be put into the UTGame/Movies/ sub directory, as follows:

    C:UsersBob_2DocumentsMy GamesUnreal Tournament 3UTGameMovies>dir
     Volume in drive C is System
     Volume Serial Number is 7041-5D71
    
     Directory of C:UsersBob_2DocumentsMy GamesUnreal Tournament 3UTGameMovies
    
    10/21/2008  12:46 AM              .
    10/21/2008  12:46 AM              ..
    09/09/2008  09:36 PM         8,290,412 End3rsIntro.bik
    10/21/2008  02:07 PM         1,760,384 End3rsLoading.bik
                   2 File(s)     10,050,796 bytes
                   2 Dir(s)   2,928,775,168 bytes free

    This is something that is not working within the Mod switch hierarchy yet.

  2. Oh, and for those who are clueless (already had three emails about this) You dont need to bother worrying about the file type. They should be created from text files. These ini files are just ascii/unicode text, don’t stress. Just create them from the Right click New > Text document menu and rename them appropriately. If you dont see the extension (defaults to txt and needs to be changed to ini) you can turn them back on in your folder options. If you dont know how to do that, google is your friend.

    =)

  3. I just lost a huge chunk of my document, but i wanted to jump in here and let you guys know that there is a quick change i would like to recommend. Moving your code to multiple packages is something that our team is currently working on and if you are interested in it as well you may want to make a small change. It looks like when you note your additional mod packages they are actually built in reverse order. To remedy this you can do as follows:

    [ModPackages]
    ModPackagesInPath=..WhiteSrc
    ModOutputDir=..WhiteUnpublishedCookedPCScript
    +ModPackages=WhiteUtility
    +ModPackages=WhiteMisc
    +ModPackages=WhiteUI
    +ModPackages=WhiteWeapons
    +ModPackages=WhitePlayer
    +ModPackages=WhiteGamePlay
  4. Is custom “StartupMovies” an expected support in the next patch?
    I’ve tried a few different ways including MyModDirectory/Movies, UTGame/Movies etc.. and the only way I was able to get a movie to show was to backup one of the movies that come with the game and rename my Bink video to the same title. Although this is unacceptable for modding as it involves replacing official game content.

    1. I realize there is a lot of interest in this topic. I will have to get into it soon, but my initial testing of the process was with my buddy John Ingato and his Exterminator project. The movies are loaded from the UTGamesMovies directory and it worked on my end as well as his. I will be getting into the intro movie in due time, i just need to get through the prescribed four subjects before my mod leaves them behind. This month i have to keep my eyes on the mod pretty closely, as we are gearing up for our first release and having a movie in the intro is not a priority. If there is support for the need for an intro video i would gladly devote time to it. As things stand i have already fallen behind schedule with the localization section.

  5. @Bob

    Great suggestion. We have been doing this for months now and I was just about to suggest it myself. It allows for code to have better scalability over the development cycle and could possibly help better support mutators for your mod.

  6. I’m using the mod switch and I’m running into some problems, that seem like they might be because of config files. Well, one almost certainly is. My script package’s .ini is being created in the UTGame/Config folder instead of my config folder, as with all of the other package’s .ini’s. If I move them manually to my config folder it won’t read them.

    Another problem I’m having, which may or may not be related, is I have a custom game type. In its defaultproperties its assigns MapPrefixes(0):’MC’ and it does the same in the UTMyPackage.ini, but it will not find my MC-Test.up3 map, and if I do a console command to open MC-Test.ut3, it stops on the loading screen.

    I’ve been trying everything to fix this stuff. Can’t think of what I’m doing wrong.

    1. The first one is a mix of issues, but will be addressed in the next patch. Give the 2.0 patch beta a try some time.

      The second is also addressed int he 2.0 patch, but you can work around it if you insist on not updating. You just have to put the contents of your maps ini files into your utgame.ini (i think it will work elsewhere though.)

  7. Well, its a team project for class, and updating isn’t an option right now (we work on it at school and have no control over their copy.)

    I don’t have an ini file for the map. So I’m unsure how to address the problem. Is there something I need to do to generate it? I know I have had maps before with ini files. Could this be a different problem? The map loads fine as a DM if I switch the prefix. It just will not load at all with the MC prefix if I try to load it with the console command. It freezes on the load screen.

  8. Hello Bob, first of all thank you for these tutorials. They have been a major help for me to tinker and mess around with UT3. However, I’m having one small issue. The part where you made a simple class to test for compiling…where my make.exe is not seeing that package.

    In my DefaultEditor.ini file I have the following…

    [Configuration]
    BasedOn=..UTGameConfigDefaultEditor.ini

    [Directories]
    UNR=..UZGameUnpublishedCookedPCCustomMaps
    BRUSH=..UZGameUnpublishedCookedPC
    COLLADAAnim=..UZGameUnpublishedCookedPC
    GenericImport=..UZGameUnpublishedCookedPC
    GenericExport=..UZGameUnpublishedCookedPC
    GenericOpen=..UZGameUnpublishedCookedPC
    GenericSave=..UZGameUnpublishedCookedPC

    [UnrealEd.ThumbnailManager]
    +RenderableThumbnailTypes=(ClassNeedingThumb[…]

    [ModPackages]
    ModPackagesInPath=..UZGameSrc
    ModOutputDir=..UZGameUnpublishedCookedPCScript
    ModPackages=UZGame
    ModPackages=UZMenu
    ModPackages=UTExplore

    The only package that the make.exe see’s ironically is the UTExplore package. Which is a custom gametype that I built following another tutoiral in the original UTGame directory. i merely moved it over to the new directory for testing. And the UZMenu Package holds the 3 .UC menu files that is in your later tutorial. I’m assuming I have a simple type somewhere but I can’t see it. Any ideas? Thanks.

  9. Hey, thanks for this. I was having some issues with my configuration directory, but this post helped out a lot.

Leave a Reply