The Way of the Unreal: UDK Property Tips and Tricks – Part 1

Get the UDK
The Way of the Unreal is a recurring series for intermediate to advanced developers looking to get more out of the Unreal Engine.
 
Click here to see them all
Click here to request a topic
Click here to get the UDK

Whether you’re a one man team, a group of dedicated guys, or a group of girls objecting to the unfair gender typing in my previous examples, chances are your UDK project will live and die by organization. Indeed, in the wide range of indie projects out there it is the few projects that actually finish that stand out, and keeping a clean codebase free of pitfalls is key to that goal.

Having said that, you’re likely to love and hate object properties in Unreal.

There’s no doubt that properties, the variable declarations in your uc files, do a lot for Unreal. They handle saving, loading, and garbage collection, plus they create a uniform interface for your content creators to tweak and twiddle your mass of bits into something resembling art. But once you’ve finished writing up your first scripts, populating your test levels with armies of static cubes, make sure you understand some of the property system’s more subtle features or risk getting severely bitten later down the road.

It's a trap!
What horrors are hidden within?

 

But hey, buck up there champ. Stick with it to the end of the post. Once you’ve “eaten your vegetables” by reading through my dire warnings, I’ll reward you with a property trick you’re unlikely to find in the official documentation.

— Property Tip: Understand Your Keywords —

Your first scripts are likely cribbed from the many examples found in the UDK. At first glance variable declarations are simple enough.

var()           int         m_SomeProp;         // Some property

Couldn’t be easier! Well, unless you’re counting the over 30 different specialized property keywords.

// You ain't seen nothing yet.
var protected transient duplicatetransient noimport input   byte    m_WTF;

Don’t be shy: click the link above the code snippet. It will take you to the official UnrealScript reference. Bookmark it. Understand exactly what each keyword does and why you (and the engine scripts you’re probably copying) are actually using it. Really grasping all of the specialized keywords in UnrealScript is something that I see even experienced game developers falter on. It doesn’t help that the documentation is… succinct, to put it nicely.

Here are a few common ones I see misused or left out when they should be used:

  • transient
    • This means that your property won’t be saved or loaded from disk, but will still get values from defaultproperties. Generally used for variables that are modified when the game is running.
       
      If you don’t intend your property value to be loaded from disk, USE TRANSIENT EVERY TIME. I see this one left off quite often, and it can surprise you later on down the line. Much of the time it just happens to work without the keyword (a side effect of how properties are saved), but a change in the class’ usage may snare you in a difficult bug.
       

      Every time. Use it. Every time. Really. Repeat after me. There will be a quiz tomorrow.

  • duplicatetransient/noimport
    • I see these confused with each other a lot, occasionally mistaken to mean the same thing, or worse assumed that using transient will get the same behavior (which it doesn’t).
       
      noimport means the property’s current value won’t be copied for text imports, while duplicatetransient is similar, but only for dedicated “duplicate” operations. Both are intended when you want a value to be set uniquely on each instance of your object and want to keep the value from being copied.
       
      In general most programmers are looking for noimport since copying and pasting actors in the editor is actually a text import under the hood. duplicatetransient is mostly only applicable to non-actor objects duplicated using “Create a Copy” in the Content Browser, e.g. objects like AnimSets and SoundCues.
  • instanced
    • Exactly the same as using the export and editinline keywords together, instanced is a useful tool that often gets tossed about to try and jiggle bugs free.
       
      Technically, instanced causes a fresh copy of the object referenced by your property to be created each time a text export is done.
       
      What this means in practice is that you can create sub objects that each instance of your class will get their own copy of. For example in the following code…
       

      class ThinkingActor extends StaticMeshActor;

      // Holds the brain for this actor
      var transient instanced MyBrainClass    m_Brain;

      defaultproperties
      {
          Begin Object Class=MyBrainClass Name=MyBrain
          End Object
          m_Brain=MyBrain
      }


       
      …each ThinkingActor in the game will get its own copy of the brain sub object. This means each actor is free to change the properties of its brain at run time, probably by calling functions on the brain itself. I the instanced keyword were left off each ThinkingActor would share the same brain. A tale of conformity gone mad.

      What instanced is not for is patching over problems where object data is being incorrectly messed with causing bugs. In this example…

       
      // Not a sub object
      var()       StaticMesh      m_Mesh;


       
      You are not meant to mess with m_Mesh since you’re pointing to the static mesh itself, presumably shared by many objects. If you incorrectly change that object at runtime you might get bugs that “magically” go away by incorrectly applying the instanced keyword.

      If you’re guilty of this practice don’t lose heart. By all means, flagellate yourself with whips and say the Lord’s Prayer 10,000 times as penance. But then go, and sin no more.

— Property Trick: Use Copy and Paste to Snoop Your Objects —

This is a simple, invaluable trick for better understanding the inner workings of properties. Simply put:

  • Open a map.
  • Select any actor.
  • Copy (Ctrl-C).
  • Open NotePad (or your favorite text editor).
  • Paste (Ctrl-V).

Surprised?


I knew it!

Copy and paste in Unreal is done using the clipboard which allows, among other things, copying actors between levels. It can also tell you quite a bit about how your object properties are working. Look at the text you just pasted. Look familiar? It probably looks quite a bit like the values you enter into the defaultproperties section on your classes. That’s because defaultproperties doesn’t contain UnrealScript, but rather the standard text format for objects.

Whenever you’re in doubt about what is going on in an object (including the variables that aren’t exposed to the editor), just copy and paste the object text to see what’s up. I’ll be making extensive use of this feature in future Property Tips to better explain how objects work.

While you’re at it crack open all the objects in Unreal to better feast on the delicious goo inside. Don’t just stick to your own creations. The more complex the object, the greater and more educational the sweet, sweet nectar.

 
 

Coming soon in UDK Property Tips and Tricks – Part 2: how defaultproperties works and more useful tricks.


 
 
Examples in this post were tested against the February 2011 version of the UDK. Want to have a particular topic covered in a post like this? Leave your request in the comments below or use the contact form.