Connecting to Worldweave

Connecting your game to Worldweave enables player identity (Root accounts), session relay via Strands, the Living World simulation, cross-game social features, achievements, and ranked matchmaking. Connection is opt-in and requires a developer account and an API key.

What connecting means

When your game starts and a Worldweave connection is active, the engine:

Authenticates the local player against the Root, creating a session token
Selects the nearest Strand for relay and Living World state delivery
Begins streaming world-state deltas via The Signal
Enables all IWorldStateQuery calls to return real data instead of defaults

Your game code does not manage this process. The WorldweaveAuthService handles it automatically on startup once a valid WorldweaveClientConfig is present.

Step 1: Register your game

Go to portal.softfire.dev and sign in with your developer account. If you do not have one yet, create it — it is free. Under My Games, click Register New Game and fill in:

Display name — shown to players in the social layer and achievement notifications
Description — a short description for the game browser
Platform targets — Windows, Linux, macOS, console targets you plan to ship on

After registering, your game receives a Game ID (a stable UUID) and your first API key.

Step 2: Add WorldweaveClientConfig

WorldweaveClientConfig is a JSON-serialised asset that lives in your content directory. Add it to your project by creating the file Content/Worldweave.ww-config.json:

{
  "gameId": "your-game-id-here",
  "apiKey": "ww_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "environment": "production"
}

Then reference it in your MGCB .mgcb pipeline file:

/build:Worldweave.ww-config.json

The engine loads WorldweaveClientConfig automatically at startup when it is present in the content directory. No code changes are needed — the config’s presence alone activates the Worldweave client.

Step 3: Test the connection

In the Softfire editor, open Project Settings → Worldweave. If the config file is detected and valid, a Test Connection button is shown. Click it to verify that the engine can reach the Root and that your API key is accepted. A green status indicator confirms the connection.

You can also test at runtime — the WorldweaveAuthService emits a WorldweaveConnectedEvent that you can subscribe to in your startup code:

Services.Get<WorldweaveAuthService>().Connected += (sender, e) =>
{
    Logger.Info($"Worldweave connected. Session: {e.SessionId}");
};

Degraded mode

If the Root is unreachable at startup — due to network loss, a Root outage, or MAU ceiling — the engine enters degraded mode:

Your game continues to run normally in local-only mode
All IWorldStateQuery calls return their cached or default values
EchoService.Emit() calls are silently dropped (not queued)
Social features, achievements, and ranked matchmaking are unavailable
Players are not prompted or blocked — the game continues without interruption

Your game code can detect degraded mode via WorldweaveAuthService.IsConnected. Use this to conditionally show or hide online features in your UI.

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

if (auth.IsConnected)
{
    // Show online leaderboard
}
else
{
    // Show local high scores only
}

MAU tiers

Worldweave uses a Monthly Active User model for billing. Key tiers:

Tier	MAU ceiling	Cost
Indie	10,000	Free
Studio	None	Per-MAU, billed monthly
Enterprise	Custom	Contact sales

When an Indie-tier game reaches the MAU ceiling, new connections enter degraded mode automatically — existing active sessions are unaffected. Softfire sends an email notification to the developer account owner. See the full MAU Tiers and Pricing page for details.