Class: PersistentObject

.Persistence~ PersistentObject

The PersistentObject is the class from which all of the more complex persistent data types are derived. People, Apparel, Transformable attributes, Inventories of various sorts, and many other classes of objects, are all are ultimately derived from PersistentObject.

Deriving types and classes in this way allows us to present a more straightforward API to the end-user of the library, saving them the headache of dealing directly with the Persistence API. The PersistentObject constructor returns a Proxy Object that traps all external field accesses and redirects them through the Persistence API. This allows the end-user of the library to (mostly) treat PersistentObjects the same as plain JavaScript objects, extending them with arbitrary fields, etc.

(Note however: Due to apparent limitations of Proxy Objects, if you subclass one of the built-in persistent classes, the proxy field accesses don't work from methods defined in the subclass itself. In this case, you must use the low-level persistence API instead. But it isn't difficult, and is detailed below.


new PersistentObject(id)

You should never instantiate a PersistentObject directly! Instead, you must define it with PersistentObject.define(), and then instantiate it with the obj() function when you want to use it. You must also never store PersistentObjects in Sugarcube variables! Just store their ids, instantiate them with obj() as needed, and then let them be garbage-collected.

Parameters:
Name Type Description
id string

The id of the Persistence defaults entry to be associated with this instance.

Source:

Members


<readonly> id :string

The Persistence id of the object.

Most of the time you'll only be interacting with the Persistence id when you define your object at initialization time in PersistentObject.define(), and when you fetch it with obj(). This field is generally only used internally by derived classes. You probably won't need to use this field unless you are actually extending the library itself.

Type:
  • string
Source:

<readonly> parent :LibEcho.Persistence.PersistentObject

The fully instantiated parent of this object, or undefined if it is a toplevel object (has no parent).

This field is generally only used internally by derived classes. You probably won't need to use this field unless you are actually extending the library itself.

Type:
Source:

name :string

The display name of the object, without any article. For example: "Joe", "ancient relic", "pair of gloves". Will be undefined if the object has no name.

Type:
  • string
Source:
Example
var someDude = obj("joe");
alert( "someDude's name is " + someDude.name + "." );

<readonly> aName :string

The display name of the object, with the correct article prepended. For example: "Joe", "an ancient relic", "a pair of gloves". Will be undefined if the object has no name.

If the first character of the .name field is capitalized, the name will be treated as proper, and no article will be prepended. Ie. "Joe". Otherwise, if the first character of the .name field is a vowel, the "an" article will be prepended. Ie. "an ancient relic". Otherwise, the "a" article will be prepended. Ie. "a pair of gloves".

These rules do not always work. For example, "an honorable man" or "a European swallow". In these cases, the .nameIsProper and .nameIrregularArticle fields may be used to manually specify the behavior of this field.

Type:
  • string
Source:
Example
alert( "You are carrying " + obj("some_item").aName + "." );

<readonly> AName :string

Identical to .aName, but with the first character capitalized.

Type:
  • string
Source:

<readonly> aGenericName :string

Same as .aName, but operates on the genericName instead.

Type:
  • string
Source:

<readonly> AGenericName :string

Same as .AName, but operates on the genericName instead.

Type:
  • string
Source:

<readonly> theName :string

The display name of the object, with the "the" prepended unless the object is proper. For example: "Joe", "the ancient relic", "the pair of gloves". Will be undefined if the object has no name.

These rules do not always work. For example, "the European swallow". In this case, the .nameIsProper field may be used to manually specify the behavior of this field.

Type:
  • string
Source:
Example
alert( "You place " + obj("some_item").theName + " in the large box." );

<readonly> TheName :string

Identical to .theName, but with the first character capitalized.

Type:
  • string
Source:

<readonly> theGenericName :string

Same as .theName, but operates on the genericName instead.

Type:
  • string
Source:

<readonly> TheGenericName :string

Same as .TheName, but operates on the genericName instead.

Type:
  • string
Source:

nameIsProper :boolean

Set this field to True to suppress the printing of an article in the .aName and .theName fields. Useful for proper names, book titles, etc.

You'll generally want to set this field with Persistence.define(), and then never touch it again. The only time you may need to change this field at runtime is if you change something's name to something that doesn't work with the usual rules.

Type:
  • boolean
Source:
Example
var book = obj("atlas_shrugged");
// book.name is "\"Atlas Shrugged\" (a novel by Ayn Rand)"
// With the " being the first character, it won't be recognized as proper.
// So .aName will return: a "Atlas Shrugged" (a novel by Ayn Rand).
book.nameIsProper = true;
// Now .aName will properly return just: "Atlas Shrugged" (a novel by Ayn Rand).

nameIrregularArticle :string

Set this field to override the default article choice in .aName. Setting it back to null will return things back to normal.

You'll generally want to set this field with Persistence.define(), and then never touch it again. The only time you may need to change this field at runtime is if you change something's name to something that doesn't work with the usual rules.

Type:
  • string
Source:
Example
obj("honorable_man").nameIrregularArticle = "an";
obj("european_swallow").nameIrregularArticle = "a";

genericNameIsProper :boolean

Same as .nameIsProper, but operates on the genericName instead.

Type:
  • boolean
Source:

genericNameIrregularArticle :string

Same as .nameIrregularArticle, but operates on the genericName instead.

Type:
  • string
Source:

thumbnail :string

A thumbnail image name for the object (used in inventory displays). If a thumbnail image is not defined, it returns the value of .image instead.

FIXME Make this work with external images instead of just image passages.

Type:
  • string
Source:
Example
FIXME Add an example.

image :string

A detail image name for the object (used in object details displays).

FIXME Make this work with external images instead of just image passages.

Type:
  • string
Source:
Example
FIXME Add an example.

inventoryCategory :string

The inventory category of this object. Used for inventory sorting. Case-sensitive. If falsy, then category is assumed to be "Other".

Type:
  • string
Source:
Example
FIXME Add an example.

Methods


<static> define(id, objectClass, defaults)

Defines the default data for a PersistentObject (or subclass thereof) within your game. Persistence.define() must only be called at initialization time, from story javascript or initialization passages. The results of trying to use this function after the game has started are undefined.

All PersistentObjects (and subclassed objects thereof) must be defined using this method before they can be used within the game.

Parameters:
Name Type Description
id string

a toplevel Persistence id which will be used to fetch the object later. All toplevel ids must be unique.

objectClass class

an ES6 class, ultimately derived from PersistentObject, which defines "what" the object is (ie. Person, Apparel, etc etc).

defaults object

a JS object that defines the PersistentObject's default values. Available defaults are documented in the sections pertaining to the built-in persistent object classes.

Source:
Throws:

Error if id contains invalid characters, objectClass is not ultimately derived from PersistentObject, or defaults isn't a valid Javascript object.

Returns:

Nothing.

Example
LibEcho.Persistence.define( "joe", LibEcho.Person.Man, {
	"name" : "Joe",
	"lastName" : "Blow",
	"inventory" : {
		"contents" : [
			"revolver",
		]
	},
	"apparel" : {
		"contents" : [
			"boxers", 
			"jeans", 
			"tshirt", 
			"socks",
			"tennisshoes",
		]
	}
} );

<static> fetch(id, forceClass)

Instantiates a working copy of an object (whose class was ultimately derived from PersistentObject), so that its data may be accessed and manipulated.

DO NOT store these objects themselves in the story format's Persistence engine!!! Doing so will needlessly clog up your available savegame space. Simply instantiate an object using this method when you need to use it, and then just let the garbage collector free it when you are done.

Since this method is used so much, you may use the window global obj() function as a shorthand for LibEcho.Persistence.obj().

Parameters:
Name Type Description
id string

a Persistence id denoting an object (whose class is ultimately derived from PersistentObject) to instantiate.

forceClass class

an optional ES6 class object, ultimately derived from PersistentObject, to instantiate the object as. This argument is really only used internally, and (unless you are doing something very weird) you'll probably never need to use it.

Source:
Throws:

Error if id contains invalid characters, forceClass is not ultimately derived from PersistentObject, or there has been no object defined with Persistence.define() that matches the given id.

Returns:

(or subclass) an instantiated object, previously defined with Persistence.define().

Type
LibEcho.Persistence.PersistentObject
Examples
var joe = LibEcho.Persistence.instantiate( "joe" );
alert( "Joe's last name is " + joe.lastName() + "!" );
alert( "Joe's last name is " + tf("joe").lastName() + "!" );

toString()

Overridden.

Source:
Returns:

the value of this.aName.

Type
string