How to program a text adventure in C

9. Code generation

So far, our adventure has 10 objects. Each object consists of 5 attributes (the fields in struct OBJECT). A real text adventure is likely to have hundreds, even thousands of objects, and the number of attributes per object is likely to rise as well (see the next chapter). In its current form, maintaining such a big list of objects and attributes would be hard.

For example, when we added objects wallField and wallCave in the previous chapter, we had to do so in three different places: once in object.h (as a #define), and twice in object.c (an element in array objs, and a separate array for the tags). This is clumsy and error-prone.

Instead of maintaining object.h and object.c by hand, we will start generating the files from a single source that is more suited to our needs. This new source file could be in any language you like (typically some domain-specific language), as long as you have the tools to convert it back to C. Below is a simple example. Consider the following layout to organize our objects:

- ObjectName
      AttributeName AttributeValue
      AttributeName AttributeValue
      ...
- ObjectName
      AttributeName AttributeValue
      AttributeName AttributeValue
      ...
- ...

Based on the objects we have gathered so far, we could construct the following source file. The file name does not matter much; I simply named it object.txt, to make it clear it is related to object.h and object.c.

I made up the syntax myself, so it is safe to assume there are no standard tools to translate it to C. We will have to write our own code generator! Since this code generator will be a separate program, completely independent of our adventure program, we can write it in any language we like - not necessarily C. Here is one possible implementation, written in AWK:

We actually need to call this AWK script three times to generate the C sources:

awk -v pass=h  -f object.awk object.txt >  object.h
awk -v pass=c1 -f object.awk object.txt >  object.c
awk -v pass=c2 -f object.awk object.txt >> object.c

As you can see, object.c is generated in two passes; for object.h, a single pass is sufficient. I could have made three separate AWK scripts, one for each pass, but instead I made a single big script combining all three, which seemed like the right thing to do considering the many similarities.

Our code generator script is very basic; it does no syntax checking on the attribute values. Most typos made in object.txt will pass through the generator without any errors. This is not a problem though: the syntax checks performed afterwards by the C compiler are sufficient. When compilation fails, the trick is to recognize your mistakes in the C code, then find and fix the original source in object.txt. To make this task just a little bit easier, the least we can do is let the code generator add some comments in the generated C code (see object.awk line 52). The AWK script may also pass errors over to the C compiler, by outputting a #error directive as part of the generated code (see line 25).

Notes:

• Important: as of now, we will not be making any manual changes in object.h and object.c; these would only be discarded by our code generation process.
• This mixture of languages (C, AWK and a domain-specific language) may seem confusing at first. Then again, this is still relatively simple compared to the mixture of server-side and client-side techniques the average web developer finds himself confronted with.
• Because object.txt is converted to plain C code, compiled, and linked with the other modules, all of its data will be part of the final executable. Like any source file, object.txt does not have to be present when the executable is running (i.e. when somebody is playing the game). This, of course, is just a matter of choice. It is very well possible to keep object.txt apart from the executable, and have the executable import the data from object.txt at runtime. This is particularly interesting when you are building your own adventure development system. Do keep in mind that it will make your code slightly more complicated; you will have to put more effort in parsing object.txt, since there will be no C compiler to back you up. All this is outside the scope of this tutorial; we will focus on using the benefits of the C compiler as much as possible.

Visualization

When it comes to choosing a domain-specific language, keep in mind that code generation is not its only benefit. A simple AWK script, similar to the one above, can be used to visualize a map of your virtual world by drawing a graph.

Execute this script with the commands below, and object.txt will be converted into map.png; the picture you see on the right. Please note that this picture is not part of the game; it is not something the player will (should) ever see. It is merely a developer's tool, making it easier to spot mistakes in object.txt.

awk -f map.awk object.txt > map.gv
dot -Tpng -o map.png map.gv

Notes:

• For the command dot to work, you need to install Graphviz first.
• Notice how this picture matches the map I drew by hand in chapter 6 (except for the orientation). Our map is still very trivial, but as the number of locations grows, this soon becomes a useful tool to validate object.txt against your intended map.
• I have used DOT as an intermediate language here (map.gv). If your adventure has a really complex map, you may even consider using a graph editor to design your map, then try to generate C code from the resulting DOT output (or whatever graph description language the editor is capable of). This is a great way to design your locations and passages, and it gives you far better control over the graphical presentation of the map. However, this approach may be less suitable to maintain the other objects and attributes.

Makefile

Calling AWK manually each time object.txt has been modified, soon becomes tedious. It is best to make these calls part of your build process. For example, a simple makefile for our adventure might look like this:

Now a single command make will do everything that is necessary to construct a new executable (named lilcave here) and a new map image. Notice I put not only object.txt, but also object.awk in the dependency rules (lines 9 and 12). Although technically, object.awk is more of a development tool than it is a source file, it is still subject to change; already so in the next three chapters.

Next chapter: 10. More attributes