Heroic Lands

Class SohlTour

SoHL's guided-tour base class — the enabler for the SoHL Guided Tours epic. Extends Foundry's NUE Tour to add three things a stock declarative tour cannot do:

  1. Scene-setting navigation — a step may open an, awaiting the render, so a selector that lives on a not-yet-open tab resolves after navigation. Only navigation is ever automated; the user's meaningful choices are never made for them (PRIME DIRECTIVE — assist, don't play the game).
  2. Gated steps — a value gate keeps Next disabled until a target control holds a required value; a state gate keeps it disabled until a predicate over document/DOM state passes. The decision is the Foundry-free sohl.entity.tour model; this class only reads the live sheet to feed it and toggles the button.
  3. Re-render survival — when the watched sheet re-renders between or during a step, the highlight/tooltip is re-anchored to the fresh target element.

A free step (no gate) behaves exactly like a stock Foundry step.

For a driven (railroaded) tour — the Automated Combat tour — it adds two more capabilities, used only where the tour is meant to perform the workflow rather than coach it:

  1. Drive steps — a step's drive actions (import an adventure, activate a scene, start/advance a combat, set a target) are performed and awaited before the step is shown, so the next step's targets exist. The ordering/await logic is the Foundry-free sohl.entity.tour.runDrive; this class only supplies the executor.
  2. Seeded RNG — with SohlTourConfig.seedRng set, sohl.random is seeded at tour start for reproducible scripted rolls and guaranteed-restored on every exit path (completion, abort, Escape, navigation, mid-step error) via a fire-once sohl.entity.tour.RngLease — the tour's one hard teardown obligation.

See

https://kb.heroiclands.org/dev/how-to/guided-tours/ for the authoring guide.

Hierarchy

  • TourBase
    • SohlTour

Indexable

  • [key: string]: any

Constructors

constructor

Accessors

canStart currentSohlStep spotlightTarget

Methods

_getTargetElement _postStep _preStep _renderStep exit progress

Constructors

constructor

Accessors

canStart

currentSohlStep

spotlightTarget

  • get spotlightTarget(): undefined | HTMLElement

  • The element the current step spotlights (the fade ring is drawn around it), or undefined when the step has no SohlTourStep.spotlight. Exposed for tests and callers that need to confirm what the step is pointing at.

    Returns undefined | HTMLElement

Methods

_getTargetElement

  • _getTargetElement(selector: string): null | Element

  • Resolve a selector, preferring the open sheet's element so highlights are scoped correctly even when several sheets are open.

    Parameters

    • selector: string

      The CSS selector to resolve.

    Returns null | Element

    The matched element, or null if none.

_postStep

_preStep

  • _preStep(): Promise<void>

  • Perform scene-setting navigation and (re)arm the current step's gate watchers before the step is shown.

    Returns Promise<void>

_renderStep

  • _renderStep(): Promise<void>

  • Render the step, then gate its Next button. Written to be idempotent so it can double as the re-anchor path after a sheet re-render.

    Returns Promise<void>

exit

  • exit(): void

  • Exit the tour at the current step — the chokepoint for abort, the Escape keybinding, and a mid-step render error (Foundry's progress() calls exit() before rethrowing). Restore the seeded RNG first, then defer to the base teardown.

    Returns void

progress

  • progress(stepIndex: number): Promise<void>

  • Progress to a step. Delegates to the base stepper, then — on reaching a terminal status (normal completion or a reset to unstarted) — restores the seeded RNG. Combined with exit (abort/Escape/error) and the pagehide safety net, this guarantees restore on every exit path.

    Parameters

    • stepIndex: number

      The step index to progress to.

    Returns Promise<void>

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods