UnrealScript Hello World

This page is one of a series of UnrealScript Lessons.

Previous tutorials:

You've set up your environment: Setting Up UnrealScript

Overview

This tutorial will teach you how to compile a small mutator whose sole purpose in life is to write "Hello World" into the Unreal Tournament [log file]? (UnrealTournament.log or UT2003.log).

We assume that you've never tried building anything in UnrealScript before, and you haven't got a clue where to actually start. What follows applies equally well to UT and UT2003.

Create the Directory Structure

In your UT directory create a directory called MutHelloWorld.

In the newly created MutHelloWorld directory create another directory called Classes. (For more on this step, see Set Up Package Folders.)

You should now have the following directory structure

{Base Directory}\MutHelloWorld
{Base Directory}\MutHelloWorld\Classes

So far so good. Now let's write the code.

Creating the mutator

Within the {Base Directory}\MutHelloWorld\Classes directory create a new file called HelloWorld.uc.

This is just a normal text file so you can use Notepad, vi, or any other text editor application of your choice to create/edit it. The uc extension means that it's an Unreal Class file. All UnrealScript code is contained in UC Files (see that page for tips on working with them).

Caution: Be careful to actually name your file HelloWorld.uc, not HelloWorld.uc.txt when using Notepad or another Windows text editor. By default Windows Explorer would hide the ".txt" part of the file name, so only "HelloWorld.uc" would show up along with a "text file" icon. The compiler won't find that file though and complain about it.

Place the following code within the file you just created (HelloWorld.uc)

class HelloWorld extends Mutator;

function PostBeginPlay()
{
  Super.PostBeginPlay(); // Run the super class function (Mutator.PostBeginPlay).
  Log("Hello World");    // Write our log message
}

Caution: Note that the name of the class must be exactly the same as the filename.

This is already enough for UT, but in UT2003 we need some more. Add the following lines at the end of the file:

defaultproperties
{
  FriendlyName="Hello World Mutator"
  Description="Log 'Hello World'."
}

There – that's all we need in the code. The PostBeginPlay() function is called immediately after the object has "entered the game" so to speak. All we need this function to do is write a line to the log.

Save the file and, if you used notepad, make sure it has an extension of .uc and not .uc.txt.

Creating the package interface file

The package interface file has an extension of .int. This file tells UT what classes are available within the package of the same name (it has a .u extension instead) for interrogation and/or public use. All INT files need to live within the {Base Directory}/System directory. So lets create our INT file now.

Using your favourite text editor create a file called MutHelloWorld.int in the {Base Directory}/System directory. All INT files are plain text so you can look at the others in the {Base Directory}/System directory if you wish. Just don't change any of them.

Add the following two lines of text to your MutHelloWorld.int file and save it to disk:

[Public]
Object=(Class=Class,MetaClass=Engine.Mutator,Name=MutHelloWorld.HelloWorld,Description="Hello World Example")

The Description=... part won't be used in UT2003, but it helps identifying the mutator if you have more than only one of them in your package.

Caution: Make sure you don't indent any of the lines within the .int file. The .int files are not parsed correctly by the Unreal Engine when lines are indented.

Compile Your Code

So far we have created our code and created a file that will tell UT about our fantastic mutator. We still don't actually have any code that UT can run. We need to compile our code into a package file (a .u extension). To do this we need to tweak the Game Ini File – UnrealTournament.ini or UT2003.ini depending on which game you are using.

Open the INI file in your favourite text editor and search for the following string EditPackages=. You'll find a whole list of them. These are the packages that the compile command you are about to learn will attempt to build when executed. Only packages that are not found will be built.

Immediately after the last EditPackages=.... line (doesn't matter what the .... is) add the following line:

  EditPackages=MutHelloWorld

Save the file and get a command prompt up. Change the directory you are in until you are in the {Base Directory}/System directory. Once in the {Base Directory}/System directory enter the following command:

  ucc make

This will run the compiler. It will list each package you have on your EditPackages=... lines in your UT ini file, but will only attempt to compile a package if it's .u (or package file) is not there. In this case, because this is the first time we have built our mutator the package file MutHelloWorld.u doesn't exist.

Assuming you weren't told about any errors you should be able to see your compiled mutator's package file MutHelloWorld.u in your {Base Directory}/System directory.

That's All Folks

Right, we've created our package interface file (.int), written our code (.uc), and compiled it into a package file (.u) it's now time to test our mutator.

Start up Unreal Tournament and go to the mutator page. You should see your Hello World mutator in the list of available mutators. Add it to the game and start killing things.

Once you've been in the game for a few seconds quit unreal tournament. If you look in your unreal tournament log file (UNREALTOURNAMENT.LOG or UT2003.LOG) you should be able to find your Hello World message in there. If you can then your mutator worked Well done. If you can't and did everything as explained above, look again. It has to be in there .

Some Other Things to Look At

OK, so now you've built your first mod you're probably wanting to make one that does more than write to the UT log file. Well, here's some suggested reading.

UMake – Will make building and managing your mods easier
Mod Authoring – An excellent overview of the types of mods - it's a little dated now but worth the read.

Don't forget about the search function in the Wiki.

On a final note, I have found a difference between UT and UT2003. In the UT2003.INI file there are 2 EditPackages=.... sections. One for the game, and one for the editor. It seems that the EditPackages=.... in the editor section (2nd in the file) is re-written whenever the editor is closed. So if you start UnrealEd (UT2003 version) up and it complains about a missing package file, check the UnrealEd EditPackages=... section in your UT2003.INI file.

Comments

Tarquin: Nice idea, Ent. I was pondering adding a 2nd section on making a class in UEd for scripting from a mapper's POV, but now there's all these "macro"-style classes, I'm not sure it's needed. BTW, what do you think of "Hello World" as a simpler name for this page?

Mychaeel: "UnrealScript Hello World" maybe? (A "Mapping Hello World" might be nice too.) If the complexity of a programming language's "Hello World" is any indication for its learning curve though, UnrealScript appears to be rather scary though. – What about using Level.GetLocalPlayerController().ClientMessage instead of "Log" for that Hello World script though? That'd give people something to look at in-game. – And I'd be in favor of mentioning UMake somewhere after explaining the individual compilation steps.

EntropicLqd: I did think about actually displaying the Log message on screen - but decided that the additional code might be too scary - if it only appears once people would miss it so it would have to be on a timer ..... The benefit of using Log() is that it forces people to look in their UT log file - a good reminder that it exists. I am intending to add some additional reading links to the page - but didn't get time last night. In terms of the name of the page, feel free to rename it to anything you feel is more appropriate.

Harmeister: I've converted this to a wizard and added it to WOTgreal 2.805. Same content, different format.

Tarquin: you mean you've embedded this tutorial in WotGreal? That's cool, as long as you give credit where it's due. I think it was EntropicLqd who wrote most of this page. A credit to him & the UnrealWiki would be good.

Harmeister: Yup. There are links all over coming back to this page. And the intro page says that it was converted.

UserEquals1D10T Does the INT file server the same function as a header file does in C++?

EntropicLqd: They are similar - but INT files are not compulsory. You don't actually need an INT file to run a mod if you specify it on the command line (e.g. CTF-Coret?mutator=MutMyMutator.MyMutator). However, both UT and UT2K3 use the INT files to determine which mods are installed. They essentially search through the INT files for public classes of type Mutator and GameInfo so they can list gametypes and mutators in the interface. So if you want your mutator/mod to appear in the menus then you need to create an INT file.

DUc0N I added the Linux remark about halfway through (Compile...). You'll correct me if I'm wrong, right? ;-) (Edit:) And then I discovered that coding mods under Linux simply doesn't work. Damn. Maybe we can get the people at Epic and GCC together on that one? > :-)

Foxpaw: From what I've heard, UCC takes quite a while to compile so it isn't high on the list of things to debug at Epic right now.

help HE I GOT A PROBLEM I CANT SEE MY MUTATOR IN MY MUTATOR LIST CAN ANY BODY HELP ME pLAESE MOH_FAN1942@HOTMAIL.COM

EntropicLqd: Check that the .int and .u files are both within the System directory of your UT/UT2003 installation. It's probably not working because your caps-lock seems to be stuck.

Category Tutorial