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 “bob”, then the id of Bob's femininity transformable would be “bob.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: “bob”, “cocktail_dress”, etc.

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

setDefaults() must only be called at initialization time, from story javascript or initialization passages. This function is used to define all of the top-level PersistentObjects in your game.

LibTF.Persistence.setDefaults( "cassidy", LibTF.Person, {
	"name" : "Cassidy",
	"lastName" : "Chase",
	"applyTFImmediately" : false,
	"apparel" : [
		"boxers", 
		"jeans", 
		"tshirt", 
		"socks",
		"tennisshoes",
	],
	"initialState" : [ "male" ],
} );

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

var bob = LibTF.Persistence.instantiate( "bob" );
alert( "Bob's last name is " + bob.lastName + "!" );

Sugarcube/Snowman shortcut for the above:

alert( "Bob's last name is " + tfGet("bob").lastName + "!" );

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

if( LibTF.Persistence.has("european_swallow.irregularArticle") )
	alert( "It would appear that european_swallow has an irregular article defined!" );

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

var article = LibTF.Persistence.get( "european_swallow.irregularArticle" );
alert( "You see " + article  + " european swallow here!" );

(Would print “You see a european swallow here!”, assuming the data record contained “a”.)

• id is the persistence id whose data record we want to set.
• value is the value we want to set it to.
• Returns: Nothing.
• Throws: Error if: id contains invalid characters.

Sets the data record associated with id in the LibTF persistence engine.

LibTF.Persistence.set( "european_swallow.irregularArticle", "the" );

• id is the persistence id whose data record we want to reset.
• Returns: the previous value, if the record was reset, or null if it was not reset.
• Throws: Error if: id contains invalid characters.

Resets the data record associated with id to whatever it was defined with in setDefaults().

LibTF.Persistence.reset( "european_swallow.irregularArticle" );