State and saves

These commands and selectors manage the beat on screen and the reader’s saves.

Commands

update

Builds the beat at a position in the screenplay, and applies it to state.

update(ctx: UpdateContext): Promise<UpdateResult>

interface UpdateContext {
  lexiaRef: LexiaRef;
}
interface UpdateResult {
  hasContent: boolean;
}

Loads the beat’s lines with fetchBeat, then updates state to match.

hasContent is true if the beat has anything for the reader to see.

Example

const { update } = getCommands();
await update({ lexiaRef });

commit

Saves the current state as a step in the reader’s history, which the reader can step back to.

commit(ctx?: CommitContext): Promise<CommitResult>

Example

const { commit } = getCommands();
await commit();

canDiscardState

Returns whether the current state can be discarded, for example before loading a bookmark over unsaved progress.

canDiscardState(ctx?: CanDiscardStateContext): Promise<CanDiscardStateResult>

interface CanDiscardStateResult {
  canDiscard: boolean;
}

Always returns true. Decorate it to protect progress your plugin doesn’t want lost, like asking the reader before discarding an unsaved beat.

Example

decorateCommand("canDiscardState", async (context, next) => {
  if (hasUnsavedProgress()) {
    return { canDiscard: false };
  }
  return next(context);
});

quickSave

Saves a quicksave bookmark of the current state.

quickSave(): Promise<void>

Example

const { quickSave } = getCommands();
await quickSave();

quickLoad

Loads the most recent quicksave bookmark, and redraws the scene. Does nothing if there’s no quicksave.

quickLoad(): Promise<void>

Example

const { quickLoad } = getCommands();
await quickLoad();

Selectors

getExpressionValues

Returns the values of the inline expressions in the current beat, keyed by expression ID.

getExpressionValues(): { expressionValues: Record<string, any> }

Use it with onChange to respond when an expression’s value changes.

Example

const { getExpressionValues } = getSelectors();
const { expressionValues } = getExpressionValues();