NarrativeEngine class
NarrativeEngine - Core processor for in-game sentence execution
This class is responsible for executing in-game sentences one by one, enabling narration, player interaction, and navigation control.
It uses a ListQueue to manage upcoming sentences and exposes
processed ones through callbacks for display.
Each sentence is delegated to a NarrativeInterpreter for instruction parsing.
Key Responsibilities:
- Manage sentence queue (enqueue, process, clear)
- Control execution flow (pause, resume, cancel, complete)
- Support external stream listeners for engine status updates
- Integrate blocking flow (e.g., wait for user tap)
- Deduplicate writing using external
SafeNarrativeWriter
Usage Example:
final engine = NarrativeEngine(
onStatusChange: (status) => print('Status: $status'),
onSentencesChanged: (sentences) => setState(() {}),
);
engine.registerInterpreter(myInterpreter);
engine.enqueue(sentences);
engine.process(onComplete: () => print("Done"));
Constructors
-
NarrativeEngine({ValueChanged<
ProcessingStatus> ? onStatusChange, ValueChanged<List< ? onSentencesChanged, ValueChanged<BaseNarrativeModel> >int> ? onProcessingIndexChanged, NarrativeInterpreter? interpreter}) - Constructor with optional status change and sentences changed callbacks.
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- interpreter ↔ NarrativeInterpreter?
-
Interpreter responsible for executing sentence logic (read, write, ask, etc.)
getter/setter pair
-
onProcessingIndexChanged
→ ValueChanged<
int> ? -
Callback when processing index changes.
final
-
onSentencesChanged
→ ValueChanged<
List< ?BaseNarrativeModel> > -
Callback when processed sentences list changes.
final
-
onStatusChange
→ ValueChanged<
ProcessingStatus> ? -
Callback for status changes (idle, processing, paused, etc.)
final
-
onStatusChanged
→ Stream<
ProcessingStatus> -
Stream of status changes (useful for UI or controllers).
no setter
- processingIndex → int
-
Index of the currently processing sentence.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
-
sentences
→ List<
BaseNarrativeModel> -
List of displayed/written sentences.
no setter
- status → ProcessingStatus
-
Current processing status.
no setter
Methods
-
addSentenceToWritten(
BaseNarrativeModel baseSentenceModel) → void - Appends a sentence to the visible list of written sentences.
-
cancel(
) → void - Cancels sentence processing and resets everything.
-
clearProcessedSentences(
) → void - Clears all processed sentences.
-
continueAfterUserInput(
) → void - Resumes processing if waiting on user input.
-
dispose(
) → void - Disposes resources (call when done with the engine).
-
enqueue(
List< BaseNarrativeModel> newSentences) → void - Adds new sentences to the queue to be processed.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
pause(
) → void - Pauses the engine (useful for "tap to continue" style interactions).
-
pauseUntilUserContinues(
) → Future< void> -
Pauses execution and blocks until
continueAfterUserInput()is called. -
process(
{VoidCallback? onComplete, VoidCallback? onInterrupted}) → Future< void> - Starts processing the sentence queue.
-
registerInterpreter(
NarrativeInterpreter interpreter) → void - Registers or replaces the sentence interpreter.
-
reset(
) → void - Completely clears all internal state.
-
resume(
) → void - Resumes the engine from a paused state.
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited