Pre-release
AdventureJS Docs Downloads
Score: 0 Moves: 0

Class:Settings

Defined in: adventure/Settings.js, line 5

Framework class

Settings is a repository for global Game options. Settings is created automatically by Game. This is an internal class that authors should not need to construct. However, authors can set options from their game file as shown below, or change them during runtime with calls to MyGame.settings.set().

Example:

var MyGame = new adventurejs.Game( "MyGame", "GameDisplay" );
MyGame.settings.set({
  max_undos: 20,
  show_room_names_in_exit_descriptions: false,
  can_auto_open_apertures: false
});

Private Constructor:

var foo = new adventurejs.Settings(game)

Parameters:

  • game Game
    A reference to the game instance.
Inherited Overrides

Methods Collapse all  |  Expand all

set(props) → {adventurejs.Settings}

Defined in: adventure/Settings.js, line 743

Parameters:

  • props Object
    A generic object containing properties to copy to the instance.
Provides a chainable shortcut method for setting a number of properties on the instance.

Returns:

adventurejs.Settings Returns the instance the method is called on (useful for chaining calls.)

Properties  | 

concatenate_descriptions :Boolean

Defined in: adventure/Settings.js, line 672

Default value: false

When a user inputs look or examine, the game looks for a base description for the specified asset, and also looks for any modified descriptions, such as looking with a special light or through a lens or from a particular location. If a modified description is found, depending on how you write descriptions, you may want the modified description appended to the base description, or you may want the modified description to completely replace the base description. This is purely a matter of stylistic preference. See the examples below to learn more about the distinction.

Example:

Consider this chalice: it has a base description for "look" and a modified description for "look with occult candle", and it makes sense that we might want to print both. 
var MyGame = new adventurejs.Game( "MyGame", "GameDisplay" );
MyGame.createAsset({
  class: "Chalice",
  name: "chalice",
  place: { in: "Treasure Room" },
  descriptions: {
    look: {
      default: "The chalice is baked from rough clay. ",
      "with occult candle":
        "The light of the candle reveals glowing runes inscribed in the clay. ",
    },
  },
});
Now consider this sword. It's set up the same way, but it's written such that we want the modified description to replace the base description entirely. 
var MyGame = new adventurejs.Game( "MyGame", "GameDisplay" );
MyGame.createAsset({
  class: "Chalice",
  name: "chalice",
  place: { in: "Treasure Room" },
  descriptions: {
    look: {
      default: "It's an unremarkable steel sword. ",
      "with occult candle":
        "Seen beneath the light of the occult candle, the sword dances with eldritch flames. ",
    },
  },
});
disambiguation_considers_last_turn :Boolean

Defined in: adventure/Settings.js, line 721

Default value: true

Determine whether to consider the last turn when disambiguation is required. For example, consider a room with a gold key, a silver key, and a brass key, where player inputs "take gold key", and then on the next turn inputs "unlock door with key". By default, the parser will find all three keys and prompt for disambiguation, ie "which key did you mean". But we can guess that the player probably meant the key that they just picked up.
enable_events :Boolean

Defined in: adventure/Settings.js, line 476

Default value: true

If true, room/zone events will print. See Scene Events for more information.
handful :Number

Defined in: adventure/Settings.js, line 389

Default value: 100

Standard value for holding in hands, in ml. Generally if player tries to interact with substances without a container they're given some kind of "slips through your fingers" message but in the case of something like "throw sand" when player is on a beach, we'll let them throw a handful of sand, and if the containing object is not infinite, subtract this amount from it.
if_input_is_an_asset_name_examine_it :Boolean

Defined in: adventure/Settings.js, line 255

Default value: true

If true, when player enters just a noun, treat it as if player typed "examine x". Otherwise play dumb.
if_input_is_empty_print_room_description :Boolean

Defined in: adventure/Settings.js, line 210

Default value: false

If true, when player enters a blank line, treat it as if player typed "look". Otherwise play dumb.
if_parser_has_no_response_print_this :Boolean

Defined in: adventure/Settings.js, line 226

Default value: true

When the parser can't understand a player's input, it prints a generic statement using this string. The statement is also used in some other arbitrary places, which is to say, players may see it a lot. If you would like to customize this output you can do so by setting this property to your preferred output and including $(input) as a token to be replaced with the player's input. For example: 
MyGame.settings.set({
  if_parser_has_no_response_print_this: "I didn't understand $(input). ",
});
This example wraps the player's input in an element so that it can be styled differently from the rest of the output. This isn't required and you can omit the if you prefer. And in fact you don't even need to include the original input if you prefer not to. Just omit $(input) from your string and the string will be printed as you set it.

if_parser_has_no_response_print_this supports the use of getStringOrArrayOrFunction meaning that you can vary it up if you like by setting it to a rotating array of strings or a contextually aware function.
infer_containers :Boolean

Defined in: adventure/Settings.js, line 528

Default value: true

If true, some verbs, on receiving input of sentence structure "verb substance" may infer a substance container if one is required and player is carrying it. This pattern is intended to help with situations where the player may input something like "drink water" without specifying a container. If the player is carrying a glass of water, the game can infer it instead of prompting the player for an object, which may seem obnoxious in some circumstances.
infer_containers_automatically_picks :Boolean

Defined in: adventure/Settings.js, line 560

Default value: true

If true, when infer_containers results in multiple assets, automatically pick one. Otherwise prompt player to select one.
infer_containers_prefers_reservoir :Boolean

Defined in: adventure/Settings.js, line 543

Default value: true

If player inputs something like "throw rock at water", the word "water" may be ambiguous because multiple water containers are present: a glass of water, a bottle of water, a lake. If any of those containers is a body of water like a lake or ocean, we can probably assume that the player meant "throw rock in lake". If infer_containers_prefers_reservoir is true, the verb throw's logic will make that assumption, rather than prompting player to specify an indirect object.
infer_objects :Boolean

Defined in: adventure/Settings.js, line 569

Default value: true

If true, some verbs, on receiving input of sentence structure "verb noun" may infer an indirect object if one is required and player is carrying it. This pattern is intended chiefly for locks and keys, with the idea being that if player inputs "unlock door" while carrying a door key, the game can infer the door key instead of prompting the player for a key, which may seem obnoxious in some circumstances. It works with lock / unlock, seal / unseal, open / close, and some others.
infer_objects_after_first_use :Boolean

Defined in: adventure/Settings.js, line 586

Default value: true

If true, infer_objects will only be applied once a player has already interacted with the direct object. This pattern is intended to prevent giving away puzzle solutions. For example, perhaps there are many keys but only one that opens a certain lock, and determining which key opens the lock is part of a puzzle. If this is set to true, it would prevent players from being able to unlock the door without trying all the keys to find the correct one.
infer_objects_automatically_picks :Boolean

Defined in: adventure/Settings.js, line 602

Default value: true

If true, when infer_objects results in multiple assets, the first found asset will be used Otherwise prompt player to select one.
jump_height :Boolean

Defined in: adventure/assets/tangibles/Character.js, line 99

Default value: 1

We can track the user's y position. This option sets the maximum distance that the player can travel vertically. 1 is considered to be about the height of a person.
jump_length :Boolean

Defined in: adventure/assets/tangibles/Character.js, line 108

Default value: 1

We can track the user's x/z position. This option sets the maximum distance that the player travels horizontally when moving within a room. 1 is considered to be about the height of a person.
log_level :Number

Defined in: adventure/Settings.js, line 44

Default value: 1

Console logging: control the types of statements that print to console. Useful for debugging. 0 = critical ( warnings & errors only ) 1 = high 2 = medium 3 = low
log_level :Number

Defined in: adventure/Settings.js, line 64

Default value: 1

Console logging: control what keywords print to console. Warnings and Errors will print regardless of settings. See the available list of keywords below. Comment any to remove those from console output.
log_trace_level :Number

Defined in: adventure/Settings.js, line 56

Default value: 0

Trace log statements: control which log levels call console.trace() Useful for debugging.
max_undos :Number

Defined in: adventure/Settings.js, line 35

Default value: 10

Each level of undo stores a snapshot of the entire game state in memory. Raising a game's undo count will increase its memory requirements.
mouthful :Number

Defined in: adventure/Settings.js, line 378

Default value: 100

Standard value for drinking, in ml. If player drinks from a Vessel, this is the quantity of liquid that will be removed from it (unless the Vessel has custom drink logic).
move_verb_hooks_to_end_of_queue :Boolean

Defined in: adventure/Settings.js, line 286

Default value: true

When players apply a verb to a group of objects, such as "take all", if any of those objects have a verb hook, that may create awkward output. For example, let's say there are four medallions and one is cursed, using verb_hooks.take, and the player inputs "take all medallions": 
"You take the gold medallion. You take the brass medallion.
Oh no, taking the onyx medallion transported you to the
nether realms! You take the silver medallion."
This option tries to provide a little bit of control over that by saying: if player picks up these four objects, take the cursed one last. It doesn't solve all problems. For instance, if two of our medallions each took the player to a different location, that might break something. Some situations can't be solved programmatically and just come down to good game design.

Alternately, you may want to handle assets with verb_hooks first. Let's say you have an explosive item, and if player inputs "take all" you want the explosive to be picked up first and then end the turn in order to prevent other items from handled in the same turn.

For more information on verb_hooks, see Verb Phases

Valid values are: -1 (move to beginning of queue), 0 (leave in place), 1 (move to end of queue). Warning: may cause undesired side effects.
move_verb_hooks_to_start_of_queue :Boolean

Defined in: adventure/Settings.js, line 324

Default value: false

See the explanation for move_verb_hooks_to_end_of_queue above. This reverses that. When using a verb on multiple items, you can choose to move items with custom functions to the beginning of the queue. If this option is set true, it will override move_verb_hooks_to_end_of_queue. Included for completionism. Warning: this may cause undesired side effects.
open_containers_automatically :Boolean

Defined in: adventure/Settings.js, line 357

Default value: true

If true, if player tries to interact with an asset that is inside another, closed asset, the closed asset will be automatically opened if player is carrying any necessary Keys.
open_containers_automatically_after_first_use :Boolean

Defined in: adventure/Settings.js, line 367

Default value: true

If true, if player tries to interact with an asset that is inside another, closed asset, the closed asset will be automatically opened, but only if player has already opened or closed that asset before, and if player is carrying any necessary Keys.
person :String

Defined in: adventure/Settings.js, line 435

The person setting allows you to change the pronouns in all of the default response strings built-in to AdventureJS. For instance, if take has a response that says You pick up the axe. you can change the word You to I in this and all other responses by setting person from seconds to first.
print_debug_messages :String

Defined in: adventure/Settings.js, line 468

If print_debug_messages is true, some failure responses may print additional information to the game display. Intended as a debugging aid.
print_inferred :Boolean

Defined in: adventure/Settings.js, line 734

Default value: true

If true, the game will print inferences such as "take candy (from baby)".
pronouns :Object

Defined in: adventure/Settings.js, line 420

The pronouns setting is a lookup table for use with person.
randomize_arrays_in_getStringOrArrayOrFunction :Boolean

Defined in: adventure/Settings.js, line 264

Default value: true

Todos: List properties that this applies to.

We're all about strings here. Your job as an author is to write lots and lots and lots of them. Sometimes it gets boring seeing the same string over and over again, and you just want to show some alternates. Some properties let you do that through the use of getStringOrArrayOrFunction. You can feed getStringOrArrayOrFunction a string or an array or a function (that returns a string). If you provide an array, this setting determines whether strings in the array are presented in sequence, or randomly. If this setting is true, arrays will be randomized.

For more information, see How to Use String|Array|Function
reach_height :Boolean

Defined in: adventure/assets/tangibles/Character.js, line 73

Default value: 1

We can track the user's y position. This option sets the maximum distance that the player can reach vertically, ie when climbing an object like a tree. 1 is considered to be about the height of a person.
reach_length :Boolean

Defined in: adventure/assets/tangibles/Character.js, line 82

Default value: .33

We can track the user's x/z position. This option sets the maximum distance that the player can reach horizontally within a room. 0.33 is considered to be about arm's length.
room_temperature :Number

Defined in: adventure/Settings.js, line 402

Default value: 20

Todos: celsius/farenheit conversion

Room temperature in celsius.
show_compass_rose_in_status :Boolean

Defined in: adventure/Settings.js, line 611

Default value: true

Set the visibility of the compass rose in the status bar.
show_disambiguation_as_ordered_list :Boolean

Defined in: adventure/Settings.js, line 150

Default value: false

If true, disambiguation prompts will present an ordered list rather than plain text.

'Disambiguation' means the player has asked for an object that could refer to multiple things, and the Parser hasn't been able to narrow it down to one object. Let's say there are three cats of different colors in the room. Normally the game would ask the player: 
which cat did you mean, the orange cat, the black cat, or the piebald cat?
If this is true, prompts will look like this instead: 
Which cat did you mean?
1) the orange cat
2) the black cat
3) the piebald cat
When this is done, the player can enter 1, 2, or 3 and the parser will understand their choice.

For more information about Disambiguation, see How to Disambiguate
show_room_names_in_exit_descriptions :Boolean

Defined in: adventure/Settings.js, line 108

Default value: true

If set true, Exit descriptions can include the name of the Room that the Exit leads to. (The logic for this may also consider other conditions such as whether the player knows about the other Room.) Though this is a global setting, Exits can have their own setting. Exit setting overrides global setting.
show_room_names_in_exit_descriptions_only_after_exit_has_been_used :Boolean

Defined in: adventure/assets/tangibles/Room.js, line 300

Default value: null

If set true, Exit descriptions can include the name of the Room that the Exit leads to once player has used the Exit.

Setting this to true or false per room will override global Settings for that room.
show_room_names_in_exit_descriptions_only_after_exit_has_been_used :Boolean

Defined in: adventure/Settings.js, line 137

Default value: true

If set true, Exit descriptions can include the name of the Room that the Exit leads to once player has used the Exit. Though this is a global setting, Exits can have their own setting. Exit setting overrides global setting.
show_room_names_in_exit_descriptions_only_when_room_is_known :Boolean

Defined in: adventure/assets/tangibles/Room.js, line 285

Default value: null

If set true, Exit descriptions can include the name of the Room that the Exit leads to once player knows about the destination Room. Generally player must visit a room to know about it, but there can be exceptions.

Setting this to true or false per room will override global Settings for that room.
show_room_names_in_exit_descriptions_only_when_room_is_known :Boolean

Defined in: adventure/Settings.js, line 122

Default value: false

If set true, Exit descriptions can include the name of the Room that the Exit leads to once player knows about the destination Room. Generally player must visit a room to know about it, but there can be exceptions. Though this is a global setting, Exits can have their own setting. Exit setting overrides global setting.
states :Object

Defined in: adventure/Settings.js, line 410

States lookup for substances.
stride_length :Boolean

Defined in: adventure/assets/tangibles/Character.js, line 90

Default value: .33

We can track the user's x/z position. This option sets the default distance that the player travels horizontally when moving within a room. 1 is considered to be about the height of a person.
take_assets_automatically :Boolean

Defined in: adventure/Settings.js, line 338

Default value: true

If true, if player tries to interact with an asset that is not carried but which needs to be carried, player will automatically pick up the asset.
take_assets_automatically_after_first_use :Boolean

Defined in: adventure/Settings.js, line 347

Default value: true

If true, if player tries to interact with an asset that is not carried but which needs to be carried, player will automatically pick up the asset, but only if they have previously interacted with the asset.
when_travel_fails_list_exits :Boolean

Defined in: adventure/Settings.js, line 96

Default value: true

If set true, when player tries to go in a direction that hasn't got an Exit, print the current room's Exits as a reminder of what Exits are available. Though this is a global setting, Rooms can have their own setting. Room setting overrides global setting.
xz_determines_reachability :Boolean

Defined in: adventure/Settings.js, line 645

Default value: false

We can track the user's x/y/z position. This option sets whether x/z are considered in determining reachability. All tangible assets are created at a default position of x:0,y:0,z:0. At this position, reachability checks will always return true. Now imagine you have a dorm room with a bed and a desk, where the bed is at x:3 and the desk is across the room at x:-3. If this property is true, then their relative distance apart will be taken into account when determining reachability.
xz_determines_reachability :Boolean

Defined in: adventure/Settings.js, line 659

Default value: false

Todos: implement this

We can track the user's x/y/z position. This option sets whether y is considered in determining reachability. By default, all tangible assets are positioned at x:0,y:0,z:0. Now imagine you have a roof that is 2 high. If this property is true, the height of the roof will be taken into account when determining reachability of objects on the roof.