Lifecycle and readiness

Understand realms, dependency-first activation, bounded loading, readiness acknowledgement and deterministic teardown.

ILitherarpAddon

Member	Realm	When it runs
`string AddonId { get; }`	both	Required stable identity. It must normalize to the configured id.
`string DisplayName { get; }`	both	Human-readable name. The default is `AddonId`.
`string Version { get; }`	both	Implementation version. The default is `1.0.0`.
`int ProtocolVersion { get; }`	both	Application protocol. It must match the manifest. The default is `1`.
`Task OnHostLoadingAsync(context, cancellationToken)`	host	Bounded async setup before `OnHostLoaded`. The platform timeout is 15 seconds.
`void OnHostLoaded(context)`	host	Register authoritative gameplay and host state.
`Task OnClientLoadingAsync(context, cancellationToken)`	client	Bounded async presentation setup before `OnClientLoaded`.
`void OnClientLoaded(context)`	client	Register panels, phone apps and client handlers.
`void OnHostReady(context)`	host	Runs after the complete host dependency plan is active.
`void OnClientReady(context)`	client	Runs after the complete client dependency plan is active.
`void OnHostTick(context)`	host	Runs every frame while active. Repeated recoverable failures quarantine the tick callback.
`void OnClientTick(context)`	client	Runs every client frame, including a listen host client. It has a separate repeated-failure quarantine.
`void OnHostShutdown(context)`	host	Runs when a host realm that completed its loaded phase is retired.
`void OnClientShutdown(context)`	client	Runs when a client realm that completed its loaded phase is retired. On a listen host this runs before host shutdown.
`void OnShutdown(context)`	both	Legacy combined shutdown. It runs once after realm-specific shutdown when at least one loaded phase completed.

1[LitherarpAddon( "myaddon" )]
2public sealed class MyAddon : ILitherarpAddon
3{
  public string AddonId => "myaddon";
  public string DisplayName => "My Addon";
  public string Version => "1.2.0";
  public int ProtocolVersion => 2;
8
  public Task OnHostLoadingAsync( LitherarpAddonContext context, CancellationToken token )
      => LoadDefinitionsAsync( token );
11
  public void OnHostLoaded( LitherarpAddonContext context ) { }
  public Task OnClientLoadingAsync( LitherarpAddonContext context, CancellationToken token )
      => LoadPresentationAsync( token );
  public void OnClientLoaded( LitherarpAddonContext context ) { }
  public void OnHostReady( LitherarpAddonContext context ) { }
  public void OnClientReady( LitherarpAddonContext context ) { }
  public void OnHostTick( LitherarpAddonContext context ) { }
  public void OnClientTick( LitherarpAddonContext context ) { }
  public void OnHostShutdown( LitherarpAddonContext context ) { }
  public void OnClientShutdown( LitherarpAddonContext context ) { }
  public void OnShutdown( LitherarpAddonContext context ) { }
23}

Realms

Realm	Host	Client
`Shared`	Host loading, loaded, ready and tick.	Client loading, loaded and ready.
`Server`	Host loading, loaded, ready and tick.	Not sent as a client code addon.
`Client`	No host lifecycle. A listen host can run its client lifecycle.	Client loading, loaded and ready.

Activation order

Validate manifest identity, parent package, versions, conflicts, capabilities and package revisions.
Resolve the dependency plan.
Mount packages and discover the one attributed implementation for each id.
Run async loading, then loaded callbacks in dependency order.
After the plan is active, run ready callbacks.
Finish host world bootstrap. WorldReady then becomes observable.
On each client, finish the verified snapshot barrier. ClientWorldReady then becomes observable for that successful snapshot.

Client readiness

The host sends a fingerprint over the exact enabled package revisions and client code plan. A joining client mounts and activates that snapshot, then acknowledges the same fingerprint. Initial pawn creation waits for a successful acknowledgement when required client work exists.

A required client package or code failure disconnects the client with a bounded error message.
A stale acknowledgement for an older hot snapshot is ignored.
Existing players acknowledge a changed hot snapshot too. The client readiness barrier is lowered while that snapshot is reconciled.
clientReadinessTimeoutSeconds is clamped from 15 to 300 seconds. Its default is 90.
The local listen-host connection is ready immediately.

Teardown

Context-managed registrations are removed in reverse teardown order. Tracked objects and components are destroyed during normal disable. Cancellation sources are canceled and disposed. Services, network messages, storage writes and per-player sections are cleaned up by the context.

Use OnHostShutdown, OnClientShutdown, legacy OnShutdown or OnTeardown for state created outside a context registration. Do not rely on addon assembly static fields being reset by disable.