Tutorial 1: First steps

So you want to create a simple game in QuestJS? Here is how if you want to write JavaScript code directly. There is an editor that is under development.

Programs

You need a text editor to create games. You can use Notepad on Windows, and Mac and Linux will have similar. If you are just starting out, you may prefer to stick with the basic software you already have, and that will work fine.

I personally like Notepad++. It will allow you to have several files open at once, and will colour the JavaScript code. It has a load of other features too, including a spell-checker plug-in, which you should also get. For Mac, you might want to try CODA, Textmate or Atom. On Linux try Notepadqq or SciTE. I am not familiar with any of them, so cannot offer any specific recommendation.

Another option is Microsoft Visual Studio, which is available for Windows, Mac and Linux. It is a much bigger download, but is a proper "Integrated Development Environment" that supports JavaScript, and offers features like code completion.

You also need software to unzip and zip files. On Windows I recommend 7Zip (it is free), but you can just use Windows Explorer. Mac and Linux also have free apps available, for instance iZip and FreeArc, but again I not familiar with any of them.

Setting Up

The first step to actually creating a game is getting the files. Go to the Code page, linked towards the top, far left of this page (or click here. You will see a longish list of files and folders, look for the QuestJS zip files. There are a few, one for each sub-release. They are all named something like QuestJS-0-2.zip. Find the one with the highest number - i.e., the most recent release. Click on the name to go to the web page for that file, and then click the download button (towards the right, about halfway down).

This is the base game in a ZIP file. I suggest you create a new folder; you can then unzip the files into that folder. You should find you now have a "index.html" file, and some folders.

The "game" folder is where you create your game, and already has some files. You should see "settings.js", which obviously has settings, "data.js", where we create the rooms and items in your world, and "code.js", where any supporting code can go.

You will see an assets folder, which itself contains other folders, where you can put images, sounds, etc. The CSS folder has data on how your game will be displayed, so will be important if you want to change the colours or fonts.

You should not ever need to touch the other two folders, "lang" and "lib".

The "index.html" file is the web page that runs your game - and again you probably never need to change it. However, this is the entry point to your game. If you double-click on it, you should see the base game, and already be able to do LOOK, WAIT and EXAMINE ME. It is worth doing that now to confirm everything is working so far.

The Player and a Room

Before we create anything, we will take a quick look at the default game, with just the player in a room.

Open up "data.js", and you should find the two objects there. It will look like this:

"use strict"

createItem("me", PLAYER(), {
  loc:"lounge",
  synonyms:['me', 'myself'],
  examine: "Just a regular guy.",
})

createRoom("lounge", {
  desc:"The lounge is boring, the author really needs to put stuff in it.",
})

The "use strict" bit at the top tells Javascript we will be using a stricter version of JavaScript. It is optional, but I advise having it as the first line in all your JavaScript files.

As you can see, we use the createItem function to create an item (anything that is not a room, so that includes the player), and createRoom to create a location. In fact, behind the scenes these are both objects in the same list, just as in Quest 5, but createItem and createRoom give them some useful defaults.

There is a lot of punctuation in JavaScript and we need to get it right. We will go through it, building it up to see why it is there. The createItem function has a parameter list that starts and ends with parentheses.

  createItem()

The createItem function (and the createRoom function) can take any number of parameters, but expects the first to be the name of the object, and all the rest to be dictionaries. In this case we add a built-in dictionary using "PLAYER()" (which is a function that returns a dictionary, so has its own empty parameter list in brackets) and then our own dictionary, which starts and ends with curly braces.

It is worth pointing out at this point that strings in JavaScript can use either single or double quotes, but you need the same at each end! This means you can use single quotes in a string delineated by double quotes, and vice versa. You can also use backticks to delimit strings; they work slightly differently, but you will probably not notice.

You might also be wondering what a dictionary is. A dictionary is a collection of values, where each value is accessed through a key. If you think about a real-world dictionary, the values are all the definitions. The words are the keys. To find a value, the definition of a word, you use the key, i.e., look up the word. So in computing a dictionary is a whole bunch of key-value pairs. And really, that is all an object is in both Quest 5 and Quest 6 - and indeed any interactive fiction system, I would guess.

  createItem("me", PLAYER(), {});

The createItem function adds a set of default values to our object. The PLAYER template then adds a whole bunch more. Now we can add our own custom values to the object.

The name part of a name-value pair should be a string, composed of letters, digits and underscores - and as it has to be a string, it does not need quote marks here. The value, however, can be anything! In this case we have three name-value pairs, arranged one on each line, with the names; "loc", "synonyms" and "examine".

createItem("me", PLAYER(), {
  loc:"lounge",
  synonyms:['me', 'myself'],
  examine: "Just a regular guy.",
})

Note that you need a comma between each name-value pair. If each pair is on a line on its own, I also add one after the last pair, though it is not required - it is annoying when you add another line and realise you have forgotten it, so is a good habit to get into.

The "loc" attribute determines where the object is (the location). It should be a string, so needs to go inside quotes.

The "synonyms" attribute is a list of alternative names - the square brackets indicate this is a list or array. For most objects this is not required, but the user might refer to the player as "me" or "myself", so we need it here.

The "examine" attribute is what the user sees when she examines the object. In this case it is a string, but it can be a function (i.e., script), which we will look at later.

Trouble-shooting

We better look quickly at what to do if it does not work. You need to open the developer tools in your browser. Try pressing F12. If that fails, in Chrome it is under "More tool", in Firefox it is under "Web tools" and MS Edge just has Developer Tools in the tools menu. You can use [CTRL]-[SHFT]-I as a short cut or [CTRL]-[SHFT]-J or [CTRL]-[SHFT]-K in Firefox. On a Mac, I guess that would be [Command]-[SHFT]-I.

Hopefully you now have a split window, with the game in one part and the developer tools in the other. You can usually control how they are arranged; I prefer to have the developer tools on the right, and will be describing it on that assumption.

So in the developer tools sections, make sure you have "Console" selected at the top (you may need to pull the divider to the left to see the list of tabs across the top). Any errors will show up here. Hopefully none so far, but when one or more appear look at the top one and it will give you a file name and a line number. This tells you exactly where the error is (a big advantage over Quest 5!). I recommend keeping this open whenever you look at your game, so you can quickly see if there are errors.

Note that one small error can generate lots of messages. Only the first one is important - try to fix that, then reload your game. You may need to scroll to the top to find it.

Settings

Let's take a quick look at the "settings.js" file.

"use strict"

settings.title = "Your new game"
settings.author = "Your name here"
settings.version = "0.1"
settings.thanks = []
settings.warnings = "No warnings have been set for this game."
settings.playMode = "dev"

Change the title to whatever you want, and set the author to you. Just be careful the quotes are preserved.

settings.playMode is set to "dev" (short for "development"). When you release your game you should set this to "play". Some debugging features will be disabled, and if the user tries to navigate to another page, a warning will appear asking if she is sure (details here).

You should check your game frequently. Reload the page in your browser, and see if the title has been changed.

Now you have made the game yours, continue to Rooms and exits...