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

Class:Settings

constructor description methods properties

Defined in: adventure/Settings.js, line 5

Framework class

Description

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

Index

Methods:

Properties:

Methods Collapse all  |  Expand all

getCommonWordMessage
getCommonWordMessage(word) → {string}

Defined in: adventure/Settings.js, line 1025

Parameters:

  • word string
    The unknown word.
Get if_word_is_common_print_this and substitute word if needed.

Returns:

string
getUnknownVerbMessage
getUnknownVerbMessage(word) → {string}

Defined in: adventure/Settings.js, line 995

Parameters:

  • word string
    The unknown verb.
Get if_verb_is_unknown_print_this and substitute word if needed.

Returns:

string
getUnknownWordMessage
getUnknownWordMessage(word) → {string}

Defined in: adventure/Settings.js, line 1010

Parameters:

  • word string
    The unknown word.
Get if_word_is_unknown_print_this and substitute word if needed.

Returns:

string
getUnparsedMessage
getUnparsedMessage()

Defined in: adventure/Settings.js, line 977

Take input and return a standardized "unparsed" message. settings.if_parser_has_no_response_print_this.
set
set(props) → {adventurejs.Settings}

Defined in: adventure/Settings.js, line 965

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  | 

ambient_temperature
ambient_temperature :Number

Defined in: adventure/Settings.js, line 489

Default value: 20

Todos: celsius/farenheit conversion

Ambient temperature in celsius.
apply_color_classes_to_written_strings
apply_color_classes_to_written_strings :Boolean

Defined in: adventure/Settings.js, line 954

Default value: true

If true, when player inputs "write 'foo' with red pen", the written text will be printed to the display with a CSS class that is the name of the color. For example: foo
auto_mount_vehicles
auto_mount_vehicles :Boolean

Defined in: adventure/Settings.js, line 692

Default value: false

If true, when player tries inputs something like "ride east on bike" while not nested on the bike, the game will attempt to nest the player automatically. Otherwise the game will return "you're not on the bike".
auto_open_containers
auto_open_containers :Boolean

Defined in: adventure/Settings.js, line 444

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

Defined in: adventure/Settings.js, line 454

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

Defined in: adventure/Settings.js, line 616

Default value: true

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

Defined in: adventure/Settings.js, line 658

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

Defined in: adventure/Settings.js, line 675

Default value: false

If true, when player tries to travel while kneeling or sitting or lying on the floor, player will stand up automatically.
auto_take_assets
auto_take_assets :Boolean

Defined in: adventure/Settings.js, line 425

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

Defined in: adventure/Settings.js, line 434

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

Defined in: adventure/Settings.js, line 667

Default value: false

If true, when player tries to travel while nested, player will auto-unnest unless prevented by circumstances.
concatenate_descriptions
concatenate_descriptions :Boolean

Defined in: adventure/Settings.js, line 763

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. ",
    },
  },
});
debug_keywords
debug_keywords :Object

Defined in: adventure/Settings.js, line 132

Display debugging: control what keywords print to the display. See the available list of keywords below. Set individual properties to true to print debug messages to the display.

verbaction, verbreaction, and verbphase each represent types of hooks that authors can use to inject custom code. Enabling these will show you what hooks fire during a turn.
disambiguation_considers_last_turn
disambiguation_considers_last_turn :Boolean

Defined in: adventure/Settings.js, line 812

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

Defined in: adventure/Settings.js, line 575

Default value: true

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

Defined in: adventure/Settings.js, line 879

Default value: false

If true, when player inputs "go to room", if there are any unlockable doors between player and destination, goTo will fail, leaving player at their origin room. If false, goTo will partially succeed, and only take player as far as the locked door.
goto_excludes_unvisited_locations
goto_excludes_unvisited_locations :Boolean

Defined in: adventure/Settings.js, line 890

Default value: true

If true, when player inputs "go to room", if the player hasn't visited the room, goTo will fail.
goto_prints_room_descriptions
goto_prints_room_descriptions :Boolean

Defined in: adventure/Settings.js, line 898

Default value: true

If true, when player inputs "go to room", the game will print the description of each room traveled through. If false, room descriptions will be omitted in favor of simple concatenated travel messages, ex: "You go east. You go north.". Note: If the rooms player travels through print messages on enter or exit, those messages may be inserted awkwardly.
handful
handful :Number

Defined in: adventure/Settings.js, line 476

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

Defined in: adventure/Settings.js, line 372

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

Defined in: adventure/Settings.js, line 277

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

Defined in: adventure/Settings.js, line 292

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 <em> element so that it can be styled differently from the rest of the output. This isn't required and you can omit the <em> 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.
if_room_is_dark_print_this
if_room_is_dark_print_this :Boolean

Defined in: adventure/Settings.js, line 360

If the current room is dark, print this instead of a room description.
if_verb_is_unknown_print_this
if_verb_is_unknown_print_this :Boolean

Defined in: adventure/Settings.js, line 347

If the player uses a word that is not known to the parser, print this error message back to the player. Include {word} to print the word back to the player.

if_verb_is_unknown_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.
if_word_is_common_print_this
if_word_is_common_print_this :Boolean

Defined in: adventure/Settings.js, line 320

If the player uses a word that is not known to the parser, but listed in game.dictionary.common_words, print this error message back to the player. Include {word} to print the word back to the player.

if_word_is_common_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.
if_word_is_unknown_print_this
if_word_is_unknown_print_this :Boolean

Defined in: adventure/Settings.js, line 334

If the player uses a word that is not known to the parser, print this error message back to the player. Include {word} to print the word back to the player.

if_word_is_unknown_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
infer_containers :Boolean

Defined in: adventure/Settings.js, line 584

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_prefers_reservoir
infer_containers_prefers_reservoir :Boolean

Defined in: adventure/Settings.js, line 599

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

Defined in: adventure/Settings.js, line 625

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

Defined in: adventure/Settings.js, line 833

Default value: true

If true, when an asset becomes known, it will be known by all player characters. Only useful when using player character switching.
log_keywords
log_keywords :Object

Defined in: adventure/Settings.js, line 67

Console logging: control what keywords log to console. Warnings and Errors will print regardless of settings. See the available list of keywords below. Set false to remove those from console output.

Set log_keywords.all to true to log all keywords.

this.log_keywords = {
  • all: false,
  • character: false,
  • copyoperations: false ,
  • debug: false,
  • dictionary: false,
  • display: false,
  • exit: false,
  • game: false,
  • parser: false,
  • print: false,
  • room: false,
  • saverestore: false,
  • substanceemitter: false,
  • substancemixer: false,
  • tangible: false,
  • travel: false,
  • tutorial: false,
  • utility: false,
  • verb: false,
  • verbaction: false,
  • verbreaction: false,
  • verbphase: false,
  • vessel: false,
  • warning: false,
};
log_level
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_trace_level
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_level_of_modified_descriptions_to_stack
max_level_of_modified_descriptions_to_stack :int

Defined in: adventure/Settings.js, line 910

Default value: 1

This is a subtle and complex setting. Description modifiers allow authors to provide alternate descriptions for assets when they are seen in certain conditions, such as when wearing x-ray specs, or under a black light, or from a particular location. It's even possible for authors to create complex modifiers that require two or more conditions, such as when wearing the x-ray specs AND under the black light. The logic that determines when to print these descriptions can stack them, or not, depending on this setting, which is to say, if it finds three separate descriptions whose conditions are all met, it may print them all, or only one.

For example, let's say that "through x-ray specs" and "with black light" are two separate modifiers. If max_level_of_modified_descriptions_to_stack is 0, only the first one found will be printed. If max_level_of_modified_descriptions_to_stack is 1, both descriptions will be printed.

On the other hand, let's say the author has set "through x-ray specs, with black light" as a third option. It's one combined modifier with two clauses, that is only satisfied if both conditions are tru. If max_level_of_modified_descriptions_to_stack is 0 or 1, only the combined description will be printed. If max_level_of_modified_descriptions_to_stack were set to 2 or higher, the description for "through x-ray specs, with black light" would print, as would any other double claused descriptions whose conditions were met.

See Description Modifiers and Advanced Descriptions for more info.
max_undos
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
mouthful :Number

Defined in: adventure/Settings.js, line 465

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).
name_for_dark_rooms
name_for_dark_rooms :Boolean

Defined in: adventure/Settings.js, line 366

If the current room is dark, print this instead of a room name.
obfuscate_saves
obfuscate_saves :Boolean

Defined in: adventure/Settings.js, line 871

Default value: false

If true, text of saved game files will be obfuscated to make them non human readable.
objects_must_be_used_before_inferring
objects_must_be_used_before_inferring :Boolean

Defined in: adventure/Settings.js, line 642

Default value: false

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

Defined in: adventure/Settings.js, line 684

Default value: false

If true, player will be prevented from traveling while kneeling or sitting or lying on the floor.
person
person :String

Defined in: adventure/Settings.js, line 522

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_inferred
print_inferred :Boolean

Defined in: adventure/Settings.js, line 825

Default value: true

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

Defined in: adventure/Settings.js, line 555

If print_room_contents is true, a list of room contents will be appended to room descriptions.
print_room_exits
print_room_exits :String

Defined in: adventure/Settings.js, line 548

If print_room_exits is true, a list of exits will be appended to room descriptions.
print_verbose_room_descriptions_on_first_visit
print_verbose_room_descriptions_on_first_visit :String

Defined in: adventure/Settings.js, line 568

If true, game will print brief descriptions of rooms on subsequent visits.
pronouns
pronouns :Object

Defined in: adventure/Settings.js, line 507

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

Defined in: adventure/Settings.js, line 851

Default value: false

This is an optional flag for authors who use random room / zone events. It's intended so that players can use verb "quiet" to suppress these random events. Whether that is respected is up to authors.
randomize_arrays_in_getStringOrArrayOrFunction
randomize_arrays_in_getStringOrArrayOrFunction :Boolean

Defined in: adventure/Settings.js, line 381

Default value: false

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

Defined in: adventure/Settings.js, line 403

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 the array loops back to the beginning when the last item is reached. If this setting is true, arrays will be reset.

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

Defined in: adventure/Settings.js, line 862

Default value: true

If an author uses room / zone events and/or character idle events, players may use verb "quiet" to suppress them, if respect_quiet is true.
seen_by_all_players
seen_by_all_players :Boolean

Defined in: adventure/Settings.js, line 842

Default value: true

If true, when an asset becomes seen, it will be seen by all player characters. Only useful when using player character switching.
show_compass_rose_in_status
show_compass_rose_in_status :Boolean

Defined in: adventure/Settings.js, line 702

Default value: true

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

Defined in: adventure/Settings.js, line 217

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

Defined in: adventure/Settings.js, line 175

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

Defined in: adventure/Settings.js, line 204

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

Defined in: adventure/Settings.js, line 189

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
states :Object

Defined in: adventure/Settings.js, line 497

States lookup for substances.
when_travel_fails_list_exits
when_travel_fails_list_exits :Boolean

Defined in: adventure/Settings.js, line 163

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

Defined in: adventure/Settings.js, line 736

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

Defined in: adventure/Settings.js, line 750

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.