Beginner's Guide to Unreal Using UnrealScript

Purpose

In this document I will attempt to provide an introduction to programming for Unreal using Unrealscript and outline the basic class structure that Unreal uses. This is intended for beginners who are looking for a starting point in creating Unreal modifications. I strongly suggest also reading Tim Sweeney's "Introduction to Unrealscript", as this document is more specific in the application of Unrealscript to Unreal, and his introduction is more general to Unrealscript. This will not cover the use of header files and other libraries, as it is not currently available to the public at the time this document was written. Comments, suggestions, praise should all be sent to Ray Davis via email at mailto:ca@planetunreal.com. Thanks go to Tim Sweeney, Steven Polge, and the rest of the Epic team for making a cool game, and being cool developers who actually respond to questions. You guys rock. :-)

Introduction

Unrealscript is a language developed solely for developing game content for Unreal. It is based on Java and C++, so if you have any experience in either of those languages, or just C, the learning curve for Unrealscript will be relatively small, but if you do not have any previous experience I strongly suggest that you first learn one of those languages and then return to Unrealscript. Unrealscript adheres to a syntax style common to both Java and C++/C, sharing many keywords found in Java.

Unrealscript is an Object-Oriented-Programming language (OOP for short), which means that it is based on the concept of classes and inheritance. It is important to note that Unrealscript doesn't have all the features of a more complete OOP language such as Java, mainly it doesn't support things like multiple-inheritance, but luckily none of these missing features are necessary to make a fully functioning modification. There are several tutorials that will quickly get you acquainted with the concept of OOP if you are unfamiliar with it, Brandon Reinhart's being one that can be found here.

A unique feature to Unrealscript that is not found in either Java or C++ is states. States are a feature that allows you to define different implementations of functions within the same class (very similiar to function overloading in OOP), and generally they are used for time-based programming. For example, say you had a Player class that contained 3 states, Walking, Running, and Idle. Say that you wanted the Player to do a flip in the air if he jumps while running, and that you didn't want to have him jump at all while standing still (or Idling). One way to do this using states is to define your jump function in both the Running and Idle states, then in the Running state code a simple flip in that version of the Jump function, and then code a standstill in the Idle state's version of the Jump function. So now when your player is running (and thus in the Running state) it will do a flip if it jumps, and will do nothing if its not running. Sorry if this isn't a very good example, but it should help make it a bit clearer how states can be very useful.

Unreal stores Unrealscript code into packages (optionally along with textures, sounds, and models) in your Unreal\System directory. To keep all your new classes in a single package for easy distribution, just specify the same package name in the package field when you create your new subclasses.

Using Unrealed to edit UnrealScript

Unrealed has a builtin class browser, editor, and compiler for Unrealscript which is easily accessible. Start up Unrealed normally and on your right there should be a collapsable tree starting with "+Actor" and having several other classes underneath it such as "-Brush" and "-Info". By clicking on the "-" or "+" next to a classname you can collapse/expand the class tree to show its child classes, and by double-clicking on the class name itself it will bring up an editable window with the class code (if there is any) inside it. By right-clicking on the class name you can bring up a small menu that allows you to create a subclass of the current class or edit the default properties. NOTE: For most modifications you will want to subclass pre-existing classes and save them to your own packages, because if you modify the original Unreal code you will not be able to play with other versions of Unreal due to mismatches (mainly as a cheat preventing measure I believe).

To compile and save newly edited code just press F7 to compile all changed scripts, and then at the bottom of the tree select save, find you package, and click on save. Unrealed will then save you code (compiled or not) into a file in your Unreal\System directory by the name of your packagenamge and a ".u" extension (i.e. "blah.u" for the blah package).

Unreal's Class Structure

Object and Actor

Everything that is coded Unrealscript is derived from a very abstract and basic Object class, and from that we get many internal classes that deal with the engine itself (mainly sound, graphics, etc) and more importantly the Actor class which pretty much encompasses all of what you will want to modify for partial modifications. The Actor class defines the majority of standard variables and functions that are necessary for all classes, and all game-content related material is contained in classes derived from Actor. Players, weapons, artificial-intelligence, and even the game itself is derived from the base class of Actor. Important functions to note in Actor are BeginPlay(), Spawn(), Touch(), Tick(), and Destroy(). The BeginPlay() function is called whenever an instance of this class is put into play, into the game. It is very useful to initialize important variables and do other actions at the point of creation. The Spawn() function is used to create an instance of a class and put it into play. Touch() is called whenever this actor is touched by another actor, and is useful for causing damage or altering variables in the other actor. The Tick() function is called every game tick, generally as much as possible, so use it to perform actions continously or check for certain conditions. NOTE: Be careful not to put too much code into a Tick() function because it is very easy to overload the game and cause noticeable lag if too much is going on. Use the Destroy() function to destroy this instance of the class when you no longer want it to be in play.

Pawns

The Pawn class contains the ScriptedPawn (AI), FlockPawn (Insect/Flock AI), PlayerPawn (Players), and more recently the Bot classes, essentially all of the "living entities" in a level. The Pawn class defines basic variables, movement and other miscellanous functions common to all Pawns. Health, Groundspeed/Airspeed, and JumpZ are just some of the useful variables found in all Pawns.

PlayerPawn encompasses all players, a.k.a. clients, that are available in the game. It has several child classes, mainly UnrealIPlayer, then Human/Skaarj, and then the various male/female players. PlayerPawn contains all of the functionality of the players (movement, input handling) while the rest of the children classes handle all of the animations and sounds specific to the various players. The PlayerInput() and PlayerCalcView() are two functions that can be altered in your own classes to create some very cool modifications. PlayerInput() handles all input from the player, calls pertinent functions, and modifies appropriate data. PlayerCalcView() handles the calculations of the view of the player, and can easily modified to create a third person view, etc.

The ScriptedPawn is where you will find all AI-related game content (the exception being FlockPawns). This class defines the framework which Unreal's Skaarj, Nali's, Queen, and every other creature you will find in the game. The AI uses states heavily, and is based upon the common pathnode-using technique for navigation. Thankfully Steven Polge is a very good programmer, and has designed a very robust AI that can be used to make new creatures very easily with very little to no new code, using editable variables to define all aspects of the AI. I strongly suggest you read Steven Polge's "Unreal Creature Care and Feeding Guide" if you plan to do any major AI programming, or if you just want to get a more in-depth understanding of how things work.

FlockPawns are special case AI that powers those wonderful schools of fish and swarms of flies that don't really do much other than look cool. You can modify these to make them a bit more intelligent if you wanted to I suppose, but they are pretty good at being insects already. NOTE: FlockMasterPawns actually handle the creation of FlockPawns, and you should spawn these instead of individual FlockPawns, as they are coded to self destruct if they don't have a FlockMasterPawn.

The Bot class used to be found beneath the ScriptedPawn class, but has since been moved to just a child of Pawn as its AI is noticeably different than average ScriptedPawns in its function and purpose. This is the class to study if you think you've got ideas on how to make more realistic/deadly/unique Bots in Unreal. NOTE: Bots still share the same initial structure as ScriptedPawns, so Steven Polge's AI guide will also be useful for understanding Bots.

Info

The Info class is a generalized class that encompasses all classes that deal with various game-related information, such as the current rules (Deathmatch vs SinglePlayer vs TeamGame), ZoneInfo which is used to create lava, water, or just plain empty space, and PlayerReplicationInfo which contains special networking information for Players. Most of my coding experiences in the Info classes has been in GameInfo to define new game types, or variations on the classics, such as ASMD-only deathmatch. It is also conceivable to subclass the ZoneInfo class to create new types of zones such as toxic goop from Mars, or maybe a specialized case of water that reflects weapon shots, etc.

Triggers

The Trigger class handles the operation of lifts, doors, and other events by responding to certain actions in the game and then performing another action, either by modifying another actor or by setting off other triggers, or both. Triggers are invisible in the game and are generally triggered by touch, proximity, or by another trigger. It is also to call the Trigger() function from another class to set off a trigger, say to open all the doors in a level at once or something. Subclass the Trigger class to create special case triggers, or other event-driven gameplay.

Effects

Effects covers all the special effects in Unreal, like explosions, laser blasts, etc. Subclass effects to create your own special effects, or combine other existing ones.

Inventory

The Inventory class, a child class of Actor, contains both the Pickup classes and Weapon classes. Pickup is all the items other than weapons that a Pawn will pick up and use in a game, be it health, armor, or ammo. Use the Pickup class to make your own unique items in a game, such as can of beans, or maybe even a landmine. The Weapon class handles all the functions for firing and aquiring weapons in a game. All of the individual Unreal weapons are defined as subclasses of the Weapon class, and handle the specifics of the weapons, such as animations and creating the projectiles/weapon effects. Just subclass weapon to create new weapons, provided you have a new model, or you can subclass one of Unreal's weapons and just use its model. NOTE: Weapons are based on an important variable, bInstantHit. If this is set to true, then the weapon will not create a projectile (such as a rocket), and instead will do instant damage to any targets in the line of sight (such as the rifle).

All the rest

There are many classes that are used to create the remaining things you see in Unreal, such as the HUD for players, lights, moving brushes, menus, or new projectiles. Experimentation, and just plain browsing through the code should help you gain a basic understanding of how everything else is layed out and how it works.

Vectors and Angles

Unreal uses the concept of Vectors and Angles to handle all of the movement and rotation of Actors in the 3d game world. A vector is a structure that consists of 3 components, X, Y, and Z values, where the X axis is forward/back, Y is left/right, and Z is up/down. You can modify these values directly to alter an Actors postition in the world, using the SetLocation() function with a new vector for the new location. Rotation is handled by an Angle structure which also consists of 3 components, Pitch, Yaw, and Roll, where Pitch will rotate up/down, Yaw to the left/right, and Roll will roll as though your were tilting your head to the left/right. Using SetRotation() you can alter what direction an Actor is facing, or convert a rotation to a vector to alter the direction of an Actor's velocity, etc.

If you're in college and would like to know more about 3d mathematics, I'd suggest taking some Physics classes and Linear Algebra, as vectors/matrices are common topics. Also try searching online for 3d mathematics tutorials, I know QDevels has a 3d tutorial, as does Weapons of Destruction on PlanetUnreal.

Conclusion

Although I'm sure you probably have many more questions, that is beyond the scope and purpose of this document, but you can find tutorials on more specific applications of Unrealscript at various websites, including Chimeric at http://www.planetunreal.com/chimeric. Also, make sure you frequent the Unreal Technology Page at http://unreal.epicgames.com, as it contains the latest news from the Unreal development team, and contains a lot of useful information.