Language Reference and Tutorial

Variables
Objects
Actions
The 'Guts' of an Object
The 'Guts' of an Action
Calling Actions
The start Object
A Tiny Example Game

Variables

Variables are declared using the var keyword. They must be declared before they are used. As a rule, I recommend all variables be declared at the beginning of the script document. Variables are global and it will be easier to keep track of them if they are all declared in one place.

Variables may contain only numeric values. In practice, I have found that I mostly use them as booleans by using them to store 1 or 0. However, if you look at The Space Guppy's Script, you will see a few non-boolean uses.

When declaring a variable, you may give it a starting value by using the assignment operator, "=". Variables not given a starting value automatically begin with the value of 0 (zero). The var statement must terminate with a semicolon ";". Here is an example:

var magic_chest_closed=1;
var dragon_slain;

In this example, two variables are declared. magic_chest_closed is given a starting value of 1 (probably to be used as a "true" indicating that the magic chest is closed). dragon_slain is also declared, but not given a default value and is thus 0 (probably to indicate that the dragon has not yet been slain).

Objects

Everything in Dave's Game Engine is an object: items, rooms, people, etc. Objects contain actions, allowing you to interact with them. You declare an object with the object keyword. Declaring an object is very simple. It's what you put in the object that counts.

To declare an object, you must use the object keyword followed by the name of the object. Then you must define the object by typing an open curly-bracket "{", the contents of the object, and then a close curly-bracket "}". Take a look at this example:

object castle_entry
{
  castle_entry's contents
}

In this example, an object called castle_entry is declared. It's definition is then contained in the open and close curly-brackets.

Actions

Actions are what make the game run. They are what allow you to interact with objects and change the game world. An action always belongs to an object and is defined inside the object.

Declaring an action is easy. Simply insert an action keyword into an object followed by the name of your action, an open and close parenthesis "()", an open curly-bracket "{", the contents of the action, and then a close curly-bracket "}". Here is an example of an action declaration:

object sword
{
  action sharpen()
  {
    sharpen's contents
  }
}

In this example, an action called "sharpen" has been given to an object called "sword". When the sharpen action is called, the contents of the action will run, causing things to happen in the game.

The 'Guts' of an Object

An Object's object_description

The object_description string is used by the game engine to describe the object in text so that it can be clicked on in location descriptions or in the inventory. If the object is not going to be a location or an inventory item, it's okay to not have an object_description.

To define an object_description, simply place object_description = "your description"; inside the curly brackets of the object. Here is an example:

object sword
{
  object_description = "Silver Sword";
}

In this example, the "sword" object has been given a description of "Silver Sword". That is how the sword object will appear if it shows up in the Inventory.

The is_inv_item Option

Some objects can be placed in the player's Inventory. When this is the case, it should be indicated by adding a line with is_inv_item; to the object's defintion. To actually add this object to the Inventory, you'll need to set a special variable. See inv_object for more information. Take a look at this example:

object sword
{
  object_description = "Silver Sword";
  is_inv_item;
}

In this example, the "sword" object has been modified so that it can be placed in the Inventory.

An Object's lookat Action

Every object should probably contain a "lookat" action. When a location or inventory item is examined, the lookat() action is automatically called. You can also specifically call the lookat action of an object to let the player examine it.

A lookat action is declared the same way any other action would be. As with all other actions, it will contain a text block (more on those in the Guts of an Action section used to describe the object. Here's what one looks like:

object sword
{
  object_description = "Silver Sword";
  is_inv_item;

  action lookat()
  {
    @
     Though tarnished by age, this sword is of excellent craftsmanship.  It has
     gold inlays in the tang and leather cord wrapped around the handle.
    @
  }
}

The above example expands upon our sword object. The lookat action has been used to describe the sword in greater detail. The @ signs are used as delimiters for a text block. Again, these will be explained later.

The 'Guts' of an Action

Actions can contain any number of variable settings, text blocks, and if/else logic. All of these things are to be placed in the body of the action definition:

object sword
{
  action sharpen()
  {
    stuff goes here
  }
}

Setting Variables

Setting variables is easy. Just use the assignment operator "=" and terminate the statement with a semicolon ";". It is best explained with this simple example:

object sword
{
  action sharpen()
  {
    sword_is_sharp = 1;
  }
}

This sets the sword_is_sharp variable to 1 (true) when the sharpen action is called. Please note that this action is not complete without at least one text block, so keep reading.

location

There is a special variable that is always available called "location". The location variable always holds the present position of the player's character in the game world. The player can always click on the name (object_description) of the object that is set as the location (which will run the object's lookat action). Setting the location is easy:

object hallway
{
  action open_red_door()
  {
    location = kitchen;
  }
}

This sets the character's location to the "kitchen" object when the open_red_door action is called. Please note that this action is not complete without at least one text block, so keep reading.

inv_object

Above, we mentioned the is_inv_item keyword which can be applied to an object so that it can be placed in the Inventory. Once you have done that, you'll want the ability to add and remove the object from the inventory. This is done through a special variable which is created at runtime for you called inv_your object's name. Let's show how this works with a pair of actions:

object sword
{
  is_inv_item;

  action pick_up()
  {
    inv_sword = 1;
  }

  action drop()
  {
    inv_sword = 0;
  }
}

In this example, there are two actions. By the names, it should be pretty clear what these actions do. You can see that the inv_sword variable is used to indicate that the object is in the inventory (1) or not (0). Remember, this variable is created for you by the game engine when you use the is_inv_item keyword, so you do not need to create it. Please note that neither of these actions is complete without at least one text block, so keep reading.

Text Blocks

The most important thing that each action should have is at least one text block. A text block defines the text that will show up when the player calls an action. A text block starts and ends with '@'. It may contain any characters except for '@'s (which the game engine would interpret as the end of your text block!). The use of HTML formatting in your text block is encouraged to aid readability or interest. Check out how this text block completes our "sharpen" action in the sword object:

object sword
{
  action sharpen()
  {
    sword_is_sharp = 1;
    @
      You deftly sharpen the sword with the whetstone.  The edge has been
      ground perfectly straight and flat again.  You shave a yak with it
      to test its sharpness.  "Nice."
    @
  }
}

In the above example, the paragraph of text in the text block is displayed when the sharpen action is called. Notice that the quoted "Nice." needs no extra formatting and will show up verbatim.

If/Else Logic

We have learned how to create and set variables. But they're worthless without being able to test them. That's what the if and else keywords are for. Ifs and elses can be placed anywhere inside an action to make different things happen depending on the condition of variables. The syntax is simple to grasp, so check out this example:

object sword
{
  action cut_rope()
  {
    if(sword_is_sharp == 1)
    {
      @
        The sword slices cleanly through the rope and you are freed
        from the trap!
      @
    }
    else
    {
      @
        The sword is dull and barely frays the rope.  You are still
        trapped and the lion is getting closer!
      @
    }
  }
}

As you can see above, an if statement needs a variable test in parenthesis. The test must take the form of a variable name (sword_is_sharp in this case) followed by the equality test operator "==" and then the number value to be compared. If the test is true, the actions in the "if" statement's curly-brackets will run. In this case, it will show a statement that you have been freed from a trap. If the test fails (sword_is_sharp is any value besides 1), then the actions in the else section will run instead (darn that lion).

You can also conditionally put together text blocks with if and else statements. This can be very helpful in preventing you from having to copy-and-paste large chunks of text. Here is an example of that:

object door
{
  action lookat()
  {
    @
      The door is covered in a faded and flaking red paint.  It appears
      to be made of stout wood and held together by massive metal bolts.
    @
    if(door_unlocked == 1)
    {
      @
        It is slightly ajar.
      @
    }
    else
    {
      @
        You push on the door, but it does not budge.
      @
    }
  }
}

Here we have a text block containing a description of the door that always displays when it is looked at (with the lookat action). After that is a test of the door_unlocked variable. If the result is true, we display that the door is "slightly ajar." If it is false, then "it does not budge." Note: though the previous two examples have had both an if and else statement, the else portion is completely optional. Only use it if you need it.

Calling Actions

By now you are surely wondering how to actually call the actions that we have been creating. It's easy to do. You'll just need to create a special link in your game text. When the user clicks on the link, the specified action is called. Take a look at one:

object sword
{
  action lookat()
  {
    @
      This sword looks dull.  
      You should [sword->sharpen():apply your whetstone] to it.
    @
  }

  action sharpen()
  {
    @
      You sharpen the sword!
    @
  }
}

As you can see, our action link is the [sword->sharpen():apply your whetstone] bit in the lookat text block. This link has two parts separate by a colon ":". The first part is the action to be called. The action is specified by the object "sword" then the action member operator "->" and then the name of the action "sharpen" and a pair of parenthesis "()". The second part is the text that will appear in the link ("apply your whetstone"). When the player clicks on the link, the action will be called, displaying "You sharpen the sword!" It's easy to do once you get the hang of it.

The start Object

The only thing you have left to learn is how a game begins. This is done through a special object called "start". It is the only object you are required to have in your game. The first thing that happens when a game starts for the first time is that start's "lookat" action is called. After that, it's all up to you. I recommend constructing your start object so that it works something like this:

object start
{
  action lookat()
  {
    location = castle_entrance;
    @
      Welcome to Wizard Battle IV!  You have been riding all day.
      You are currently at the entrance to Lord Foo's castle.
    @
  }
}

You'll notice that I set the location to castle_entrance. Otherwise your player will start out in a limbo. Don't do that. Feel free to include any action links you wish in start's lookat text block. The action works just like any other, it just happens to be called first.

A Tiny Example Game

If you've read this far, you have read about every element of Dave's Game Script Language. Now it's time to put everything together in an extremely simplistic game so that you can see how everything fits together. In this example, you must escape from a dungeon by freeing a bear from his chains. But first you must find the key...

var bear_freed;

object start
{
  action lookat()
  {
    location = dungeon;
    @
      Welcome to Escape The Dungeon!  You are trapped in a
      dungeon!
    @
  }
}

object dungeon
{
  action lookat()
  {
    @
      The dungeon is dark and musty. 
      A [dungeon->try_door():heavy door] set into one of the
      stone walls.  There is a bear in the dungeon with you.
    @

    if(bear_freed == 0)
    {
      @
        The bear is heavily chained and can only "grrr" at you.
      @
    }

    if(inv_key == 0)
    {
      @
        There is a [dungeon->lift_bucket():bucket] overturned
        on the ground.
      @
    }
  }

  action try_door
  {
    if(bear_freed == 1)
    {
      location = outside;
      @
        You try the door.  It does not budge.  However, the
        bear sees your efforts. He gets up and breaks through
        the door.  You are now outside!
      @
    }
    else
    {
      @
        You try the door.  It does not budge.  If only you were
        strong like a bear...
      @
    }
  }

  action lift_bucket
  {
    inv_key = 1;
    @
      Curious, you lift up the bucket.  Underneath is a key.  You
      pick it up.  They key is now in your inventory.
    @
  }
}

object key
{
  is_inv_item;

  object_description = "A Small Key";

  action lookat()
  {
    inv_key = 0;
    @
      You take a closer look at the key.  What might it unlock?  You
      look around until you see the padlock holding the chained bear.
      Aha!  You unlock the chains and the bear is free!  You toss the
      key away.  You won't be needing that anymore.
    @
  }
}

object outside
{
  object_description = "Outside";

  action lookat()
  {
    @
      All around you is green grass and sunshine.  The bear is already 
      running towards some trees.  You might as well start walking to
      the nearest town to get something to drink.  THE END.
    @
  }
}

Hopefully you liked this example game. Obviously a lot of detail could have been added. The bear could have been fleshed out into an object that you could interact with more fully, for example. But this example demonstrates every feature of the language. Enjoy.

Dave's Game Script Language