In the attic of the wizard’s house is a welding machine. Let’s allow the players to weld the chain to the bucket if they bring those items to that location. Here’s the code to make this happen:

 (defun have (object)
    (member object (inventory)))

 (defparameter *chain-welded* nil)

 (defun weld (subject object)
   (if (and (eq *location* 'attic)
             (eq subject 'chain)
             (eq object 'bucket)
             (have 'chain)
             (have 'bucket)
             (not *chain-welded*))
       (progn (setf *chain-welded* t)
               '(the chain is now securely welded to the bucket.))
     '(you cannot weld like that.)))

First, we need an easy way of checking whether the player is currently carrying an object, using the have function . Remember that we created a command for checking what the player is carrying, named inventory. If an object is a member of the inventory, it means the player must “have” that object.

Next, our program needs some way of keeping track of whether or not the chain and bucket are welded together, since there will be actions later in the game that are possible only once this welding has happened. For this purpose, we create a global, dynamic variable named *chain-welded* .

Finally, we need to create the welding command itself . Welding is possible only if a slew of conditions are met :

If these conditions are met, we set our *chain-welded* variable to true and print a message indicating this success. If any of the conditions fail, we indicate that the welding was unsuccessful .

Let’s try the command in the CLISP REPL:

> (weld 'chain 'bucket)
(YOU CANNOT WELD LIKE THAT.)

Well, that’s exactly the right response. After all, we’re not in the attic, and we aren’t carrying the right objects. So far, so good.

Next, let’s try our new command in our fancy game-repl:

> (game-repl)
weld chain bucket
I do not know that command.
quit

What? Why doesn’t it “know” that command? The answer is simple: Our game-repl has some basic protections against running unauthorized commands. To remedy this, we need to add weld to our list of permitted commands:

> (pushnew 'weld *allowed-commands*)
(WELD LOOK WALK PICKUP INVENTORY)
> (game-repl)
weld chain bucket
You cannot weld like that.

By using the pushnew command, the weld function is added only to the allowed commands if it wasn’t already present in that list. Problem solved!

In the wizard’s garden, there is a well. Let’s create a command that lets the player dunk the bucket in the well to fill it with water:

 (setf *bucket-filled* nil)

 (defun dunk (subject object)
   (if (and (eq *location* 'garden)
             (eq subject 'bucket)
             (eq object 'well)
             (have 'bucket)
             *chain-welded*)
        (progn (setf *bucket-filled* 't)
               '(the bucket is now full of water))
      '(you cannot dunk like that.)))

 (pushnew 'dunk *allowed-commands*)

As with our weld command, we first need a variable to keep track of whether the bucket has been filled yet . Next, we need a dunk function . Notice how, with dunking, we once again have a long list of conditions that need to be met before we can successfully complete the action . Some of these are similar to those we needed for our welding command. For instance, dunking also requires the player to be in a specific location with the correct object. Other conditions are dunking-specific, such as the fact that the player needs to have a welded chain before being able to dunk. Finally, we need to push the dunk function onto our list of allowed actions .

Now that we’ve created two custom game actions for our game, it’s obvious that the weld and dunk commands are very similar in some ways. However, as in our SVG library, each game command needs to contain a certain amount of dynamic logic in it, to customize the behavior of the command. Let’s write a game-action macro that addresses these issues. It will make it much easier to create new game commands.

 (defmacro game-action (command subj obj place &body body)
   `(progn (defun ,command (subject object)
             (if (and (eq *location* ',place)
                       (eq subject ',subj)
                       (eq object ',obj)
                      (have ',subj))
                 ,@body
             '(i cant ,command like that.)))
           (pushnew ',command *allowed-commands*)))

This game-action macro embodies the common pattern between our dunk and weld commands. The parameters to game-action are the name of the command, the two objects involved in the action, the place it needs to occur, and some arbitrary additional code in the body parameter that lets us add custom logic to the command .

The main job of the game-action macro is to define a new function for a command . It may be surprising to you that a macro can do something as powerful as define a new function on its own, but there is nothing to stop it from doing this. I hope this example shows you just how flexible and mind-bending the Common Lisp macro system can be.

Since all game actions for this game require the location, subject, and object, we can take care of some of the conditions directly within this macro . However, we’re going to leave other conditions open for each specific command. Notice, for example, that the subject of the game sentence needs to be owned by the player , but the object does not. This makes sense, since there are many actions that can be performed, such as “throw rock dragon,” where the object of the sentence (dragon) does not need to be in the player’s inventory.

Once the basic macro-level conditions have been met, we will defer the rest of the logic to the level of the individual command . If the conditions were not met, we print an error message, customized with the name of the current command . Finally, we pushnew the command into the list of allowed commands for our fancy game-repl .

One thing we do not do in this macro is define or set any global variables. If a game command needs to define a *chain-welded* or *bucket-filled* global variable, it must do this itself. This makes sense, since there is clearly no guarantee that there will be a one-to-one relationship between state variables for our game and particular commands. For instance, some commands may be permitted multiple times, making the state unnecessary. Or an action may depend on multiple state variables. Having this kind of variation in the commands is what makes them unique and fun.

With this macro, we now have a simple DSL for creating new game actions! Essentially, this command gives us our own programming language, specialized for the domain of creating game commands. Let’s rewrite our previous weld and dunk commands using our new game command programming language:

(defparameter *chain-welded* nil)

(game-action weld chain bucket attic
             (if (and (have 'bucket) (not *chain-welded*))
                 (progn (setf *chain-welded* 't)
                        '(the chain is now securely welded to the bucket.))
               '(you do not have a bucket.)))

(setf *bucket-filled* nil)

(game-action dunk bucket well garden
             (if *chain-welded*
                 (progn (setf *bucket-filled* 't)
                        '(the bucket is now full of water))
               '(the water level is too low to reach.)))

As you can see, these commands have become much easier on the eyes. Notice how weld checks for ownership of the bucket, whereas dunk does not need to check for ownership of the well.

To further illustrate the value of using macros to implement our game command DSL, let’s implement a more complicated game command, splash:

(game-action splash bucket wizard living-room
   (cond ((not *bucket-filled*) '(the bucket has nothing in it.))
         ((have 'frog) '(the wizard awakens and sees that you stole his frog.
                         he is so upset he banishes you to the
                         netherworlds- you lose! the end.))
         (t '(the wizard awakens from his slumber and greets you warmly.
              he hands you the magic low-carb donut- you win! the end.))))

For this command, there are three distinct scenarios that might happen:

With our game-action macro, we can support many action commands, each with special idiosyncratic behavior. Still, we are able to avoid unnecessary repetition.