Shader Syntax Coloring Plugin in MonoDevelop Addins Repository

Xamarin 5.0 provided the impetus to finally put the shader coloring plugin into the live Xamarin Studio Addin Repository. This will host and build versions of the plugin for both Xamarin Studio 4.x and Xamarin Studio 5.x. An added benefit is you can search, download and install the plugins within the Add-in Manager in MonoDevelop. The steps to do this in Xamarin Studio are simple:

  1. open the Add-in Manager from the menus
  2. on the Add-in Manager Update tab hit ‘Refresh’
  3. on the Add-in Manager Gallery tab search for ‘mime’
  4. install “Unity Mimetypes”
Advertisements

C# Memory Management for Unity 3D

If you’re developing games in any space or developing anything in the mobile space you’re going to have to be concerned about memory management. A lot. It doesn’t matter if you’re doing it manually, reference counting, using ARC or garbage collection. If you’re pushing the envelope in any way the details of how memory is managed matter greatly. In Unity 3D the C# garbage collection is one of those details, and there’s very few articles which deal with it specifically. Wendelin Reich just changed that:

I learned the hard way that in game development, you cannot rely on automatic memory management.

Wendelin Reich’s C# Memory Management for Unity Developers

Syntax Coloring Shader Files in Xamarin Studio 4

Since Xamarin released the renamed MonoDevelop 4 as Xamarin Studio I’ve been using it alongside Unity 3D for all my development. It’s definitively better than the Unity-bundled version of MonoDevelop (2.8 with Unity’s patches) for C# development on a Mac. I think I’ve found my new favorite IDE – a title that MonoDevelop has previously never quite taken. There’s still a few rough edges though. The ones I care about most are Unity related. The Unity debugging plugins are missing, but I can live with that for a while. Unfortunately syntax coloring isn’t enabled for shader files, at least those with .shader and .cginc extensions. It’s amazing how hard code becomes to write when syntax coloring isn’t present!

Shader Code Fades to Black And White

Thanks to some helpful feedback on the Xamarin forums it’s clear that all the parts are there, but those file extensions need to have their mime type correctly for CG shaders. That requires writing a add-in, although it only needs to contain an XML file which gets compiled into a dll. Michael Hutchinson pointed me at the getting started documentation for add-ins. Add a dash of effort and out pops https://github.com/jools-adams/monodevelop-unity-mimetypes. Just compile it and drop the dll here (on Mac):

~/Library/Application Support/XamarinStudio-4.0/LocalInstall/Addins

Unity3D Live Code Reloading

After University I worked with 3 brothers. They’d written the software for an ISDN (remember that?) test system called the A8619. It was basically a PC, with a custom card in it, which contained (amongst many other things) another x86 processor. There was another team having trouble programming the x86 on the card. You wrote software for the card in C, compiled it to a binary, burnt it onto a prom, put it in the card, rebuilt the PC. It hurt; they were getting nowhere fast. So these chaps wrote a simple program for the card. It just sat there waiting for the host PC to send it another program.

Whenever host PCs program was restarted it would send the latest binary down to the card. Suddenly the development cycle became compile and run. I often felt that games I’ve worked on needed this – big titles take an age to load and then navigate to the area you’re trying to test. Only then do you find out that it works or not. Rubbish!

We can do better. Unity does – it supports live code reloading while running the game in the editor. There’s limits, of course, so code reloading broke at some point while we were developing Monkey Slam, and never got fixed. Next time I want to understand what’s acceptable, and keep it going all the way through. The code reloading uses Unity’s underlying serialization mechanism to preserve state while code is unloaded and reloaded. The only difference between ‘editor’ serialization and the normal case turns out to be that private variables are serialized for code-reloads.

This makes total sense to me intuitively. When you did a little deeper it become clear why Awake() is used instead of a constructor. The constructor is called after every code reload; Awake() is only called when the object is created. The correct values are serialized into each object after code-reload after each object is constructed. Breaking the game on code-reload simply means that something in the run-time state is not being correctly serialized. The Unity documentation covers the basics, but left me with a bunch of questions. Here’s a few more details:

  • Statics: are not serialized at all. Initial assignment and static constructors will re-run on code-reload.
  • Properties: all properties are not serialized. Counter-intuitively that’s what you want. Properties are code – they will work after code-reload as long as the object state is correctly serialized. For auto-generated properties the private backing field is serialized fine.
  • Collections: arrays and List are serialized are documented as being the only serialized collections. They work, but Queue and Dictionary do not. The loss of Dictionary is the biggest roadblock for me. Add Dictionary and I could imagine writing a game. Without Dictionary that’s … hard.

The good news is though that you can nest one of the supported collections within a class of your own and have it serialize correctly. So it’s perfectly possible to implement Queue on top of List and have Unity code-reload it. You could also do that for Dictionary if you’re prepared to settle one of the performance compromises possible implementing it while relying on List serialization. I suspect in many cases one of these implementation strategies and compromises would be acceptable:

  • a linear search over unsorted List. For relatively small numbers of entries this is probably fast enough. Assuming List uses a contiguous block of memory internally it may even faster for less than about 100 items as it’s cache friendly.
  • maintain a sorted List. In this case lookup is fast, but insertion is linear as list entries after the insertion point need to be moved. Great for read-only data.
  • use a contained Dictionary and in the Unity editor maintain a backing List which all Dictionary entries are appended to. You can avoid slow lookups on the List by blinding appending new values. On code reload you take the last value for a given key from the list and insert it into a clean Dictionary. To avoid an arbitrary size overhead of the List you could “garbage collect” the List if it’s size became bigger than a certain multiple of the Dictionary size.

All of the above would make a great projects for GitHub. I’d be tempted just to implement the Dictionary with a linear search over a List first, until there was a clear performance reason for other solutions. Years ago, when people wrote their own collections routinely I wrote a lot of software that just used lists and it was almost always fine!

I guess the question is whether that’s all worth it to maintain code-reloading? Alternately @Unity3D could we get Dictionary serialization working please?

Post Script

Recently there have been a couple of great blog posts about Unity serialization, both worth checking out. The main Unity blog has a lot of serialization details posted, and Jacob Pennock wrote a great post on leveraging Unity serialization for game configuration. I’d love to see all this detail wound into the Unity documentation.

Coroutines In Unity3D – The Gritty Details

In my last post I talked about why some code is easier to write, read and maintain in Unity 3D when it’s written using coroutines, and touched on how Unity3D uses C# iterators to implement them. Now let’s look at how Unity3D makes these work as coroutines.

With iterators your code is responsible for creating an iterator and causing the iterator code to continue after a yield statement, such as using foreach in the MSDN example. In Unity’s world coroutines work if you are a class derived from MonoBehaviour. This class has a function StartCoroutine() which can start any function which returns IEnumerator as a coroutine.

Coroutines aren’t very useful until they include a yield statement. Unity uses the values returned by yield as scheduling information – to decide when to call the next portion of the coroutine. I’ve never found a complete list of acceptable return values from yield for Unity3D. Here’s the ones I know about:

It’s not multithreading!

There’s no multi-threading going on here. All scripts in Unity are called on a single thread, so no locking of variables is required. However other scripts may change global or object state between function calls or across a yield instruction. At times it becomes important to know when during a frame the coroutine will be executed. The overall execution order documentation says:

  • Most coroutines run after Update() and before LateUpdate()
  • Coroutines started from LateUpdate() run after LateUpdate()
  • return yield new WaitForFixedUpdate() // causes a coroutine to run after the next FixedUpdate()

As a final complication StartCoroutine() causes the coroutine to run immediately, until its first yield.

That All Sounds Hard

It’s not. I’ve dug in here, and documented all the gritty details. 90% of the time you don’t need these details at all. Looking at my coroutines they are almost all using

  • yield break;
  • yield return null;
  • yield return StartCoroutine().

What are you waiting for? If it sounds like coroutines will solve a problem for you – try them out!

C# Coroutines In Unity3D

Why?

It seems like the best way to explain coroutines is by example. We’ll look at a portion of the class which controls the front-end in a game, and doesn’t use coroutines. It’s not horrible, but the logic is scattered across a delegate – OnPlayButton() and UpdateFrame(). We need a class member to hold a reference to the active UI page.

public class Frontend: GameState
{
    // need a member variable to hold a reference between functions
    private ZoneSelectUIPage mZoneSelectUIPage;

    public void Create()
    {
        mPlayButton = UITextButton.Create(GlobalResources.Instance.ButtonToolkit,
                                          "blank_up.png", "blank_down.png", font,
                                          fontMat, fontDropShadowMat, fontHighlightMat);
        mPlayButton.SetText("Play");
        mPlayButton.pixelsFromTopLeft(20, 20);

        // add delegate to handle button presses
        mPlayButton.AddOnTouchUpInside(OnPlayButton);
        ...
    }

    private void OnPlayButton(UIButton sender)
    {
        Hide();

        mZoneSelectUIPage = ZoneSelectUIPage.create();
        mZoneSelectUIPage.Show();
    }

    // called once a frame - that's how the game engine works!
    public GameState UpdateFrame()
    {
        if (mZoneSelectUIPage != null)
        {
            if (mZoneSelectUIPage.Level >= 0)
            {
                GlobalResources.Instance.SetLevel(mZoneSelectUIPage.Zone,
                                                  mZoneSelectUIPage.Level);
                mNextState = LevelLoadState.Instance;
            }

            if (mZoneSelectUIPage.Done)
            {
                mZoneSelectUIPage.Destroy();
                mZoneSelectUIPage = null;

                Show();
            }
        }

        return mNextState;
    }
}

On top of that there’s also a bunch of code to test whether mZoneSelectUIPage is null – we may not have one! The page also needs to explicitly contain a property ZoneSelectUIPage.Done which we can test to see if it’s work is done. Re-writing that using coroutines moves the logic into a single function CoroutineUpdate() and makes the logic linear to read.

public class Frontend: MonoBehaviour, GameState
{
    public void Create()
    {
        mPlayButton = UITextButton.Create(GlobalResources.Instance.ButtonToolkit,
                                          "blank_up.png", "blank_down.png", font,
                                          fontMat, fontDropShadowMat, fontHighlightMat);
        mPlayButton.SetText("Play");
        mPlayButton.pixelsFromTopLeft(20, 20);

        // now we start a coroutine to do our work
        StartCoroutine(CoroutineUpdate());
        ...
    }

    // called once a frame - that's how the game engine works!
    // bridge to the engine by having the coroutine set mNextState
    public GameState UpdateFrame()
    {
        return mNextState;
    }

    public IEnumerator CoroutineUpdate()
    {
        while (true)
        {
            // wait until the next frame update
            yield return null;

            if (mPlayButton.TouchUp)
            {
                Hide();

                ZoneSelectUIPage zoneSelectUIPage = ZoneSelectUIPage.create();

                yield return StartCoroutine(zoneSelectUIPage.CoroutineUpdate());

                if (zoneSelectUIPage.Level >= 0)
                {
                    GlobalResources.Instance.SetLevel(zoneSelectUIPage.Zone,
                                                      zoneSelectUIPage.Level);
                    mNextState = LevelLoadState.Instance;
                }

                zoneSelectUIPage.Destroy();

                // exit the coroutine
                yield break;
            }
        }
    }
}

Also we no longer have to check whether zoneSelectUIPage is null – it’s a local variable we’ve just created – or whether it’s finished. Once ZoneSelectUIPage.CoroutineUpdate() returns it’s done.

For this simple example the code is neater and simpler. As more buttons and pages are added the more of a win using coroutines is. Often game classes will end up with a state enumeration and state member variable, and the UpdateFrame() function becomes a gigantic switch statement. Each state may need additional variables, which become member variables. Over time it becomes hard to follow the logic and remember which variables affect which state. I’ve always found code like this to be hard to write and harder to read. With coroutines the entire state machine is written in a linear fashion with local variables and yield statements. There’s a more direct mapping of the code written to its effect. That’s got to be a win!

C# Support

C#, of course, doesn’t really support coroutines. You’ve probably noticed that I’m using yield statements which are part of iterators. Iterators provide the language infrastructure to return a value from partway through a function (using yield), and then start executing the function again at a later time from just after the yield statement. Unity3D adds support for using iterators as coroutines, which I’ll cover in my next post.