My First Mod

How to create your first playable scripted Workshop mod!

Introduction

This guide will walk you through the basic steps of creating your first Workshop mod by using UnrealScript. You do not need to have any prior programming or UnrealScript knowledge to follow along on this tutorial, but it will help immensely if you want to do anything more complex.

This tutorial assumes you've followed my Getting Started With POSTed guide. You'll need to be set up with POSTed and a copy of the UnrealScript source to get started. Reading Testing Quickly and Effectively With the Command Prompt will also be helpful, but it's not required.

Throughout this guide we'll go through a few simple steps on how to create a mod that turns your most basic of weapons, the foot, into a kicking machine of death. Yes, you can do this already with the MightyFoot cheat, but you wouldn't learn anything if you used that instead, would you? :P

Quick primer: Mutator/P2GameMod

Before we start I'll explain a couple quick things about how the POSTAL 2 implementation of Steam Workshop works. Basically, there are two types of content that our Workshop supports: maps and mods. You can include all other kinds of content such as skins, animations, characters, weapons, and so forth, but the in-game Workshop Browser only sees them as custom maps or game mods.

This tutorial covers game mods. Specifically, the Workshop Browser needs game mods to be in the form of a class called P2GameMod, which is a subclass of the engine's Mutator, which is actually the base class for MULTIPLAYER game mods. P2GameMod has its own hooks to allow you to do specific things during the single-player game.

You can also create your own game types by subclassing P2GameInfoSingle, but that's outside the scope of this tutorial. For an example of this, look at the Sandbox and Ultimate Sandbox gametypes inside WorkshopSample.

The takeaway from all of this is that when making content for POSTAL 2, if it's not contained to a specific custom map, it has to be part of a P2GameMod. P2GameMod is fairly versatile, so whether it's a new weapon, custom pawn skins, or whatever the hell else, you should be able to do it with a P2GameMod.

Creating your own package

First, we'll need to create a package to compile. We'll call it DeadlyKick. In your POSTAL2Editor folder (where you unzipped all the UnrealScript files earlier), create a folder called "DeadlyKick", then open that up and create another folder called "Classes".

Next, we'll copy the Sample Workshop Mod to use as a base for our deadly-kick mutator. Go back to POSTAL2Editor, open up WorkshopSample, then Classes, and look for a file called SampleWorkshopMod.uc. Right-click and copy that, then go back up to POSTAL2Editor. Open DeadlyKick, then Classes, and then paste. Rename the file to DeadlyKick.uc, and open it up with your text editor.

The first thing we'll need to change is the class name. If you have two UnrealScript classes or objects that share the same name, you're gonna have a bad time. Underneath the comment block you'll find the class definition line. It currently reads:

class SampleWorkshopMod extends P2GameMod;

Change it to say:

class DeadlyKick extends P2GameMod;

(It's OK to name the class the same thing as the package, just don't give two classes the same "base" name)

Congratulations, you've scripted your first mod! It doesn't actually do anything yet, and it currently exists only as a script file and not a compiled .U file, but hey, first steps first.

Before we try to compile it, let's have this mod do something. Namely, let's have it screw with the foot weapon, and make it super-powerful. If you scroll throughout the file, you'll find an array of mostly-empty functions. Each one can be used to override something different about the base game: the player pawn, his inventory, the appearance or attributes of NPCs, and so on.

There's a nice global function called CheckReplacement that you can use to alter almost any actor that's spawned into the world. We're going to use it to make our foot weapon deadly. Look for the following section of code:

function bool CheckReplacement(Actor Other, out byte bSuperRelevant)
{
	return true;
}

And change it to look like this:

function bool CheckReplacement(Actor Other, out byte bSuperRelevant)
{
	if (FootAmmoInv(Other) != None)
		FootAmmoInv(Other).DamageAmount=9999;

	return true;
}

A quick note: there are two components to every weapon in the Unreal Engine: the weapon itself, and its ammo. In POSTAL 2, the weapon class handles the first-person model, firing modes, and other similar things, while the ammunition handles dealing damage. What we did here is override the paltry 3 damage of the foot to a whopping 9999, guaranteeing an instant kill to nearly everything in the world.

Save your file, and then go to POSTAL2Editor\System. We need to compile your script into a .U package so the game can use it. To do this, open Postal2.ini, and look for a section titled [Editor.EditorEngine]. If you scroll down to the bottom of that section, you'll see a bunch of "EditPackages=" lines like this:

EditPackages=AWShell
EditPackages=Postal2Extras
EditPackages=Postal2Holidays
EditPackages=EDStuff
EditPackages=P2R
EditPackages=PostalArcade

Add your DeadlyKick package to the end there:

EditPackages=AWShell
EditPackages=Postal2Extras
EditPackages=Postal2Holidays
EditPackages=EDStuff
EditPackages=P2R
EditPackages=PostalArcade
EditPackages=DeadlyKick

(Note: if your package was instead called AwesomeMod, you'd put AwesomeMod there instead.)

Save Postal2.ini. It's time to compile your package, and to do that we'll go to the command line. If you followed my Getting Started with POSTed guide, you should have a cmd.exe shortcut right there in the System folder. Go ahead and open it up, and run the command:

ucc make

You'll see a bunch of stuff appear, and at the end you should see something like this:

--------------------DeadlyKick - Release--------------------
Analyzing...
Parsing DeadlyKick
Compiling DeadlyKick
Success - 0 error(s), 0 warnings

If you got an error, check to make sure you followed the above steps correctly and there are no typos in your changes. Otherwise, you should now have a file called DeadlyKick.u. Time to test it!

Testing and enhancements

Let's test our mod from the command line. We don't currently have an INT file for it, so the game doesn't know it exists. However, using the power of the command line, we can force the game to use our mod right off the bat. We'll use the built-in TestMap for testing. Go to the command line and enter:

postal2 testmap?Mutator=DeadlyKick.DeadlyKick

(If you named your package or class name something else, use that name instead. For instance, if your package is AwesomeMod and your game mod class is KickassGameMod, you'd use Mutator=AwesomeMod.KickassGameMod)

You'll see the WARNING splash, then be dumped into the testing area. Go kick some pawns to see if your code worked. If you've followed along correctly so far, one kick should kill anything on that map!

Once you're done playing around, exit the game (quick shortcut: bring up the console with the tilde ` key, then enter "quit")

Next we're going to add some more functionality to our kick. To look at all the cool things we can do, let's have a look at the FootAmmoInv source code. Open up POSTAL2Editor\Inventory\Classes\FootAmmoInv.uc and scroll down to the bottom, the "default properties" section:

defaultproperties
{
	DamageAmount=3
	bInstantHit=true
	Texture=None
	DamageTypeInflicted=class'KickingDamage'
	MomentumHitMag=120000
	FootKickWall=Sound'WeaponSounds.Foot_KickWall'
	FootKickDoor=Sound'WeaponSounds.Foot_KickDoor'
	TransientSoundRadius=80
}

We've already tweaked the damage amount. bInstantHit needs to stay true, and foot ammo doesn't have a HUD texture icon. However, we can do some cool things with the next two lines. The MomentumHitMag is a number that determines how far a hit will knock the target actor. Let's double that number and see if it does anything. Go back to DeadlyKick.uc, and change your CheckReplacement function to look like this:

function bool CheckReplacement(Actor Other, out byte bSuperRelevant)
{
	if (FootAmmoInv(Other) != None)
	{
		FootAmmoInv(Other).DamageAmount=9999;
		FootAmmoInv(Other).MomentumHitMag=240000;
	}
	return true;
}

I've made two major changes here. First, I added curly braces before and after our property reassignments -- if you want more than one statement to execute as part of an if, it needs to be enclosed in a block. Second, we've doubled the MomentumHitMag of the foot. Save your changes, and go back to the command line.

You may have tried to recompile DeadlyKick already, but there's something you need to know: if you don't delete your old .U file first, UCC won't attempt to recompile the package. You can do this from the command line like such:

del DeadlyKick.u

Once you've done this, go ahead and ucc make, then run your mutator on TestMap again (hit the up arrow a few times and the postal2 line will reappear, saving you the trouble of typing it all out again)

You'll notice that people or bodies you kick now go flying further! Feel free to play with the MomentumHitMag value, but be aware that extremely high values may cause the ragdoll system to fail, turning the pawn into a pile of meaty gibs, or even worse -- cause a crash to desktop.

You may have noticed that when NPCs kick you or other people, they don't get the damage boost. This is because the NPC kick damage is defined in the pawn itself, and not as a weapon like with the Dude. Additionally, the NPC kick damage is defined as a constant and not a variable, so changing it isn't as straightforward, and won't be covered here.

Next let's try changing the DamageType. Different damage types have different effects. We're going to give it the 'Gibbed' damagetype, which (as you may guess) gibs anything it kills:

function bool CheckReplacement(Actor Other, out byte bSuperRelevant)
{
	if (FootAmmoInv(Other) != None)
	{
		FootAmmoInv(Other).DamageAmount=9999;
		FootAmmoInv(Other).MomentumHitMag=240000;
		FootAmmoInv(Other).DamageTypeInflicted=class'Gibbed';
	}
	return true;
}

Save, recompile, and run. Now your kick targets turn into meat chunks!

We're going to make one more change before we're done here. Let's change the Gibbed damage type to the same damage type used by the scythe and see what happens:

function bool CheckReplacement(Actor Other, out byte bSuperRelevant)
{
	if (FootAmmoInv(Other) != None)
	{
		FootAmmoInv(Other).DamageAmount=9999;
		FootAmmoInv(Other).MomentumHitMag=240000;
		FootAmmoInv(Other).DamageTypeInflicted=class'ScytheDamage';
	}
	return true;
}

As expected, your foot has now become a slicing weapon of death! You can also use class'MacheteDamage', and instead of slicing bodies in half, it will only slice off limbs and heads.

Either way, we're done here. Let's find out how to make this a Workshop mod.

Creating an INT file and testing with the in-game Workshop Browser

Okay, so, as explained earlier, your mod is invisible to the game unless it has a properly-crafted INT file. Let's set one up now. Go into the POSTAL2Editor\System folder, and create a file called DeadlyKick.int:

[Public]
Object=(Name=DeadlyKick.DeadlyKick,Class=Class,MetaClass=Postal2Game.P2GameMod)

Short and simple. This tells the game that we have a P2GameMod called DeadlyKick.DeadlyKick. You'll note this is the same line we put for Mutator=, so if you named your package or class name different, you'd use that instead.

Anyway, save that file, and then launch Postal2.exe normally (either by the command line with no arguments, or double-click in Explorer) Go to New Game, Workshop, and then click on the Mods tab.

You'll see your mod... actually, no you won't. Turns out I've been following along here and neglected to mention something important! What you actually see is "Sample Workshop Mod" -- we forgot to rename our mod. Quit out of that and open up DeadlyKick.uc again, and go down to the bottom. We need to change a few of our mod's Default Properties.

///////////////////////////////////////////////////////////////////////////////
// Default properties required by all P2GameMods.
///////////////////////////////////////////////////////////////////////////////
defaultproperties
{
	// GroupName - any Game Mods with the same GroupName will be considered incompatible, and only one will be allowed to run.
	// Use this if you make mods that are not designed to run alongside each other.
	GroupName=""
	// FriendlyName - the name of your Game Mod, displayed in the game mod menu.
	FriendlyName="Sample Workshop Mod"
	// Description - optional short description of your Game Mod
	Description="An example of how to do various things with P2GameMod."
}

Change the FriendlyName to "Deadly Kick", and write something appropriate for the Description:

///////////////////////////////////////////////////////////////////////////////
// Default properties required by all P2GameMods.
///////////////////////////////////////////////////////////////////////////////
defaultproperties
{
	// GroupName - any Game Mods with the same GroupName will be considered incompatible, and only one will be allowed to run.
	// Use this if you make mods that are not designed to run alongside each other.
	GroupName=""
	// FriendlyName - the name of your Game Mod, displayed in the game mod menu.
	FriendlyName="Deadly Kick"
	// Description - optional short description of your Game Mod
	Description="Grants the player a deadly foot."
}

Save, recompile, and reload POSTAL 2. New Game --> Workshop --> Mods, you should now see Deadly Kick in there. Double-click on it to add it to the active mods list, then hit Start. If you've done everything correctly, your in-game boot should now be slicing and dicing bystanders (or doing whatever else you might have modded it to do)

Conclusion

Normally, the next step you'd take (after thoroughly testing your mod to make sure it works correctly and doesn't cause issues) would be to upload it to Workshop via POSTed. This is covered in our official Steam Workshop Guide. In order for your mod to work correctly when subscribed to, you'll have to include both the .U and .INT files. If you don't, your mod will be unplayable by end users!

Now that you know the basics of creating your own P2GameMod, get out there and make some awesome ♥♥♥♥! Remember to start simple. Don't try to bite off more than you can chew or you'll get discouraged easily.

If you have any questions about how to create Workshop mods, or about scripting for POSTAL 2 in general, don't hesitate to ask in our Workshop Discussion Forum. I try to answer questions when possible, but if I'm not around, chances are someone else will be able to help!

[Normal Pills Enjoyer]

Whenever I try to test the mod in-game, I always just get "Unregonized command"

[girthquake]

Too bad people still won't listen to this.

[DsC.sashusilver]

Thanks for this guide! I will try it the next days :)

[12GOVNOU]

My game can't see this "DeadlyKick" mod. There is just nothing in "mods' in workshop option in main menu.

[Enkay]

There should be a ZIP file containing UnrealScript source. See Getting Started With POSTed for details.

[Maple Wavebeam]

I'm not finding the SampleWorkshopMod.uc file. I'm looking in .../Steam/SteamApps/common/POSTAL2Editor. Is this it, or is there a different POSTAL2Editor folder?