Development Sprints 8-10: Prototypes and Metadata II, finished today. Good riddance.

This was a difficult series of sprints in that “outside influences”, aka: our day jobs, required our full attention over those nine weeks. Additionally for me, my previous blitz through GUI container object creation left quite a few bugs behind. My initial attempt at creating a real multi-container map window fell flat on its face right out of the gate. More thorough container work needed to be done… and I just wasn’t up for it.

Enter XML

After trying to muscle my way through my stories, after returning from a business trip to Japan, I decided to start a new subproject: XML.

Our rules and other documents are written in Apple’s Pages word processor application. While revisions are stored under a source control system, it is a binary file, which is not a friendly format for such systems. File revision comparisons are also not easy to track as you have to rely on the application.

I decided to convert the TOCS Basic Rules and TOCS WWII Rules from this format to an XML format and write a script to generate HTML versions of the rules, with PDF document generation to follow at a later date.

While I didn’t quite finish the XML conversion, I got 95% complete and was able to post the HTML versions of the rules to a hidden area of our website. The advantages were immediate:

• the HTML docs are linkable and easier to use than the PDFs
• as XML is a text format, revisions are a simple ‘diff’ away
• large-scale rules edits will be easier

The docgen.rb script was surprisingly easy to write, once I knew what the tag structure was going to be for the docs. In fact, it was the only story we completed in nine weeks of interrupted development. There is still some more work to do, and some crazy ideas have been brainstormed from this work, but the concept is sound.

One note about large-scale rules edits being easier came from my experience with NES’ Winter’s Victory project. After a playtest, I remarked to Mark Hinkle, the designer of WV and owner of NES, that a rules section should be moved to another area of the rules for easier reference. His reply was that he was not going to do that; it was too much work for too little effort.

The problem is that all section numbering and cross-references are hard-coded. Moving, for example, 13.0 Retreats to an earlier section of the rules, like 11.0 perhaps, would require a renumbering of rules sections 11, 12 & 13 and would also require all cross-references throughout the rule book to be updated. That is a lot of work.

The XML solution that I hit upon was to avoid hard-coded numbering of rules sections. Instead, the XML processor collects the section and heading tags and keeps a sequential list of them. When a document is generated, its section number is based on its position in this list. Moving an entire rules section would simple changes its place in the list and its section number.

Cross-references are handled as xref tags with the tag attribute being the section heading text. This ensures that all xrefs refer to specific sections and its associated section number. When a document is generated, the cross-reference numbering is handled by looking up the section heading the xref tag refers to and uses that generated section number. If you change a section heading, you will have to change all xref tag attributes that referred to that section. Apart from that, section numbering is automatic.

Footnotes in our rules sets were also hard-coded, with sequential numbers sprinkled throughout the rules and a list at the end of the document. Now, footnote tags and associated text are placed directly at its place in the rules. During document generation, the footnote tags are replaced with the sequential numbers and the text is collected and written at the end of the document.

For HTML document generation, these xref and footnote tags are replaced with links that will take you to those cross-referenced rules or footnotes.

So far, it’s all working quite well. I still have some italicized text to account for, and it’s tedious work, but the concept is sound. The AttM module Mission Briefs will be converted next.

Map Metadata

Paul will be continuing with creating the AttM map metadata as I work on the mapreader.rb script to validate the data. This project also shows great promise in providing needed map reading capability to the game engine.

The Playtest

In the background, our AttM playtest continues. Based on this, we have collected quite a few rules changes and clarifications to the system. It was this collection that spurred my thoughts on converting the rules to XML.

Right now, I’m mostly happy with the system. There are some subconscious issues that I need to spend some time processing. There are times when I’m facing a challenge that my opponent has set up and there are times when I’m challenged by the rules themselves. The former is fine, excellent even. The latter needs to be minimized. Everything we have in the rules makes sense, but I feel that it needs some tuning.

Other Influences

In addition to my day job, Steel and Steam has also been taking up a bit of my brainspace. And now… Running Eight, a train-based card game. Without going into too much detail in this post, I had been stumped by a design element of Running Eight that threatened its derailment. I have since figured out a solution and I think I’ve got the kernel of an entertaining 60-90 minute 3-8 player card game. More details to follow in a later post…