Differences

This shows you the differences between two versions of the page.

--- libtf:documentation:api:persistence [2018/02/24 19:08] – lee
+++ libtf:documentation:api:persistence [2018/09/24 15:45] (current) – removed lee
@@ Line 1: / Line 1: @@
-[[libtf:documentation:api:start|<-- Back]]
-====== LibTF.Persistence ======
-Most web browsers only allow for 10 megs (though some are as low as 5) of on-disk storage per origin.  This not only has to contain the current game state, but also //all previous// game states in the game history.  This is a particular problem with very large and/or complicated Twine games.
-In an attempt to minimize this issue, LibTF uses a defaults and delta persistence system.  "Persistent Objects", be they characters within the game and their statistics and inventory, articles of clothing and their state, etc etc, are all "created" outside of the story format's persistence system at initialization time.  When an object's state is changed, only the differences from the object's default state are stored within the story format's persistence system.  This greatly reduces the story format's persistence load, versus storing every object's full state within every game history moment, while still allowing the flexibility for almost all objects to be modified and tracked in the game history.
-In order to be persistent, all persistent objects must ultimately derive from the LibTF.PersistentObject class.
-Each PersistentObject that is tracked by LibTF.Persistence has an "id" field (hereafter referred to as the "persistence id"), a simple alphanumeric-underscore string (whitespace, punctuation, and special symbols are not allowed).
-A PersistentObject may be the "child" of another PersistentObject.  This is tracked in the id field via a dot notation.  For example, each Person object contains a Feminimity object (subclassed from Transformable) that tracks the Person's femininity changes.  If the game contains a Person with the id of "joe", then the id of Joe's femininity transformable would be "joe.femininity".
-You won't generally need to worry too much about the id hierarchy.  LibTF takes care of most of it for you.  The vast majority of the time, you'll only need to know the ids of toplevel objects that you have explicitly created: "joe", "cocktail_dress", etc.
-===== Fields =====
-None.
-===== Methods =====
-==== LibTF.Persistence.setDefaults( id, objectClass, defaults ) ====
-  * //id// is a toplevel persistence id which will be used to fetch the object later.  All toplevel ids must be unique.
-  * //objectClass// is an ES6 class object, ultimately derived from PersistentObject, which defines "what" the object is (ie. Person, Apparel, etc etc).
-  * //defaults// is a Javascript object that defines the PersistentObject's default values.  Available defaults are documented in the sections pertaining to the built-in persistent object classes.
-  * Returns: Nothing.
-  * Throws: Error if: //id// contains invalid characters, //objectClass// is not ultimately derived from PersistentObject, or //defaults// isn't a valid Javascript object.
-Define a top-level PersistentObject within your game.  setDefaults() must only be called at initialization time, from story javascript or initialization passages.
-<code javascript>
-LibTF.Persistence.setDefaults( "joe", LibTF.Person, {
-	"name" : "Joe",
-	"lastName" : "Blow",
-	"applyTFImmediately" : false,
-	"apparel" : [
-		"boxers",
-		"jeans",
-		"tshirt",
-		"socks",
-		"tennisshoes",
-	],
-	"initialState" : [ "male" ],
-} );
-</code>
-==== LibTF.Persistence.instantiate( id, forceClass=null ) ====
-  * //id// is a persistence id denoting an object (whose class is ultimately derived from PersistentObject) to instantiate.
-  * //forceClass// is 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.
-  * Returns: An instantiated object, previously defined with setDefaults().
-  * Throws: Error if: //id// contains invalid characters, //forceClass// is not ultimately derived from PersistentObject, or there has been no object defined with setDefaults() that matches //id//.
-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 when you need to use it, and then just let the garbage collector free it when you are done.
-In the Sugarcube 2 and Snowman story formats, you may use the tfObj() function as a shorthand for this, since it is used so much.
-<code javascript>
-var joe = LibTF.Persistence.instantiate( "joe" );
-alert( "Joe's last name is " + joe.lastName + "!" );
-</code>
-Sugarcube/Snowman shortcut for the above:
-<code javascript>
-alert( "Joe's last name is " + tfGet("joe").lastName + "!" );
-</code>
-==== LibTF.Persistence.has( id ) ====
-  * //id// is a persistence id to check for.
-  * Returns: True there is a data record for //id// in the LibTF persistence engine, or False if there is not.
-  * Throws: Error if: //id// contains invalid characters.
-Checks to see if there is a record for //id// in the LibTF persistence engine.
-<code javascript>
-if( LibTF.Persistence.has("european_swallow.irregularArticle") )
-	alert( "It would appear that european_swallow has an irregular article defined!" );
-</code>
-==== LibTF.Persistence.get( id ) ====
-  * //id// is the persistence id whose data record we want to retrieve.
-  * Returns: The data record associated with //id//, or null if there isn't one.
-  * Throws: Error if: //id// contains invalid characters.
-Checks to see if there is a record for //id// in the LibTF persistence engine.
-<code javascript>
-var article = LibTF.Persistence.get( "european_swallow.irregularArticle" );
-alert( "You see " + article  + " european swallow here!" );
-</code>
-(Would print "You see a european swallow here!", assuming the data record contained "a".)
-==== LibTF.Persistence.set( id, value ) ====
-  * //id// is the persistence id whose data record we want to set.
-  * //value // is the value we want to set it to.
-  * Returns: Nothing, which is a bug.  It ought to return the previous value.
-  * Throws: Error if: //id// contains invalid characters.
-Sets the data record associated with //id// in the LibTF persistence engine.
-<code javascript>
-LibTF.Persistence.set( "european_swallow.irregularArticle", "the" );
-</code>
-==== LibTF.Persistence.reset( id ) ====
-  * //id// is the persistence id whose data record we want to reset.
-  * Returns: the previous value (before reset).
-  * Throws: Error if: //id// contains invalid characters.
-Resets the data record associated with //id// to whatever it was defined with in setDefaults().
-<code javascript>
-LibTF.Persistence.reset( "european_swallow.irregularArticle" );
-</code>
-[[libtf:documentation:api:start|<-- Back]]

Echo Hollow

Echo Hollow

Differences

Echo Hollow

Echo Hollow

User Tools

Site Tools

Differences

Page Tools