On Creating Tools

When I started coding my own engine and game, one of my constraints was that I wasn’t going to write an editor for whatever game I made. This was mostly a time saving constraint. Good tools take time, as I certainly learned while making console games. Often the editor tools to go with a new system took as much time to write and debug as the system itself.

However, as I work on a new game, I find that I need an editor for some things. I need to be able to place objects, make paths, and edit properties. Which is potentially a huge project unto itself. So I’ve been looking for ways to write such a tool with minimal code. More immediately, I’ve been working on some procedural generation code for terrain, but I want to be able to edit the generation properties and see results immediately, instead of changing parameters, running the code to see a result, quitting the program, and repeating over and over.

Also important, is the need to not waste time on user interface for code that is under-going development. If I add a parameter to the terrain generation code, then decide I don’t need it, I shouldn’t be spending time adding a new button or number edit field on some UI. This means some sort of automatic user interface.

So what I need is an automatic property page style dialog that uses type reflection to determine field names, types, and values.

Type Reflection

The idea of reflection is that the code that’s running knows about the properties of itself as it’s running. Given some code that defines some data and the functions that operate on that data, the code can find out and use names, types, and all sorts of other useful information about itself. Strangely, the engine sort of has this functionality, but it wasn’t built for this purpose. It just needed some extra glue to make it work.

Serialization

What the engine does have is a very flexible serialization system. A single function is created to read and write data to and from disc. It can operate in binary mode or text mode. Text mode is a bit fancy. I wrote it to be able to edit data (since I had no editor) in a human readable way. It looks somewhat like JSON, but I built it to look more like the C++ class that is used in code. For example, here’s an ImageBuffer (that’s called a texture in most engines…)

ImageBuffer editorSheet { String _imageName = "Build/EditorSheet.png"; Type _type = Rectangle; Usage _usage = Texture; Format _format = RGBA8; Flags _flags = Mipmaps; AddressMode _addressU = Clamp; AddressMode _addressV = Clamp; AddressMode _addressW = Clamp; FilterMode _filterMode = Linear; }

The C++ that defines the ImageBuffer looks very similar.

class ImageBuffer { protected: int32 _width; int32 _height; ImageType _type; Usage _usage; Format _format; Flags _flags; AddressMode _addressU; AddressMode _addressV; AddressMode _addressW; FilterMode _filterMode; System::String _imageName; };

And serializing the image to and from disc looks like this:

bool ImageBuffer::Serialize(IO::Stream& stream) { IO::Serializer s(stream); s.Serialize(_InternalField(_width)); s.Serialize(_InternalField(_height)); s.Serialize(_Field(_type)); s.Serialize(_Field(_usage)); s.Serialize(_Field(_format)); s.Serialize(_Field(_flags)); s.Serialize(_Field(_addressU)); s.Serialize(_Field(_addressV)); s.Serialize(_Field(_addressW)); s.Serialize(_Field(_filterMode)); s.Serialize(_Field(_imageName)); PlatformSerialize(s); return true; }

There’s some magic here. The stream of data could be text or binary, (or something else) and when the serializer is instantiated for that stream, an appropriate reader or writer is created. The _Field and _InternalField macros define what’s available to the text reader, and what isn’t. For example width and height come from the image, and aren’t user editable.

Nothing says that the serializer has to come from or go to disc. It could be to memory, or some other crazy system, like following object pointers for garbage collection. So by writing a new back end for the serializer, I get exactly what I need for reflection. The field names, types, values, and addresses are available. I even know which fields I can present visibly and which ones not to.

So with a tiny bit of extra code, I get object reflection without modifying any of my engine code. Amazing! Did I luck out or what? While the ImageBuffer example doesn’t show it, this system also works for user defined types, enums, flags, pointers, arrays, colors, type ids, etc.

The User Interface

Again, I’m lucky. In making Banished I wrote a UI system that has a lot of control types. So again I don’t have to write a ton of code or bring in a separate UI library.



The UI in the engine has edit boxes, number edits and spinners, combo boxes, list boxes, check boxes, scroll bars, windows, layout tools, sprites, text, etc. Another game may not have needed so many different controls. I’m not sure what I’d be doing for making this user interface otherwise.

Putting it Together

So all I really needed to do was write some code that would create a control for each specific type. Number edits for integers, a set of check boxes for flags, combo boxes for enums, etc. When the user changes the values in the controls, I’d just need to push the new value into the back end of my serializer and send the data back to the object using the Serialize function.



And since the serialization system is already built to do things like compile a PNG into a block compressed format ready for GPU use, when the values are changed in the propery editor, the same compilation occurs as if it were being loaded from disc.



Easy!



I say that it was easy, but it’s more that the new functionality wasn’t invasive to the existing engine. It was still a fairly sizeable bit of code and took a while to write properly.

The Property Editor

So without too much fuss, and zero engine modifications (just additional code), I have a property editor for any object in my engine. I can edit textures, sounds, or any new game object I add to the engine.



I have a few more editors to write. For example I don’t have a color picker. Right now I just type in a hex value like 0xFFCO80AB. But that shouldn’t be too bad to create in a day or so. And I probably need some resource editor that allows me to browse everything on disc.



I could also modify the serialization functions to provide some meta-data for the editor. For example minimum/maximum values for numbers, increments for spinners, read only fields, field groupings, etc. But this will require modifying every existing serialization function. All in good time.



This is a long way from a full featured editor, but it’s a start and it has a lot of possibilities. First is that I can edit all objects that I serialize without any additional code. It can also be used to do strange things, like editing the user interface properties of the property editor. And because it uses my own UI, in the future I could use it in game to select objects, see their properties, and change them for debugging purposes.



Awesome.