Client Integration - World Engine

High-level overview of integrating game clients with Cardinal using the client SDKs. For the full SDK reference documentation, see:

Initializing the Client

Create a client with a configuration object that specifies the auth URL and region configs. For local development, use dev auth to bypass the normal authentication flow.

Unity C#
TypeScript

using WorldEngine.SDK;
using WorldEngine.SDK.Client;

var config = new WorldClientConfig
{
    AuthUrl = "http://localhost:3000",
    AuthClientOverride = new DevAuth("dev@argus.gg"),
    Regions = new Dictionary<string, RegionConfig>
    {
        ["us-west-2"] = new RegionConfig
        {
            GatewayUrl = "http://localhost:8080",
            DisplayName = "US West"
        }
    }
};

var client = new WorldClient(config);

// TODO: update

Authentication

Unity C#
TypeScript

var result = await client.SignInAsync();
if (result.Error == null)
{
    var user = result.Data;
    Debug.Log($"Signed in as {user.Email} (Persona: {user.PersonaId})");
}

// Get current user
var currentUser = client.GetUser();

// TODO: update

Sign out when the user logs out of your game.

Unity C#
TypeScript

await client.SignOutAsync();

// TODO: update

Connecting to a Shard

A shard is a single instance of your game world running on the server. The shard client is your connection to that instance, allowing you to query entities, send commands, and subscribe to events. To connect, specify the shard’s address (region, organization, project, and shard ID) and call connect to get a shard client.

Unity C#
TypeScript

var addr = new ShardAddress
{
    Region = "us-west-2",
    Organization = "my-org",
    Project = "my-game",
    ShardId = "game-shard"
};

var shard = client.ConnectShard(addr);

// TODO: update

Disconnect from the shard when you no longer need it.

Unity C#
TypeScript

client.DisconnectShard(addr);

// TODO: update

Querying Entities

To query entities, define client-side classes with field mappings that correspond to component field names on the server. Build queries to specify which components to find and how to match them. See Queries for more details.

Unity C#
TypeScript

// Define entity classes with Field attribute mapping
public class PlayerTag
{
    [Field("nickname")]
    public string Nickname { get; set; }
}

public class Health
{
    [Field("hp")]
    public float Hp { get; set; }
}

public class PlayerEntity
{
    [Field("playertag")]
    public PlayerTag PlayerTag { get; set; }

    [Field("health")]
    public Health Health { get; set; }
}

// Build and execute query
var query = new QueryInfo
{
    Find = new List<string> { "playertag", "health" },
    Match = QueryMatch.Contains,
};

var results = await shard.QueryAsync<PlayerEntity>(query);
foreach (var (entity, id) in results)
{
    Debug.Log($"Player: {entity.PlayerTag.Nickname} Health: {entity.Health.Hp}");
}

// TODO: update

Sending Commands

Build a command payload and send it to the shard. See Commands for more details.

Unity C#
TypeScript

var payload = new Dictionary<string, object>
{
    ["target"] = "enemy-123",
    ["damage"] = 50
};

await shard.SendCommandAsync("attack-player", payload);

// TODO: update

Subscribing to Events

Subscribe to events with handler callbacks. See Events for more details.

Unity C#
TypeScript

var handler = evt =>
{
    Debug.Log($"New player event: {evt.Payload}");
};
await shard.SubscribeEventAsync("new-player", handler);

// TODO: update

Unsubscribe when you no longer need to receive events.

Unity C#
TypeScript

await shard.UnsubscribeEventAsync("player-death", handler);

// TODO: update

​Initializing the Client

​Authentication

​Connecting to a Shard

​Querying Entities

​Sending Commands

​Subscribing to Events