UnrealScript Lessons

This is a page aimed at newcomers to UnrealScript. Head over to UnrealScript for a full reference. Readers of this page are invited to create pages, suggest ideas for topics or expand on what is already here.

Introductions

These pages cover some of background knowledge you'll need before you begin.

Unreal Engine Core – Describes how Unreal is setup so it can be modified
Object Oriented Programming Overview – Describes OOP as the method used to modify and control all aspects of Unreal. You should read this if you never used an OOP language (like Java).
Unreal Object Oriented Programming – How Unreal specifically defines OOP. This is where the rubber meets the road.
UnrealScript For Non-Programmers – Never programmed before? You need to start somewhere. Start here.

Tutorials (2003/2004)

This is a sequence of tutorials for Unreal Tournament 2003/2004. They're arranged in order of increasing complexity, starting from the very first steps in scripting. UT scripting tutorials are farther down.

1 UnrealScript Installation

Setting Up UnrealScript – Getting everything set up ready to begin coding in Windows OS.
Using UCC Under Linux – How to setup a friendly Unreal scripting environment in Linux. (Unsupported)

2 Simple mutators

These start with the extremely simple. These are all single classes, but there is considerable scope for modifying the game once we get started.

UnrealScript Hello World – The absolute simplest piece of UnrealScript we could think of.
MutTutorial – A simple player jump boost mutator.
Modifying Vehicle Weapons – How to change the weapons on a vehicle.
Regen Mutator – A simple regenerating mutator for UT2003 & UT2004.
Modify Mutator Tutorial – The Cooler for UT2003.
Super Arena Mutator – An intermediate gameplay mutator for UT2003.
TheHealer – The Healer for UT2003.
Bulldog Player – A UT2003 tutorial for creating a player that is a vehicle instead of a normal character.

3 More complex mutators

These require more than a single class to implement.

Power Core Volume Control Mutator – A tutorial on changing volume levels.
Weapon Mutator Tutorial – Minigun HE mutator.
MiceMenGrav Mutator – Uses Config and Gamerules.
Adding an Adrenaline Combo With A Mutator – Tutorial on adding adrenaline combos in UT2004.
Fire and Forget Self-Guided Missile - Not a complete mutator, but contains a real working code.

4 Class-based mutators/gametypes

RegularEngine/Player Classes – Overview of how Player Classes work within the RegularEngine framework for UT2004. For an older or alternate tutorial, see Making A Class-Based Mod.
Spawning Your Own Bot – A intro to show you how to spawn and get control of a bot. So that you can write your own customized AI-Controller
Basic AI Scripting Tutorial – Recreating the NaliCow NPC for UT2004, focusing on the custom AI.

5 Replication

Introduction To Replication – How objects sync with each other in online games.
ProjectileDestroyerVolume – (Needs description!).

6 Other

Stat Points System – Shows how to use stat points to change a gun speed, ammo held, etc.
Using The Mod System In UT2004 – Shows how to use the mod system in ut2004 by guiding you through a series of basic procedure type pages.

Tutorials (UT)

This is a sequence of tutorials for UT. The are arranged in order of increasing complexity, starting from the very first steps in scripting. Unreal Tournament 2003/2004 scripting tutorials are farther up.

1. Mutators

UT Low Gravity Mutator – A simple gravity mutator.
Changing the Enforcer (UT) – A mutator that modifies the Enforcer.

Class tutorials

These tutorials look at single classes. They are in no particular order (for now).

TriggerJumpPad – Using states.
Barrel – Using states (more complex).
Tab Controls – Using a tab control in a mutator.

Understanding Existing Unreal Code

UT2003: Creating a new Weapontype – Create a new weapon based off a pre-existing (built-in) weapon's code.
UT and UT2003: Using LocalMessages – (Needs description!).
UT2003: The Code References Page – Several classes have been posted and heavily commented for learning. Other classes are upcoming.

Unreal Specific Objects

Classes and Objects
- Package – Introduction to UT's code packaging system.
- Traversing Classes – Introduction to interacting and manipulating variables, functions, and values that exist in other classes.
- Input keys – Introduction to creating classes that allow user-inputted keys, and I include a trigger I made to use an Activate key (For original UT).
UnrealScript Vector Maths – Guide to using vectors.

When You Get Stuck

Building on Previous Experience

If you already have programming experience in a different language, the following topics will help you find out the similarities and differences between the languages you know and UnrealScript.

Please add pages for other languages. Just add UnrealScript questions and insights you gathered during your own learning process there as they come in.

Lessons in progress

Requests

Lizardman6: I would like to see a stat points system for UT2004... :-)

Unknown: I have a idea for a tutorial: how to change the main menu of ut2004

UnReally: I am making a weapon which has a unique secondary firemode: it fires a projectile that i would like to do the following: upon striking another player, NOT a wall etc., the player hit takes damage, AND the projectile forks out to nearby players like chain lightning (whether this splitting is instanthit or further projectiles does not matter), just as long as there is some sort of chain-lightning style thing going on. If neone has any ideas how to script this, please help out.

Craze: Hey, how about some UT weapon tutorials, please make a weapon from scratch tutorial and a more advanced weapon tutorial and a instant hit weapon tutorial.

Tarquin: I would really like a basic tutorial on replication: maybe something like a Trigger actor that does something to all players when touched.

NickR: I wouldn't mind some small replication examples just showing one type replication related code. Like when the simulated key word should be used or if static functions can be called from either the client or server and run on either.

Foxpaw: I'm not sure about tutorials, but those are (fairly) easily explained. Simulated functions run on actors with ROLE_SimulatedProxy or better. However, only if they are called from another simulated function. Entry points like Tick can be declared as simulated when you override them to facilitate this. A short example:

simulated function Tick( float Delta )
{
  Super.Tick( Delta );

  DoStuffOnServerOnly();
  DoStuffOnBoth();
}

// Called from a simulated function, but not simulated itself,
// the engine skips over this function on clients. (or rather,
// the non-authority version, which is usually the client)
function DoStuffOnServerOnly()
{
  DoStuffOnClient();
}

// A simulated function getting called from another simulated
// function. This gets called on both machines.
simulated function DoStuffOnBoth()
{
}

// Oops! This is a simulated function, but gets called from a
// non-simulated function, so although it COULD run on a client
// (because it's simulated) the code that calls it doesn't run
// on the client and so this won't ever get called.
simulated function DoStuffOnClient()
{
}

Static functions on the other hand, have no relation to replication and are functions that exist outside the context of an object. Static functions can't get replicated, obviously, because they aren't associated with any particular instance of an object. They can access only default variables and stuff. See Static Function and Simulated Function.

Also, feel free to refactor this somewhere or expand it into a full tutorial.. it's more a demonstration at the moment.

Tarquin: Thanks... but see, you've alreayd lost RepliN00bs with this: run on actors with ROLE_SimulatedProxy or better.... how does Replication actually WORK? Should we imagine multiple facets of the same actor on different machines, or many actors on different machines that somehow correspond to each other?

Foxpaw: Well, they're different actors, but they have a unique identifier so they "correspond" to each other. An actors Role variable determines it's replication behaviour. ROLE_Authority is usually the one on the server, and it runs all functions, simulated or not. ROLE_SimulatedProxy is usually on the client, and runs only simulated functions. ROLE_DumbProxy runs no functions, but still replicates variables. ROLE_None replicates nothing.

WheatPuppet: Can we cram this stuff into a tutorial somewhere!? I hate having code on a Tutorial frontpage.

Tarquin: maybe create Introduction to Replication?

WheatPuppet: Sounds good to me... I'm not particularly qualified to write a tute or doc on replication, though. I wonder if anyone but Tim Sweeny is. It seems to me that replication is the single least-understood aspect of UScript. I'd be willing to throw together a page as a starter in a few days (a.k.a. after final exams).

Tarquin: actually, I just meant throw the stuff we don't want here onto that page and leave it to fester Maybe someone more qualified will come along and clean up. At least this page will be tidier.

JimRimya: How about a simple weapons mod, like increasing the firing rate of the rocket launcher. Or maybe making all weapon spawn points be rocket launchers. What I'm getting at is something like rocket arena in Q3. Thanks!

M.r.bob: The GUI for UT2004 is very different from the GUI for UT2003, someone needs to make a tutorial for a UT2004 mutator with a GUI. Like one that lets you change the amount of health the pawns have, that would be a cool and simple mutator, and would teach people who only have 2004 how to make a decent mutator. Please Please Please

Bob_The_Beheader: I'd really like to see a tutorial for making heat-seeking or homing projectiles.

SuperApe: That's a good one. I just helped someone with that on BUF by using some code borrowed from BulldogRocket. That already has an Actor (Pawn) property defined for target, you just set it at launch to any (non-teammate) controlled Pawn. For the purposes making a lesson out of it, you'd want to set up how the projectile is fired. (i.e., make a new hand-held weapon? replace an existing vehicle weapon?)

Bob_The_Beheader: Cool. It does seem to me that the projectile of the heat-seeking weapon is more important then the code for the weapon itself. All you'd need to do for the weapon code in the tutorial would be to change an existing weapon's properties to fire your new heat-seeking projectile. Wait... I take that back. The weapon would need to contain code for aquiring the target, probably. Unless you wanted the projectile to aquire a target on it's own. This might make it a really difficult weapon to use, which I don't think is a characteristic of heat-seeking weapons . I think maybe the existing code for the Rocket Launcher and it's projectile would do nicely for this tutorial. You could just reduce the time required for a target lock, and up the manuverability of the rocket projectile, to make it move more like an AVRIL. Also probably reduce the damage the rocket deals and maybe the max ammo count of the launcher, in order to keep gameplay balanced. I've never seen the Bulldog at work, so I'm not sure how it's weapon works, but the target property does sound useful for this. You could just have it be set to the enemy Pawn closest to your crosshair (?? I think... :confused: ) I think making this a hand-held weapon would be better suited for a tutorial, because then you could test it in a small, quick-loading 1v1 DM map instead of some monster long-loading ONS map.

Bob_The_Beheader: Does anyone out there know how to code a melee weapon?... I guess I could just look at the code for the melee weapons in the ChaosUT mod...

Grudge Mutator

Tarquin: This is an idea I've had for some time for a simple mutator, and it strikes me that it could serve as a simple tute for netcode. It's called Grudge, and it would implement a few extra announcements to do with who is killing who. This is how it works:

Suppose Player Bob kills you, and after you respawn your first kill is Bob: it's a "Revenge" (cue announcement and screen message)
If you get killed by Bob, and then after respawning Bob kills you AGAIN (and you've not managed to kill him), then it's a "Grudge". If that happens again, there could be further announcements...

Bob_The_Beheader: I'm not sure I understand you here, Tarquin. At first I thought you were talking about something like the Revenge Rune, but are you saying that all this would do is display the message "Revenge" and later possibly "Grudge" onscreen? This sounds like the mutator on the UTAN clan's gibzilla CTF server, I forget what it's called.

Tarquin: I've actually made a start on this. A beta version is available.

Bob_The_Beheader: By the way, I'm not good enough to kill ANYONE twice in a row, not unless I'm very lucky .

Guest:(TurkeyFromHell) Tarq, I'm just started trying to make a mutator to prevent revenge killing (for a camping server), and the only way I can see to go about it (being so unfamiliar with the majority of the Engine's class system as I am) is to extend off of Pawn and redefine the TakeDamage function. Is there an easier/less... drastic way to do this?

Eliot: try extending GameRules it contains a function for damage too.

Guest:(TurkeyFromHell) Yes lol I just decompiled an existing revenge mutator to see how it worked , ty.

Discussion

DUc0N:Thought it might be nice to mention semi-up-front that mod authoring under Linux is NOT supported as of yet. Stay tuned though, I for one plan to gripe

Mr.Bob/his brother: these pages really need to be updated for 2004 im trying to figure out how to make a High gravity mutator. :cheesy:

EntropicLqd: Well, you could start by looking at the code for the low gravity mutator that gets shipped with UT2004, and then rather than make the gravity less, make it more. Seems like a good place to start to me.

Tarquin: I decided that Instant Start wasn't really suitable as a lesson.

Mr.bob: KEWL! my thingy is finally at the top, and i didn't even have to put it there!

Fearless: It would be nice to have a subject about modifying a standard UT weapons as this is what someone beginning in Uscript would like to do.

Prospero: A tutorial on the finer points of coding for networking would be rad. There are a lot of comments to the effect of "this isn't coded for networking", but why it is wrong is rarely explained.

Bob_The_Beheader: Fearless: first UScript thing I did at least was modify an original weapon. I kind of integrated this into learning how to make models and textures for UT. Now the link gun has a new model and shoots yellow glowing exploding rings! :cheesy:

OlympusMons: Added link to using the mod system in ut2004 but the page itself is ruff, if anyone could lend a hand with suggestions or give me feedback on how well it works for them Id greatly appreciate it.