State and settings

Inkweaver saves your plugin’s data for you. There are two kinds:

• State follows the story. It’s saved in bookmarks, and it rewinds and replays along with the reader.
• Settings belong to the reader, not to a point in the story. They’re the place for preferences like volume or text speed.

State

Your plugin’s state is a single object that holds any serializable data. It’s private to your plugin.

You can read your state with getState. To change it, use setState or updateState:

const { inventory } = getState();
updateState({ inventory: [...inventory, "brass-key"] });

The object getState returns is frozen, so you can’t edit it in place. Always use setState or updateState. That’s how Inkweaver records the change in the reader’s history.

When to change state

Change state while Inkweaver is updating a beat. You can do that in any of these:

• A decoration of the update command
• An onLabel callback
• An onChange callback

When the update finishes, Inkweaver takes a snapshot of every plugin’s state. The reader can rewind to that snapshot, or save it in a bookmark. You can read more in the beat loop.

Caution

Changes made after the snapshot aren’t saved in history or bookmarks. Inkweaver logs a warning when it drops one, so if you see that warning, look for state changes outside the update step.

Starting values and migrations

defineInitialState sets your state’s starting value. Most plugins only need this:

defineInitialState({ journalEntries: [] });

If a new release of your plugin changes the shape of its data, or fixes how the data was stored, add a migration with defineStateMigration. Pass it two things: the version that introduced the change, and a function that takes the data from the previous version and returns it in the new shape:

// Adds an `isRead` flag to each journal entry, defaulting to unread.
defineStateMigration("2.0.0", (oldState) => {
  const journalEntries = oldState.journalEntries.map((entry) => ({
    ...entry,
    isRead: false,
  }));
  return { ...oldState, journalEntries };
});

When Inkweaver loads saved state, anything missing from the top level comes from your initial state. That only goes one level deep, so a new value inside a nested object, like isRead above, still needs a migration.

Inkweaver records which version of your plugin saved the reader’s data, and runs only the migrations it still needs. The version comes from the version field in your plugin.json, or in project.json for your novel’s own scripts.

Caution

Migrations must be pure and deterministic. Inkweaver runs them whenever it loads state, including when the reader loads a bookmark or steps through their history.

For the details, see defineInitialState and defineStateMigration.

Settings

Settings work like state, but they aren’t tied to the reader’s place in the story. You can read and change them using getSettings, setSettings, and updateSettings:

const { masterVolume } = getSettings();
updateSettings({ masterVolume: 0.8 });

defineInitialSettings sets your settings’ starting values, and defineSettingsMigration adds migrations to them. Both work the same way as the state calls above.

Settings don’t rewind

When the reader steps back and plays forward again, any code that changed a setting runs again. For example, a reader who unlocks something, steps back, and replays will unlock it twice. Make sure any code that changes settings is idempotent.

Let the reader change settings

To let the reader change a setting, add a field for it to a menu, and connect the field’s value and setValue to your settings. Menus and input walks through an example.