Difference between revisions of "Getting started with Unreal Script"

From Tripwire Interactive Wiki
Jump to: navigation, search
(Initial Content)
 
(Cleaned up page, added references.)
Line 1: Line 1:
 
==Creating a Basic Mutator==
 
==Creating a Basic Mutator==
  
Step-by-step Instructions
+
This is a step-by-step guide, taken from the [http://forums.tripwireinteractive.com/showthread.php?t=43484 tutorial] of the same name, written for the official [http://forums.tripwireinteractive.com/index.php Tripwire Interactive forums] by [http://forums.tripwireinteractive.com/member.php?u=15711 Benjamin].
  
'''1. Create directory hierarchy'''
+
===Create directory hierarchy===
  
Create a directory in .../steamapps/common/killingfloor with the same name you wish to give your mutator. Create a subdirectory inside this named Classes. You should now have a directory structure that looks like this:
+
Create a directory in ''.../steamapps/common/killingfloor'' with the same name you wish to give your mutator. Create a subdirectory inside this named ''Classes''. You should now have a directory structure that looks like this:
  
 
:::.../steamapps/common/killingfloor/ExampleMutator/Classes
 
:::.../steamapps/common/killingfloor/ExampleMutator/Classes
  
'''2. Create main mutator script file'''
+
===Create script file===
  
Inside the classes subdirectory create a file with a .uc extension with a name matching the mutator's main directory name, for example ExampleMutator.uc. The path of this file should look like this:
+
Inside the ''Classes'' subdirectory create a file with a .uc extension with a name matching the mutator's main directory name, for example ''ExampleMutator.uc''. The path of this file should look like this:
  
 
:::.../steamapps/common/killingfloor/ExampleMutator/Classes/ExampleMutator.uc
 
:::.../steamapps/common/killingfloor/ExampleMutator/Classes/ExampleMutator.uc
  
'''3. Tell compiler we want to include this mutator in the compilation'''
+
===Add mutator to compilation===
  
In order to have the compiler actually compile your mutator you must add an entry for it in a file named killingfloor.ini, located in the game's system directory. Open this file, search for the section with several lines beginning with EditPackages=PackageName. Add an entry at the bottom of this list to include the name of your mutator package, which should look like this:
+
In order to have the compiler actually compile your mutator you must add an entry for it in the game's configuration file, named ''killingfloor.ini'', located in the game's system directory. Open this file, search for the section with several lines beginning with ''EditPackages=PackageName''. Add an entry at the bottom of this list to include the name of your mutator package, which should look like this:
  
 
:::EditPackages=ExampleMutator
 
:::EditPackages=ExampleMutator
  
'''4. Add some code to the mutator script'''
+
===Write mutator script===
  
 
Code:
 
Code:
Line 34: Line 34:
 
}
 
}
 
</pre></blockquote>
 
</pre></blockquote>
This is the bare minimum for compiling a mutator that can be seen in Killing Floor (actually, FriendlyName and Description aren't strictly necessary but why compile without them?). The GroupName property must start with the letters KF else it won't be seen by the game.
+
This is the bare minimum for compiling a mutator that can be seen in Killing Floor (actually, FriendlyName and Description aren't ''strictly'' necessary). The ''GroupName'' property must start with the letters ''KF'' else it won't be seen by the game.
  
'''5. Compile using UCC'''
+
===Compile===
  
Compiling the mutator is as simple as calling ucc make, which can be found in the system directory (in fact the file is simply called ucc.exe and make is a command line argument). Note that if you have previously compiled the mutator you must remove its .u file from the system directory in order to recompile (otherwise the mutator will be ignored in the compilation process).
+
Compiling the mutator is as simple as calling ''ucc make'', which can be found in the system directory (in fact the file is simply called ''ucc.exe'' and make is a command line argument). Note that if you have previously compiled the mutator you must remove its ''.u'' file from the system directory in order to recompile (otherwise the mutator will be ignored in the compilation process).
  
If you cannot find ucc.exe you may not have the Killing Floor SDK installed. Find it on Steam in the 'tools' section.
+
If you cannot find ''ucc.exe'' you may not have the [http://wiki.tripwireinteractive.com/index.php/Killing_Floor_(modding) Killing Floor SDK] installed. Find it on Steam in the ''tools'' section.
  
Additionally you may want to remove certain files and have the console wait before closing, so that you can view the compilation output (and thus determine if it failed and why). You could do all this by opening command prompt and typing the commands manually, but it's far simpler to use a batch file. Create a batch file (anywhere - the desktop is good for easy access) with a name such as ExampleMutator.bat and copy the following lines in:
+
Additionally you may want to remove certain files and have the console wait before closing, so that you can view the compilation output (and thus determine if it failed and why). You could do all this by opening command prompt and typing the commands manually, but it's far simpler to use a batch file. Create a batch file (anywhere - the desktop is good for easy access) with a name such as ''ExampleMutator.bat'' and copy the following lines in:
  
 
Code:
 
Code:
Line 53: Line 53:
 
You may need to alter the paths if you have the game installed to a different hard drive or have a different directory structure. The third line removes a file generated by UCC which while exists will prevent connecting to servers (may not apply to all).
 
You may need to alter the paths if you have the game installed to a different hard drive or have a different directory structure. The third line removes a file generated by UCC which while exists will prevent connecting to servers (may not apply to all).
  
Run the batch file and tada! If compilation was successful, you have just made your first mutator. If not, you have made a mistake.
+
Run the batch file and tada! If compilation was successful, you have just made your first mutator. If not, you have made a mistake and should re-read this article to try to find where you went wrong.
  
'''6. Functional mutator example'''
+
===Example===
  
 
Here is a functional, more interesting mutator to take a look at:
 
Here is a functional, more interesting mutator to take a look at:
Line 86: Line 86:
 
}
 
}
 
</pre></blockquote>
 
</pre></blockquote>
What does it do? It increases the health of each player by 2 points every second.
+
What it does: Increases the health of each player by 2 points every second.
  
'''7. Where do I go from here?'''
+
===Where do I go from here?===
  
Now that you understand how to compile a mutator, I'd recommend first taking a look at the official [http://udn.epicgames.com/Two/UnrealScriptReference.html UnrealScript Language Reference] which covers all aspects of the language itself. If you plan to write mutators which work online it's vital that you understand how the networking is handled, and I'd suggest reading the [http://udn.epicgames.com/Three/NetworkingOverview.html#Unreal Networking Architecture Unreal Networking Architecture] article on this. If you want to know more about the engine (and particularly which classes are available to use) you can either browse through the script files yourself, or check out the [http://wiki.beyondunreal.com/ BeyondUnreal Wiki].
+
Now that you understand how to compile a mutator, I'd recommend first taking a look at the official [http://udn.epicgames.com/Two/UnrealScriptReference.html UnrealScript Language Reference] which covers all aspects of the language itself. If you plan to write mutators which work online it's vital that you understand how the networking is handled, and I'd suggest reading the [http://udn.epicgames.com/Three/NetworkingOverview.html Unreal Networking Architecture] article on this. If you want to know more about the engine (and particularly which classes are available to use) you can either browse through the script files yourself, or check out the [http://wiki.beyondunreal.com/ BeyondUnreal Wiki] for more general information relating to Unreal Engine itself.
 
 
Original Tutorial Author: Benjamin
 

Revision as of 20:42, 20 September 2012

Creating a Basic Mutator

This is a step-by-step guide, taken from the tutorial of the same name, written for the official Tripwire Interactive forums by Benjamin.

Create directory hierarchy

Create a directory in .../steamapps/common/killingfloor with the same name you wish to give your mutator. Create a subdirectory inside this named Classes. You should now have a directory structure that looks like this:

.../steamapps/common/killingfloor/ExampleMutator/Classes

Create script file

Inside the Classes subdirectory create a file with a .uc extension with a name matching the mutator's main directory name, for example ExampleMutator.uc. The path of this file should look like this:

.../steamapps/common/killingfloor/ExampleMutator/Classes/ExampleMutator.uc

Add mutator to compilation

In order to have the compiler actually compile your mutator you must add an entry for it in the game's configuration file, named killingfloor.ini, located in the game's system directory. Open this file, search for the section with several lines beginning with EditPackages=PackageName. Add an entry at the bottom of this list to include the name of your mutator package, which should look like this:

EditPackages=ExampleMutator

Write mutator script

Code:

class ExampleMutator extends Mutator;

defaultproperties
{
    GroupName="KFExampleMutator"
    FriendlyName="Example Mutator"
    Description="Mutator description here"
}

This is the bare minimum for compiling a mutator that can be seen in Killing Floor (actually, FriendlyName and Description aren't strictly necessary). The GroupName property must start with the letters KF else it won't be seen by the game.

Compile

Compiling the mutator is as simple as calling ucc make, which can be found in the system directory (in fact the file is simply called ucc.exe and make is a command line argument). Note that if you have previously compiled the mutator you must remove its .u file from the system directory in order to recompile (otherwise the mutator will be ignored in the compilation process).

If you cannot find ucc.exe you may not have the Killing Floor SDK installed. Find it on Steam in the tools section.

Additionally you may want to remove certain files and have the console wait before closing, so that you can view the compilation output (and thus determine if it failed and why). You could do all this by opening command prompt and typing the commands manually, but it's far simpler to use a batch file. Create a batch file (anywhere - the desktop is good for easy access) with a name such as ExampleMutator.bat and copy the following lines in:

Code:

del "C:\Program Files\Steam\steamapps\common\killingfloor\System\ExampleMutator.u"
"C:\Program Files\Steam\steamapps\common\killingfloor\System\UCC.exe" make
del "C:\Program Files\Steam\steamapps\common\killingfloor\System\steam_appid.txt"
pause

You may need to alter the paths if you have the game installed to a different hard drive or have a different directory structure. The third line removes a file generated by UCC which while exists will prevent connecting to servers (may not apply to all).

Run the batch file and tada! If compilation was successful, you have just made your first mutator. If not, you have made a mistake and should re-read this article to try to find where you went wrong.

Example

Here is a functional, more interesting mutator to take a look at:

Code:

class ExampleMutator extends Mutator;

function PostBeginPlay()
{
	SetTimer(1, true);
}

function Timer()
{
	local KFHumanPawn Player;
	
	foreach DynamicActors(class 'KFHumanPawn', Player)
	{
		if (Player.Health + 2 <= Player.HealthMax) Player.Health += 2;
		else Player.Health = Player.HealthMax;
	}
}

defaultproperties
{
    GroupName="KFExampleMutator"
    FriendlyName="Example Mutator"
    Description="Mutator description here"
}

What it does: Increases the health of each player by 2 points every second.

Where do I go from here?

Now that you understand how to compile a mutator, I'd recommend first taking a look at the official UnrealScript Language Reference which covers all aspects of the language itself. If you plan to write mutators which work online it's vital that you understand how the networking is handled, and I'd suggest reading the Unreal Networking Architecture article on this. If you want to know more about the engine (and particularly which classes are available to use) you can either browse through the script files yourself, or check out the BeyondUnreal Wiki for more general information relating to Unreal Engine itself.