Project Suite Management Utility

Overview

The PSMU is a 3rd party tool developed by Mavrik Games for use with the Unreal Development Kit. It makes setting up and editing custom game projects much easier by manipulating and arranging configuration files, content folders, and even code files. It can also automatically generate nFringe projects for each game project and Visual Studio solution files for each project suite to create organized project hierarchies. It is designed to eliminate the issue of "switching between multiple projects in a single installation [being] cumbersome and confusing" mentioned here. It has four main purposes:
  1. Prepares the UDK environment and file structure for easier multi-game development
  2. Provides a fast, simple interface for switching between game projects as well as creating and deleting game projects
  3. Migrates game projects to the latest installed UDK version making it easier to keep your projects up to date
  4. Exports game projects to separate the code and content specific to those projects from the code and content that comes with the UDK for easier sharing and backup
The PSMU helps you keep any game specific changes to the configuration and code files local to the game project so that those changes don't affect other games being created. It also organizes the content hierarchy for each game project in a way similar to the structures already in place for the example UTGame, making it simple to find your content related to each game project in the Content Browser. See http://udn.epicgames.com/Three/BasicGameQuickStart.html#Content Directory for more information.

Disclaimer

The PSMU makes a lot of changes to your UDK installation, so if you've already started work on a project, it is highly recommended that you use the PSMU on a fresh UDK installation and copy your project files/changes over to avoid accidental corruption to your project(s). Due to the many different possibilites of setting up a UDK project, there's no way to guarantee that the PSMU will work perfectly for everyone, especially if the UDK installation has been modified. Also, as with any software, there can exist unknown defects that can adversely affect your project files, so you should always keep a backup of your project files before you use the PSMU to safeguard against any software/user error. Mavrik Games will not be held responsible for any detrimental effects resulting from using the PSMU.

Interface

The first time you run the PSMU, it will ask you to locate your UDK directory. By default, this should be the C:\UDK folder. You can change this location by clicking on the "[Change UDK Location]" link at the top of the main interface. Once you have chosen your UDK installation directory, the main interface will open. There are four sections:
  1. Suite/Version Information
  2. Game Projects
  3. Configuration File List
  4. Options
Game Projects Suite and Version Info Configuration File List Options

Suite/Version Information

Here the PSMU shows the suites you've created and the versions of the UDK installed in the directory. A "suite" is just a collection of game projects grouped together however you choose. For example, you can use your studio's name, the title of a series of games, or game genres as your suite names. You can create as many suites as you like and the PSMU will store their names for future use. Suite names must not contain spaces or special characters.

In order to create a suite, just type the name into the combo box and add a game project. You can also create a new suite by typing in the name and clicking the "Switch Suite" button if it's enabled. The "Switch Suite" button is enabled as long as there is at least one other suite in the list so you can transfer games back and forth between suites. To completely remove a suite and all its game projects from PSMU, just click the "Delete Suite" button. This will not actually delete any of the files or folders associated with this suite if any exist. Instead it will only remove the suite from the "suiteList" node in the PSMUSuiteData.xml file located in the root UDK folder. The next time you start PSMU, you can type in the deleted suite name again to restore it to the "Suite Name" combo box. Also, any game projects it finds in the file system will automatically be added back to the "Game Project List" box unless they are also listed in the "excludedList" node in the PSMUSuiteData.xml file.

The "UDK Version" drop down is automatically populated with the UDK version folder names located in the root UDK directory. You can edit different versions individually and independently of each other.

Game Projects

The "Game Projects" section lets you add and remove game projects to/from your suite. To add a game to the list, just type in a name in the "Game Name" text field and click the "Add Game" button. To remove a game, select the game in the list and click the "Remove Game" button. Selecting a game project from the list will set it as the current game project once the "Execute" button is pressed if the Edit Config Files/Set Current Game option is selected. Game project names must not contain spaces or special characters.

When you select a suite from the "Suite Name" combo box, the "Game Projects" list is automatically populated with any game projects already in that suite. It first searches the PSMUSuiteData.xml file for any game projects associated with the suite. Then it looks in the file system and manually adds any game projects it finds in the suite folder structure, as long as that game project is not in the "excludedList" node of the PSMUSuiteData.xml file.

The "Execute" button is enabled as long as there is at least one game project in the "Game Projects" list for the currently selected suite and either the Edit Config Files/Set Current Game option is unchecked or a game project is currently selected.

When you add a game to a suite, PSMU will add that game to a list of game projects to create when you click the "Execute" button. It will go through the file system and create the appropriate folders according to the options you have chosen. If you remove a game by clicking the "Remove Game" button, PSMU will not delete the folders if they've already been created, but those game names will be added to the "excludedList" node in the PSMUSuiteData.xml file located in the root UDK folder. The next time PSMU is started, it will ignore any game projects that have been excluded. Adding the game back to the suite will remove it from the "excludedList" node.

Configuration File List

This is a list of all the Default*.ini configuration files found in the Config folder of the currently selected UDK version that have not already been overridden by PSMU. An overridden configuration file is one that will need to be edited for your game projects. For example, in order to run your custom game instead of the default UTGame, you have to change the DefaultGame property in the [Engine.GameInfo] section of the DefaultGame.ini file to be your game as well as add your game package to the EditPackages property in the [UnrealEd.EditorEngine] section of the DefaultEngine.ini file. So both the DefaultEngine.ini and DefaultGame.ini files need to be overridden (see http://udn.epicgames.com/Three/BasicGameQuickStart.html#Compiling and http://udn.epicgames.com/Three/BasicGameQuickStart.html#Testing for more information). It is also very common to override the DefaultInput.ini file as most custom games will have different key mappings than the UTGame. These three files are checked by default, but you can choose to un-check them if you're not going to edit them. You can always run the PSMU again and override a configuration file later if you don't know which ones you'll be using yet.

When you override a configuration file, a corresponding configuration file is created inside the Config\<suite name>\<game project name> folder. For example, if you create a suite called "MavrikGames" and a game project called "Astra" and override the DefaultGame.ini file, a file is created in the Config\MavrikGames\Astra folder called AstraGame.ini. That's the file you'll edit with any settings specific to that game. PSMU will also rename the DefaultGame.ini to Game.ini (or Engine.ini if you override DefaultEngine.ini, Input.ini for DefaultInput.ini etc) in the root config folder and create a new DefaultGame.ini file. You must NOT delete these files because PSMU uses them to construct the config file hierarchy. If you override the DefaultEngine.ini and DefaultGame.ini files, PSMU will automatically edit the EditPackages and DefaultGame properties to make your game the one that launches as mentioned in the previous paragraph. These changes are made to the <game project name>Game.ini and <game project name>Engine.ini files because they are settings specific to that game. For more information on how the configuration files work and how they are structured, visit http://udn.epicgames.com/Three/DirectoryLayout.html#Config and http://udn.epicgames.com/Three/ConfigurationFiles.html#Working with Configuration Files.

Options

The options allow you to choose which aspects of the UDK environment PSMU will affect when you hit the "Execute" button. They correspond to the Configuration, Content and Code components of the UDK template. If you leave all of them unchecked, then the UDK file structure remains unchanged, but the PSMUSuiteData.xml file will be updated to reflect any changes you made. Below is a more detailed description of what each option entails:
  • Edit Config Files/Set Current Game - With this option enabled, PSMU will create the configuration file structure detailed in the Configuration File List section for the configuration files that have been checked. It will also edit the configuration files to set the current game to the game project selected in the "Game Project List" box. This is the game that the DefaultGame property gets set to and is compiled and built when you run either the Front End tool, the "make" command, launch the game through Visual Studio etc.
  • Setup Content Folder Structure - This option creates a file structure for the game content for each game project. It organizes the movies, maps and content into their appropriate suites and game projects, as well as creates a blank map and content file as placeholders/templates for each game project for use in the Unreal Editor. You can use these files to start adding content and maps or just delete them. In addition, it creates a folder in the UDKGame\Flash directory for each game project for use with Scaleform files. The folder name is just the name of the game project, with a suffix of "GFx". According to the way UDK imports .swf files for use with Scaleform, this name becomes the package name when you import the .swf, and any sub-folders become the groups of the package. You're free to organize your scaleform project inside this folder in any way you wish, as long as you follow the guidelines set by UDK for the actual .swf files and imported images. If you migrate your projects to a new version of UDK, PSMU will copy all the contents of this folder exactly as you have them structured.
  • Setup Code Environment - With this option selected, PSMU will add game project folders to the file structure in the Development\Src folder. It will even create GameInfo, PlayerController and Pawn classes as templates for each game project. You can edit and use these templates or delete them and write your own. See http://udn.epicgames.com/Three/BasicGameQuickStart.html#UnrealScript Project for more information. Checking this option will also create a Visual Studio solution file in the Development folder for each project suite. It will also generate nFringe Visual Studio projects and user files in the Development\Src folder for each game project and add them to the appropriate Visual Studio solution. Each game project folder still exists physically in the root Src folder in order to allow the scripts to be compiled, but only the game projects in the appropriate suite are included in the corresponding Visual Studio solution, keeping game projects organized by suites. In other words, the Visual Studio projects in each Visual Studio solution correspond to the PSMU game projects in each PSMU suite. In addition to the file structure for Unrealscript code, PSMU will also create folders in the Development\Flash directory following the <suite name>\<game project name> structure. You can use these folders for custom Scaleform Actionscript classes and flash projects, following whatever file structure you like for packages and class paths. If you migrate your projects to a new version of UDK, PSMU will copy all the contents of these folders exactly as you have them structured.

PSMU/nFringe Code Environment

Previous versions of the PSMU required that you create an nFringe project for each project suite before running the PSMU to set up your code. This is no longer necessary as the latest version of the PSMU generates the solution and project files automatically. The solution files are created in the Development folder to keep them separate from the project files in the Development\Src folder. This makes it much easier to find the solution file for the suite you're working on as it's not buried among all the project files. To work on the games in a particular suite, just open the *.sln file for that suite. You can change the properties for each project in the solution individually, such as which map to load, whether to skip intro movies, or what position to open the log window. Visual Studio has no way of tracking which game is selected as the "Current Game" in PSMU, so in order to launch the correct game from Visual Studio for debugging, you need to set the appropriate project as the "StartUp Project" by right clicking on the project in the "Solution Explorer" window, and selecting the "Set as StartUp Project" option.

When you create Unrealscript files that are specific to a certain game project, you just place them in the "Classes" folder for that game just as you would do if you weren't using the PSMU. However, these files will only show up for that game project in Visual Studio. In other words, none of the other game projects will have access to those classes, even if they are in the same project suite. To create Unrealscript files that are accessible to all your game projects (libraries), you just need to create a folder in the Development\Src folder (with a "Classes" sub folder) that doesn't have the name of any of your game projects. That way, the PSMU doesn't filter it out and includes it in all your game projects along with all the rest of the folders that come with UDK.

Important Information About Game Project Code Package Names

In order to conform to the Unreal standard of code packages for game source files ending with the word "Game" (UTGame, UDKGame, CustomGame etc.), the latest version of the PSMU automatically appends the word "Game" to the end of the game name when it creates the code package in the Development\Src folder. For example, if you create a game project called "Astra", PSMU will create a folder called "AstraGame" in the Development\Src folder, which is where all the Unrealscript source files for the game "Astra" should go. The purpose of this naming convention is to distinguish the package for the actual game source files as opposed to source files for the editor, which full licensees have access to, or other engine/library code.

If this is the first version of the PSMU that you've used, there's no need to even worry about this change. However, if you've set up your environment using a previous version of the PSMU and you use this version, when the PSMU starts you will be prompted to make a decision about whether or not you want to switch over to this new package name convention. If you decline, PSMU will store your decision in the PSMUSuiteData.xml file and it will continue to use the old naming convention. If you accept, you need to be aware that you will potentially need to change the package name in any configuration files, Unrealscript source files, and/or content files that reference those package names (like the [Engine.GameInfo] section in the DefaultGame.ini configuration file which assigns the DefaultGame property to the <packagename>.<gameinfo> script class).

If you do switch, it is recommended that you immediately export your game projects before executing any setup or migrating any projects to a newer version of the UDK. That way, if you can't get the new package names working, you'll still have a working version that you can revert to. If you need to revert, just delete your game source folder(s) that end with "Game", delete the "gameSuffix" node in the PSMUSuiteData.xml file, and copy your exported projects back over into your UDK installation to overwrite any files that referenced the new package names. When you run the PSMU again, it will prompt you again about using the new package names, so just click no.

Switching Game Suites

If you ever need to move a game over to a different suite, just click the "Switch Suite" button. A new dialog box will pop up and allow you to select the suites you're transferring the game to and from.


As long as you haven't selected the same suite, you'll be able to transfer games back and forth. When you're finished, click the OK button and the dialog box will close. The main form is immediately updated, but nothing is saved until you click the "Execute" button. All the files and folders related to the transferred game(s) will be moved to the new suite(s) and the PSMUSuiteData.xml file will be updated accordingly.

Exporting Game Projects

You can export individual game projects to another folder by selecting the game project from the "Game Projects" list, selecting which components of the UDK template you want to export from the options, and clicking the "Export" button. A dialog box will appear asking you to select a destination folder. Next, a window showing a file tree will open allowing you to select any additional files that weren't automatically included by the selected options. This allows you to include any code libraries, a custom splash screen, and any other files you might want to export. When you click "OK", PSMU will immediately copy only the files and folders associated with the selected game project and the selected options over to the destination folder along with the additional files you specify. You can safely export more than one game project to the same location due to the fact that different game projects will be in separate folders. A new PSMUSuiteData.xml file is also written to the destination folder that includes references for only the game projects that have been exported there as well as the additional files you included. Any matching files already in the destination folder will be overwritten, so be careful to back up anything you need beforehand. The exported game projects can then be copied over to another installation of the UDK (on another machine for example), and PSMU will automatically detect and include these game projects. This makes setting up all your game projects on multiple machines very simple. Exporting a game project is also an easy way of isolating it from other suites/game projects so you can share it without including all of the other game projects in your UDK installation.

Version Migration

Migrating your suite and game projects from an older version of UDK that has been set up using PSMU is simple. When you run PSMU, it will detect multiple versions of the UDK and allow you to choose which version you want to edit. If you've set up the configuration files on the earlier version, the PSMUSuiteData.xml file should have a list of which configuration files you'll need to override and automatically check those files for you in the "Configuration File List" box. It should also have a list of the suites and game projects you've created.

To begin the migration, select the folder of the version of the UDK you want to migrate to in the "UDK Version" drop down. When you click "Execute", PSMU will tell you that it found multiple versions of the UDK and ask if you'd like to migrate those projects over to the version you have selected in the "UDK Version" drop down. If you click "Yes", PSMU will have you choose the folder of the previous UDK version. Next, the additional files window will open and allow you to select any additional files you would like to migrate over to the new version. For example, if you have a custom splash screen or if you've created code libraries or changed some engine code, you would want to select those files so they would get copied over to the new version. When you click the done button, PSMU will copy all the projects and additional files over to the new version. The PSMUSuiteData.xml file will be updated to include a list of these additional files so that the next time you migrate, they will automatically be checked in the additional files window.

If when the PSMU asks if you'd like to migrate your projects over to the new version you click "No" instead, PSMU will ask if you want to ignore the other versions. If you click "Yes", it stores the other versions in the PSMUSuiteData.xml file's "ignoreVersions" node and won't ask you about those versions again. You can edit the PSMUSuiteData.xml file and remove the version from the "ignoreVersions" node if you change your mind later.

To migrate from versions that haven't been set up with PSMU, you need to set up the new version with PSMU and copy the changes you made from the older version's configuration files into the appropriate game specific configuration files in the new version. For the content and code, you just need to copy the files over into the new file structure.

PSMUSuiteData.xml

PSMU saves its settings to the PSMUSuiteData.xml file in the root folder of the UDK. You can also edit this file manually, which can be useful when setting up new installations on multiple machines. The xml nodes should be pretty easy to understand, but here's a quick breakdown:
  • suite - Suite names that have been entered. Each has a "current" attribute with a value of 'true' or 'false' that tells PSMU if it was the selected suite the last time PSMU was run.
  • game - Game projects that have been added to the game project list. Each has a "suite" attribute with the value of the suite it belongs to.
  • excluded - Game projects that have been excluded by removing them from the game project list. Each has a "suite" attribute with the value of the suite it belongs to.
  • config - Configuration files that have been overridden.
  • version - UDK versions that have been ignored for migration.
  • manifest - The location of the "UnSetup.Manifests.xml" installation manifest file. When overriding configuration files, PSMU updates the manifest so that when you package your game those files will be installed.
  • gameSuffix - The suffix to append to the end of the game project code package names. By default, the suffix is "Game" to conform to the Unreal Engine standard.
  • file - Additional files that should be checked in the file tree window that pops up whenever you export a project or migrate your projects to a new UDK version