Skip to main content

Prompt Context: Beat, Structure, and Story

This page covers the core context values (message, textBefore, isStartOfText, novel, act, chapter, scene, pov, storySoFar, and storyToCome) plus their related helpers and properties. Use them to pull beat text, structure metadata, scene context, POV metadata, and outline-level story context into your prompts.

Beat text​

message​

Retrieves the message content of the current scene beat that triggered the prompt.

message -> string

Return value Plain text content from the active prompt source.
Format Text only. Line breaks are preserved.

Example

Instructions from the beat:
{message}

textBefore​

Retrieves the text content immediately preceding the current beat within the scene.

textBefore -> string

Return value Plain text content from the scene before the current beat.
Format Text only. Paragraph breaks are preserved.

Example

Previous paragraph(s):
{textBefore}

Conditional usage You can use textBefore in conditions (empty text evaluates as false), but prefer isStartOfText for start-of-scene checks.

{#if not(textBefore)}
  This is a brand new scene with no preceding text
{#endif}

isStartOfText​

Checks whether the current beat is at the start of the scene (meaning there is no text before it).

isStartOfText -> boolean

Return value true when there is no prior text in the scene; otherwise false.

Example

{#if isStartOfText}
  This is the opening paragraph of the scene.
{#endif}

Structure context​

Novel​

Returns the current novel as a lightweight XML tag with core metadata.

novel -> Novel

Return value A self-closing <novel /> tag with metadata attributes when available.
Attributes title (always), author (when set), and tense (raw tense value like past).

Example

{novel}

Sample output

<novel title="Unnamed Noirpunk Story" author="Pen Name" tense="past"/>

Common fields

  • novel.id - unique novel ID.
  • novel.title - novel title.
  • novel.author - author name (empty if unset).
  • novel.tense - human-readable tense label (for example, past tense).
  • novel.language - full language name (for example, US English).
  • novel.outlineStats - compact outline XML with structural counts and word totals.

novel.hasSeries​

Indicates whether the current novel belongs to a series. Returns true when the novel is part of a series; otherwise empty. This exists so prompts can adjust assumptions about reader familiarity and continuity expectations when writing sequels versus standalones.

Example

{#if novel.hasSeries}
  When writing this scene, remember that readers are already familiar with the world and characters from previous books in the series.
{#endif}

novel.outline​

Provides an outline XML snapshot built from scene summaries (not full scene content). It is intended to give the LLM the overall feeling and direction of the novel rather than a verbatim transcript. For best results, keep scene summaries current so the outline reflects the latest story beats.

The outline respects the novel structure mode. If the novel is in "Chapters + Scenes" mode, the outline omits <act> tags and places chapters directly under <outline>. If the novel is in "Scenes only" mode, the outline contains only <scene> tags.

Structure mode examples

<outline>
  <act number="1" title="The First Act">
    <chapter number="1" title="Intro">
      <scene title="Chapter 1: Intro - Scene 1" number="1" pointOfView="Sally Quinn">
        Harry Calder walks across a floodwall bridge in neon-lit Neon Vale</scene>
      <scene title="Chapter 1: Intro - Scene 2" number="2" pointOfView="Harry Calder">
        Harry Calder pulls a holo-lens from his coat pocket and places it on eyes.</scene>
      <scene title="Chapter 1: Intro - Scene 3" number="3" pointOfView="Harry Calder">
        Entering a bar. Sitting there. Watching people.</scene>
    </chapter>
  </act>
  <act number="2" title="The Second Act">
    <chapter number="1" title="Pressure Points">
      <scene title="Chapter 1: Pressure Points - Scene 1" number="1" pointOfView="Harry Calder" />
      <scene title="Chapter 1: Pressure Points - Scene 2" number="2" pointOfView="Harry Calder" />
    </chapter>
  </act>
</outline>

novel.outlineStats​

Provides a compact outline XML that includes structural totals and word counts. This is built from the scene text (not summaries) and is meant for quick macro-level planning prompts or token-light context checks.

Structure mode examples

<novel title="My New Novel" author="Sally Quinn" tense="past" pov="Sally Quinn" word_count="940432">
  <act number="1" title="The First Act" chapters_count="13" words_count="33456">
    <chapter number="1" title="Intro" scene_count="3" word_count="9023"/>
  </act>
</novel>

novel.fullText​

Provides the full novel XML built from the actual scene text, not summaries. It is intended for complete prose context and is not limited by length, so it can be much larger than novel.outline.

The full text respects the novel structure mode. When a novel is configured without acts or chapters, the XML omits those tags and renders the scene list directly.

Structure mode examples

<novel>
  <act number="1" title="The First Act">
    <chapter number="1" title="Intro">
      <scene title="Chapter 1: Intro - Scene 1" number="1" pointOfView="Sally Quinn">
      Neon Vale flickers like a tired billboard, rain slicks the chrome alleys, and the skyways hum with strangers.
      </scene>
    </chapter>
  </act>
</novel>

Act​

Returns the current act as a prompt object. In acts + chapters mode, {act} emits a self-closing <act> XML tag. When the novel structure omits acts, {act} renders an empty string.

act -> Act

Return value A self-closing <act /> tag with metadata attributes when available. When the novel structure omits acts, the return value is an empty string.
Attributes title (when the act has a custom name) and number (when numbering is enabled).

Example

{act}

Sample output

<act title="Act I" number="1"/>

Common fields

  • act.id - internal act ID.
  • act.number(target?) - act number when numbering is enabled; otherwise empty. The target may be a PromptAct, PromptChapter, or PromptScene. When the novel structure omits acts, this always renders empty.

act.title​

Returns the display title for an act (custom title or "Act X"). The target argument is optional; when provided, it can be a PromptScene or PromptChapter, and the title resolves to the act containing that object. If omitted, it uses the current act. When the novel structure omits acts, this renders empty.

Example

{act.title}
{act.title(scene.next)}

If you want the current scene’s act title, a faster way is scene.act.title. When the novel structure omits acts, this renders empty.

act.name​

Returns the raw act name from the title field (empty if unset). The target argument is optional; when provided, it can be a PromptScene or PromptChapter, and the name resolves to the act containing that object. If omitted, it uses the current act. When the novel structure omits acts, this renders empty.

Example

{act.name}
{act.name(scene.next)}

If you want the current scene's act name, a faster way is scene.act.name. When the novel structure omits acts, this renders empty.

act.summary​

Provides an outline XML snapshot built from scene summaries, matching the shape of novel.outline for a single act. The target argument is optional; when provided, it can be a PromptAct, PromptChapter, or PromptScene, and the outline resolves to the act containing that object.

Structure modes

  • Acts + Chapters + Scenes: output includes a single <act> wrapper with nested <chapter> and <scene> tags.
  • Chapters + Scenes: output omits <act> tags and places <chapter> tags directly under <outline>.
  • Scenes only: output omits <act> and <chapter> tags and places <scene> tags directly under <outline>.

Sample output

<outline>
  <act number="1" title="The First Act">
    <chapter number="1" title="Intro">
      <scene title="Chapter 1: Intro - Scene 1" number="1" pointOfView="Sally Quinn">
        Harry Calder walks across a floodwall bridge in neon-lit Neon Vale</scene>
      <scene title="Chapter 1: Intro - Scene 2" number="2" pointOfView="Harry Calder">
        Harry Calder pulls a holo-lens from his coat pocket and places it on eyes.</scene>
      <scene title="Chapter 1: Intro - Scene 3" number="3" pointOfView="Harry Calder">
        Entering a bar. Sitting there. Watching people.</scene>
    </chapter>
  </act>
</outline>

act.fullText​

Provides the full-text XML for an act, matching the shape of novel.fullText when scoped to the act. The target argument is optional; when provided, it can be a PromptAct, PromptChapter, or PromptScene, and the output resolves to the act containing that object.

Structure modes

  • Acts + Chapters + Scenes: output includes a single <act> wrapper with nested <chapter> and <scene> tags.
  • Chapters + Scenes: output omits <act> tags and places <chapter> tags directly under <novel>.
  • Scenes only: output omits <act> and <chapter> tags and places <scene> tags directly under <novel>.

Sample output

<outline>
  <act number="1" title="The First Act">
    <chapter number="1" title="Intro">
      <scene title="Chapter 1: Intro - Scene 1" number="1" pointOfView="Sally Quinn">
        Harry Calder walks across a floodwall bridge in neon-lit Neon Vale</scene>
      <scene title="Chapter 1: Intro - Scene 2" number="2" pointOfView="Harry Calder">
        Harry Calder pulls a holo-lens from his coat pocket and places it on eyes.</scene>
      <scene title="Chapter 1: Intro - Scene 3" number="3" pointOfView="Harry Calder">
        Entering a bar. Sitting there. Watching people.</scene>
    </chapter>
  </act>
  <act number="2" title="The Second Act">
    <chapter number="1" title="Pressure Points">
      <scene title="Chapter 1: Pressure Points - Scene 1" number="1" pointOfView="Harry Calder" />
      <scene title="Chapter 1: Pressure Points - Scene 2" number="2" pointOfView="Harry Calder" />
    </chapter>
  </act>
</outline>

Helpers​

  • act.previous, act.next - adjacent acts (empty if this is the first/last act). Returns a PromptAct, so chaining like act.next.next works.

Chapter​

Returns the current chapter as a prompt object. In acts + chapters and chapters + scenes modes, {chapter} emits a self-closing <chapter> XML tag. When the novel structure omits chapters, {chapter} renders an empty string.

chapter -> Chapter

Return value A self-closing <chapter /> tag with metadata attributes when available. When the novel structure omits chapters, the return value is an empty string.
Attributes title (when the chapter has a custom name) and number (when numbering is enabled).

Example

{chapter}

Sample output

<chapter title="The Departure" number="1"/>

Common fields

  • chapter.id - internal chapter ID.

chapter.title​

Returns the display title for a chapter (custom title or "Chapter X"). The target argument is optional; when provided, it can be a PromptScene or PromptChapter, and the title resolves to the chapter containing that object. If omitted, it uses the current chapter. When the novel structure omits chapters, this renders empty.

Example

{chapter.title(scene.next)}

If you want the current scene's chapter title, a faster way is scene.chapter.title. When the novel structure omits chapters, this renders empty.

chapter.name​

Returns the raw chapter name from the title field (empty if unset). The target argument is optional; when provided, it can be a PromptScene or PromptChapter, and the name resolves to the chapter containing that object. If omitted, it uses the current chapter. When the novel structure omits chapters, this renders empty.

Example

{chapter.name(scene.next)}

If you want the current scene's chapter name, a faster way is scene.chapter.name. When the novel structure omits chapters, this renders empty.

chapter.number​

Returns the chapter number when numbering is enabled; otherwise empty. The target argument is optional; when provided, it can be a PromptScene or PromptChapter, and the number resolves to the chapter containing that object. If omitted, it uses the current chapter. When the novel structure omits chapters, this renders empty.

Example

{chapter.number(scene.next)}

If you want the current scene's chapter number, a faster way is scene.chapter.number. When the novel structure omits chapters, this renders empty.

chapter.act​

Returns the PromptAct that contains the current chapter. Use it to access act metadata from a chapter (for example, chapter.act.title or chapter.act.number). When the novel structure omits acts or chapters, this renders an empty string.

chapter.summary​

Provides a chapter-level summary XML block, matching the <chapter> section used inside act.summary. The target argument is optional; when provided, it can be a PromptChapter or PromptScene, and the summary resolves to the chapter containing that object. If omitted, it uses the current chapter.

Structure modes

  • Acts + Chapters + Scenes and Chapters + Scenes: output includes a <chapter> wrapper with nested <scene> tags.
  • Scenes only: output omits the <chapter> wrapper and returns <scene> tags directly.

Sample output

<chapter number="1" title="Intro">
  <scene title="Chapter 1: Intro - Scene 1" number="1" pointOfView="Sally Quinn">Harry Calder walks across a floodwall bridge.</scene>
  <scene title="Chapter 1: Intro - Scene 2: Barfly" number="2" subtitle="Barfly">He enters the bar and watches the regulars.</scene>
</chapter>

chapter.fullText​

Provides the full-text XML for a chapter, matching the <chapter> block used inside act.fullText. The target argument is optional; when provided, it can be a PromptChapter or PromptScene, and the output resolves to the chapter containing that object. If omitted, it uses the current chapter.

Structure modes

  • Acts + Chapters + Scenes and Chapters + Scenes: output includes a <chapter> wrapper with nested <scene> tags.
  • Scenes only: output omits the <chapter> wrapper and returns <scene> tags directly.

Sample output

<chapter number="1" title="Intro">
  <scene title="Chapter 1: Intro - Scene 1" number="1" pointOfView="Sally Quinn">Neon Vale flickers.</scene>
  <scene title="Chapter 1: Intro - Scene 2" subtitle="Barfly" number="2">
    Line one.
    Line two.
  </scene>
</chapter>

Helpers​

  • chapter.previous, chapter.next - adjacent chapters (empty if this is the first/last chapter, or when the novel structure omits chapters).

Scene​

Returns the current scene as a prompt object. Rendering {scene} directly emits a <scene> XML tag with beat-free text.

scene -> Scene

Return value The current scene as <scene> XML when rendered directly. The tag includes title and number, plus subtitle and pointOfView when available.
Format Beat-free scene text inside the tag; empty scenes render as self-closing tags.

Example

{scene}

Sample output

<scene title="Chapter 3: The Gate - Scene 2: Arrival" number="2" subtitle="Arrival" pointOfView="Mara">
  The ship touches the dock under cover of fog.
</scene>

scene.fullText(value?)

  • Signature: scene.fullText(value?) -> string
  • Behavior: Renders the current scene when called without arguments. Accepts a single scene, a list of scenes, a raw string, or a number and returns XML or the value as-is. Returns an empty string for null or invalid values.
{scene.fullText(scene.previous)}

Common fields

  • scene.id - internal scene ID.

scene.title​

Returns the structural scene title without the subtitle. The target argument is optional; when provided, it can be a PromptScene, and the title resolves to that scene. If omitted, it uses the current scene.

Example

{scene.title(scene.next)}

If you already have a scene object, a faster way is scene.next.title.

scene.fullTitle​

Returns the full descriptive title for a scene, including the subtitle when present. The target argument is optional; when provided, it can be a PromptScene, and the full title resolves to that scene. If omitted, it uses the current scene.

Example

{scene.fullTitle(scene.next)}

If you already have a scene object, a faster way is scene.next.fullTitle.

scene.number​

Returns the scene number within the chapter. The target argument is optional; when provided, it can be a PromptScene, and the number resolves to that scene. If omitted, it uses the current scene.

Example

{scene.number(scene.next)}

If you already have a scene object, a faster way is scene.next.number.

scene.subtitle​

Returns the subtitle text when set. The target argument is optional; when provided, it can be a PromptScene, and the subtitle resolves to that scene. If omitted, it uses the current scene.

Example

{scene.subtitle(scene.next)}

If you already have a scene object, a faster way is scene.next.subtitle.

scene.labels​

Returns a comma-separated list of label XML for the scene. The target argument is optional; when provided, it can be a PromptScene, PromptChapter, or PromptAct. Passing a chapter or act returns labels from all scenes under that scope. When no labels are assigned, this returns an empty string.

Example

{scene.labels(chapter)}

Sample output

<label name="Time: Flashforward"/>, <label name="Status: Draft"/>

scene.hasLabel​

Returns a PromptSceneList of scenes in the novel whose labels match name. Matching is case-insensitive and trims whitespace. When no scenes match, it returns null, which is falsy in Lis Novel prompts, so you can use it directly in #if conditions. Rendering the list directly emits newline-separated <scene> XML (see Prompt Object Types).

Example

{#if scene.hasLabel("Status: Draft")}
  It's a draft, ignore it
{#endif}

When you use the helper to gate outline context, the outline XML looks like this:

<outline>
  <act number="1" title="The First Act">
    <chapter number="1" title="Intro">
      <scene title="Chapter 1: Intro - Scene 1" number="1" pointOfView="Sally Quinn">
        Harry Calder walks across a floodwall bridge in neon-lit Neon Vale</scene>
      <scene title="Chapter 1: Intro - Scene 2" number="2" pointOfView="Harry Calder">
        Harry Calder pulls a holo-lens from his coat pocket and places it on eyes.</scene>
      <scene title="Chapter 1: Intro - Scene 3" number="3" pointOfView="Harry Calder">
        Entering a bar. Sitting there. Watching people.</scene>
    </chapter>
  </act>
  <act number="2" title="The Second Act">
    <chapter number="1" title="Pressure Points">
      <scene title="Chapter 1: Pressure Points - Scene 1" number="1" pointOfView="Harry Calder" />
      <scene title="Chapter 1: Pressure Points - Scene 2" number="2" pointOfView="Harry Calder" />
    </chapter>
  </act>
</outline>
note

Matching is case-insensitive and trims whitespace.

scene.hasMention​

Returns a PromptSceneList of scenes in the novel that mention the lore entry matching name (including aliases). Mentions are detected from the scene text only, not from scene beats. When no scenes match, it returns null, which is falsy in Lis Novel prompts, so you can use it directly in #if conditions. Rendering the list directly emits newline-separated <scene> XML (see Prompt Object Types).

Example

Scenes that mention the Deadly Weapon: {scene.hasMention("Deadly Weapon")}

Example (Condition)

{#if scene.hasMention("The One Who Must Not Be Named")}
  This scene mentions the super evil villain, which means you should make sure no other character mentions the villain by name.
{#endif}
note

Matching is case-insensitive and trims whitespace.

scene.hasReference​

Returns a PromptSceneList of scenes in the novel that have the lore entry matching name manually attached in the Outline (which is on the sidebar) or in the Storyboard view. This checks manual references rather than text mentions. When no scenes match, it returns null, which is falsy in Lis Novel prompts, so you can use it directly in #if conditions. Rendering the list directly emits newline-separated <scene> XML (see Prompt Object Types).

Example

Scenes tied to the Deadly Weapon: {scene.hasReference("Deadly Weapon")}

Example (Condition)

{#if scene.hasReference("The One Who Must Not Be Named")}
  This scene is explicitly linked to the villain, so keep the tension high.
{#endif}
note

Matching is case-insensitive and trims whitespace.

scene.references​

Returns a PromptLoreList of lore entries manually linked to a scene (from the Outline sidebar or the Storyboard view). The scene argument is optional; when provided, it can be a PromptScene, and references resolve to that scene. If omitted, it uses the current scene. Rendering the list emits comma-separated lore entry XML (see Prompt Object Types). When no entries are linked, it renders as an empty string.

Example

Scene references: {scene.references}

Sample output

<character name="Detective Jane" aliases="Jane"/>, <character name="Captain Rex"/>

Example (Condition)

{#if wordCount(scene.references)}
  References: {scene.references}
{#endif}

scene.hasSubtitle​

Returns a PromptSceneList of scenes in the novel with subtitles. If you pass a subtitle, it filters to scenes whose subtitle matches (case-insensitive). If you omit the argument, it returns all scenes that have any subtitle. When no scenes match, it returns null, which is falsy in Lis Novel prompts, so you can use it directly in #if conditions. Rendering the list directly emits newline-separated <scene> XML (see Prompt Object Types).

Example

Scenes with subtitles: {scene.hasSubtitle}

Example (Filter)

Scenes with the "Cliffhanger" subtitle: {scene.hasSubtitle("Cliffhanger")}

Example (Condition)

{#if scene.hasSubtitle("The Confrontation")}
  This scene has a confrontation subtitle, so keep the stakes high.
{#endif}
note

Matching is case-insensitive and trims whitespace.

Helpers​

  • scene.previous, scene.next - adjacent scenes.
  • scene.previousSamePOV, scene.nextSamePOV - adjacent scenes with the same POV.
  • scene.hasSummary, scene.hasText - render the current scene only when summary/text exists.

Point of view​

Returns the effective point of view for the current context. Rendering {pov} directly emits a <pointOfView> XML tag.

pov -> PointOfView

Return value A <pointOfView /> tag with POV attributes when available.
Attributes type (for example, third person limited) and character (when the POV is tied to a character).

Example

{pov}

Sample output

<pointOfView type="third person limited" character="Mara"/>

pov.character​

Returns the POV character name when one is set. The scene argument is optional; when provided, it can be a PromptScene, and the POV character resolves to that scene. If omitted, it uses the current scene. When no character is set, it returns an empty string.

Example

POV character: {pov.character}

Example (Condition)

{#if pov.character}
  Write from {pov.character}'s perspective.
{#else}
  Write from the author's perspective.
{#endif}

Common fields

  • pov.type - human-readable POV type.

Helpers​

  • pov.isFirstPerson, pov.isSecondPerson, pov.isThirdPerson - emit the POV XML when matched; otherwise empty.
  • pov.isLimited, pov.isOmniscient - emit the POV XML when matched; otherwise empty.

Rendering behavior​

How scene, chapter, act, and lore values render​

Some helpers return objects or lists that render as XML when placed directly in a template:

  • Single scene values render as <scene> XML (same format as {scene.fullText}).
  • Scene lists render as newline-separated <scene> XML.
  • Chapter values render as <chapter> XML in acts + chapters and chapters + scenes modes; otherwise they render an empty string.
  • Act values render as <act> XML in acts + chapters mode; otherwise they render an empty string.
  • Lore lists render the entry XML tags directly (newline-separated for {lore.context}, comma-separated for {scene.references}).
  • {pov} renders a <pointOfView> XML tag.

See Prompt Object Types for how these objects and lists stringify to XML.

Story outline​

Story outline rules​

Applies to both storySoFar and storyToCome.

Arguments None. Both helpers are computed from the current scene that triggered the prompt.
XML schema The output is an XML outline rooted at <storySoFar> or <storyToCome>. In acts + chapters mode it nests <act>, <chapter>, and <scene> tags; in chapters-only mode it omits <act> tags; in scenes-only mode it omits both <act> and <chapter> tags.
Scene attributes title, number, subtitle (when present), and pointOfView (POV character name when available, otherwise the POV type).
Act and chapter attributes number (when numbering is enabled) and title (when a custom title exists).
Rendering details Attribute values are XML-escaped. Scene summary text is inserted as-is, so < and & inside summaries are not escaped.
Empty output If there are no matching scenes, the helper renders an empty string.

tip

If you need a specific slice of the manuscript, use {act.summary}, {chapter.summary}, or the scene helpers in the main context reference.

storySoFar​

Returns the summaries of the novel up to the current scene.

storySoFar -> Outline

What it includes

  • All scenes before the current scene (the current scene is excluded).
  • Only scenes with non-empty summaries.
  • Only scenes marked as included in context (scenes with "Exclude from Context" enabled are omitted).
  • Acts and chapters only appear if they contain at least one included scene.

Examples

{#if storySoFar}
  Story so far:
  {storySoFar}
{#endif}
{#if storySoFar}
  Use the outline below to maintain continuity:
  {storySoFar}
{#endif}

Sample output

<storySoFar>
  <act number="1" title="Act I">
    <chapter number="1" title="The Departure">
      <scene title="Chapter 1: The Departure - Scene 1: The Letter" number="1" subtitle="The Letter" pointOfView="Mara">
        Mara receives a coded letter and decides to leave the island.
      </scene>
      <scene title="Chapter 1: The Departure - Scene 2" number="2" pointOfView="third person limited">
        The crew prepares the ship and hides the cargo.
      </scene>
    </chapter>
  </act>
</storySoFar>

storyToCome​

Returns the outline of what happens after the current scene.

storyToCome -> Outline

What it includes

  • All scenes after the current scene (the current scene is excluded).
  • Scenes with empty summaries are included as self-closing <scene /> tags.
  • Only scenes marked as included in context (scenes with "Exclude from Context" enabled are omitted).
  • Acts and chapters only appear if they contain at least one included scene.

Examples

{#if storyToCome}
  Upcoming outline:
  {storyToCome}
{#endif}
{#if storySoFar}
  Story so far:
  {storySoFar}
{#endif}

{#if storyToCome}
  Story to come:
  {storyToCome}
{#endif}

Sample output

<storyToCome>
  <act number="2" title="Act II">
    <chapter number="5" title="The Pursuit">
      <scene title="Chapter 5: The Pursuit - Scene 1" number="1" pointOfView="Mara" />
      <scene title="Chapter 5: The Pursuit - Scene 2: The Ambush" number="2" subtitle="The Ambush" pointOfView="Mara">
        Mara walks into a trap and loses the map.
      </scene>
    </chapter>
  </act>
</storyToCome>