Captain’s Log 9.14.2015 : Puzzle Design Docs

by Angel Leigh McCoy

The GO team has been working hard on puzzles for Chapter 01 of the Danika Dire series. Anyone who plays puzzle adventure games or hidden object adventure games knows that the puzzles are the cornerstone of the gameplay in them. We take our puzzles very seriously.

Alison McKenzie is our primary puzzle designer, and I assist from time to time. This past week has been one of those times as Alison has been off getting married to her true love. Meanwhile, I’ve been working to get design docs ready for our programmers. This is no small task and I’ve learned a few things about the elements required to make a good one.

I’d like to walk you through how I build a puzzle design doc, and I welcome your thoughts and suggestions for improvement!

Audience

Tip #1: Know your audience. Who will be reading the design doc and what information do they need? A design doc can have several audiences at Games Omniverse. Concept artists need one for concepting the puzzle art and programmers need one to code the puzzle. Both of these documents serve very different purposes, and if you try to combine them, you will end up confusing your audience or bogging them down with too much information. It’s better to write separate docs for each audience.

For the purpose of this log, I’ll discuss the doc for a programmer audience.

Organization

Because you’re creating a document to explain the vision in your head to another person, you have to put those thoughts down in a clear and concise manner. This means you have to have spent time thinking through the puzzle, getting to know it intimately, and coming to an understanding of the gameplay. You have to have made most of the design decisions before you even start to document it. I say “most” because you will discover while writing it up that some things you thought would work, actually won’t. The very act of writing it all down works like a sieve to weed out the broken bits.

The fewer words the better, but those words should be carefully chosen for maximum effectiveness.

Simple is golden! If it’s too complicated to describe on paper, it may be too complicated to be an enjoyable puzzle!

In order to be clear and concise, it helps to be organized about the layout of information. Build a foundation first. Give the more general information at the top, then delve deeper into the puzzle as you progress.

General Information

Note who designed the puzzle.

Designer: Angel

Note who the programmer is:

Programmer: Jason

Note the status of the art:

Art: Temp

In our game, location sometimes matters, so we have a field for the location of the puzzle.

Location: Ballroom

Sometimes, there is a story situation surrounding what happens in the puzzle.

Situation: A raven has gotten into the house and is making a mess.

Express what the puzzle needs to do in a goal statement. Keep these short and straightforward. This is not the place to describe the puzzle, but it gives the programmer a bird’s-eye-view of what will be happening in the puzzle. Two examples:

Goal: Shoo the raven out the window.

Goal: The player fixes a broken object by finding and dragging the pieces into place.

Add any other general directions such as scene size, software requirements, code restrictions, etc.

Scene Size: 1920×1080
Software: Unity 4.6.8, NGUI, Dialogue System
Note: Do not worry about inserting dialogue. We’ll add that later.

Start State

In this section of the design doc, I describe what the puzzle looks like and what it’s doing when it first loads. This gives the programmer a starting point and all puzzle behavior will branch off that.
As I’m writing it, I try to envision the puzzle and all its aspects. Here’s an example:

The background is the room. The pieces of the broken vase are scattered around the room (where set by the scripter). The player has a hand-broom and a dustpan in inventory (required for puzzle to launch).

Other elements you can mention here include audio fx or music, any special dialogue hints that play upon start, PC or NPC location, etc.

Gameplay

This is perhaps the most difficult to do well because you have to think through, step by step, how the game will be played. It’s important to choose your words carefully here. Vague words like “it” or “they” can confuse the reader, and it’s better to spell it out.

Most puzzle begin with the player manipulating something, so that’s the best place to start. What and how does the player initiate the action?

The gameplay may be very simple:

The player left-click-holds on a piece and drags it into place. If the player releases the piece in the wrong place, the piece returns to its original spot. If the player releases the piece in the correct place, the piece locks into its place and cannot be moved again.

The above establishes that the items are called “pieces” and I reuse that word whenever appropriate to avoid confusion.

If the actions can be separated into groups, all the better. This is especially useful in a more complex puzzle. For example:

BASIC PLAY: The player left-click-holds on a piece and drags it to the pile. If the player releases the piece in the wrong place, the piece returns to its original spot. If the player releases the piece in the correct place, the piece locks into its place and cannot be moved again.

BLOCKED PLAY: A block happens when rocks falls, burying a piece. If a piece is blocked, the player cannot interact with it until the blockage is cleared.

CLEARING BLOCKAGE:
1. In order to clear a blockage, the player must first combine the broom and the dustpan into one object by left-click-holding over one of the two, dragging it to the other, and releasing it. The objects then switch to a combined broom/dustpan image.
2. The player then clicks on the broom/dustpan to make it the cursor. With the broom/dustpan as the cursor, the player must click on the blockage.
3. If successful, play an animation of the broom sweeping dirt into the dustpan and clear the blockage. If successful, play dialogue and audio fx.

SOLVE: If the player solves the puzzle by finding and moving all the pieces to the pile correctly, then the pile images changes to the VASE image. Play success dialogue and audio fx.

RESET: If the player clicks the reset button, all pieces return to their original places and all of this puzzle’s progress variables are cleared. The puzzle is reset to its Start State.

SKIP: If the player clicks the skip button, the puzzle automatically is set to a SOLVED state as if the player successfully completed the puzzle. All progress variables are automatically set as they would be if the puzzle had been solved naturally.

Art

Never underestimate the power of a picture. It really is worth a thousand words. If you can mock up what the puzzle should look like, it will take you so much farther toward clear communication than would a block of text.
In addition, it will help the programmer a great deal if you make temp art for them in advance. The art should be all the pieces you would need to make the actual puzzle when it’s done. The images don’t have to be beautiful, they just have to be functional. Throughout this article, I’ve included mock-ups and pieces of temp art that we used for puzzles much like the one describe above.

In Conclusion

I love puzzles, and I’ve had a great time designing these. I love when I can exercise my left brain and really chew into a technical problem. Working on the Danika Dire project has afforded me the opportunity to take both my right and left brains out for long walks in the countryside. It’s been a wonderful experience.

Signed: Angel Leigh McCoy