Creating a Simple UDK Game using nFringe and the UnrealScript Language

Introduction

UDK is a free version of the Unreal Engine 3 for noncommercial development. The Unreal Engine 3 is one of the most popular professional game engines used today, used in games such as Gears of War, Unreal Tournament 3, and Mass Effect. The UDK, however, does not come with the C++ source code for the Unreal Engine 3.

The UDK can be downloaded from the link below:

• http://www.udk.com/download

The language used to program the Unreal Engine 3 is UnrealScript. UDK comes with a compiler for UnrealScript, however, it lacks a proper IDE. The IDE that I prefer to use is nFringe. nFringe is a language module for Visual Studio 2008 (it can also be used with Visual Studio 2005). If you do not have Visual Studio, you can use it with Visual Studio 2008 shell.

While you could theoretically build an entire game using WordPad, I find this quite unrealistic. nFringe allows for Intellisense and automatically detects incorrect syntax, saving you precious time during game development. nFringe, however, is not built for use with the UDK, and the debugging features do not work with UDK.

nFringe can be downloaded from:

• http://wiki.pixelminegames.com/index.php?title=Tools:nFringe

In this tutorial, we will:

• Set up an nFringe project correctly
• Write a simple game using UDK
• Compile this game and run it

A Quick Note

I originally wrote this for the March version of UDK, some things have changed in later builds; the most obvious being the change of the directory UTGame to UDKGame. However, the UnrealScript language has mostly remained the same (with the addition of some new capabilities like Flash GUIs).

The programming guides/tutorials on Epic's official site have also improved from the original writing of this tutorial. If you are interested in UnrealScript, I suggest you look at them (link at the bottom).

Background

It is important that you have prior experience with a programming language (preferably object-oriented) before you attempt to develop with UnrealScript.

It is also important that you know the basics of the Unreal Editor as all level creation is done through it. It is not very difficult to use and this tutorial doesn't require much knowledge of it.

At this point, you should have both UDK and nFringe installed. We will create a basic project.

Important Directories

Go to the directory where you installed the UDK, you should see four folders.

• Binaries - Holds all of the important binaries required to build UnrealScript and launch the Unreal Engine 3 as well as the Unreal Editor.
• Development - Contains all of the base raw source code (in UnrealScript) that our work will inherit from. All raw scripts for your game should be located in this directory.
• Engine - Leave this folder alone, it is not in the scope of this tutorial.
• UDKGame - Holds the compiled scripts and assets for your game (this has been changed from UTGame in newer versions of UDK).

Creating a Project

NOTE: (UDK Base Directory) refers to the directory where UDK is installed.

Now that you have nFringe installed, start Visual Studio and create a new solution with an UnrealScript project in the directory (UDK Base Directory)/Developement/Src, it should be a UnrealEngine 3 Licencee Project.

NOTE: The directory of the project is highly important, as the UnrealScript compiler will not find your source code if it is not placed in the correct directory.

After the project is created by Visual Studio, close your current solution. Go to the directory of the solution and move all files into (UDK Base Directory)/Developement/Src, including your solution and project file.

Double click on the solution file to open Visual Studio. Visual Studio will be unable to find your project, so just add it to your solution manually (Add -> Existing Project...).

If you have performed these steps correctly, you should see all of UDK's base source code in your project contained within separate folders.

Go to your project's property page and go to the General page. Under Script Compiler you should see four user input boxes, three of them should be grayed out.

Make sure that your target game (under "Game") is set to UnrealEngine 3 Licensee.

Now go to UCC Path and specify this file: (UDK Base Directory)/Binaries/Win32/UDK.exe. This is the UnrealScript compiler that nFringe will run when we build our project.

Next, go to the Build page of the project properties and scroll down to "Script Outputs", check "manually set UCC output directory" and input this directory: (UDK Base Directory)\UDKGame\Script.

Now, take a breath, we have just performed all the necessary steps to build our project with UDK. To make sure everything works, build your project, if it succeeds, then you are ready to perform the next step.

UnrealScript File Types

UnrealScript is an object-oriented scripting language. These are the types of files commonly used in UnrealScript:

• UC Files - Raw UnrealScript, these are basic text files which hold the majority of the code that is written. Each .uc file holds a class and that class must have the same name as the name of the file.
• U Files - Compiled UnrealScript modules, these contain multiple classes and are the files used by the UnrealEngine.
• UCI Files - UnrealScript Include files, these are beyond the scope of this tutorial.
• INI Files - Configuration files.

Creating UnrealScript Modules

Your project should contain multiple folders. Each one of these folders contains an UnrealScript module, a collection of UnrealScript classes.

Create a new folder inside your project and name it "MyGame", this will be the module we will store all of our classes in.

Inside each module, there is a folder named "Classes", this is essential, without this folder, the UDK compiler will be unable to find your UnrealScript classes. Go ahead and create a folder named "Classes" inside your "MyGame" module folder. We will place all of our code inside this folder.

Writing Our Code

Create 3 empty UnrealScript files inside your "Classes" folder, name them "UPawn", "UController", and "UGameInfo".

• UPawn - This will be the class we use for the player. (Inherits from GamePawn)
• UController - This will be the class that acts as the controller for the player. (Inherits from GamePlayerController)
• UGameInfo - The class that holds all the info about our game. (Inherits from GameInfo)

Open your UGameInfo.uc file, it should look like this:

class UGameInfo extends Object;

DefaultProperties
{

} 

This segment of code defines a class named UGameInfo that is a child of Object. The DefaultProperties block is part of every class and, just like it suggests, defines all the default properties for a class and adds components to the class. Lines in the DefaultProperties block are not followed by a semicolon.

Now of course, we do not want the UGameInfo class to be a child of Object, we want it to be a child of GameInfo, so replace Object with GameInfo.

Your UGameInfo.uc file should now look like this:

class UGameInfo extends GameInfo;

DefaultProperties
{

}    

Now, before we move on to the other files, quickly add these default properties:

class UGameInfo extends GameInfo;

DefaultProperties
{
	DefaultPawnClass = class'MyGame.UPawn'
	PlayerControllerClass = class'MyGame.UController'
	bDelayedStart = false
}  

This tells our UGameInfo class that the pawn class we will use for our game is UPawn, and the controller class we will use is UController.

A Note About Class Types

As you can see in my example, when you want to use a class type as a variable, you use the class keyword and then the module followed by the name of the class. For example, if I want to reference the class GameInfo in the module Engine I would write:

class'Engine.GameInfo'    

However, if the class you are referring to is in the same module as your script, it is not necessary to specify the module:

class'UPawn'

Adding Objects

Alright, now open your UPawn.uc file.

Change the parent class to GamePawn and then we'll add a collision cylinder for our UPawn.

Here is what the code should look like:

class UPawn extends GamePawn;

DefaultProperties
{
	begin object Class=CylinderComponent Name=CylComponent
		CollisionRadius =+ 20.0
		CollisionHeight =+ 40.0
		end object

	Components.Add(CylComponent)
	CylinderComponent = CylComponent
}    

This segment of code defines an object of class CylinderComponent with the name CylComponent, a radius of 20 and a height of 40, then it adds this component to the Pawn's components and sets the CylinderComponent to CylComponent.

Now we'll add a dynamic light environment to our pawn.

class UPawn extends GamePawn;

DefaultProperties
{
	begin object Class=CylinderComponent Name=CylComponent
		CollisionRadius =+ 20.0
		CollisionHeight =+ 40.0
		end object

	Components.Add(CylComponent)
	CylinderComponent = CylComponent

	begin object Class=DynamicLightEnvironmentComponent Name=UPawnEnvironment
		bSynthesizeSHLight = true
		end object
	
	Components.Add(UPawnEnvironment)
	LightComponent = UPawnEnvironment
}  

Next, go to the UController.uc file and make sure it looks like this:

class UController extends GamePlayerController; 

DefaultProperties
{

}  

That is it! You have created a simple game where the only thing you can do is run around and jump. Good Job! Unfortunately, you still need to compile this and tweak the Unreal Engine 3 configuration to run this code.

Compilation

This stage is fairly easy, it just involves overwriting the default .ini files that are included with the UDK.

Go to (UDK Base Directory)/UDKGame/Config.

You should see a file named DefaultEngine.ini.

NOTE: You should create a backup of all of the default config files in case you screw something up very badly; however, you could also delete the config files and UDK would automatically create the default configuration files again in the config directory.

Open the DefaultEngine config file, and scroll down until you see this section:

[UnrealEd.EditorEngine]
EditPackagesOutPath=..\..\UTGame\Script
FRScriptOutputPath=..\..\UTGame\ScriptFinalRelease
+EditPackages=UDKBase
+EditPackages=UTGame
+EditPackages=UTEditor
+EditPackages=UTGameContent
AutoSaveDir=..\..\UTGame\Autosaves
InEditorGameURLOptions=?quickstart=1?numplay=1 

Insert this line after +EditPackages=UTGameContent.

+EditPackages=MyGame   

This will include the MyGame module in the compilation.

You should now be able to build your project and the respective "MyGame.u" should appear in your UCC output directory - (UDK Base Directory)/UDKGame/Script.

Configuring UDK

If you have already attempted to run this, then you might have noticed that UDK does not actually use your classes when it runs. Changing this is simple, it involves changing the default configuration files that are included with the UDK.

Go to (UDK Base Directory)/UDKGame/Config.

You should see the file named DefaultGame.ini.

Go to the Engine.GameInfo section in the configuration file and change it to this:

[Engine.GameInfo]
DefaultGame=MyGame.UGameInfo
DefaultServerGame=MyGame.UGameInfo
PlayerControllerClassName=MyGame.UController
GameDifficulty=+1.0
MaxPlayers=32
DefaultGameType="UTGame.UTDeathmatch";
+DefaultMapPrefixes=(Prefix="DM",bUsesCommonPackage=FALSE,GameType="UTGame.UTDeathmatch")
+DefaultMapPrefixes=(Prefix="CTF",bUsesCommonPackage=FALSE,
	GameType="UTGameContent.UTCTFGame_Content")
+DefaultMapPrefixes=(Prefix="VCTF",bUsesCommonPackage=FALSE,
	GameType="UTGameContent.UTVehicleCTFGame_Content")

Now you can test this out by creating a map and then playing on it. There should be no HUD when you play.

Final Comments

Eventually, I will write a part II to this tutorial that will show how to:

• Use Inventory Managers
• Create Pickup Factories
• Check Win Conditions
• End the Game

The book Mastering Unreal Technology Volume III will also be available for purchase soon and it will focus on UnrealScript.

But until then, look at some of these Unreal websites:

• http://wiki.beyondunreal.com/Legacy:UnrealScript
• http://udn.epicgames.com/Three/UnrealScriptReference.html
• http://chimeric.beyondunreal.com/tutorials.php
• http://www.hourences.com/book/tutorialsindex.htm