Caller-owned interpreter over a compiled sequence asset. 更多...

#include <SequenceRuntime.h>

类
struct	Event
	One observable transition; every field is owned by the event. 更多...

Public 类型
enum class	EventKind : std::uint8_t { Started , NodeEntered , Blocked , Stepped , Resumed , Ended , Failed }
	Observable runtime transition. 更多...

using	AssetResolver = std::function< const SequenceAsset *(const std::string &)>
	Resolves a called asset id to a borrowed, externally owned asset.

using	ConditionEvaluator = std::function< SequenceConditionOutcome(const eve::Value &)>
	Evaluates one authored condition value.

using	EventSink = std::function< void(const Event &)>
	Single event outlet; invoked synchronously without locks.

Public 成员函数
eve::Result< void >	start (const SequenceAsset *asset, eve::Value bindings=eve::Value::Object{})
	Begin a sequence at the asset entry node.

eve::Result< void >	runUntilBlocked ()
	Execute nodes until the sequence blocks, ends or fails.

eve::Result< void >	advance ()
	Acknowledge a host-presented `wait` or handler-less `Await` step.

eve::Result< void >	select (std::string_view routeLabel)
	Answer a blocked `choice` node by route label.

eve::Result< void >	selectRouteForTransaction (std::string_view routeLabel)
	Enter one already prepared choice route transactionally.

eve::Result< void >	resumeStep (eve::Value result)
	Resume a step whose handler returned `Blocked`.

eve::Result< void >	resumeCommand (std::string_view requestId, eve::StateValue result)
	Resume the exact blocked command with a legacy state value.

eve::Result< void >	resumeCommand (std::string_view requestId, eve::Value result)
	Resume the exact blocked command with a canonical value.

void	stop ()
	Stop and clear the active sequence without emitting `Ended`.

eve::Result< void >	captureState (eve::Value &out) const
	Capture the complete cursor, bindings, locals and call stack.

eve::Result< void >	restoreState (const eve::Value &in)
	Restore a captured cursor through the configured asset resolver.

void	setAssetResolver (AssetResolver resolver)

void	setConditionEvaluator (ConditionEvaluator evaluator)

void	setStepRegistry (const StepKindRegistry *registry)
	Bind the step vocabulary; passing nullptr disables non-core steps.

void	registerCommand (std::string name, SequenceCommandHandler handler)
	Register a named generic command handler.

void	unregisterCommand (std::string_view name)
	Remove a named generic command handler.

void	setCommandDispatcher (SequenceCommandHandler dispatcher)
	Install the catch-all command dispatcher used after named lookup.

void	clearCommandDispatcher ()
	Remove the catch-all command dispatcher.

void	setHostContext (void *host)
	Install the opaque consumer context forwarded to every step handler.

void	setEventSink (EventSink sink)

bool	isActive () const
	Whether a sequence is currently loaded.

bool	isBlocked () const
	Whether execution is suspended and awaiting host acknowledgement.

bool	isWaitingStep () const
	Whether the suspension is a step awaiting `resumeStep`.

bool	isWaitingCommand () const
	Whether the suspension is a command awaiting `resumeCommand`.

const SequenceAsset *	asset () const
	Borrowed active asset, or nullptr. @lifetime Owned by the caller of `start`.

const SequenceNode *	currentNode () const
	Borrowed current node, or nullptr. @lifetime Invalidated by the next transition.

const std::string &	currentNodeId () const

const eve::Value &	bindings () const

const eve::Value &	locals () const

eve::Value &	locals ()

const eve::Value &	lastStepResult () const
	Value supplied by the most recent `resumeStep`.

const SequenceCommandRequest *	lastCommandRequest () const
	Last emitted command request, or nullptr when none has been emitted.

const std::string &	pendingCommandRequestId () const noexcept
	Stable id of the blocked command, or an empty string.

const SequenceConditionOutcome *	lastConditionResult () const
	Last evaluated condition outcome.

静态 Public 属性
static constexpr std::string_view	SaveSchema = "eve.dialogue.runner"
	Stable cursor save schema retained across the L1 ownership migration.

static constexpr std::int64_t	SaveVersion = 2
	Current cursor save schema version.

static constexpr int	kExecutionBudget = 10000
	Upper bound on nodes executed by one `runUntilBlocked` call.

详细描述

Caller-owned interpreter over a compiled sequence asset.

The runtime owns only the execution cursor: the current asset, node, call stack, parameter bindings and step locals. Persistent progress, completion facts and gameplay state stay with the domain owner that persists them.

The runtime never interprets a step payload. Control-flow types (branch / choice / call / command / wait / end) are handled here; every other type is routed through the configured StepKindRegistry.

在文件 SequenceRuntime.h 第 67 行定义.

成员类型定义说明

◆ AssetResolver

using eve::dnut::SequenceRuntime::AssetResolver = std::function<const SequenceAsset*(const std::string&)>

Resolves a called asset id to a borrowed, externally owned asset.

在文件 SequenceRuntime.h 第 75 行定义.

◆ ConditionEvaluator

using eve::dnut::SequenceRuntime::ConditionEvaluator = std::function<SequenceConditionOutcome(const eve::Value&)>

Evaluates one authored condition value.

Consumers adapt their own condition system (for example eve::decision::Condition) to this contract, so the language core does not depend on any domain or decision module.

在文件 SequenceRuntime.h 第 83 行定义.

◆ EventSink

using eve::dnut::SequenceRuntime::EventSink = std::function<void(const Event&)>

Single event outlet; invoked synchronously without locks.

在文件 SequenceRuntime.h 第 97 行定义.

成员枚举类型说明

◆ EventKind

enum class eve::dnut::SequenceRuntime::EventKind : std::uint8_t

strong

Observable runtime transition.

枚举值
Started
NodeEntered
Blocked
Stepped
Resumed
Ended
Failed

在文件 SequenceRuntime.h 第 86 行定义.

成员函数说明

◆ advance()

eve::Result< void > eve::dnut::SequenceRuntime::advance ( )

Acknowledge a host-presented wait or handler-less Await step.

返回: Success, or a failure while preserving the current cursor.

备注: Rejects a choice node: a choice must be answered with select.

在文件 SequenceRuntime.cpp 第 396 行定义.

引用了 currentNode(), node, eve::Result< void >::ok() , 以及 eve::PreconditionViolation.

被这些函数引用 eve::dialogue::DialogueFlow::advanceChecked().

◆ asset()

const SequenceAsset * eve::dnut::SequenceRuntime::asset ( ) const

inline

Borrowed active asset, or nullptr. @lifetime Owned by the caller of start.

在文件 SequenceRuntime.h 第 218 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::getConversationId() , 以及 start().

◆ bindings()

const eve::Value & eve::dnut::SequenceRuntime::bindings ( ) const

inline

在文件 SequenceRuntime.h 第 222 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::getText() , 以及 start().

◆ captureState()

eve::Result< void > eve::dnut::SequenceRuntime::captureState ( eve::Value & out ) const

Capture the complete cursor, bindings, locals and call stack.

参数

out	Receives an owning object value usable by `restoreState`.

返回: Success; capturing a stopped runtime yields {"active":false}.

在文件 SequenceRuntime.cpp 第 534 行定义.

引用了 eve::Value::boolean(), eve::Value::integer(), SaveSchema, SaveVersion, eve::Value::set(), eve::Value::string() , 以及 eve::Result< T >::success().

被这些函数引用 eve::dialogue::DialogueFlow::captureStateChecked(), eve::rpg::RpgStorySession::Impl::persistProgress() , 以及 eve::dialogue::DialogueFlow::select().

◆ clearCommandDispatcher()

void eve::dnut::SequenceRuntime::clearCommandDispatcher ( )

inline

Remove the catch-all command dispatcher.

在文件 SequenceRuntime.h 第 198 行定义.

◆ currentNode()

const SequenceNode * eve::dnut::SequenceRuntime::currentNode ( ) const

Borrowed current node, or nullptr. @lifetime Invalidated by the next transition.

在文件 SequenceRuntime.cpp 第 74 行定义.

引用了 eve::dnut::SequenceAsset::findNode().

被这些函数引用 advance(), eve::dialogue::DialogueFlow::getNodeKind(), eve::dialogue::DialogueFlow::getRouteCount(), eve::dialogue::DialogueFlow::getRouteId(), eve::dialogue::DialogueFlow::getRouteText(), eve::dialogue::DialogueFlow::getText(), eve::dialogue::DialogueFlow::getVoice(), eve::dialogue::DialogueFlow::getVoiceDuration(), eve::dialogue::DialogueFlow::getVoiceStatus(), resumeStep() , 以及 eve::dialogue::DialogueFlow::select().

◆ currentNodeId()

const std::string & eve::dnut::SequenceRuntime::currentNodeId ( ) const

inline

在文件 SequenceRuntime.h 第 221 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::getNodeId().

◆ isActive()

bool eve::dnut::SequenceRuntime::isActive ( ) const

inline

Whether a sequence is currently loaded.

在文件 SequenceRuntime.h 第 210 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::isActive(), eve::rpg::RpgStorySession::Impl::persistProgress(), eve::dialogue::DialogueFlow::removeSourceChecked(), eve::dialogue::DialogueFlow::renameConversationChecked() , 以及 eve::dialogue::DialogueFlow::renameNodeChecked().

◆ isBlocked()

bool eve::dnut::SequenceRuntime::isBlocked ( ) const

inline

Whether execution is suspended and awaiting host acknowledgement.

在文件 SequenceRuntime.h 第 212 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::isBlocked().

◆ isWaitingCommand()

bool eve::dnut::SequenceRuntime::isWaitingCommand ( ) const

inline

Whether the suspension is a command awaiting resumeCommand.

在文件 SequenceRuntime.h 第 216 行定义.

◆ isWaitingStep()

bool eve::dnut::SequenceRuntime::isWaitingStep ( ) const

inline

Whether the suspension is a step awaiting resumeStep.

在文件 SequenceRuntime.h 第 214 行定义.

◆ lastCommandRequest()

const SequenceCommandRequest * eve::dnut::SequenceRuntime::lastCommandRequest ( ) const

inline

Last emitted command request, or nullptr when none has been emitted.

在文件 SequenceRuntime.h 第 228 行定义.

◆ lastConditionResult()

const SequenceConditionOutcome * eve::dnut::SequenceRuntime::lastConditionResult ( ) const

inline

Last evaluated condition outcome.

返回: Borrowed nullable pointer owned by this runtime. @lifetime Valid until the next condition evaluation, stop, or destruction.

在文件 SequenceRuntime.h 第 238 行定义.

◆ lastStepResult()

const eve::Value & eve::dnut::SequenceRuntime::lastStepResult ( ) const

inline

Value supplied by the most recent resumeStep.

在文件 SequenceRuntime.h 第 226 行定义.

◆ locals() [1/2]

eve::Value & eve::dnut::SequenceRuntime::locals ( )

inline

在文件 SequenceRuntime.h 第 224 行定义.

◆ locals() [2/2]

const eve::Value & eve::dnut::SequenceRuntime::locals ( ) const

inline

在文件 SequenceRuntime.h 第 223 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::getText().

◆ pendingCommandRequestId()

const std::string & eve::dnut::SequenceRuntime::pendingCommandRequestId ( ) const

inlinenoexcept

Stable id of the blocked command, or an empty string.

在文件 SequenceRuntime.h 第 232 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::getPendingCommandRequestId().

◆ registerCommand()

void eve::dnut::SequenceRuntime::registerCommand	(	std::string	name,
		SequenceCommandHandler	handler
	)

Register a named generic command handler.

在文件 SequenceRuntime.cpp 第 136 行定义.

引用了 handler , 以及 name.

◆ restoreState()

eve::Result< void > eve::dnut::SequenceRuntime::restoreState ( const eve::Value & in )

Restore a captured cursor through the configured asset resolver.

参数

in	Value previously produced by `captureState`.

返回: Success, or a structured failure that leaves the runtime unchanged.

备注: A saved asset whose version no longer matches is rejected rather than silently replayed against changed content.

在文件 SequenceRuntime.cpp 第 554 行定义.

引用了 active, eve::Value::arraySize(), eve::Value::asBool(), eve::Value::asInt(), eve::Value::asString(), eve::Value::at(), Blocked, eve::Conflict, current, eve::Value::find(), eve::dnut::SequenceAsset::findNode(), index, eve::InvalidArgument, eve::Value::isArray(), eve::Value::isBool(), eve::Value::isInt64(), eve::Value::isObject(), eve::Value::isString(), name, nodeId, eve::NotFound, eve::dnut::SequenceNode::payload, eve::PreconditionViolation, request, eve::dnut::SequenceCommandRequest::requestId, SaveSchema, SaveVersion, stop(), eve::Result< T >::success(), eve::dnut::SequenceNode::type, eve::UnknownVersion , 以及 eve::dnut::SequenceAsset::version.

被这些函数引用 eve::dialogue::DialogueFlow::restoreStateChecked() , 以及 eve::dialogue::DialogueFlow::restoreStateJsonChecked().

◆ resumeCommand() [1/2]

eve::Result< void > eve::dnut::SequenceRuntime::resumeCommand	(	std::string_view	requestId,
		eve::StateValue	result
	)

Resume the exact blocked command with a legacy state value.

参数

requestId	Stable request id exposed by `pendingCommandRequestId`.
result	Owning result stored in the command's `resultLocal`, if any.

在文件 SequenceRuntime.cpp 第 492 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::resumeCommandChecked().

◆ resumeCommand() [2/2]

eve::Result< void > eve::dnut::SequenceRuntime::resumeCommand	(	std::string_view	requestId,
		eve::Value	result
	)

Resume the exact blocked command with a canonical value.

在文件 SequenceRuntime.cpp 第 496 行定义.

◆ resumeStep()

eve::Result< void > eve::dnut::SequenceRuntime::resumeStep ( eve::Value result )

Resume a step whose handler returned Blocked.

参数

result Owning result value exposed to the sequence.

返回: Success, or a failure while preserving the suspended cursor.

备注: When the suspended node payload names a result local, the value is stored there; it is always available through lastStepResult.

在文件 SequenceRuntime.cpp 第 465 行定义.

引用了 currentNode(), error, eve::Failed, eve::Value::find(), key, node, eve::Result< void >::ok(), eve::PreconditionViolation, Resumed, eve::Value::set() , 以及 eve::Result< T >::success().

◆ runUntilBlocked()

eve::Result< void > eve::dnut::SequenceRuntime::runUntilBlocked ( )

Execute nodes until the sequence blocks, ends or fails.

返回: Success on a suspension point or clean end, or a structured failure. @thread Owner thread only. @reentrancy As start.

在文件 SequenceRuntime.cpp 第 240 行定义.

◆ select()

eve::Result< void > eve::dnut::SequenceRuntime::select ( std::string_view routeLabel )

Answer a blocked choice node by route label.

参数

routeLabel Exact authored route label on the current choice node.

返回: Success, or a structured failure leaving the cursor unchanged.

备注: A route whose condition is rejected fails without advancing, so the caller can present the choice again.

在文件 SequenceRuntime.cpp 第 418 行定义.

◆ selectRouteForTransaction()

eve::Result< void > eve::dnut::SequenceRuntime::selectRouteForTransaction ( std::string_view routeLabel )

Enter one already prepared choice route transactionally.

备注: Uses capture → enter/run → restore, so a failed route keeps the exact suspended choice cursor.

在文件 SequenceRuntime.cpp 第 420 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::select().

◆ setAssetResolver()

void eve::dnut::SequenceRuntime::setAssetResolver ( AssetResolver resolver )

inline

在文件 SequenceRuntime.h 第 187 行定义.

被这些函数引用 eve::rpg::RpgStorySession::Impl::configureRuntime() , 以及 eve::dialogue::DialogueFlow::DialogueFlow().

◆ setCommandDispatcher()

void eve::dnut::SequenceRuntime::setCommandDispatcher ( SequenceCommandHandler dispatcher )

inline

Install the catch-all command dispatcher used after named lookup.

在文件 SequenceRuntime.h 第 196 行定义.

◆ setConditionEvaluator()

void eve::dnut::SequenceRuntime::setConditionEvaluator ( ConditionEvaluator evaluator )

inline

在文件 SequenceRuntime.h 第 188 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::configureIntegration() , 以及 eve::rpg::RpgStorySession::Impl::configureRuntime().

◆ setEventSink()

void eve::dnut::SequenceRuntime::setEventSink ( EventSink sink )

inline

在文件 SequenceRuntime.h 第 207 行定义.

◆ setHostContext()

void eve::dnut::SequenceRuntime::setHostContext ( void * host )

inline

Install the opaque consumer context forwarded to every step handler.

参数

host	Borrowed pointer the core stores but never dereferences. @ownership Borrowed; the caller keeps it alive for as long as the runtime may dispatch. @thread Set on the owner thread before the next `runUntilBlocked`. @reentrancy Does not invoke callbacks.

在文件 SequenceRuntime.h 第 206 行定义.

引用了 host.

被这些函数引用 eve::rpg::RpgStorySession::Impl::configureRuntime().

◆ setStepRegistry()

void eve::dnut::SequenceRuntime::setStepRegistry ( const StepKindRegistry * registry )

inline

Bind the step vocabulary; passing nullptr disables non-core steps.

在文件 SequenceRuntime.h 第 190 行定义.

被这些函数引用 eve::rpg::RpgStorySession::Impl::configureRuntime() , 以及 eve::dialogue::DialogueFlow::DialogueFlow().

◆ start()

eve::Result< void > eve::dnut::SequenceRuntime::start	(	const SequenceAsset *	asset,
		eve::Value	bindings = `eve::Value::Object{}`
	)

Begin a sequence at the asset entry node.

参数

asset	Borrowed asset; it must outlive the runtime.
bindings	Owning parameter bindings; must be an object.

返回: Success after the sequence reaches its first suspension point.

备注: Validation and execution are transactional; a rejected start leaves the prior runtime state unchanged. @thread Owner thread only. @reentrancy Emits events synchronously; the sink must not re-enter this runtime.

在文件 SequenceRuntime.cpp 第 142 行定义.

引用了 asset(), bindings(), eve::dnut::SequenceAsset::entry, eve::Value::find(), eve::dnut::SequenceAsset::id, eve::InvalidArgument, eve::Value::isObject(), key, eve::Value::keys(), eve::dnut::SequenceAsset::parameters, eve::dnut::sequenceParameterTypeName(), eve::Value::set(), Started, eve::dnut::SequenceAsset::validate() , 以及 value.

被这些函数引用 eve::dialogue::DialogueFlow::startChecked().

◆ stop()

void eve::dnut::SequenceRuntime::stop ( )

Stop and clear the active sequence without emitting Ended.

在文件 SequenceRuntime.cpp 第 121 行定义.

被这些函数引用 eve::dialogue::DialogueFlow::clear() , 以及 restoreState().

◆ unregisterCommand()

void eve::dnut::SequenceRuntime::unregisterCommand ( std::string_view name )

Remove a named generic command handler.

在文件 SequenceRuntime.cpp 第 140 行定义.

引用了 name.

类成员变量说明

◆ kExecutionBudget

constexpr int eve::dnut::SequenceRuntime::kExecutionBudget = 10000

staticconstexpr

Upper bound on nodes executed by one runUntilBlocked call.

Authored content can contain a cycle by mistake; the budget turns that into an observable failure instead of a hang.

在文件 SequenceRuntime.h 第 105 行定义.

◆ SaveSchema

constexpr std::string_view eve::dnut::SequenceRuntime::SaveSchema = "eve.dialogue.runner"

staticconstexpr

Stable cursor save schema retained across the L1 ownership migration.

在文件 SequenceRuntime.h 第 70 行定义.

被这些函数引用 captureState() , 以及 restoreState().

◆ SaveVersion

constexpr std::int64_t eve::dnut::SequenceRuntime::SaveVersion = 2

staticconstexpr

Current cursor save schema version.

在文件 SequenceRuntime.h 第 72 行定义.

被这些函数引用 captureState() , 以及 restoreState().

该类的文档由以下文件生成:

src/modules/dnut_interpreter/SequenceRuntime.h
src/modules/dnut_interpreter/SequenceRuntime.cpp

类

Public 类型

Public 成员函数

静态 Public 属性

详细描述

成员类型定义说明

◆ AssetResolver

◆ ConditionEvaluator

◆ EventSink

成员枚举类型说明

◆ EventKind

成员函数说明

◆ advance()

◆ asset()

◆ bindings()

◆ captureState()

◆ clearCommandDispatcher()

◆ currentNode()

◆ currentNodeId()

◆ isActive()

◆ isBlocked()

◆ isWaitingCommand()

◆ isWaitingStep()

◆ lastCommandRequest()

◆ lastConditionResult()

◆ lastStepResult()

◆ locals() [1/2]

◆ locals() [2/2]

◆ pendingCommandRequestId()

◆ registerCommand()

◆ restoreState()

◆ resumeCommand() [1/2]

◆ resumeCommand() [2/2]

◆ resumeStep()

◆ runUntilBlocked()

◆ select()

◆ selectRouteForTransaction()

◆ setAssetResolver()

◆ setCommandDispatcher()

◆ setConditionEvaluator()

◆ setEventSink()

◆ setHostContext()

◆ setStepRegistry()

◆ start()

◆ stop()

◆ unregisterCommand()

类成员变量说明

◆ kExecutionBudget

◆ SaveSchema

◆ SaveVersion