Controlling Moai Rendering Order - Part 2

This is the second of two posts looking at ways to control object rendering order in Moai. That is, managing which objects appear on top of which other objects in your game.

The first post looked at the more straight-forward techniques of using insertProp() ordering and pushRenderPass() layering. This post looks at two more techniques: Partition priority and render tables. It requires digging a little bit under the hood to see first: what the code is doing when you insertProp, and, second: what happens when you pushRenderPass. Both techniques are very handy, so without further ado...

See full post...

Controlling Moai Rendering Order - Part 1

Using Moai, how can you ensure one object appears over top of another? Maybe you need a starfield to appear under your ships, perhaps you want to see through a translucent window to objects behind a building, or maybe you just need a dialog button to appear over its background.

Most 3d games use a z-buffer to record the depth of each pixel rendered, and rely on a z-test so that pixels closer to the viewer can take precedence over pixels further away. Many 2d games, on the other hand, rely on rendering order to control which objects display over what. Every new object rendered simply overdraws ( or blends on top of ) whatever is currently on the screen.

In Moai, by default, it's rendering order that controls appearance. How, then, do you control the rendering order of objects? In what follows, I'll explain four techniques you can use to get your scenes rendering how you want...


See full post...

Implementing Quests and Dialogs

I've been wanting to write up something about how quests and data work in Dawn -- a slice through the engine from top to bottom -- but I haven't had a good hook to do so yet.  I think, though, since I'm in the process of porting Dawn's dialogs over to Moai, its conversation system could provide a good example.

I'm motivated to write about quests because there seems to be little to none in the way of books, articles, and blog posts on the subject -- and yet quests -- or quest like systems -- are an essential component of many games. Finding a way to talk about them, and finding ways to compare and contrast solutions, would be valuable (and interesting!). Dawn's implementation is just one possible way. Other games I've worked on have done radically different things. Ultimately, I'd love to learn more about what others have done.

First, a quick update to provide context. I finally have the first piece of the dialog GUI working the way I want. It's not graphically pretty, but the point really for me is the underlying UI framework supporting it. It means it's possible to build (some small, pre-measured) nested ui components using an html/flex+css like syntax. For town menus, which can have variable numbers of elements, I'll need to finish measurement and sizing - but from there I'll have a good foundation for much more complex UI like combat and shops.

Mori, not to be confused with Moai.
They get angry about that.

From the game's perspective, all dialogs are launched from quests, so let's start at the top....


See full post...

Testing Moai's Positioning

Today a bit of clarification about the way Moai handles the positions of objects. My motivation is two fold. First, I'm working on the UI for character conversation in Dawn, and so I wanted to test my assumptions about the way MOAI works. Second, I wanted to follow up on a misleading statement I made in my first post about connected objects and their joints.


See full post...

Extending Moai in C++

Moai's technique of enabling C++ class instances to have arbitrary Lua data tacked onto them is great. The fact their framework also allows objects to live until both Lua and C++ agree the object memory is no longer needed is even better.

What's not so good about Moai's system is that its bulky. For every class you want to expose, you have to write a helper class inheriting from MOAILuaObject. If you want to see an example, take a look at MOAIFoo included as part of the moaicore source. It's fairly straightforward ( a couple of magic macros worth exploring ), but it doesn't directly solve the question of what to do when you already have your own hierarchy of classes.

To solve the impedance mismatch between an existing class hierarchy and theirs, at least one of their docs recommends using multiple inheritance to merge the two hierarchies together. From an architectural point of view, I believe the game's code should be able to treat Moai as a separable library that helps "get stuff done". Moai's classes should be seen and used by the rest of the code base only when absolutely needed. Multiple inheritance, unfortunately, tends to lead exactly the opposite direction.

All I really want^(tm) is to take an arbitrary class, and expose it in Lua with all the goodness Moai classes have.

Rocking. Let's do it.


See full post...

Don't repeat yourself.

I'm pretty sure the first time I saw DRY -- "Don't Repeat Yourself" -- used as an acronym, I was working with Rails. As far as acronyms go, I like it. And, while it's certainly not the only aspect of good code design worth having a shorthand for, it does serve as a useful reminder from time to time. ( Not to mention, lede for this post. )

When you find yourself typing the same code -- or reenacting the same pattern of code -- over and over again, DRY asks: how can I automate this? How can I abstract away the details? How can I program my programming? 

Enter here the dark side of Lua, because implementing C++ interfaces for Lua code is a lot more RY than D.  Declare your class and its member methods. Yes, in both your .h and .cpp. Then, declare static function versions of those methods, again probably in both your .h and .cpp. Now, use those functions to map the Lua calls to the methods ( isn't this the only part we really care about? ). Then, implement a registration function containing pairs of string names for your functions, and oh yeah, those same functions again. Okay, not the end of the world, but surely we can do better....

See full post...

baby steps

I'ven't had a whole lot of time this week to program, but finally have something decently visual ( and even somewhat functional ) on screen via Moai.

A somewhat functional main menu:

And a scrolling clickable world:

The background map is made of 256x256 textured tiles, and the towns are their own sprites floating above. Both the menu and the world map are using a UI system which allows for a full set of DOM-like mouse events, and some very naive vbox,hbox code ( there's no measure pass, so the boxes have to be told how big they are. )

The data for the towns ( their names, descriptions, etc. ) are getting pulled from the same protobuffer data files the flash version used, and the code uses the Lua protobuffer reflection lib I wrote so that the C++ side and the Lua side can share the same in-memory game data structures.

The most painful part was...

See full post...

another lua curiosity: multiple return values

The previous curiosity was an example of something that didn't work, but one might argue should. This one is something that does work, and at first might be surprising. It revolves around the way Lua handles return values....

See full post...

Moai: First Impressions

I’ve been working with Moai for about a week now, and I wanted to share my impressions of it, and what I’ve learned so far.  I first heard about Moai from the folks at DoubleFine. They are using it on their new 2D adventure game, and what they said made me want to check it out.

So far, I’ve been decently impressed.  It’s not a complete game authoring solution, and it's not supposed to be. It tries to do one thing well, and I think it succeeds.

See full post...

like a rock.

hsm-statechart is now available as a lua rock!
See full post...

not that this works...

Two lexical curiosities for you: one that doesn't work at all, and one that works... sometimes. I'm not claiming that either should work mind you... okay, maybe the second one, but, then, I have ulterior motives.

See full post...

Hula

Just a follow up on my last post, I've put up the code for parsing lua statecharts ( aka. hula, which stands for... ummm... let me make something up off the cuff: the "hsm-statechart under lua api" ), and a unit test (which is the only sample code for the lua bits right now).

A quick postmortem:

See full post...

Lua state machines

It's nice to have some time, now and then, to tackle ideas purely because they are interesting. I've had state machines on my mind for a decent bit of time, and have been working on an open-source statechart engine I call hsm-statechart.  I'm also looking for new paid work, and it just so happens one of the groups I'd most like to work with uses Lua for scripting, so I figure now's as good a time as any to (re)learn it. 

As a practical task, getting lua and hsm-statechart working together seems worthwhile. Lua excels at gluing different bits of an application together and, coincidentally enough, that's also what statecharts are meant for. The combo seems like it would be a powerful one.

There are any number of simple lua finite state machines, and even SMC can target lua. But, only Miros and rFSM seem to provide hierarchical statecharts. They are both pure lua. The former ( Miros ) is a port of Samek's engine, while the latter ( rFSM ) looks to be its own unique implementation. I haven't evaluated either in depth, but both seem useful. It's Edward Pereira, though, who seems to have what's closest to my mind: a relatively easy to read textual statechart in Lua.

What follows is the approach I'm taking, it's a sketch of a design and an explanation. It's the sort of thing I normally do scribbling in my notebook ( and, in fact it started the day that way ), but if it's interesting or useful to even just one other person out there in game dev land, so much the better -- so here goes.  The advantages of this implementation are hopefully going to be readability, and interoperability with C. It might be interesting to compare speed, but I don't think that's a killer feature unless Lua LCA finding is really slow, and transitions are triggering fast and furious.


See full post...

hsm-statechart code

Over on google code, I've put up a pure C version of my statechart code.

It's a C port from C++ of a port from ActionScript3.0. The new version still needs work to make state declarations actually look more like their statecharts but it's fully functional. Docs and more blogging on statecharts to come.


See full post...

Whitespace

This has just become my favorite programming language of all time: http://compsoc.dur.ac.uk/whitespace/.

Most modern programming languages do not consider white space characters (spaces, tabs and newlines) syntax, ignoring them, as if they weren't there.... Whitespace seeks to redress the balance. Any non whitespace characters are ignored; only spaces, tabs and newlines are considered syntax.

See full post...

State Hierarchy and LCA

Earlier, I posted about State Descriptors. Now I want to show why using state descriptors to track the depth of each state in a statechart can be so useful. Namely: it enables fast, low overhead, LCA - lowest common ancestor - searches.

Since no one can be more bored of the main menu example than I, here's part of the state machine I use for exploration and combat in Dawn of Sorcery.  I'll show you what the LCA means in terms of this state machine, and why it's necessary, and then I'll show how having the depth on hand via descriptors can make the LCA search trivial.

Combat in Dawn of Sorcery

See full post...

State Descriptors

Practical Statecharts in C/C++ has a chapter describing various ways of implementing the actual states for a statemachine. It's a good read, though as inevitably happens when trying to be exhaustive, he missed a few options. ( To be fair, he was trying to list the "standard" methods, not all possible options.) 

I want to tackle one important category of options missing from his list ( and from other people's ), what I'll call here a "State Descriptor". It's a pretty simple idea, but a powerful way of describing states.

To get at what a "State Descriptor" means, let's first separate the idea of *identifying* a state from the actual *processing* code which handles the incoming events for that state.

This separation is implicit when we talk about states, but this separation vanishes during implementation. Let's take a look...


See full post...

Statechart Data 3 - Instance Data

In the introductory post, I used the example of a game's main menu to highlight some of the issues with data that programmers have to worry about when working with state machines.  Subsequent posts have looked at different places to store and retrieve data in order to address those issues. First, was global and machine storage, followed by using events ( particularly the state entry event ) to bounce data from place to place.

That leaves just two remaining categories: state instance data and model data.

See full post...

Statechart Data 2 - Events and Entry

Second in a series of posts about how state machines can store and manipulate data. Figuring out how state machines integrate cleanly into a codebase -- how they do this essential task of data management - is, i think, one of their biggest impediments to adoption.

Jumping right in, one of the most obvious spots for data storage ( other than global storage ) are inside the events that the state machine is responding to.  There are good things, and bad things, about using events for data handling, and it turns out not all statechart implementations are created equal...

See full post...

Some statechart resources

As long as I'm writing about statecharts... maybe it'd be helpful if I shared some of the resources I've found useful.

David Harel is the person who formalized/invented what was adopted as the UML Statechart spec. He has a free book, Modeling Reactive Systems with Statecharts, that's a decent ( if a bit slow ) introduction. His original paper is useful too, but since UML has evolved things a bit, it's probably not a perfect starting place for newcomers.

Miro Samek wrote Practical UML Statecharts which I highly recommend to all.  Samek also published an article sized version ( as a pdf here ) which is definitely worthwhile. He is plugging the sale of his company's software, and he does overstate ( no pun intended ) the usefulness of statemachines ( to their detriment, I think: they're not perfect for everything, and a good analysis of their shortcomings would help to better illustrate how they fit in with everything else we as programmers do ), but that doesn't stop him from writing clear and informative explanations. I particularly like his look at all the different ways statemachines can be implemented. ( But, then, that's the kind of programming discussion I like the most. )

The Boost Meta State Machine tutorial is good for getting a quick read of statechart syntax; absent is the why and how of using state machines. Wikipedia's various articles are decent enough, and the old UML 1.3 docs ( scrib, or pdf of just the statechart bits ) are great. ( Unfortunately, I've found the new 2.x docs to be impossibly dense. )

It's interesting how few resources there are which discuss exactly how UI and statecharts fit together. Apparently, Constructing the User Interface with Statecharts by Ian Horrocks is a good one, but at 100+ dollars for a used paperback, it's a little pricey to pickup on blind faith.

If you've got any good links, be sure to let me know.

See full post...

Statechart Data 1 - Global and Machine Storage

In the previous post, i gave an example of a series of graphical menus, and asked how exactly do those statecharts interact with the menuing system, and specifically: how do statecharts create and manipulate user interface data?

Let's start right at the very top with the outermost menu:

   Main Menu:
   - entry / display_options();
   - button[0] >> New Game.
   - button[1] >> Continue Game.
   - button[2] >> Options.

And dig into some pseudo code.


See full post...

Statechart Data - Statecharts are not flowcharts.

Statecharts are meant to be descriptions of reactive behavior. The outside world generates events, a state machine processes those events, responds with predefined actions, and then waits for the next event. A flowchart, on the other hand, receives data as input and transforms that data as it passes it along; stage after stage. Wikipedia has a whole section on this difference, my favorite (paraphrased) quote being:

 
In a state diagram, processing is associated with transitions, whereas in a flowchart processing is associated with nodes. A state machine sits idle in a state waiting for an event to occur; a flowchart is busy executing activities.

I find that a useful mantra to mumble to myself while setting up states ( thank goodness only my cats are around to complain ) because programming state machines has a different feel than programming normal procedural code. Frequently, I think, we as programmers want our code to be *doing* something. But, with state machines, your code is just sitting there, waiting to react, waiting for a chance to do something.

Another way to think about all this is that you aren't are writing instructions to control movement from state to state, but rather only documenting how those changes happen. Your machine code is only "following along" with changes happening elsewhere.  At it's essence, that is what a purely reactive system means. It reacts to the world, it doesn't control the world. ( The prime example Harel uses in his book, for instance, is an emergency warning system for aircraft. )

So, that's all great in theory, but how does it stand up in practice?  Consider a simple main menu with several choices...

See full post...

Quick and dirty textual statecharts

I'm working on a few posts about statecharts -- but I don't want to write a introduction to statecharts as there are plenty of people out there who have done a better job than I would, so I'll more or less jump into the thick of it ( once I get there ). If I have my druthers, I'll post the C++ statechart toolkit I've been working on with as liberal a license as I can.... soon....

Textual Statecharts

The one thing I would like to note first, though it'll probably be pretty obvious, is the notation I've adopted for writing UML states without diagrams.  It's straightforward enough, but just to document once by example, here's Samek's toaster oven chart ( original posted below ) rendered as text:

    Heating:
    - enter /start_heater();
    - exit  /stop_heater(); 
    - init  >> Toasting.   
    - toast >> Toasting.
    - bake  >> Baking.
    - open  >> Open.
      Toasting:
      - enter /arm_timer();
      - exit  /disarm_timer();
      - do [timer elapsed] / eject_toast();
      Baking:
      - enter/set_temp();
      - exit /set_temp();
    Open:
    - enter /illuminate();
    - exit  /extinguish();
    - close >> Heating.

I think this is pretty easy to read even without knowing a thing about statecharts, but it more or less follows the UML syntax. And it's also vaguely YAML-like...

See full post...