CPU Dreams

All About Coroutines

fernando@cpudreams.com (Fernando Zapata) — Thu, 18 Feb 2010 01:04:00 +0000

One of my favorite features in Unity is its built-in support for coroutines. Coroutines are a kind of cooperative multithreading, where coroutines all running on a single "regular" thread take turns executing by yielding control of execution to one another. Because switching between coroutines is cooperative they are easier to program than regular threads since you do not have to worry about managing locks to protect shared state.

Coroutines make scripting behavior that is spread out over multiple frames a breeze. For example if you wanted to have a traffic light cycle between red, yellow, and green you could do it all in a single coroutine:

function TrafficLight() {
  color = Red;
  yield WaitForSeconds(1.0);
  color = Yellow;
  yield WaitForSeconds(1.0);
  color = Green;
}

Coroutines can also wait for one another which makes ordered cooperation between coroutines a breeze.

function RunOnGreen() {
  // wait for green light
  // traffic light cycle ends in green
  yield TrafficLight();
  // model reaction time
  yield WaitForSeconds(0.1);
  print("Catch me if you can!");
}

Now you can do all this without coroutines, but alternatives such as event driven callbacks, and state machines are usually not as elegant or concise. Needless to say coroutines are a nice programming tool.

Because I needed more complete control over coroutines in a portion of my code for Wisp I ended up writing my own CoroutineScheduler similar to the one built-in to Unity. Today I contributed this code to the Unity community wiki. Most Unity games will never need this level of control over coroutines and are better off using the built-in support. But seeing how coroutine support is implemented on top of standard .Net/Mono generators leads to a better understanding of how coroutines work behind the scenes which is something anyone can benefit from. The coroutine scheduler is also useful if you want to add coroutine support to a non-Unity based project, and I think you will find the code easy to follow.

To understand coroutines at an even deeper level, you should understand how generators work behind the scenes. Generators allow you to create a function that returns a lazy IEnumerator that yields a sequence of objects. You can also get an IEnumerator by calling GetEnumerator on a regular collection such as an ArrayList.

// if array contents are 1, 2, 3
// then this will print 1 2 3
var arrayEnumerator = someArray.GetEnumerator();
while (arrayEnumerator.MoveNext()) {
  print(arrayEnumerator.Current);
}

When you use a "for in" or "foreach" loop construct an IEnumerator is used behind the scenes.

Here are similar examples this time using generators.

function CountTo3() {
  yield 1;
  yield 2;
  yield 3;
}

function CountToN(n : int) {
  for (var i = 1; i <= n; i++) {
    yield i;
  }
}

// print 1 2 3 
// without allocating an array of size 3
var generator = CountToN(3);
while (generator.MoveNext()) {
  print(generator.Current);
}

Behind the scenes a generator is translated to a state machine. This is where the magic happens. As I noted earlier an alternative to the TrafficLight coroutine is to use a state machine. In fact the TrafficLight coroutine is implemented as a state machine it just happens automatically when the generator is translated into one by the compiler. You can see the state machine class for any generator function by inspecting the .Net assembly using Reflector. But to give you a general idea of what is happening here is a simple example.

function ThreeMore(start : int) {
  yield ++start;
  yield ++start;
  yield ++start;
}

// ThreeMore as a state machine
class ThreeMore {
  var state = 0;
  var current;
  var start : int;

  // function parameters become object attributes
  function CounToN(start : int) {
    this.start = start;
  }

  function MoveNext() : boolean {
    switch (state) {
      case 0: current = ++start; break;
      case 1: current = ++start; break;
      case 2: current = ++start; break;
      default: return false;
    }
    state++;
    return true;
  }
}

The actual state machine classes generated by the compiler will be a bit different from this example. But the key points to take away are that generators are implemented as classes and on each call to a coroutine function a new instance of their compiler generated state machine class is created. The function parameters are translated into object attributes and function code is spread across multiple state machine states to allow execution to enter and leave the coroutine while maintaining parameter and stack state as object attributes.

That does it for now. I hope you find this post useful.

Disclaimer: Example code was typed into blog editor and may not compile.

The Storm Programming Language

fernando@cpudreams.com (Fernando Zapata) — Fri, 12 Feb 2010 01:11:00 +0000

One of my goals with Wisp is to give players the ability to easily generate their own content without leaving the game. From maps, to campaigns, and custom scenarios. The editors to support this player generated content should allow you to go beyond simple map building and into the realm of custom gameplay through scripting. With this in mind, I created Storm a scripting language for the strategy game Wisp. My other motivation was that creating Storm would help me get experience in language implementation and design.

Since, I've discussed my language with some of you I thought I'd post a demo so you could try it out first hand and describe my work in more detail. Storm is a not an object oriented language, but it does let you create .Net objects and invoke/access their members. Its design was inspired by Clojure, Boo, Arc, Go, and JavaScript. Storm is an s-expression based language, so it has a Lisp like syntax. It currently has the following features:

Integer and floating point numbers, with a full set of math operators
Booleans, with a full set of relational operators
looping and conditional expressions, with support for iterators
Literal syntax and built-ins for arrays and hashtables
Generic .Net object integration (use this for other data structures and foreign code)
Functions and variables with lexical scoping
A module system with public and private functions and variables (case based visibility)
Foreign modules, expose arbitrary .Net objects and functions as Storm modules
Configurable execution time limits (an infinite loop will not freeze the game)
Configurable stack limits (infinite recursion will not crash the game)
Sandboxing, limit API access and run multiple interpreters
Optional dynamic scopes, for things like mapping a single module to multiple game objects
Chain operator, (-> obj foo (bar baz)) becomes (bar (foo obj) baz) think "obj.foo.bar(baz)"

Storm currently does not have macros, closures, generators/coroutines, or exceptions. Not much work is left to add macro and closure support, but I stopped work on Storm before getting them in, they will come later. I'm leaning against adding exception support. Generators are more work as rewriting them as state machines is not trivial, but it is something I would like to include at some point. I haven't done any optimization, but performance seems adequate for my needs. The implementation uses a hand written recursive descent lexer and parser and an AST based interpreter.

If your curious the best way to learn more about the language is to look at the Doc module in the demo then try code in the Scratch module. I've included a description of the grammar and sample code for all features. The Game module shows how you could use Storm's dynamic scopes to support a MonoBehaviour like scripting interface (it drives the cube in the demo).

While this demo exposes Storm as a low level scripting language that you can use to create your own Unity like MonoBehaviour scripts, this is not how I expect to use the language in Wisp. Players will probably never see any Storm code or be able to type in scripts. Instead players will work at a higher level of abstraction with GUIs that in the back end generate Storm code. Think of Storm as executable XML or JSON format that can be serialized and stored in a central database of user content.

On other fronts, pun intended ;), I've begun work on the AI behaviour engine and I recently completed the networking engine with resynchronization support. The main technical components of Wisp are coming together nicely and I'm looking forward to doing more game play specific implementation work.

Resolutions

fernando@cpudreams.com (Fernando Zapata) — Wed, 20 Jan 2010 18:26:00 +0000

Resolutions are easier to keep if you share them with friends. My wife and I took a short working vacation to the Texas Hill Country to plan our goals for 2010. My primary goal is to launch a private beta of Wisp before the end of the year, preferably before this years Unite. Some of my other goals for the year are to read 52 books (finished 26 last year), exercise (Monday through Friday), and practice drawing (Tuesday, Thursday, and Saturday). What are your goals for 2010?

I just finished the networking engine for Wisp and have begun work on the AI layer. After the AI layer is complete I'll have finished the main technical components of Wisp and part of the gameplay. There will still be plenty to be done but I'll have a solid foundation to build on.

Unite 2009

fernando@cpudreams.com (Fernando Zapata) — Thu, 12 Nov 2009 22:52:00 +0000

It's been over a week now since I got back from Unite so this post is long over due :). As expected I had a great time at the conference and Unity brought out the big guns. A huge part of the Unity crew was there and all of them were first class acts. One of my favorite parts of the conference were the hands on sessions where you could talk one on one with a Unity developer on any Unity related topic. Nothing beats going straight to the source :). For example, I got to speak with the creator of Boo about future language support. I also met a wonderful engineer from Photon which gave me a head start in networking. And these are just two of many such conversations. Suffice it to say, if you are interested in Unity then Unite is well worth it. There were over 500 attendees and everyone was really exited about the future. It was encouraging to meet other Unity developers and artists not to mention educational. On the last day a bunch of us got together for dinner and had a great time :).

(Photo by Brady)

But now the time for conferences is over. This next year is going to be an exiting ride as I prepare my game for release. I probably won't be attending any conferences until many months from now. But I won't miss next years Unite :).

On another note, I recently uploaded my interpolation library to the Unity wiki, and Brady released an updated version of his SpriteManager 2 with a sweet timeline editor for 2D sprites. Check it out!

Community

fernando@cpudreams.com (Fernando Zapata) — Thu, 22 Oct 2009 21:00:00 +0000

Welcome to the CPU Dreams blog. I start this blog to share my experiences as an indie game developer, to share resources with other members of the gaming community, and to share information on CPU Dreams first game, "Wisp". This summer I began my dream of becoming an independent game developer by creating CPU Dreams. My first project, the strategy game Wisp, will use the Unity engine. Even though this is my first time working as a game developer, I have over a decade's worth of experience as a professional software developer. Until now, I have kept my game development a hobby. All the horror stories permeating the game industry kept me away from pursuing my true passion. In recent years, the industry has changed, and there are new and exciting opportunities for small independent studios. Seeing this window of opportunity open, and not knowing when I would get a better chance, I took a leap of faith to start my dream. I know I still have a long road ahead of me, but I have no regrets, and I'm enjoying every minute of my new calling.

In fact, I've been enjoying programming in Unity so much that it is difficult to pull myself away from it, even for a little bit, to start this blog. Without Unity, I don't think working full time on Wisp would be possilbe. The Unity community is equally helpful and I want to give something back by sharing code that others in the community might find useful.

I just posted my MessageRouter module to the Unity Community Wiki. MessageRouter is a subscription based messaging/event system that provides an efficient method for broadcasting game events to interested parties while maintaining loose coupling. There are several other messaging/event systems in the wiki but this implementation has several features not available in the other implementations which some may find useful. I picked this module because it was generic and easy to extract from the rest of my game's specific code. I plan on extracting and sharing as much as I can. I have several other modules already in mind (dolly-zoom component, interpolation module, and a message timeline) and hope to contribute them soon.

Back in September I attended GDC Austin for the first time. I didn't know exactly what to expect, but wanted to meet new people in the community so that I wouldn't feel like that much of an outsider. I had a great time and met many indie developers that I always admired. I was also fortunate enough to meet fellow Unity users and meet some of my heroes at Unity Technologies :D. Meeting just a small part of the Unity community was so wonderful that it made up my mind to go to Unite conference. If you are going, I hope to see you there next week =)