Last night I was hacking around with Ruby and decided that to teach myself how to program better I would do something interesting for Wezzle. I had the idea of taking the XML markup for our achievements and making some sort of generator using our achievement pseudo-language.

Our achievement language basically amounts to what is known in computing as a Domain Specific Language (DSL). Luckily for me Ruby is a pretty good language for writing DSL’s.

I decided to start with the achievements that I find to be the hardest to write, COLLISION. A COLLISION occurs between 1 or many items. There are two seperate types of collisions which can be defined as either an AND or an INTO relationship. These can be seen in the following two examples:

Example 1:

<achievement name="A Tale of Two Rockets" difficulty="SILVER">
  <description>Fire a rocket into another rocket.</description>
  <rule type="COLLISION" operation="BETWEEN">
    <item type="ROCKET" />
    <item type="ROCKET" />
  </rule>
</achievement>

Example 2:

<achievement name="A Tale of Two Rockets" difficulty="SILVER">
  <description>Fire a rocket into another rocket.</description>
  <rule type="COLLISION" operation="BETWEEN">
    <item type="ROCKET" >
      <item type="ROCKET" />
    </item>
  </rule>
</achievement>

While these two examples may look the same, they mean two different things. The first one can be written as COLLISION BETWEEN ROCKET AND ROCKET simply means that two rockets will be activated in a single turn. The second one however would be written like COLLISION BETWEEN ROCKET INTO ROCKET and means a rocket will be fired and activate another rocket by hitting it.

I have written a generator in ruby that takes an achievement (currently only collisions) in the following form:

BEGIN COLLISION
achievement:Rocketeer:BRONZE
description:Fire a rocket into a rocket and fire a rocket and a rocket.
rule:COLLISION BETWEEN ROCKET INTO ROCKET
rule:COLLISION BETWEEN ROCKET AND ROCKET
END

This is currently defined within the program and will output the properly formatted and tabbed XML which you can then paste into your achievements.xml file. The goal is to have it work for all achievements, and I will keep you updated as to the progress should I choose to continue. As it stands, you can find the current version here although it’s a little bit ugly. Please note, you must have ruby 1.9+ in order to run it.

I’d like to talk a bit about a cool little feature of Wezzle that nobody knows about. Wezzle reads all of its information from XML. Neat!

Ok, ok, so that’s not that groundbreaking. I never said it was, but it IS cool. Because of this, all of Wezzle’s attributes are fully customizable.

The first time you run it, Wezzle generates four files located in your home directory in a folder called .Couchware/Wezzle. Three of these files are XML files, achievements.xml, game-settings.xml and user-settings.xml. The fourth file is the log file.  These files contain your personal settings and achievements, modify them to your hearts content! If you ever run into a problem, you can just delete the file and the game will load the default settings.

I know what you are thinking: “Awesome. Every game has customizable settings, why is this so special?”. Well my friends, it’s special because Wezzle understands XML! What this means is, you guys can create content and as long as it conforms to our specifications (which we will release with or shortly after we release Wezzle) Wezzle will understand it. These three XML files are loaded on top of our base settings, which means things like custom tilesets, custom tile colours and even custom achievements are easy!

I’m going to look a little bit at achievements. Wezzle’s achievement system is a rule based system. What this means is, any achievement can be expressed as a set of rules. For example, if you wanted to have an achievement for scoring more than 6000 points, the achievement would simply contain the rule: SCORE > 6000. Cool.

Additionally, an achievement is only completed iff (if and only if) all the rules evaluate to true. This means that we can combine any number of rules to make an achievement.

A huge benefit of this is that writing achievements is trivial, as long as you know the set of available tags. The achievement system already reads in all it’s achievements from an XML file and is still being expanded. Here is an example of an achievement that is currently in our test game:

<achievement name="Get A Level" difficulty="BRONZE">
  <description>Starting from level 1, get to level 2 without
  getting a game over.</description>
  <rule type="START_LEVEL" operation="EQ" value="1" />
  <rule type="LEVEL" operation="EQ" value="2" />
</achievement>

The achievement is enclosed with <achievement> tags which include meta data for that achievement including the difficulty level and name. The <description> tag is the achievements description as shown in the achievement browser. Finally, all the rules are defined in <rule> tags. Pretty simple huh? As you can see, we defined two rules with this achievement. Rule 1: Start level = 1. Rule 2: Level = 2.

When designing our XML tags for Wezzle we wanted our rules to be as readable as possible. We tried to mimic human speech. Each rule is an AND relationship. The above XML for our achievement can be read like this: START_LEVEL EQ 1 AND LEVEL EQ 2. In other words: “start level equals 1 and level equals 2″.

An achievement is considered completed iff ALL of its rules evaluate to true. Therefore, in order to achieve the achievement listed above, you must start the game at level 1 and your current level must be level 2. This means that if you start on level 2 (or any other level than 1), you cannot complete this achievement.

Now lets take a look at writing a custom achievement. In order to do this, all we have to do is write up the XML and stick it into our achievements.xml file. Wezzle will automatically read this new achievement and incorporate it into the game, including placing it into the achievement browser.

I will walk you through the creation of another one of the available achievements currently in the game. We would like to have an achievement for when a rocket fires into another rocket. In the game the name of this achievement is “A Tale of Two Rockets” and its a Silver achievement.

So to start we make our achievement tag: <achievement name="A Tale of Two Rockets" difficulty="SILVER">. Then we make our description: <description>Fire a rocket into another rocket.</description>. That’s the easy part. In order to get the functionality we need, we have to properly create our rules. The rule we are looking for here is called a COLLISION. A collision takes an operation and a list of items. We will be using the BETWEEN operation and our item types will both be ROCKETS.

Our rules will look like this: <rule type="COLLISION" operation="BETWEEN"><item type="ROCKET"/><item type="ROCKET"/></rule>. This is pretty intuitive. This XML reads as COLLISION BETWEEN ROCKET AND ROCKET. Pretty simple.

The full achievement looks like this:

<achievement name="A Tale of Two Rockets" difficulty="SILVER">
  <description>Fire a rocket into another rocket.</description>
  <rule type="COLLISION" operation="BETWEEN">
    <item type="ROCKET" />
    <item type="ROCKET" />
  </rule>
</achievement>

There’s one more thing we need to make sure of when adding our custom achievement. Within the XML file there are two entries: <entry name="User.Achievement"> and <entry name="User.Achievement.Completed">. By default the only entries in the achievement.xml file are in the User.Achievement.Completed entry. So to add our custom achievement, we will have to make a new entry for our non-completed achievement.

The final file (with a completed achievement) looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <entry name="User.Achievement.Completed">
    <achievement name="Get A Level" difficulty="BRONZE">
      <description>Starting from level 1, get to level 2 without
      getting a game over.</description>
      <date day="27" month="0" year="2009" />
      <rule type="START_LEVEL" operation="EQ" value="1" />
      <rule type="LEVEL" operation="EQ" value="2" />
    </achievement>
  </entry>
  <entry name="User.Achievement">
    <achievement name="A Tale of Two Rockets" difficulty="SILVER">
      <description>Fire a rocket into another rocket.</description>
      <rule type="COLLISION" operation="BETWEEN">
        <item type="ROCKET" />
        <item type="ROCKET" />
      </rule>
    </achievement>
  </entry>
</settings>

That’s all there is to it.

Hopefully you guys enjoyed this and will get to making or suggesting some custom achievements!