Crate plotline 

Branching sequences with subroutines and external waits.

A sequence is an ordered list of steps:

say "Hello, traveler."
say "Have you seen my ring?"
[choice] "Yes"  ──▶ ring_found
         "No"   ──▶ ring_lost

ring_found:  remove item "gold ring"
             advance quest "The Lost Ring" to stage 2
             say "You have my thanks."

plotline runs order, branches, calls, returns, jumps, and waits. The host defines the steps. Use it for dialog, quests, cutscenes, tutorials — any authored flow that must not depend on an engine.

The pieces

Sequence stores shared steps. Runner stores run state. Library stores sequences and creates their SequenceRef handles. Steps use Condition to read state and Effect to change it; both connect the host systems and also work outside the runner.

Control flow

Progress::Call enters a subroutine, and falling off its end returns to the caller. Progress::Return exits the current subroutine early. Progress::Goto clears the whole call chain before starting its target, or ends the chain when it has no target.

No clock

A step that needs to wait returns Progress::Wait with a Completion handle. The host signals the handle and calls Runner::advance. A multi-phase step can instead return Progress::Resume and manage its own per-run state through StepRun. The crate does not define timed waits.

Built-ins

The steps, conditions, and effects modules cover the common cases. steps::run wraps a closure; its body can return (), a Completion, a Progress, or any other type that implements IntoProgress. conditions::check and effects::run give the same closure-first style for conditions and effects, and steps::when conditionally runs any step. Constructors such as conditions::flag, effects::set_flag, steps::goto, and steps::stop are shorthand over the public structs and do not remove the struct-literal API.

Validation and analysis

Library::validate reports empty or duplicate names, step and nested-object warnings, and references to missing sequences. It permits cycles, which are valid in authored graphs. StepFacts::references exposes every outgoing sequence reference, including both sides of a branch. FlowModel computes reachability for one sequence — the basis for an editor’s rail display.

Diagnostics

The runner reports RunnerEvent values; the host drains them with Runner::drain_events and decides how to log them. Context::note adds location-tagged notes from inside a step.

Feature flags

The default std feature catches panics in steps, which requires panic = "unwind". Without it, the crate uses alloc only and does not catch panics.

Modules

conditions

Built-in conditions.

effects

Built-in effects.

steps

Built-in steps.

Structs

ChainFlags

Named boolean flags shared by all sequences in a chain.

Completion

A thread-safe, one-shot completion handle.

Context

State and services available during one step call.

EffectCtx

Mutable context for an Effect.

FlowModel

Reachability analysis for one sequence.

Iter

Iterator over sequence steps.

Library

Owns sequences and creates their SequenceRef handles.

QueryCtx

Read-only context for a Condition.

RailNode

Analysis data for one step.

Runner

Runs one chain at a time.

RunnerConfig

Limits for one runner.

Sequence

An ordered list of shared steps.

SequenceRef

An opaque sequence handle.

StepFacts

Snapshot of a step’s reported facts.

TypeMap

A registry with one value per type.

ValidationWarning

One warning produced by Library::validate.

Enums

AbortReason

Why a chain was aborted.

Flow

Whether execution continues after a step.

Outcome

Result of Runner::advance.

Progress

Result of one step execution.

RailShape

Shape of an analysis node.

RunnerEvent

Diagnostic event emitted by the runner.

SkipReason

Why a step was skipped.

StartError

Why Runner::start failed.

Traits

Condition

A yes/no query.

Effect

An action that completes in one call.

IntoProgress

Converts common closure results to Progress.

SequenceFacts

Read-only sequence facts for analysis and editors.

SequenceSource

Sequence facts plus step execution.

Step

Shared configuration and execution for one sequence step.

StepRun

Per-run state for a multi-phase step.

Type Aliases

ChainGuard

Host-owned value held for the life of a chain.