Pre-release
Adventure.js Docs Downloads
Score: 0 Moves: 0

Class: Settings

Defined in: adventure/Settings.js, line 6

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 675

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  | 

can_auto_open_apertures :Boolean

Defined in: adventure/Settings.js, line 338

Default value: true

If true, goTo Verb will open closed Apertures that lie between the start Room and the destination Room, but only if player has already opened those Apertures before.
can_auto_unlock_apertures :Boolean

Defined in: adventure/Settings.js, line 349

Default value: true

If true, goTo Verb will unlock locked Apertures that lie between the start Room and the destination Room, but only if player has already unlocked those Apertures before and is carrying any necessary Keys.
can_auto_unseal_apertures :Boolean

Defined in: adventure/Settings.js, line 361

Default value: true

If true, goTo Verb will unseal sealed Apertures that lie between the start Room and the destination Room, but only if player has already unsealed those Apertures and is carrying any necessary Keys.
climb_height :Boolean

Defined in: adventure/Settings.js, line 633

Default value: 1

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

Defined in: adventure/Settings.js, line 515

Default value: true

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

Defined in: adventure/Settings.js, line 428

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_inferred_multiple_indirect_objects_then_prompt :Boolean

Defined in: adventure/Settings.js, line 574

Default value: true

If true, when try_to_infer_indirect_objects results in multiple assets, prompt player to select one.
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_indirect_objects_only_after_interaction :Boolean

Defined in: adventure/Settings.js, line 558

Default value: true

If true, try_to_infer_indirect_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.
jump_length :Boolean

Defined in: adventure/Settings.js, line 651

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 45

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 65

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 57

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 36

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 417

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.
on_tie_rope_to_max_objects_drop_rope :Boolean

Defined in: adventure/Settings.js, line 388

Default value: true

If true, when player ties a rope to its maximum number of tied points, will remove rope from player's inventory.

If the rope in that situation has a verb event hook for drop, it has the potential to cause undesirable side effects. It's an unlikely edge case, but if you find yourself in that situation, try setting this to false to avoid side effects.
on_tie_rope_to_takeable_object_take_object :Boolean

Defined in: adventure/Settings.js, line 372

Default value: true

If true, when player ties a Rope to another asset, Game will move the asset into player's inventory, using player.onMoveThatToThis().

If the asset in that situation is coded with a verb event hook, it has the potential to cause undesirable side effects. It's an unlikely edge case, but if you find yourself in that situation, try setting this to false to avoid side effects.
on_untie_rope_from_object_outside_inventory_take_rope :Boolean

Defined in: adventure/Settings.js, line 402

Default value: true

If true, and player unties a rope they are not holding, which is tied to an object that is not in the player's inventory, if the rope is takeable, player will take it.

If the rope in that situation has a verb event hook for drop, it has the potential to cause undesirable side effects. It's an unlikely edge case, but if you find yourself in that situation, try setting this to false to avoid side effects.
person :String

Defined in: adventure/Settings.js, line 474

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 507

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

Defined in: adventure/Settings.js, line 459

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/Settings.js, line 616

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/Settings.js, line 625

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 441

Default value: 20

Todos: celsius/farenheit conversion

Room temperature in celsius.
show_compass_rose_in_status :Boolean

Defined in: adventure/Settings.js, line 582

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 288

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 273

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 449

States lookup for substances.
stride_length :Boolean

Defined in: adventure/Settings.js, line 642

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.
throw_at_substance_prefers_bodies :Boolean

Defined in: adventure/Settings.js, line 524

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 throw_at_substance_prefers_bodies is true, the verb throw's logic will make that assumption, rather than prompting player to specify an indirect object.
try_to_infer_indirect_objects :Boolean

Defined in: adventure/Settings.js, line 541

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.
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 660

Default value: false

We can track the user's x/z position. This option sets whether x/z are considered in determining reachability. By default, all tangible assets are positioned at x:0,y:0,z:0, and reachability checks don't consider x/z (though y is always considered). 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.