Rendering Depth

First thing we’ll need is a depth buffer. By rendering to a separate render texture we can no longer take advantage of the GPU’s built-in z-testing. Having a depth buffer will allow us to do our own z-testing. Unity made it stupid easy to get a depth buffer of the scene with version 2.6.0. On the main camera run this line somewhere in Awake:

However, for our purposes the depth buffer given to us by Unity is a bit overkill. Unity will render everything that the main camera can see. We only have dust-like particles near the camera, so there’s no reason for Unity to render depth information at far distances. So instead of taking advantage of Unity’s one-liner solution, we render our own depth buffer with a different far-clip plane. This isn’t as straight forward as setting the camera’s far-clip plane and is slightly outside of this article’s scope. We’ll address this in a future article.

Rendering the Particles

Here comes the hard part. First we’ll outline the steps we need to take to render the particles. All of this happens in the camera’s OnRenderImage function.

1. Create/Setup the render texture that we will render our particles into
2. Create/Setup the camera that will render our particles
3. Render the particles with a replacement shader
4. Blend the particles back into the screen with a composite shader

First we’ll create and setup the render texture that will hold our particles.

The downsampleFactor determines the quality of the off-screen particles. Higher numbers will give worse quality, but better performance.

Next, we’ll create and setup the camera.

And the PostProcessingHelper.GetPPCamera() function:

Notice how we are setting the layer that the particles are on. This is how the camera determines which renderers in the scene are the particles that we wish to render off-screen.

Next we render the actual particles. Telling the camera to render is easy enough.

The replacement shader is a bit unwieldy, so here it is as a file. Don’t worry too much about what’s going on in the replacement shader. Just make sure to place this shader in a Resources folder.

Lastly, we blend the particles back into the scene.

And the Composite shader (again, place this in a Resources folder):

Don’t forget to release the particles render texture!

And after you finish doing any other post processing effects you may be doing, output to the destination RenderTexture:

PRETTY PICTURES!

Click for bigger images. These all should be pixel perfect if you want to flip through or diff them.

Off-Screen Particles Disabled

Off-Screen Particles Enabled

Off-Screen Particles RGB

Off-Screen Particles Alpha

Notes

Separate Alpha Blend Function: As of Unity 2.6.1, there is no way to blend alpha channels with a different blending function. So this replacement shader takes two passes on the particles. Once to render to the RGB channel and once to render to the Alpha channel. Apparently, this will be fixed in a future release of Unity and the separate pass will not be necessary. I’ll update this replacement shader if someone reminds me when that happens. Update: Looks like this can be accomplished with a single blending function if you premultiply the alpha into the rgb channel in the pixel shader. The new blending function for rendering the particles is One OneMinusSrcAlpha. The new blending function for blending the particle RT back into the screen buffer is One OneMinusSrcAlpha. And your particle RT will need to be cleared to (0,0,0,0) instead of (0,0,0,1).

Mixed Resolution: We decided that mixed resolution particles wasn’t necessary for us. The scene is too fast moving to notice the depth sampling artifacts. Plus the performance overhead from needing a second pass for the alpha channel made mixed resolution rendering just too expensive.

Soft Particles: Soft Particles are extremely easy to implement with the off-screen particles, but we didn’t see much of a difference in the final render. We decided to just use discard instead of soft particles in the end.

Anti-aliasing: This is untested with Anti-aliasing on directx. I really doubt it’ll work correctly as is. Shouldn’t be too difficult to get it to work though.

Here is an automated solution to this problem (you’ll probably want to watch full-size on Vimeo):

You’ll need Flaming Pear’s free Solidify plugin and this set of Photoshop Actions. Enjoy!

Native Encoding

The solution to this problem is to implement a JPEG encoder in native C# or JavaScript in Unity.  The other day I saw someone link to a browser JavaScript implementation of JPEG encoding, which was based off the as3corelib implementation from Flash.  Eureka!  It looked like an easy port, and an interesting exercise, so I went ahead and brought it over Unity JavaScript.

Using the JPEG Encoder

Usage is quite simple:

The encoder is threaded, so the calling script needs to yield until it’s complete. Warning: We have never actually used threads in Unity; this might totally blow up in your face! If that’s the case it’d be easy to pseudo-thread it with a few yield statements (or just run it straight in circumstances where a frame hitch isn’t a big deal–capture the screen and hold on to the image bits until the player is at a good static GUI screen or something).

Possible Uses

Why would you want such a thing? Perhaps you want to allow the player to take screenshots from a standalone build, saved to disk. Or perhaps you want to upload images to your server (Unity has an EncodeToPNG function, but they can be quite large for network transmission). Splume, one of our first Unity games, had a level editor that simply uploaded game screenshots as thumbnails:

We also uploaded screenshots when something big would happen, like a huge scoring combo.

Download the Encoder and Sample Project

Download a simple project that takes screenshots and outputs .JPG files. Just drop JPGEncoder.js into your own projects to use native JPEG encoding. Enjoy!

Here’s our browser in action (or watch in HD):

We’re releasing it!  Download the source code or check out the README.txt file.  If you find this useful feel free to donate beer money:  paypal@blurst.com!

What’s a Trigger?

A trigger is a Collider that fires events as other Colliders enter and leave its collision volume, but without physically interacting with your scene. They are physically “invisible”.  If a Rigidbody “hits” a trigger, it passes right through, but the trigger produces OnTriggerEnter calls, when the object enters, OnTriggerStay calls, for as long as the object is inside the trigger, and OnTriggerExit calls, for when the object leaves the trigger.

Take a look at the Unity collider documentation for a more verbose explanation, as well as the collision chart for when collision events are called.

Where to Use Triggers?

We use triggers as:

Static Proximity Triggers

The most obvious trigger example is to use them as, well, actual proximity triggers. Some piece of game logic is run when the player, or another object, reaches a point in space.  You could place a trigger in front of a door which causes the door to open as the player approaches.  You can easily test the entered Collider for some layer, tag, or Component to see if the trigger should execute.  This is as sample as:

Radius Triggers

The first trick with triggers is to realize they can move. You can set a trigger as a child of an object–even another physical object like a Rigidbody–and then use the trigger to take action as other objects approach or exit a radius around your object of interest.

Take the use case of spawn points, for instance; your goal is to trigger an enemy spawn as a spawn point nears your player. You could place a script on your player that iterates all possible spawn points and spawns something if it’s near enough:

The #1 reason for using triggers, over this “manual” method, is that triggers will be faster. Much faster! There are ways to make this example better–check the sqrMagnitude of the distance to avoid a square root, cache your Transform, etc–but the crux of the problem remains: You have to run this code every Update, FixedUpdate, or at least with enough frequency to respond interactively.

However, the physics engine is already checking for trigger collisions. It’s doing the work for you! Let it do its super-fast optimized thing; believe me, you can’t compete with PhysX on an optimization level. Instead of polling for spawn points in our radius ourselves, let the physics engine send events only when something enters our player radius trigger. This becomes:

Create a gigantic trigger as a child of your player object, place this script on it, and voila! To prevent collision with your physical gameplay objects, your spawn colliders should also be triggers (yes, triggers send OnTrigger* messages when other triggers enter and exit).

Warning: Trigger colliders do respond to raycasts. You should make sure your triggers are set to the Ignore Raycasts layer if your game logic uses raycasts (or are otherwise ignored by your raycast LayerMasks).

What’s In This Space?

Another great use of triggers is to the answer a question for your game logic: What’s in this space? Perhaps you want your spawn points to fire only if they’re empty, or you want to see if two objects are near enough to count for something.

Here’s a concerete example: One of our games, Crane Wars, is a stacking game. In order to determine if different building pieces are stacked on top of one another, and should count as one building, we use triggers:

The slim box outlines on the top of the building pieces are the triggers. White indicates that nothing is in the trigger, and green–the bottom two floors of the stack–indicate that another building piece is in the trigger and is considered the “upstairs” piece in the sequence. The light blue box is a spawn point; it will spawn another piece as soon as it is empty.

In order to facilitate this game logic, we have generic scripts that track objects as they enter and leave a trigger. Unfortunately, there is no function available like collider.GetCollidersInsideTrigger(). Fear not, though, it’s fairly easy logic. The following script will track all objects that enter, and store them in a list based on their layer:

An object destroyed inside of a trigger will not send OnTriggerExit events, so we must scrub our list of any null values before returning it.

Rather than poll this list continuously, our game logic script only checks for an update when things may have changed–when something enters or exits our trigger (the same trigger, as both the generic tracker script and our game logic script are on the same object). We separate scripts like this in order to keep the tracking script generic and reusable between projects. It is easy for our gameplay script to ask the tracker script for all of the objects in our BuildingPieces layer, for instance:

We use another variant that only tracks objects that match a certain LayerMask, which lets you avoid the overhead of tracking all objects in and out. The example project includes both scripts.

By the way, visualizing the status of your triggers via Gizmos is a very useful debugging tool. In the crane wars example you can draw box colliders like:

Trigger Tips and Caveats

This article mentions a few already, but to recap:

• Other triggers will “collide” with triggers! Use this for invisible triggers that don’t collide with your actual physics (spawn point triggers, etc).
• Triggers do respond to raycasts! Make sure your triggers are set to ignore raycasts, unless you really want to raycast against them.
• An object destroyed inside of a trigger will not fire OnTriggerExit. If you track objects be wary of this. The only sure way to count objects currently inside of a trigger is to use OnTriggerStay
• Triggers are fast! Use them! Even in non-physical games you will see speed increases. For example, you could have a tower defense game where your enemies are kinematic rigidbodies and turrets track targets in range using triggers.
• There is a penalty for moving static colliders (a Collider with no Rigidbody component). If you want to move your trigger around, add a Rigidbody and set it to be kinematic.
• Triggers are great on the iPhone, since everything happens in highly optimized PhysX. You’d be surprised.

Example Project

The above-mentioned scripts are included in a quick example project (so don’t worry about copying and pasting off the post). Download the example project and check them out!

Other Uses?

How have you guys been using triggers? Share your own tips and tricks in the comments!

“one day there was no internet in the office, so I did not know what bugs to fix… so I played around with this instead :)” - Aras Pranckevičius

That day of internet outage is probably one of the happiest days for me using the Unity3d engine. On that fateful day Camera.RenderWithShader was born which lived on to become the backbone of almost all of our post processing effects. The best way to explain how this makes a world of difference in our projects is to just give examples of how we handled post processing effects before and after replacement shaders.

Jetpack Brontosaurus

What We Did

We haven’t posted a graphics postmortem for Jetpack Brontosaurus yet. This post will simplify the techniques we used in order to demonstrate how we accomplished the “multiple dimension” effect. Each object in Jetpack Brontosaurus has at least three renderers associated with it. One for the nightmare/death dimension, one for the dream/living dimension, and one for the mask that determines which dimension gets rendered to the screen. The renderers are divided into each dimension by using different layers. We have a different camera for each dimension. One camera is set to render all the renderers in the nightmare dimension, one camera is set for the dream dimension, and one for the mask. These cameras output their renders to separate render textures. Then we combine the two dimensions based on the color in the mask.

The implementation required each of the three renderers to have its own game object, material, and layer. As a result, the complexity of the scenes increased, producing redundant information and human errors.

What We Could Have Done

If we had the ability to use replacement shaders during Jetpack Brontosaurus production, everyone’s life would have been easier. Most of the renderers in Jetpack Brontosaurus used a vertex color shader. Because the renderers shared the same shader, using a replacement shader is an easy change.

An important thing to note here is that all of the tags have the same Key/Value pair.

The dream replacement shader:

The death replacement shader:

The mask replacement shader:

Now we have one shader that has texture and color information for all of dimensions in a single material. No need for more than one renderer per object anymore!

The shader used by the material for the renderers (this shader is also used for rendering the object to the scene view):

For ingame rendering the material shader is never used. The only shaders used are the replacement shaders.

Now we have a script on the scene’s camera that renders the scene with each replacement shader and then composites them. The scene’s camera should be set to render nothing in its culling mask.

Blush

Glow

The Pro Standard Assets package that comes with Unity has a simple glow effect. Their implementation uses the alpha channel of the destination render texture to decide where to render glow. This limits us a couple ways. We can not have multicolored glow effects and we can not use the alpha channel for anything else. We decided to just bite the bullet and have a separate render texture for rendering glow.

Now we’ve freed up the destination render texture’s alpha channel for something else to use and we can have glow any color we like. Other than the additional memory needed for a 32bit render texture there’s a large disadvantage to doing it our way. Glow is no longer occluded by other geometry. A workaround for this is to have objects that you don’t want to glow render black to the glow render texture. Since glow is an additive pass, anything that is black will do nothing to the original image.

The Glow Replace Shader:

For every object we wanted to glow we added two things to the object’s original shader.
- Tag: “RenderEffect” = “Glow”
- Property: _Glow_Color (”Glow Color”, COLOR) = (1,1,1,1)

Distortion

Distortion is handled in a few steps.
1. Render the scene to a render texture.
2. Render a 2 dimensional “normal” map to a render texture.
3. Draw the scene’s render texture to the screen offsetting each texels’ texture coordinate by the amount specified by the 2 dimensional “normal” map texture.

Blush used a constantly oscillating full screen normal map to distort the scene. This distortion helped established an underwater feel. We used replacement shaders to render directly to this normal map to further modify the distortion. The artists used these shaders on particles to provide distortion effects on fast-moving tentacles, enemies, and other places.

The Particle Distortion Replace Shader:

The availability of Intellisense with Visual Studio is a huge reason to use C#.  However, we liked the simplicity of Unity’s JavaScript, its similarity to Flash’s ActionScript, and some of its automagical features like compiler support for yield.  Ultimately we decided to use UnityScript here at Flashbang, and modified FlashDevelop to provide an editor environment with code completion.  We use FlashDevelop for our Flash work already, so this made sense.

Watch this in HD!

We’ve been using this tool for over a year now, internally.  It’s still a hack–so your mileage may vary–but we’ve been quite happy with it!  It’s taken us awhile to scrounge together a release, but here it is:

Installing UnityDevelop

1) Get Windows.  UnityDevelop is a modified FlashDevelop.  Unfortunately, FlashDevelop is Windows-only, which means you’ll need to find some way to run Windows alongside your Mac (unless you’re using Unity 2.5 by now, in which case you’re probably golden)!  We recommend using Synergy to share a keyboard/mouse between both monitors, or virtualizing Windows entirely.

If you virtualize Windows, seriously look into a stripped-down version of XP.  You can use nLite to do this yourself, or you can download a pre-made ISO if you don’t mind dipping into the shadier areas of the Internet.  This will reduce the memory footprint of XP tremendously (the popularity of Netbooks means there are endless tutorials and pre-made variants available).  If you run multiple monitors, you probably don’t want to run the Coherence/Unity feature, which can be slow with a ton of desktop real estate.  We run Parallels in windowed mode.

2) Download UnityDevelop (2.9 MB).

3) You probably want the classes for Unity 2.6 (replace the files in your UnityDevelop\Classes directory).

4) Unzip, and copy the UnityDevelop directory to “C:\Program Files”.  There are some hard-coded paths in here; apologies if you organize your apps differently!

Creating a Project

UnityDevelop works best if you have your scripts in a single, scripts-only directory to begin with.  Open up UnityDevelop, and go to Project->Create Project.  We directly access our Unity project files via a network share; this is fine.

Select “Empty Project” as your template, give it a name, and browse to your scripts directory.  This will look like:

A “project” is just a pointer to a directory.  If you add new files in Unity, they will show up here.  If not, click the refresh icon in the “Project Explorer” pane, or, in a worst-case scenario, just restart UnityDevelop.  In general it’s easiest to make new files in UnityDevelop directly.  The same restrictions apply here, though–make sure you do all of your script renames in Unity itself (if you rename outside of Unity it’ll look like one file was deleted and the other freshly created).

Code Editing

Now, edit away!  You’ll get autocompletion for built-in Unity scripts, as well as your own files.

Hooray!

Tips, Tricks, and Questions

Changing the Font

Our default settings file uses Consolas, which is a great programming font.  If you want to change the font, close UnityDevelop, edit Settings\ScintillaNET.xml, and restart.

Project-Wide Search

CTRL-I is the shortcut to find in project.  It populates the search terms with your selection–you can easily select something, hit CTRL-I, enter, and see results immediately.  Nice!

Goto Declaration

F4 will go to the declaration of a function.  You’ll end up in the intrinsic class files for anything Unity-specific.

Editing Into Two Directories

If you get crafty with symlinks you can edit into your “Scripts” directory and the “Editor” directory.  On your Mac, create an empty folder, and then create symlinks into your project folder for both.  Create the UnityDevelop project file in this new directory.  If none of this makes sense, don’t worry (Pro Tip:  Use a network share to access your Mac; this won’t work with VMWare/Parallels built-in sharing).

I Can’t It to Work.  Can You Help Me?

Honestly, no, we can’t.  Sorry!  It took us forever just to release this, and all we had to do was zip up some files and write this post.  We don’t have time to support it, so you’re kind of on your own.

I Added Some New Stuff.  Do You Guys Want It?

Yes please!  It would be awesome to see this grow.  Just drop us an email! FlashDevelop 3 is almost done, too, if someone wants to take a stab and making the same hacks.

Here is the source code, by the way.

Why use a Cocoa frontend?

We wanted a way to allow players to login using their Blurst user id in our iPhone games, but Unity iPhone doesn’t yet support the iPhone keyboard. We could have simply used the device id to let users pair their account via the webpage, but I wanted a more elegant solution. Furthermore, after working on iSplume (which we coded entirely using Objective-C), I found that I could make menus much faster in Apple’s Interface Builder than in UnityGUI. Adam and I planned a fair number of menus in Rebolt, so I wanted a way to make them in Cocoa/Interface Builder.

So I set a goal: Make an easily extensible Cocoa frontend for Unity iPhone that supports Blurst logins and supports any menus we might want. It should work for any project we add it to, so we don’t have to do tons of custom code for every game. Further, it should require changing as little of ReJ’s existing Objective-C AppController code as possible, in the event that it changed in a later build. Finally, I wanted an easy way to add my additional files to the XCode project once I created a build. This is particularly important because, to maintain rapid iteration times, there must be a minimal amount we have to do in XCode between creating a build and installing that build on the phone.

Basic Architecture

The basic idea is that we write our own UIApplication delegate to replace AppController, and then forward events like applicationWillTerminate: to the existing AppController once we’ve started the Unity content. We’ll also keep a loop running in the background once the Unity content is created that checks the PlayerPrefs file. We’ll use this to get back to the menus from within the Unity content. Finally, we’ll organize the Cocoa content in such a way that we can easily add it to the XCode project that Unity iPhone spits out. We’ll use a PostprocessBuildPlayer Perl script to accomplish this.

Writing our own UIApplication delegate

Our UIApplication delegate needs to do a few different things. First, we want to handle the usual application event callbacks — applicationDidFinishLaunching:, applicationWillResignActive:, etc. Unless we’re particularly interested in some event, or we’re doing something more complex than just menus, we will just forward most of these messages to ReJ’s AppController. The notable exception is applicationDidFinishLaunching:, which we will use to launch our frontend and add a scheduled timer to the app’s run loop that will listen for menu return requests.

We’ll also want a few functions for switching between Unity and Cocoa content. We’ll create launchFrontend, cleanupFrontend, and launchUnity methods to handle switching content. We’ll also create a checkForReturnToMenu: method that our scheduled timer will call regularly. This will read the PlayerPrefs file and, if it finds a specific key, hide the Unity content and re-launch our frontend.

Here’s a zipped copy of the default Flashbang UIApplication delegate files — download it and follow along as I describe the various sections.
flashbangfrontend.zip

First, we’ll take a look at the header file. Note that we explicitly adopt the UIApplicationDelegate protocol. We also keep references to the application window and the Unity AppController.

The specific details of the headers I’m importing are mostly unimportant. FBGameSettings.h is just some game-specific #defines (version number, etc). FBScene is a subclass of UIViewController and represents a generic menu scene. Specific scenes needed by an individual game are subclasses of this. FBSceneManager keeps a hash table of all scenes and handles transition animations between them. We’ll take a closer look at FBSceneSetup.h later.

Starting the Application

Now let’s take a look at the implementation of FBFrontendController. We’ll look at the applicationDidFinishLaunching: method first.

Here, we first delete the two PlayerPrefs keys we’ll use to communicate that we want to swap between Cocoa and Unity — _start_cocoa and _start_unity. This ensures that we know their initial states. Note: Unity iPhone stores PlayerPrefs using NSUserDefaults. FBPlayerPrefs is just a wrapper for NSUserDefaults that behaves like the PlayerPrefs class in Unity. We then begin a timer that runs our checkForReturnToMenu: method once per second. A shorter delay here means faster responsiveness for opening the frontend from within Unity, while a longer delay will give better performance. Finally, we run our launchFrontend method. Here’s the checkForReturnToMenu: method.

This simply checks for the proper key in PlayerPrefs and then launches the frontend if it finds it.

Launching Our Frontend

Here’s the launchFrontend method, which we call whenever we want to display our Interface Builder-constructed menu system:

Here we create the application window if it doesn’t exist, we disable interaction with the Unity view if it’s present, then we load our custom views in the window. Finally, we start our first scene using the scene manager. LoadScenesInWindow is a function defined in FBSceneSetup.h — we’ll take a quick look at that.

Recall that each SceneXXXX is a subclass of FBScene, which is a subclass of UIViewController. The init method of each SceneXXXX first calls initWithNibName: with the name of each scene’s Interface Builder xib, then adds the scene to the scene manager with an appropriate string-based key. The LoadScenesInWindow function thus initializes each view controller and adds its view to the window. The idea behind this architecture is that for any given project, we only have to edit FBSceneSetup.h, and then create the appropriate SceneXXXX subclasses to manage each of our scene xibs. That is, FBSceneController will be the same for every project.

Launching Unity

Now we’ll take a look at how we launch the Unity content.

We start out by cleaning up the frontend (which just tells the scene manager to remove its views from the window and releases them). We then set the _start_unity PlayerPrefs key, so that our loaded Unity content will know we want it to start executing. After that, there are two possible codepaths. The first time we call the method, it will call AppController’s applicationDidFinishLaunching: method, and then point our local window reference to the one created by AppController. Once the Unity content is initialized (if we’ve come back to the menu and then want to return to Unity), we find our Unity view by the tag we set in launchFrontend, return it to the front, and re-enable interaction with it.

We’ll typically want to run this method in response to a button press in some view. Here’s an example use:

Using the Frontend From Unity

To get back to the frontend from Unity, we just need to set the _start_cocoa PlayerPrefs key. Since the Unity content will continue running in the background, you’ll also want to pause your game and have a loop continue to check for the _start_unity PlayerPrefs key.

Putting It All Together — Project Organization and PostprocessBuildPlayer

So this frontend stuff is all well and good, but it would be a royal pain in the ass if we had to copy the files into the project manually and edit ReJ’s files every time we made a build. But, as usual, it’s Perl to the rescue!

We’ll first create a directory inside our project that will contain all of our frontend files. We’ll set it up so that we can also replace the application icon and splash screen in the same pass. First, create an “XCode” directory within the Unity project. Any files that you want overwritten in the default XCode project should be in the same locations with the same names. So for instance, we’ll add Icon.png and Default.png to the root of the XCode directory. Put anything that you’re adding to the project (all the frontend files) into a separate “Frontend” sub-directory. So your tree should end up something like this:

Now we’ll take a look at the PostprocessBuildPlayer script. If you aren’t familiar with it, check the Build Player Pipeline section of the Unity Manual. Here’s my script, written in Perl:

As you can see, this script does three things — copy all the files from our XCode directory to the built XCode project, change the UIApplicationDelegate in main.mm to FBFrontendController, and make the _window variable of AppController public. So we’ve managed to implement our own frontend by changing only two lines of existing code!

Building the Project

I know of no way to add files to an XCode project via the command line, so you will still have to manually add the files to the project after building. However, because of the way that we’ve organized the project, this will be relatively simple. It does mean, however, that “Build and Run” will no longer work as a one-click solution.

Build the project in Unity and open the generated project in XCode. Select Project -> Add To Project… (Cmd + Option + A), and select “Frontend” directory. In the next dialog, choose to “Recursively create groups for added folders:

That’s it! You’ll now have the references needed to run your custom frontend before the Unity content — simply build and run in XCode!

What is Unity?

Unity’s scope makes concise definition difficult.  Unity is a lot of things, and it’s used differently by different disciplines, but here’s one breakdown. Unity is:

An Integrated Editor

Unity provides an editing environment where you organize your project assets, create game objects, add scripts to these objects, and organize objects and assets into levels.  Most importantly, Unity provides a “game” view for your content.  You can hit play and interact with your content while you watch values, change settings, and even recompile scripts.

The IDE is largely stateless, in that there is little distinction between creating your levels and playing them.  For example, the editor remains functionality identical whether your content is stopped or currently playing.  This is hugely useful, because while your content is playing you can hit pause and then move things, create new objects, add scripts, and whatever else you need to do to test gameplay or chase down bugs.

Different team members and disciplines use the editor differently.  Here at Flashbang artists use the editor to smoke test new asset imports, arrange assets into levels, and tweak textures and other visuals.  A programmer may focus more on watching values and tweaking numbers.  A unified interface helps us tremendously; we don’t have people using different tools with different interfaces and workflow conventions.

A Component Architecture Paradigm

Unity utilizes a component-based architecture.  You could ignore this in creating your game logic, but you will suffer without a clear understanding of Unity’s design.  In Unity, every object in your scene is a GameObject.  An arbitrary number of Components are attached to GameObjects to define their behavior.

For example, a physical crate might be:

• GameObject
  (name, layer, tags)
  • Transform
    (position, rotation, scale, parent)
  • Mesh Renderer
    (actually draws the object)
  • Box Collider
    (define collision volume)
  • Rigidbody
    (movable physics object)

Here’s the key:  When you create a script, you create a component. For example, you could create a Jump.js script to make your cube jump when you press a key, like:

JavaScript hides some of the details, but what’s happening here is you’ve created a new Jump Component.  Your script implicitly inherits from MonoBehaviour, which inherits from Behaviour, which inherits from Component.  You now have a new component, which you can easily add to your crate!

Note:  We use JavaScript at Flashbang, for a variety of reasons, but the steps are quite similar in C#.  The only real different, aside from syntax, is that you need to explicitly define the inheritance:

A Game Engine

Unity is a fully-featured game engine.  It includes and exposes many systems needed for game creation, such as:

• Graphics Engine
  Unity’s graphic engine includes a shader language, ShaderLab, which wraps Cg and GLSL shaders with additional engine semantics.
• Physics Engine
  Unity uses NVIDIA PhysX for their physics engine, with editor and API integration (you set up collision volumes, joints, and things by adding components to your GameObjectsin the editor, and script physics with things like Rigidbody.AddForce() and MonoBehaviour.OnCollisionEnter() callbacks).
• Audio Engine
  Unity has a positional audio system.  You can play sounds in 3D space, or “2D” stereo sounds.
• Animation System
  Unity includes an animation system, including support for animation layers, blending, additive animations and mixing, and real-time vertex/bone reassignment.

There are quite a few other out-of-the-box systems there to help you, too, like particle systems, networking, UnityGUI, and so on.

A Scripting Platform

Unity embeds Mono to power its scripting environment.  You can script in C#, JavaScript, or Boo (a Python variant).  Mono itself is an open-source version of the .NET development environment.  Note that this doesn’t mean that Unity requires .NET.  Mono is totally distinct from Microsoft’s .NET, and Unity totally embeds Mono.

It’s also worth noting that Unity’s use of Mono goes above and beyond the compiler and common language runtime.  You also get the full .NET namespace, which means a huge amount of classes are available to you out of the box:  XML parsing, cryptography, sockets, and more.

As I mentioned earlier, Flashbang uses JavaScript.  Unity’s JavaScript isn’t very similar to the JavaScript language found in web browers.  It’s about as similar to web JavaScript as Flash’s ActionScript, which is to say not very similar at all.  There are a number of advantages to using UnityScript, although there are far fewer tools available (we use a custom-created hack of FlashDevelop).  With the advant of the Windows release, I imagine many newcomers will choose C# and Visual Studio.  Lucas Meijer makes a very compelling case for C# scripting over at his Unity blog.

A Scripting API

Your Mono-powered scripts have full access to Unity’s engine through Unity’s scripting API.  They’ve exposed the entirety of the engine, which means that you can do pretty much anything.  High level stuff is quite easy and simple, but you can dig all the way down to doing mesh generation or direct OpenGL calls if you’d like (which work on DirectX, thanks to Aras’ genius).

MonoBehaviour, the parent class for your scripts, provides a number of convenience members.  Things are usually quite straightfoward.  For example:

• transform.position = Vector3.zero;
• rigidbody.AddForce(Vector3.up * 10);
• renderer.enabled = false;
• particleEmitter.Emit(10);

There are a number of callbacks provided for game logic purposes:

• Start()
• Update()
• OnCollisionEnter()
• OnMouseDown()

The scripting environment supports coroutines, which are magically useful for all kinds of things.  Want to destroy an object 3 seconds after it was hit with something?

In addition to scripting your game at runtime, Unity provides a powerful editor API to create custom tools, windows, and shortcuts to expedite your workflow in the editor itself.  With Unity 2.5 the entire editor itself has been rewritten with the Unity API (which means you should be able to do practically anything they have).

More to Learn!

As you can see, Unity is quite broad.  This article should provide a good starting point for its top-level features, but even this overview hasn’t covered the whole of the software.

We’ll dive into more Unity features in depth in future Unity Basics articles.  We didn’t talk much about the Inspector (and how variables are serialized in Unity), or asset importing, or any number of other features.  What would you guys like to focus on?  Use the comments below to let us know!

For instance, take the event of a raptor dying in Raptor Safari. One option–a bad one–is to explicitly reference all neccesary managers in the raptor scripts themselves. So, to add sound we would have to add a call to our sound manager, to add scoring we call a function on our scoring manager, and so on. The problem is we shouldn’t have to edit older scripts to enable functionality in new managers. This is a recipe for errors and programmer collisions (it will be harder to add in real raptor-specific functionality if there is a constant stream of edits to support other parts of the game).

A better paradigm is to have the raptor broadcast a message about its death. This message includes all relevant information: What killed the raptor, where it died, a reference to the raptor object itself, and so on. The message is broadcast with a specific category, like “raptor”, and interested parties sign up to consume messages about this category.

This means we can add functionality about an event without editing the original script. We could add a sound for our raptor’s death, include it in our scoring systems, spawn a particle effect, and more–all without touching the original raptor logic. Perfect! But how do we accomplish this is UnityScript?

C# includes a mechanism to do this called delegates, which is a type that references a method or methods. Unity’s JavaScript doesn’t support delegates, however, and in fact we’re better served with our own system anyway, since we can do additional logic where necessary. Here’s our solution:

Messenger Singleton

We need a single object to keep track of our lists of listeners. When a script wants to listen to some classification of events, like “item” events, it has to call a function on our messenger. The messenger then keeps track of which scripts should recieve messages for which types of events. This looks like:

The actual collection of listeners is very basic. We use a Hashtable of ArrayLists. The Listen() function looks like:

We use a second function signature that accepts a Component to allow scripts to use this to register as a listener.

Message Class Structure

All messages are their own classes. To send a message you simply instantiate the class. In Minotaur China Shop, a broadcast of the item delivered message looks like:

In this particular case, the message contains the item we delivered to a custom (the first argument), and the customer to which it was delivered (the second argument). Let’s take a look at the actual MessageItemDelievered.js file:

We use our message objects to store multiple references and values. Many times we will compute additional values. For instance, for a raptor death event we may calculate the impact of the event as a scalar from 0..1 and store that in the message. If other scripts want to know the severity of the impact they can use this value, while leaving us the flexibility to tune it in a single location. This is one reason delegates wouldn’t serve us very well.

The super(”item”) line calls the constructor on the parent class, Message. This is where we stick our category identifier. You can think of the line as saying “our message is now ready, send out to anyone interested in the item category”.

Receiving Messages

You’ll notice we don’t actually define the function name the message is calling anywhere. We do this implicitly based on the class name. The naming standards we use are messages look like MessageItemDelivered and their corresponding function names look like _ItemDelivered(). The leading underscore lets us know at a glance that the function will be called by the messenger.

The messenger calls the function and sends it the instance of the message. This allows messages to contain as much data as we want, and also to precompute anything expensive once (at message composition instead of per-listener). A listening object might look like:

Because our code editing environment includes JavaScript autocomplete, it’s very easy to write these functions and see which variables a message provides without having to look it up.

Project Organization

One of the nice side effects of using one class per message is visible organization. We keep all of our messages in one folder, so it’s very easy to see which messages are available in a project. This allows collaborators to get an idea of how much functionality is exposed by other systems. If we need to create a new message–the sound designer would like to hook into something else–it’s easy to go in and add new messages, which may prove useful for other functionality later.

Adding New Messages

Adding a new message is relatively painless. We must:

• Create a new MessageSomething class (we copy/paste an existing message)
• Specify the category in the super() call
• Listeners register with the Messenger singleton
• Listeners implement _Something(msg:MessageSomething) function

Performance

Our actual broadcast functionality uses Unity’s SendMessage() function. This isn’t nearly as fast as calling functions directly with your code, but in practice it’s fast enough. You wouldn’t want to be calling multiple messages every frame, but for game events–enemy spawned, enemy killed, powerup acquired–it’s performant enough to be practical.

In our current implementation we also let null values accumulate in the ArrayLists of listeners. This hasn’t caused any problems, because we flush the Messenger along with scene changes. If you are incredibly performance-conscious, or developing for the iPhone, you may want to skip a messaging system altogether. The point of a messaging system isn’t programming performance, but production performance; it’s a fast and efficient way to get things done.

Sample Project

It’s not as complicated as it sounds, actually. In practice we create new messages in just a few minutes, and we haven’t updated the actual Messenger logic in two projects. Here’s a sample project to get you started. If you make any improvements or changes to the project, please let us know by leaving a comment!

Download Sample Project