Assets

These commands and selectors load your novel’s built files, and choose which image, cue, and locale to use.

Commands

fetchManifest

Loads the asset manifest, which lists your novel’s built files and their details.

fetchManifest(ctx?: FetchManifestContext): Promise<FetchManifestResult>

interface FetchManifestResult {
  manifest: Manifest;
}

Example

const { fetchManifest } = getCommands();
const { manifest } = await fetchManifest();

fetchLabelManifest

Loads the label manifest, indexed by label, so you can find the screenplay and line where each label appears.

fetchLabelManifest(
  ctx?: FetchLabelManifestContext,
): Promise<FetchLabelManifestResult>

interface FetchLabelManifestResult {
  labelManifest: LabelManifest;
}

Example

const { fetchLabelManifest } = getCommands();
const { labelManifest } = await fetchLabelManifest();

fetchScreenplay

Loads a screenplay file in the reader’s text language.

fetchScreenplay(ctx: FetchScreenplayContext): Promise<FetchScreenplayResult>

interface FetchScreenplayContext {
  logicalUrl: string;
}
interface FetchScreenplayResult {
  screenplay: Screenplay;
}

Example

const { fetchScreenplay } = getCommands();
const { screenplay } = await fetchScreenplay({ logicalUrl });

fetchBeat

Returns the lines of a single beat, starting at a position in the screenplay.

fetchBeat(ctx: FetchBeatContext): Promise<FetchBeatResult>

interface FetchBeatContext {
  lexiaRef: LexiaRef;
}
interface FetchBeatResult {
  lines: Array<BlockLexia | TransitionLexia>;
}

Example

const { fetchBeat } = getCommands();
const { lines } = await fetchBeat({ lexiaRef });

fetchPsd

Loads a PSD as an InkRoot, in the reader’s image language.

fetchPsd(ctx: FetchPsdContext): Promise<FetchPsdResult>

interface FetchPsdContext {
  logicalUrl: string;
}
interface FetchPsdResult {
  root: InkRoot;
}

Example

const { fetchPsd } = getCommands();
const { root } = await fetchPsd({ logicalUrl });

resolveImage

Finds the image for a character, slugline, or menu, and returns its path along with the labels inside it.

resolveImage(ctx: ResolveImageContext): Promise<null | ResolveImageResult>

type ResolveImageContext =
  | { beat: null | Beat; lexia: HeadingLexia; type: "character" | "slugline" }
  | { beat: null | Beat; menu: MenuSchema; type: "menu" };
interface ResolveImageResult {
  logicalUrl: string;
  resourceLabels: Array<ResourceLabel>;
}

beat is the beat the image is for, or null if there isn’t one.

Returns null if no image matches. To load the image itself, pass the path to fetchPsd.

Example

const { resolveImage } = getCommands();
const image = await resolveImage({ beat, lexia, type: "character" });

resolveCue

Returns the cue that should be playing for a set of lines. If none of the lines change the cue, the current cue carries on.

resolveCue(ctx: ResolveCueContext): Promise<ResolveCueResult>

interface ResolveCueContext {
  lines: Array<BlockLexia | TransitionLexia>;
}
interface ResolveCueResult {
  activeCue: undefined | ActiveCue;
}

Example

const { resolveCue } = getCommands();
const { activeCue } = await resolveCue({ lines });

Selectors

resolveLocale

Returns the locale the reader chose for one part of the novel. Readers can choose a different language for each role, so they can read in one language and listen in another.

resolveLocale(ctx: { role: LocaleRole }): { locale: string }

Role	Used for
text	The screenplay and interface text
image	Artwork
cue	Audio

The reader’s choices are stored by the language menu. If the reader hasn’t chosen, returns "und", so resolve uses whatever version each file has. Decorate it to get the locale from somewhere else.

To add a role, extend the LocaleRoles interface:

declare module "@inkweaverdev/inkweaver-sdk" {
  interface LocaleRoles {
    voice: true;
  }
}

Example

decorateSelector("resolveLocale", (context, next) => {
  if (context.role === "text") {
    return { locale: getSettings().textLocale };
  }
  return next(context);
});