Settings

Much of the behaviour of Strange Eons, including the way components are laid out, is controlled by settings. Settings are simply (key, value) pairings of text strings, although there are certain conventions that allow other kinds of data to be represented as well. For example, boolean (true/false) values can be represented using the strings "yes" (for true), or "no" for false. The following setting:

currency-symbol-before-amount 

controls whether the dollar sign should be printed before (English) or after (other languages) the dollar amount. Strange Eons provides the class resources.Settings to represent a collection of settings.

Scope of Settings

There is a standard, shared, collection of settings that can be obtained with Settings.getShared(). In addition, every game component has its own private Settings object. Keys that are defined in a component's private settings will override those in the shared settings, but only for that component. This is used to create custom versions of existing components by, for example, setting a private version of the setting that points to the image file used for the front of the card so that it points to a different image. (Note that a few settings are only read once while setting up for drawing, rather than every time the card is drawn, so these will only change if the card is saved and opened again. And for technical reasons a few settings are always looked up in shared settings rather than private settings. Therefore they can only be modified globally, not for individual cards.)

Settings are arranged in a tree structure, as a number of scopes. When you ask for the value of a setting, it is first looked for at the scope of the particular settings object you are asking. If it has been defined there, then it is returned. Otherwise, the next higher scope will be checked until eventually the top-level scope is reached. If it is not present at that scope, then the key is undefined. The following diagram illustrates the typical scopes for a setting key in a component:

If desired, you can create a new scope within an existing private settings scope by creating a new Settings object using the constructor that takes the parent scope as a parameter. This adds a new layer to the above diagram, with your new settings scope pointing to the existing parent private settings scope.

User Settings

In addition to obtaining a copy of the shared settings, it is possible to obtain the user setting scope with Settings.getUser(). When reading settings, the user scope is essentially the same as the shared scope (as can be seen from the diagram, user settings are the outermost scope of shared settings). However, the difference is that setting values can be written to the user settings scope, and these changes will persist between runs of the application. The shared settings scope does not allow you to change settings.

Settings and Script Code

A component's private settings can be accessed using its settings field, e.g.: Component.settings.set( "stamina-text-region", "0,0,100,100" );. In addition, the common library that is available from every script automatically defines a Patch object that provides functions capable of modifying settings in various ways.

The $-notation

Starting in SE 2.00.5, it is possible to access settings using special variable names that start with $ followed by the setting key. Many settings keys use hyphens, which are not legal in JavaScript variable names, so the special variable names use an underscore (_) instead. For example, the line:

$currency_symbol_before_amount = "no";

will force the $ to appear after the dollar amount in an investigator's fixed possessions, even if it would normally appear before it due to the game language. For most scripts, this syntax accesses shared settings, but within DIY scripts it will access the DIY component's private settings instead. You can change the scope that is accessed by this syntax within a script with the usesettings( source ) function (this is also part of the common library). For example, to use a particular component's private settings with the $-notation:

// This will use shared settings (except in a DIY script):
$key = "value";

// This will use the private settings of component:
usesettings( component );
$key = "private value";

// This will revert to shared settings (as would passing null):
usesettings();
$key = "another value";

To avoid confusion, it is best to call usesettings at most once during script, at the top of the file.

Starting in SE 2.00.8, helper classes have been added to Settings to make it easier to use the $-notation consistently. These classes are assigned to global variables in the common library, and they feature constructors that are able to convert settings values directly into appropriate objects. In addition, their toString() methods are defined such that assigning them to a setting variable will write an appropriate setting value. For example:

// Read a region setting, shift its location 16 units down and to the right,
// and then store the modified region back in settings.
var r = new Region( $item_front_expsym_region );
r.x += 16;
r.y += 16;
$item_front_expsym_region = r;

Glossary