Unreal Development Kit Game Programming with UnrealScript: Beginner's Guide

Go to http://udk.com/download and get the latest release.

Run the installer. It will ask us to accept the license agreement and where we want to install the UDK. By default, it will use the UDK version for the installation, but to help keep things organized it's better to use a project name. This helps if you have more than one project using the same UDK version. In this book we will be calling our project Awesome Game, so let's change the installation directory.

After installing the prerequisites and the UDK, the installer will ask us what to do next. Let's click on Return to Desktop for now.

Run the installer. It will ask what language to use.

The installer will ask where we want to install the program. The location doesn't matter, choose a convenient location or leave it at the default.

The installer will ask if you would like to add shortcuts or Replace Windows Notepad. Let's leave this at the default for now unless you don't need the shortcuts.

Review the settings and click on Install to finish the installation.

After ConTEXT is finished installing, let's run it!

Click on Options in the top toolbar, then Environment Options. In the first tab, General, set When started to Open last file/project. That way any files that we're working on will automatically open the next time we use ConTEXT.

Make sure that Remember editing positions is checked. This makes the files we're working with open in the same position the next time we open ConTEXT. This saves a lot of time remembering where we left off.

In the Editor tab, uncheck Allow cursor after end of line. This will keep our code clean by preventing unnecessary spaces all over the place.

Uncheck Smart tabs. Part of writing clean code is having it lined up, and Smart tabs tends to move the cursor to the beginning of words instead of a set number of spaces.

Make sure that Line numbers is checked. When we start compiling, any errors that show up will give us a line number which makes them easier to find and fix. This also helps when we search through our code as the searches will also give us line numbers.

Finally for this tab, set Block indent and C/Java Block Indent to 4. This comes down to personal preference but having four spaces instead of two makes it easier to quickly scan through code and find what you're looking for.

Now we're going to set up ConTEXT to compile code. On the Execute Keys tab, click on Add, then type .uc into the Extensions field that comes up.

Once that's done four keys, F9 through F12, will show up in the User Exec Keys window. Let's click on F9 to make it convenient. Once clicked the options on the right become available.

For the Execute line, click on the button to the right of the field and navigate to our UDK installation's Binaries\Win32 folder, and select UDK.exe. For Start In, copy the Execute line but leave out UDK.exe.

In the Parameters field, type "make" without the quote marks. This tells UDK.exe that we want to compile code instead of opening the game.

Change Save to All Files Before Execution. This makes sure that all of our changes get compiled if we're working in more than one file.

Check Capture Console Output and Scroll Console to the Last Line. This lets you see the compile progress at the bottom of ConTEXT, and any compiler errors will show up there as well.

Now we're going to set up an UnrealScript highlighter. Highlighters make code easier to read by color coding keywords for a programming language. Since each language has different keywords, we need a highlighter specific to UnrealScript. Close ConTEXT and find the U nrealScript.chl file included with this book, or head to http://wiki.beyondunreal.com/ConTEXT and follow the instructions for the UnrealScript highlighter. Once you have your .chl file, place it in ConTEXT's Highlighters folder.

Open ConTEXT again. In the top toolbar there is a drop-down menu, and our UnrealScript highlighter should show up in the list now. Select it and we're done setting up ConTEXT!

Run the installer. It will ask you to accept the agreement. Read through it and accept.

Choose where you want to install the program. The location doesn't matter so choose a place convenient for you.

The default setting for the components is fine, so let's use a Full Installation. This will give us a graphical interface and some extra help files if we need them.

UnCodeX will ask whether you would like to add a Start Menu folder. Select your options and continue.

Select where you would like shortcuts placed and click on Next.

Review the installation settings and click on Install!

When the installation finishes, exit without running UnCodeX.

Open UnCodeX. It will automatically detect that this is the first time we've run it and ask if we want to edit the settings. Choose Yes.

The UnCodeX window will pop up with the Source Paths tab open. This is where we will add our source code directory. Click on Add.

Navigate to our UDK installation's Development\Src folder and select it.

The directory will show up in the window below the Add button. That's all we need to do here, so click on Ok. UnCodeX will ask if we want to scan the directory. Click on Yes.

That's all we need to do! UnCodeX will scan and organize all of the files in the Src folder and display them.

In the Development\Src folder, create a folder called AwesomeGame. Inside that, create a folder called Classes. This is where all of our source code will go.

When code is compiled, the final .u file's name is the same as the folder, so in our case when we compile a file called AwesomeGame.u, it will show up in the UDKGame\Script folder. Empty folders are ignored, so let's create our first class so we have something to work with. We'll create a simple class we can place in a level to have the game run the code that we write.

Create a text file and name it AwesomeActor.uc (make sure file extensions are shown in your folders so you don't accidentally name it AwesomeActor.uc.txt).

Open the file in ConTEXT and type the following code into it.

Class AwesomeActor extends Actor
   placeable;

defaultproperties
{
   Begin Object Class=SpriteComponent Name=Sprite
      Sprite=Texture2D'EditorResources.S_NavP'
   End Object
   Components.Add(Sprite)
}

Make sure all of the punctuation is correct, particularly the opening and closing brackets after defaultproperties. The compiler is very particular about those brackets; they have to be on their own lines for anything inside them to work correctly.

The first line of our class defines the name of our object and its relationship to other objects in the game. The name of the file has to be the same as the name we type here; otherwise the compiler will give us an error. In this case both are AwesomeActor . The extends Actor part makes our AwesomeActor a child of Actor. In a way the class tree can be seen as a family tree, with classes inside the tree being children of the ones further up the chain.

The second line makes it so our class can be placed in the editor. Things like lights, path nodes, vehicles, all of these have placeable in their .uc file so the editor will let us place them. Other things like projectiles or explosions wouldn't be set as placeable since they are created while the game is running.

The section in the default properties creates a sprite so that we can see the actor in the editor and in the game.

Now, before we compile we need to let the game know about our AwesomeGame folder.

Open UDKGame\Config\DefaultEngine.ini and add our package AwesomeGame to the end of the EditPackages list.

[UnrealEd.EditorEngine]
+EditPackages=UTGame
+EditPackages=UTGameContent
+EditPackages=AwesomeGame

Save DefaultEngine.ini and close it.

Open ConText and press F9, which we set up earlier to compile our code. If we typed everything in correctly, it should give us a Success message at the end!

If there are any warnings or errors, look over the code again to make sure everything is spelled correctly and the punctuation is correct. The error message itself should provide a clue as to where to look. It will also give you a line number where the error happened.

Now that our code is compiled, let's add our AwesomeActor to a level. If you don't have an editor shortcut or can't find it in your Start menu, it's easy to make one. Go into UDK-AwesomeGame\Binaries\Win32 and right-click on UDK.exe. Click on Send To and then Desktop (create shortcut). Right-click on the shortcut it created and click on Properties. In the Target field, add editor to the end without quotes:

Now let's open the editor!

Close the Welcome Screen and Content Browser, and let's take a look at the editor real quick. To try out our code we're going to need a test map, so go to File, and click on Open, and select ExampleMap.udk to open it.

One thing we'll notice immediately is that there seems to be a lot of strange objects floating around the level. These are Actor classes that are normally invisible in game, but have sprites that can be seen in the editor. Remember the sprite we added to the default properties of our AwesomeActor? This is where it gets used.

Now let's add our AwesomeActor.

Click on the Content Browser button to open it up again.

The Content Browser will show the tab with game assets like textures and meshes at first, but we need to take a look in the Actor Classes, so select that tab in the top.

This looks a lot different than the class tree in UnCodeX though. Classes can be put into Categories so they're more organized in the editor, but right now we just need to see a normal class tree, so uncheck Show Categories.

There's our AwesomeActor class!

Select AwesomeActor and close the Content Browser. In the 3D viewport, right-click on the floor and near the bottom click on Add AwesomeActor Here.

There's the AwesomeActor, showing the sprite that we put in the default properties of our class! Normally these sprites won't show up in the game, but we didn't put any restrictions on the one in our default properties so we'll be able to see it for now.

Click on the Play button to run the game in a new window.

After you're done checking out the AwesomeActor in the level, close the game window.

Now let's save the map so we can keep using it to test. We don't want to save over ExampleMap so let's save it in our own folder. Create a new folder in the Content\Maps directory called AwesomeGame, and in the editor save the map as AwesomeMap.udk inside that folder.

Close the editor.

So we have our class set up, but is there anything more we can do with it? Usually the first task when learning a new programming language is to make a Hello World program, so let's do that now. Open up our AwesomeActor.uc file in ConTEXT. Let's add some more code.

The first thing we'll do while we're here is make it so our actor doesn't show up in the game but still shows in the editor. We can do this with a simple one line addition to our default properties.

Add a new line in the default properties and write the following:

Begin Object Class=SpriteComponent Name=Sprite
   Sprite=Texture2D'EditorResources.S_NavP'
   HiddenGame=True
End Object
Components.Add(Sprite)

Now let's add our Hello World. This will go before the default properties section.

function PostBeginPlay()
{
   `log("Hello World! ==========");
}

PostBeginPlay is a function that is run when an Actor is first created, so it's a good place for our Hello World. The log line we put inside that function will output to a text file so we can see that our class is running correctly. So now, our class should look like this:

class AwesomeActor extends Actor
   placeable;

function PostBeginPlay()
{
   `log("Hello World! ==========");
}

defaultproperties
{
   Begin Object Class=SpriteComponent Name=Sprite
      Sprite=Texture2D'EditorResources.S_NavP'
      HiddenGame=True
   End Object
   Components.Add(Sprite)
}

Before we compile, make sure the editor is closed. The compiler can't delete the old .u file if it's still in use by the editor and we'll get an error.

With the editor closed, compile the code by hitting F9 in ConTEXT.

Now open the editor, and open AwesomeMap.udk .

We don't need to do anything to our AwesomeActor, changes we make to our compiled classes automatically affect any of the actors we've placed in our levels.

Run the game by clicking on the Play button in the top as before. We'll see that our AwesomeActor is invisible now, so the line we added to the default properties is working. But where's our Hello World?

Close the game window and exit the editor. Go into the UDKGame\Logs folder and take a look at the files in there.

There should be Launch.log, Launch2.log, and any number of backups depending on how many times the game, editor or compiler has run. When they run, they create a backup of the existing Launch.log file and start a new one. Whenever more than one is run at the same time, as in the case of us running a game window from the editor, it creates a second file called Launch2.log and so on. So, since we were testing our code from a game window in the editor, let's take a look at Launch2.log.

Open Launch2.log in the UDKGame\Logs folder.

[0008.05] Log: Game class is 'UTGame'
[0008.24] Log: Primary PhysX scene will be in software.
[0008.24] Log: Creating Primary PhysX Scene.
[0008.26] Log: Bringing World UEDPCAwesomeMap.TheWorld up for play (0) at 2011.05.19-15.15.52
[0008.28] ScriptLog: Hello World! =========
[0008.28] Log: Bringing up level for play took: 0.193269