Settings - ThePix/QuestJS GitHub Wiki

The settings.js file gives the author the opportunity to customise the game to his or her liking.

In fact, there are two files, one in "lib" where the defaults are set, and one in "game" for authors. You just need to include the values you want to change in your own settings.js file.

Settings are all attributes of the settings object, and you can add also your own custom attributes - but be aware that none of these attributes are saved when the user saves their game, so they should not be used to track game state (i.e., in general they should never change during play; the only exception might be user customisation of the interface).

The values in the code snippets below are the defaults, except where noted.

There is a more comprehensive list here, but with less explanation.

Meta-Data

The first section is a set of constants for meta-data.

settings.title = "A First Step..."
settings.author = "The Pixie"
settings.subtitle = "An example game for Quest 6"
settings.version = "1.0"
settings.thanks = ["Kyle", "Lara"];
settings.warnings = 'No warning relevant for this game.'

Basic info about your game. Note that the first two are required (there is no default), and these are the only setting you must have in "settings.js". The "thanks" setting is an empty array by default; it is shown here with two entries to show how it should be formatted.

The "warnings" setting is useful for users who might have issues with certain games (for example, a description of a lavish meal might upset someone with an eating disorder, and graphics depictions of violence or sex should definitely be mentioned). Users can choose to use the WARNING command to see this information. You may also want to include further warnings that show automatically when your game starts in more extreme cases. I appreciate this is somewhat subjective.

Game play settings

settings.failCountsAsTurn = false
settings.lookCountsAsTurn = false
settings.saveDisabled = false
settings.splitLinesOn = "<br>"
settings.convertNumbersInParser = true
settings.maxUndo = 10
settings.moneyFormat = "$!"

By default Quest 6 does not count it as a turn if the user types something that the parser cannot understand (which is different to when the parser understands but the character cannot do the action). Also by default, Quest 6 also does not consider LOOK to take a turn. The first two allow you to change that.

You also have the option to disable saving.

Quest 5 considers "<br>" in a string to be a line break. Quest 6 does not work quite the same so you can have it use whatever you want.

If you use COUNTABLEs, the user can type GET FIVE BRICKS. The parser convert the word "FIVE" to the digit "5" (and any number from 0 to 20), which the COUNTABLE system can then handle. If "convertNumbersInParser" is set to false, the user will have to type the digits, not the word for the number. However, you may not want that if you have items with numbers in their names (though there are ways around that using the items "regex" attribute). Commands will process faster if this is set to false (say around 20% faster, though on my system they take around 2 ms, so not noticeable anyway).

"maxUndo" is the maximum number of times the user can undo (i.e., by default Quest 6 remembers the last ten turns). Set to zero to disable.

"moneyFormat" is clearly the format for money. The default is "$!"; a string with a single exclamation mark simply has the value inserted at the exclamation mark. As it is better to work with integers, you might want to store the money as cents rather than dollars. You can then tell Quest to shift the decimal point to places, to display in dollars. To do that, we split the exclamation mark into two, and insert the format instructions in between. Here is a new example: "!3.2! credits". This will replace the two exclamation marks and text between them with the value, however, the the 3.2 says to pad it so there are at least three digits before the decimal point and exactly two after it. Any other characters will get added to the string too.

Displaying a negative value is a further issue - $-4.62 looks odd. One convention is to put negative values in brackets, which you can do like this: "!$1,2!($1,2)!". When there are three exclamation marks Quest uses what is between the first and second for positive numbers (and zero) and uses what is between the second and third for negative numbers. The formatting is the same, but I have put the dollar sign and brackets in there too.

There are also various settings connected to specific features, but these are discussed in the pages on about the relevant feature and better read in that context.

File settings

For all these settings, filenames should be given without the path or extension.

settings.lang = "lang-en"                        // Set to the language file of your choice
settings.customExits = false                     // Set to the filename to use otherwise
settings.libraries = ["saveload", "text", "io", "command", "defaults", "templates", "world", "npc", "parser", "commands"]
settings.customLibraries = []
settings.files = ["code", "data"]                // Additional files to load
settings.favicon = 'assets/icons/favicon.png'    // The icon that appears on the tab in the browser

"lang" allows you to set the language. "customExits" allows you to override the normal "north", "south", set it to the name of the file in your game folder.

"customLibraries" allows you to add custom libraries to your game. A library is a set of files (or just one) that might be used across multiple games, possibly shared with other authors. Each entry in the array should be a dictionary with a "folder" entry, a string, and a "files" entry, an array of filenames.

The "files" array is an array of files specific to your game. By convention, "code.js" has functions, commands and other stuff, while "data.js" has all the objects, but you may want to add other files (I like to have one for NPCs for example).

You can also change the default folders:

settings.imagesFolder = 'images/',
settings.iconsFolder = 'icons/',  // set to false to turn icons off, but then you MUST set settings.favicon
settings.soundsFolder = 'audio/',
settings.videosFolder = 'video/',
settings.soundsFileExt = '.mp3',

Note that folders have a slash at the end. This allows you to set them to an empty string, and then to have all the files in one big folder. This is generally bad practice, but may be necessary for some web sites when you upload.

The User Interface

See here.

Date and time

See here.

setup and intro

These are used when the game starts, if set. "setup" must be a function, and "intro" a string. Note that "intro" is printed first so the user has something to read while "setup" runs (in practice, it will be near instant, but that it the theory).

To see how to create a dialog box at start up for character creation, see here.

Development settings

Useful when writing your game.

Set "playMode" to "dev" or "beta" when developing or beta-testing your game - see here for why!

settings.reportAllSvg = true
settings.test = false

When "reportAllSvg" is true, the draw function will output the raw SVG to the console.

Set "test" to true to allow unit testing (see here).

Other Miscellaneous Options

You can use settings.afterLoad to have something happen after a game is saved or loaded. This can be useful if your custom UI needs updating.