Client SDK Reference

The Worldweave client SDK is the set of C# interfaces and services your game code calls to interact with the platform. All services are registered in the engine’s service locator at startup — no manual dependency wiring is needed. Access any service via Services.Get<T>().

Configuration

The SDK is configured via the WorldweaveClientConfig asset at Content/Worldweave.ww-config.json. The engine loads this automatically if it is present. No code configuration is required.

{
  "gameId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "apiKey": "ww_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "environment": "production",
  "connectionTimeoutSeconds": 10,
  "deltaFrameBufferSize": 32,
  "echoRateLimitPerMinute": 60
}

Optional config fields take engine defaults if omitted. environment can be "production" or "development".

Services

WorldweaveAuthService

Handles session authentication with the Root. Runs automatically on startup when a WorldweaveClientConfig is present.

var auth = Services.Get<WorldweaveAuthService>();

// Check if the session is authenticated
bool connected = auth.IsConnected;

// Subscribe to connection events
auth.Connected    += (s, e) => Logger.Info($"Connected. Session: {e.SessionId}");
auth.Disconnected += (s, e) => Logger.Warn($"Disconnected: {e.Reason}");

// Check for pending offline-to-online migration
if (auth.HasLocalProgressPendingMigration)
    await auth.MigrateLocalProgressAsync();

---

IWorldStateQuery

Synchronous read interface over the local WorldStateCache. All methods are O(1) dictionary lookups — no network calls.

var worldState = Services.Get<IWorldStateQuery>();

WeatherSnapshot        weather  = worldState.GetWeather(zoneId);
PopulationSnapshot     wolves   = worldState.GetPopulation(zoneId, "wolf");
ResourceLevelSnapshot  iron     = worldState.GetResourceLevel(zoneId, "iron_ore");
ZoneControlSnapshot    control  = worldState.GetZoneControl(zoneId);
DiplomaticStance       stance   = worldState.GetFactionStance("faction_a", "faction_b");
WorldTime              time     = worldState.GetCurrentTime(zoneId);

---

WorldStateCache

The local in-memory store of world state, updated by The Signal. Exposes the Changed event for reacting to state transitions.

var cache = Services.Get<WorldStateCache>();

cache.Changed += (sender, change) =>
{
    if (change is WeatherChangedEvent wx)
        UpdateAmbience(wx.NewState);
};

// Force a manual refresh (sends a per-zone snapshot request to the Strand)
await cache.RequestSnapshotAsync(zoneId);

---

EchoService

Submits Echo events to the Living World simulation via the Strand. All submissions are validated and rate-limited server-side.

var echo = Services.Get<EchoService>();

EchoResult result = await echo.EmitAsync(new EchoEvent
{
    Type      = EchoEventType.Hunt,
    ZoneId    = zoneId,
    SubjectId = "wolf",
    Magnitude = 1.0f,
});

if (!result.Accepted)
    Logger.Warn($"Echo rejected: {result.RejectionReason}");

See The Echo for full documentation.

---

ChronicleService

Queries world history from The Chronicle. Queries are async — results come from the Strand, not the local cache.

var chronicle = Services.Get<ChronicleService>();

var events = await chronicle.QueryAsync(new ChronicleQuery
{
    ZoneIds    = new[] { zoneId },
    EventTypes = new[] { ChronicleEventType.WarDeclared },
    SinceTime  = WorldTime.Now.MinusDays(90),
});

See The Chronicle for the full query reference.

---

LoreGenerator

Generates procedural prose from a list of Chronicle events.

var lore = Services.Get<LoreGenerator>();

string passage = lore.GeneratePassage(
    events:    chronicleEvents,
    tone:      LoreTone.EpicChronicle,
    maxLength: 400
);

Available tones: EpicChronicle, FieldNotes, GossipRumour, OfficialDecree, AncientFragment.

---

IPlayerIdentityService

Provides access to the authenticated player’s canonical identity.

var identity = Services.Get<IPlayerIdentityService>();

Guid   playerId         = identity.CanonicalPlayerId;
string displayName      = identity.DisplayName;
bool   isAuthenticated  = identity.IsRootAuthenticated;
AuthState authState     = identity.AuthState;
// AuthState: Anonymous | DeviceIdentity | Authenticated | Expired

// Link a platform account
await identity.LinkPlatformAccountAsync(PlatformType.Steam);

---

MauUsageService

Developer tooling — query the current MAU count for monitoring dashboards or internal diagnostics. Do not expose raw MAU figures to players.

var mau = Services.Get<MauUsageService>();

MauUsageReport report = await mau.GetCurrentMonthReportAsync();

Logger.Info($"MAU: {report.CurrentMau} / {(report.Ceiling.HasValue ? report.Ceiling.ToString() : "unlimited")}");
Logger.Info($"Days remaining: {report.DaysRemaining}");

---

WorldStateSubscriptionService

Manages which zones the client receives delta frames for.

var subscription = Services.Get<WorldStateSubscriptionService>();

subscription.Subscribe(zoneId);
subscription.Unsubscribe(zoneId);

IReadOnlySet<ZoneId> active = subscription.ActiveSubscriptions;

Subscribing to a new zone triggers a per-zone snapshot from the Strand before delta frames begin.

---

LuaScriptEngine and LuaScriptSandbox

The scripting runtime. LuaScriptEngine manages the lifecycle of all loaded scripts. LuaScriptSandbox is the per-script execution context.

var engine = Services.Get<LuaScriptEngine>();

// Register an action handler accessible from Lua
engine.RegisterActionHandler(new FleeActionHandler(world));

// Load and run a script directly (for developer tooling / test)
await engine.LoadScriptAsync("scripts/my_script.lua");

// Query loaded scripts
IReadOnlyList<LoadedScript> scripts = engine.LoadedScripts;

---

ModLoader

Loads, validates, and manages .sfpak mod archives.

var mods = Services.Get<ModLoader>();

// Load all mods from the platform mod directory
await mods.LoadAllAsync();

// List loaded mods
foreach (var mod in mods.LoadedMods)
{
    Logger.Info($"Loaded: {mod.Manifest.DisplayName} v{mod.Manifest.Version}");
}

// Unload a specific mod
await mods.UnloadAsync(modId);

ModLoader validates the manifest signature, checks engine version compatibility, and enforces permission declarations before activating a mod. Mods that fail validation are listed in ModLoader.FailedMods with a reason code.

---

Service availability

All services listed above are registered by the engine at startup. They are available for Services.Get<T>() from Initialize() onward. Services that depend on Worldweave connectivity (such as EchoService, ChronicleService, MauUsageService) return safe default values or throw WorldweaveNotConnectedException (depending on the operation) when the connection is in degraded mode.

Check WorldweaveAuthService.IsConnected before calling connection-dependent services if you want to avoid exceptions.