Class TyphonRuntime

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

Top-level runtime for Typhon game servers. Wraps DatabaseEngine and DagScheduler, managing the per-tick UoW/Transaction lifecycle so game developers never handle commits manually.

public sealed class TyphonRuntime : IDisposable

Inheritance

object

TyphonRuntime

Implements

IDisposable

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Each tick: creates a UoW (Deferred) → for each CallbackSystem/QuerySystem, creates a Transaction on the executing worker thread (respecting thread affinity) → commits after each system → flushes UoW at tick end.

Pipeline systems do not receive Transactions — their entity access goes through Gather/Scatter pipelines.

Properties

CurrentOverloadLevel

Current overload response level.

public OverloadLevel CurrentOverloadLevel { get; }

Property Value

OverloadLevel

CurrentTickNumber

Number of ticks executed so far.

public long CurrentTickNumber { get; }

Property Value

long

Engine

The underlying database engine.

public DatabaseEngine Engine { get; }

Property Value

DatabaseEngine

LastTickOutcome

Outcome of the most recently completed tick. Refreshed every tick under every SystemExceptionPolicy, so it is never stale.

public TickOutcome LastTickOutcome { get; }

Property Value

TickOutcome

Remarks

This is the primary surface for a host that gates its own publication on tick success: it is pull-checkable, so the host's next loop iteration can ask "did that tick succeed?" without having subscribed to anything, and a host that wires up late does not silently miss the answer. OnTickAborted is the push counterpart.

Options

The runtime options this runtime was created with. The profiler derives session metadata from these.

public RuntimeOptions Options { get; }

Property Value

RuntimeOptions

PublishedViews

The published View registry (for diagnostics and testing).

public PublishedViewRegistry PublishedViews { get; }

Property Value

PublishedViewRegistry

Scheduler

The DAG scheduler driving tick execution.

public DagScheduler Scheduler { get; }

Property Value

DagScheduler

Systems

All registered systems including engine-internal ones (e.g. FenceExec). Use this when you need the full system list, indexed by canonical system index. For "the systems the user registered" use UserSystems instead.

public SystemDefinition[] Systems { get; }

Property Value

SystemDefinition[]

Telemetry

Telemetry ring buffer for diagnostic inspection.

public TickTelemetryRing Telemetry { get; }

Property Value

TickTelemetryRing

UserSystems

User-registered systems only (filters out engine-tagged-track systems such as the Fence DAG).

public SystemDefinition[] UserSystems { get; }

Property Value

SystemDefinition[]

Methods

Create(DatabaseEngine, Action<RuntimeSchedule>, RuntimeOptions, IResource, ILogger, IServiceProvider)

Creates a new TyphonRuntime from a DatabaseEngine and a schedule configuration.

public static TyphonRuntime Create(DatabaseEngine engine, Action<RuntimeSchedule> configure, RuntimeOptions options = null, IResource parent = null, ILogger logger = null, IServiceProvider serviceProvider = null)

Parameters

engine DatabaseEngine

The database engine for entity storage.

configure Action<RuntimeSchedule>

Action to register systems on the RuntimeSchedule.

options RuntimeOptions

Runtime options. If null, defaults are used.

parent IResource

Parent resource node. If null, uses the registry's Runtime node.

logger ILogger

Optional logger.

serviceProvider IServiceProvider

Optional DI container. When supplied, a profiler-launch override registered via AddTyphonProfiler is resolved from it. The zero-host-code profiler path works without it — pass it only when a host wants to override config in code.

Returns

TyphonRuntime

CreateSideTransaction(DurabilityMode, CommitDiscipline)

Creates a side-transaction with the specified durability mode. The caller owns the returned Transaction and must Commit + Dispose it. Side-transactions are NOT visible to the current tick's main Transactions (snapshot isolation).

public Transaction CreateSideTransaction(DurabilityMode durability = DurabilityMode.Immediate, CommitDiscipline discipline = CommitDiscipline.TickFence)

Parameters

durability DurabilityMode

discipline CommitDiscipline

Returns

Transaction

Dispose()

public void Dispose()

FatalStop()

Stops the runtime without running the OnShutdown hook — the fatal path, for a host reacting to OnTickAborted (issue #567).

public void FatalStop()

Remarks

OnShutdown deliberately runs its handlers inside an Immediate transaction, which is the right thing for an orderly stop and the wrong thing after a fatal tick: the abort means the simulation is logically incomplete, so committing a final round of shutdown writes on top of it would persist state derived from a tick that never finished. Everything else — subscription server, profiler, scheduler — is torn down exactly as in Shutdown().

Neither this nor Shutdown() is a quiescence point. Both stop new ticks; neither waits for the tick in flight. The expected caller is an OnTickAborted handler, which runs on the tick thread — so this typically returns into the very tick it is stopping, which then finishes and posts its accounting. Dispose the runtime when you need "nothing is running": Dispose() joins the tick thread.

PublishView(string, Func<ClientContext, ViewBase>, SubscriptionPriority)

Publish a per-client View factory. A new View is created per subscriber, parameterized by ClientContext.

public PublishedView PublishView(string name, Func<ClientContext, ViewBase> factory, SubscriptionPriority priority = SubscriptionPriority.Normal)

Parameters

name string

Human-readable name clients use to identify this subscription.

factory Func<ClientContext, ViewBase>

Factory that creates a View for each subscribing client.

priority SubscriptionPriority

Subscription priority for overload throttling.

Returns

PublishedView

The published View handle.

PublishView(string, ViewBase, SubscriptionPriority)

Publish a shared View for client subscriptions. All subscribers see the same data; the delta is serialized once and memcpy'd.

public PublishedView PublishView(string name, ViewBase view, SubscriptionPriority priority = SubscriptionPriority.Normal)

Parameters

name string

Human-readable name clients use to identify this subscription.

view ViewBase

A dedicated ViewBase instance for subscriptions.

priority SubscriptionPriority

Subscription priority for overload throttling.

Returns

PublishedView

The published View handle.

Remarks

The View must be a dedicated instance — it must NOT be used as a system input. Published Views are refreshed only during the Output phase; using the same View as system input would consume ring buffer entries needed by subscriptions.

RegisterContext<TContext>(TContext)

Bind an ambient context onto every registered system deriving from ChunkedCallbackSystem<TContext>. Must be called after Configure (systems must already be registered) and before Start().

public void RegisterContext<TContext>(TContext context) where TContext : class

Parameters

context TContext

Type Parameters

TContext

SetSubscriptions(ClientContext, params PublishedView[])

Set a client's subscription set. Replaces the previous set atomically. The transition is applied during the next tick's Output phase. Looks up the connection by ConnectionId — the public client identity. If the connection has been dropped between the caller obtaining the context and this call, the request is silently ignored (the next tick will see no pending change for a disposed client anyway).

public void SetSubscriptions(ClientContext client, params PublishedView[] views)

Parameters

client ClientContext

views PublishedView[]

Remarks

If called multiple times within a tick, the last call wins.

Shutdown()

Gracefully shuts down the runtime. Stops the subscription server, fires OnShutdown, then stops the scheduler.

public void Shutdown()

Start()

Starts the scheduler (worker threads + tick driver) and the subscription server (if configured).

public void Start()

Events

OnCriticalOverload

Fires when overload reaches PlayerShedding. Game code decides what to do (migrate, disconnect, split).

public event Action<TyphonRuntime> OnCriticalOverload

Event Type

Action<TyphonRuntime>

OnFirstTick

Fired once on the first tick. Use to rebuild transient state after crash recovery. The callback receives a valid Transaction for entity operations.

public event Action<TickContext> OnFirstTick

Event Type

Action<TickContext>

OnShutdown

Fired during Shutdown(). Use for cleanup (save player state, etc.). The callback receives a dedicated Transaction (Immediate durability).

public event Action<TickContext> OnShutdown

Event Type

Action<TickContext>

OnTickAborted

Fires once when a tick is aborted under AbortTickAndStop, on the tick thread, after the tick has fully drained. Never fires for a successful tick, and never fires twice — the runtime is terminal after an abort. The handler should stop the runtime (FatalStop()) and let the host decide whether to exit or rebuild the engine.

"Drained" means every system has run or been skipped — it does NOT mean the tick is over. The handler runs INSIDE the tick, on the tick thread, and the tick's own end-of-tick accounting still runs after the handler returns. So FatalStop() called from here takes effect after the current tick completes, and CurrentTickNumber advances once more once it does. Do not block in this handler: you are holding up the tick thread.

public event Action<TyphonRuntime, TickOutcome> OnTickAborted

Event Type

Action<TyphonRuntime, TickOutcome>