State and saves

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

Commands

update

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;
}

It 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

commit saves the current state as a step in the reader’s history, so the reader can step back to it.

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

Example

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

resetNovel

resetNovel resets every plugin’s state to its starting values, and empties the reader’s history.

resetNovel(): Promise<void>

startNovel runs it before going to the start label.

Example

decorateCommand("resetNovel", async (context, next) => {
  await next(context);
  updateState({ trust: 50 });
});

canDiscardState

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;
}

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

Example

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

quickSave

quickSave saves a quicksave bookmark of the current state, and replaces the last one.

quickSave(): Promise<void>

Example

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

quickLoad

quickLoad loads the most recent quicksave bookmark and redraws the scene. If there’s no quicksave, it does nothing.

quickLoad(): Promise<void>

Example

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

drawBookmarkImage

drawBookmarkImage draws a frame for a bookmark’s image.

drawBookmarkImage(ctx: DrawBookmarkImageContext): Promise<DrawBookmarkImageResult>

interface DrawBookmarkImageContext {
  beat: null | Beat;
}
interface DrawBookmarkImageResult {
  frame: null | Frame;
}

frame is null if there’s no beat to draw. Decorate it to change what a bookmark’s image shows.

Example

const { drawBookmarkImage } = getCommands();
const { beat } = getState();
const { frame } = await drawBookmarkImage({ beat });

renderBookmarkImage

renderBookmarkImage turns a bookmark’s frame into an image.

renderBookmarkImage(ctx: RenderBookmarkImageContext): Promise<RenderBookmarkImageResult>

interface RenderBookmarkImageContext {
  frame: Frame;
}
interface RenderBookmarkImageResult {
  image: null | string;
}

image is a data URL. It’s null unless a plugin decorates this command.

Example

const { renderBookmarkImage } = getCommands();
const { image } = await renderBookmarkImage({ frame });

Selectors

getExpressionValues

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();