Story class
A Story is the core class that represents a complete Ink narrative, and
manages the evaluation and state of it.
Constructors
-
Story(Container? contentContainer, [List<ListDefinition>? lists])
-
-
Story.fromJson(String jsonString)
-
Construct a Story object using a JSON string compiled through inklecate.
factory
Properties
-
aliveFlowNames
→ List<String>
-
no setter
-
allowExternalFunctionFallbacks
↔ bool
-
An ink file can provide a fallback functions for when when an EXTERNAL has been left
unbound by the client, and the fallback function will be called instead. Useful when
testing a story in playmode, when it's not possible to write a client-side C# external
function, but you don't want it to fail to run.
getter/setter pair
-
asyncContinueComplete
→ bool
-
If ContinueAsync was called (with milliseconds limit > 0) then this property
will return false if the ink evaluation isn't yet finished, and you need to call
it again in order for the Continue to fully complete.
no setter
-
canContinue
→ bool
-
Check whether more content is available if you were to call - i.e.
are we mid story rather than at a choice point or at the end.
no setter
-
currentChoices
→ List<Choice>
-
The list of Choice objects available at the current point in
the Story. This list will be populated as the Story is stepped
through with the Continue() method. Once canContinue becomes
false, this list will be populated, and is usually
(but not always) on the final Continue() step.
no setter
-
currentErrors
→ List<String>?
-
Any errors generated during evaluation of the Story.
no setter
-
currentFlowIsDefaultFlow
→ bool
-
no setter
-
currentFlowName
→ String
-
no setter
-
currentTags
→ List<String>
-
Gets a list of tags as defined with '#' in source that were seen
during the latest Continue() call.
no setter
-
currentText
→ String?
-
The latest line of text to be generated from a Continue() call.
no setter
-
currentWarnings
→ List<String>?
-
Any warnings generated during evaluation of the Story.
no setter
-
debugMetadata
↔ DebugMetadata?
-
getter/setter pairinherited
-
globalTags
→ List<String>
-
no setter
-
hasError
→ bool
-
Whether the currentErrors list contains any errors.
THIS MAY BE REMOVED - you should be setting an error handler directly
using Story.onError.
no setter
-
hashCode
→ int
-
The hash code for this object.
no setterinherited
-
hasWarning
→ bool
-
Whether the currentWarnings list contains any warnings.
no setter
-
listDefinitions
→ ListDefinitionsOrigin?
-
no setter
-
mainContentContainer
→ Container
-
no setter
-
onChoosePathString
↔ (void Function(String m, List<Object> objects)?)
-
Callback for when a path string is chosen
getter/setter pair
-
onCompleteEvaluateFunction
↔ (void Function(String m, List<Object> objects, String string, Object object)?)
-
Callback for when a function has been evaluated
This is necessary because evaluating a function can cause continuing
getter/setter pair
-
onDidContinue
↔ (void Function()?)
-
Callback for when ContinueInternal is complete
getter/setter pair
-
onError
↔ ErrorHandler?
-
Error handler for all runtime errors in ink - i.e. problems
with the source ink itself that are only discovered when playing
the story.
It's strongly recommended that you assign an error handler to your
story instance to avoid getting exceptions for ink errors.
getter/setter pair
-
onEvaluateFunction
↔ (void Function(String? m, List<Object> objects)?)
-
Callback for when a function is about to be evaluated
getter/setter pair
-
onMakeChoice
↔ (void Function(Choice choice)?)
-
Callback for when a choice is about to be executed
getter/setter pair
-
ownDebugMetadata
→ DebugMetadata
-
no setterinherited
-
parent
↔ RuntimeObject?
-
RuntimeObjects can be included in the main Story as a hierarchy.
Usually parents are Container objects. (TODO: Always?)
getter/setter pairinherited
-
path
→ Path
-
no setterinherited
-
rootContentContainer
→ Container?
-
no setterinherited
-
runtimeType
→ Type
-
A representation of the runtime type of the object.
no setterinherited
-
state
→ StoryState
-
The entire current state of the story including (but not limited to):
- Global variables
- Temporary variables
- Read/visit and turn counts
- The callstack and evaluation stacks
- The current threads
no setter
-
variablesState
→ VariablesState
-
The VariablesState object contains all the global variables in the story.
However, note that there's more to the state of a Story than just the
global variables. This is a convenience accessor to the full state object.
no setter
Methods
-
addError(String message, {bool isWarning = false, bool useEndLineNumber = false})
→ void
-
-
backgroundSaveComplete()
→ void
-
See CopyStateForBackgroundThreadSave. This method releases the
"frozen" save state, applying its patch that it was using internally.
-
BindExternalFunction(String funcName, Object? func(), {bool lookaheadSafe = false})
→ void
-
Bind a dart function to an ink EXTERNAL function declaration.
-
BindExternalFunction1<T1>(String funcName, Object? func(T1 t1), {bool lookaheadSafe = false})
→ void
-
Bind a dart function to an ink EXTERNAL function declaration.
-
BindExternalFunction2<T1, T2>(String funcName, Object? func(T1 t1, T2 t2), {bool lookaheadSafe = false})
→ void
-
Bind a dart function to an ink EXTERNAL function declaration.
-
BindExternalFunction3<T1, T2, T3>(String funcName, Object? func(T1 t1, T2 t2, T3 t3), {bool lookaheadSafe = false})
→ void
-
Bind a dart function to an ink EXTERNAL function declaration.
-
BindExternalFunction4<T1, T2, T3, T4>(String funcName, Object func(T1 t1, T2 t2, T3 t3, T4 t4), {bool lookaheadSafe = false})
→ void
-
Bind a dart function to an ink EXTERNAL function declaration.
-
bindExternalFunctionGeneral(String funcName, ExternalFunction func, {bool lookaheadSafe = true})
→ void
-
Most general form of function binding that returns an object
and takes an array of object parameters.
The only way to bind a function with more than 3 arguments.
-
BindExternalFunctionGeneral(String funcName, ExternalFunction func, {bool lookaheadSafe = true})
→ void
-
-
callExternalFunction(String funcName, int numberOfArguments)
→ void
-
-
chooseChoiceIndex(int choiceIdx)
→ void
-
Chooses the Choice from the currentChoices list with the given
index. Internally, this sets the current content path to that
pointed to by the Choice, ready to continue story evaluation.
-
ChooseChoiceIndex(int choiceIdx)
→ void
-
-
choosePath(Path p, {bool incrementingTurnIndex = true})
→ void
-
-
ChoosePathString(String path, {bool resetCallstack = true, List<Object> arguments = const []})
→ void
-
-
choosePathString(String path, {bool resetCallstack = true, List<Object> arguments = const []})
→ void
-
-
compactPathString(Path otherPath)
→ String
-
inherited
-
CompactPathString(Path otherPath)
→ String
-
inherited
-
contentAtPath(Path path)
→ SearchResult
-
-
Continue()
→ String?
-
Continue the story for one line of content, if possible.
If you're not sure if there's more content available, for example if you
want to check whether you're at a choice point or at the end of the story,
you should call before calling this function.
-
continueAsync(double millisecsLimitAsync)
→ void
-
An "asnychronous" version of Continue that only partially evaluates the ink,
with a budget of a certain time limit. It will exit ink evaluation early if
the evaluation isn't complete within the time limit, with the
asyncContinueComplete property being false.
This is useful if ink evaluation takes a long time, and you want to distribute
it over multiple game frames for smoother animation.
If you pass a limit of zero, then it will fully evaluate the ink in the same
way as calling Continue (and in fact, this exactly what Continue does internally).
-
continueMaximally()
→ String
-
Continue the story until the next choice point or until it runs out of content.
This is as opposed to the Continue() method which only evaluates one line of
output at a time.
-
ContinueMaximally()
→ String
-
-
convertPathToRelative(Path globalPath)
→ Path
-
inherited
-
CopyStateForBackgroundThreadSave()
→ StoryState
-
Advanced usage!
If you have a large story, and saving state to JSON takes too long for your
framerate, you can temporarily freeze a copy of the state for saving on
a separate thread. Internally, the engine maintains a "diff patch".
When you've finished saving your state, call BackgroundSaveComplete()
and that diff patch will be applied, allowing the story to continue
in its usual mode.
-
debugLineNumberOfPath(Path? path)
→ int?
-
inherited
-
EndProfiling()
→ void
-
Stop recording ink profiling information during calls to Continue on Story.
To generate a report from the profiler, call
-
error(String message, [bool useEndLineNumber = false])
→ void
-
-
EvaluateExpression(Container exprContainer)
→ RuntimeObject?
-
-
evaluateFunction(String functionName, [List<Object> arguments = const []])
→ Object
-
Evaluates a function defined in ink.
-
EvaluateFunction(String functionName, [List<Object> arguments = const []])
→ EvaluateFunctionTextOutput
-
-
evaluateFunctionString(String functionName, StringBuffer? textOutput, [List<Object> arguments = const []])
→ Object
-
Evaluates a function defined in ink, and gathers the possibly multi-line text as generated by the function.
This text output is any text written as normal content within the function, as opposed to the return value, as returned with `~ return`.
-
hasFunction(String functionName)
→ bool
-
Checks if a function exists.
-
ifAsyncWeCant(String activityStr)
→ void
-
-
IfAsyncWeCant(String activityStr)
→ void
-
-
KnotContainerWithName(String name)
→ Container?
-
-
knotContainerWithName(String name)
→ Container?
-
-
noSuchMethod(Invocation invocation)
→ dynamic
-
Invoked when a nonexistent method or property is accessed.
inherited
-
observeVariable(String variableName, VariableObserver observer)
→ void
-
When the named global variable changes it's value, the observer will be
called to notify it of the change. Note that if the value changes multiple
times within the ink, the observer will only be called once, at the end
of the ink's evaluation. If, during the evaluation, it changes and then
changes back again to its original value, it will still be called.
Note that the observer will also be fired if the value of the variable
is changed externally to the ink, by directly setting a value in
story.variablesState.
-
pointerAtPath(Path path)
→ Pointer
-
-
PopChoiceStringAndTags(List<String> tags)
→ String
-
-
resetCallstack()
→ void
-
Unwinds the callstack. Useful to reset the Story's evaluation
without actually changing any meaningful state, for example if
you want to exit a section of story prematurely and tell it to
go elsewhere with a call to ChoosePathString(...).
Doing so without calling ResetCallstack() could cause unexpected
issues if, for example, the Story was in a tunnel already.
-
ResetCallstack()
→ void
-
-
ResetErrors()
→ void
-
-
resetGlobals()
→ void
-
-
resetState()
→ void
-
Reset the Story back to its initial state as it was when it was
first constructed.
-
resolvePath(Path? path)
→ SearchResult
-
inherited
-
setChild<T extends RuntimeObject>(T? obj, T? value)
→ void
-
inherited
-
StartProfiling()
→ Profiler
-
Start recording ink profiling information during calls to Continue on Story.
Return a Profiler instance that you can request a report from when you're finished.
-
switchFlow(String flowName)
→ void
-
-
SwitchFlow(String flowName)
→ void
-
-
TagsAtStartOfFlowContainerWithPathString(String pathString)
→ List<String>
-
-
TagsForContentAtPath(String path)
→ List<String>
-
-
toString()
→ String
-
A string representation of this object.
inherited
-
tryCoerce<T>(dynamic value)
→ dynamic
-
-
TryCoerce<T>(Object value)
→ dynamic
-
-
UnbindExternalFunction(String funcName)
→ void
-
-
unbindExternalFunction(String funcName)
→ void
-
Remove a binding for a named EXTERNAL ink function.
-
ValidateExternalBindings()
→ void
-
-
validateExternalBindings()
→ void
-
Check that all EXTERNAL ink functions have a valid bound C# function.
Note that this is automatically called on the first call to Continue().
-
warning(String s)
→ void
-
Static Properties
-
debug
↔ bool
-
getter/setter pair
