Twine Persistent Vars Javascript

// COMMANDS TO STORE OR RETRIEVE PERSISTENT VARIABLES:
// ===================================================
// To store persistent variables from this Twine:
// -- <<run setup.saveMemory()>>
//
// To retrieve stored persistent variables from this Twine:
// -- <<set $store to setup.loadMemory()>>
//
// To remove this Twine's persistent variables from local storage:
// -- <<set $store to setup.eraseMemory()>>
//
// To clear all persistent variables from this domain:
// -- <<set $store to setup.eraseAll()>>
//
// NOTE: you could probably tweak the functions below, to take a string parameter for the Key,
// if you wanted to save/load in multiple places in Local Storage. Persistent variables from
// different Twines will probably want unique Keys, and some means to load them.
// For now, the Local Storage key is 'example-memory'.

// GENERAL OVERVIEW:
// =================
// This was created to pass variables between Twines/web games, using Local Storage and JS.
// It does this using a JS object called $memory, which contains all variables intended to
// be passed between/accessed in other games. The memory object is then parsed via JSON
// and stored in Local Storage, for later retrieval.
//
// NOTE: Not all Twine variables are stored, only variables within the $memory object.
//
// In the first passage of the Twine, run the setup.loadMemory() JS function. This will
// retrieve the $memory object from local storage. I'm not sure if it's necessary, but
// I also initialized the $memory object with the variables I expected it to have, and
// default values, so it'd have those to fall back on if there was nothing in Local Storage.
//
// Whenever persistent variables are changed in a passage, run the setup.saveMemory() function,
// to update local storage with the new values.
//
// To access variables from the memory object in a passage, use $memory.<VARIABLE NAME>

// LIMITATIONS:
// ============
// I never tested/fully implemented retrieving Local Storage across domains, but I've
// read that it's doable using iframes, and messages/event listeners. Load Local Storage
// in the iframe, and use messages to pass data from the child iframe to the parent.
// No clue if/how Local Storage can be accessed from other browsers though.
//
// Reading and writing to Local Storage can be fussy sometimes, especially if I wanted to
// modify how many variables were in the $memory object. A few times during dev the data
// got corrupted/into a state where I couldn't read or write to it. Clearing local storage
// using setup.eraseAll() seemed to fix it.

setup.saveMemory = function () {
	var store = JSON.stringify(State.variables.memory);
	try {
		localStorage.setItem('example-memory', store);
	} catch (e) {
		UI.alert('Local storage is inaccessible to save to!');
		console.log(e);
	}
};

setup.loadMemory = function () {
	try {
		var store = localStorage.getItem('example-memory');
		return JSON.parse(store);
	} catch(e) {
		UI.alert('Local storage is inaccessible to load from!');
		console.log(e);
	}
};

setup.eraseMemory = function () {
	try {
		var store = localStorage.removeItem('example-memory');
		return;
	} catch(e) {
		UI.alert('Local storage is inaccessible to erase!');
		console.log(e);
	}
};

// Clears ALL local storage persistent variables
setup.eraseAll = function () {
	try {
		var store = localStorage.clear();
		return;
	} catch(e) {
		UI.alert('Local storage is inaccessible to erase all!');
		console.log(e);
	}
};