CoreGame.SharedMeta.Serialization.MessagePack 0.1.0

SharedMeta

Framework for shared game meta-logic between Client and Server with deterministic replay.

Write game logic once in C# — it runs on the server (Orleans grains) and replays on the client (Unity / .NET) with optimistic execution, automatic rollback, and desync detection.

What You Can Build

Player profiles and progression — experience, levels, inventory, currencies. State is persisted per-player, changes are optimistic (instant on client, validated on server).

Turn-based and card games — shared game rules execute identically on both sides. Matchmaking, lobbies, multi-entity game sessions with deterministic random for shuffles and draws.

Cooperative and async multiplayer — one player's action modifies another player's state via cross-entity calls. Energy systems, trading, expeditions that span multiple entities.

Economy and resource systems — crafting, shops, timers, regeneration. Server-only random for loot drops and rewards (client can't predict or cheat). ServerPatch mode for bandwidth-efficient state diffs.

Live-ops and admin tools — server-side triggers push events to clients. Subscribers react to state changes. Hot-swappable transport (WebSocket or HTTP polling) and serializer (MemoryPack or MessagePack).

Quick Start (Unity)

1. Install the Package

Add to Packages/manifest.json:

{
  "dependencies": {
    "com.coregame.sharedmeta": "https://github.com/CoreGame-IO/SharedMeta.git#v0.1.0"
  }
}

2. Open the Project Wizard

SharedMeta > Project Wizard in Unity menu.

Configure:

• Project name — your shared namespace (e.g. MyGame.Shared)
• State name — entity state class (e.g. PlayerProfile)
• Transport — SignalR (WebSocket, real-time) or HTTP Polling (universal, no extra DLLs)
• Serializer — MemoryPack (default) or MessagePack

The Dependencies section auto-detects and installs required packages (serializer, transport).

3. Generate Projects

Use the three generation tabs:

4. Run

# Start the server
cd MyGame.Server
dotnet run

# Press Play in Unity — MetaGameClient connects automatically

Quick Start (.NET only)

dotnet build SharedMeta.sln
dotnet run --project examples/CardGame_TheFool/CardGame.Server

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Meta Layer (SharedMeta.Core, YourGame.Shared)                  │
│  Business logic: services, state, [MetaService] / [MetaMethod]  │
│  Code generation: dispatchers, API clients, context injection   │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│  Middleware Layer (SharedMeta.Client, SharedMeta.Server)        │
│  MetaContext, replay mechanism, execution modes                 │
│  (Optimistic / Server / Local / CrossOptimistic / ServerPatch)   │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│  Serialization Layer (SharedMeta.Serialization.*)               │
│  IMetaSerializer, MemoryPack / MessagePack implementations      │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│  Transport Layer (SharedMeta.Transport.*)                       │
│  IConnection: SignalR WebSocket, HTTP long-polling, InProcess   │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│  Server Backend (SharedMeta.Server.Core, Orleans)               │
│  IMetaProvider<TState>, EntityGrain, SessionManager             │
└─────────────────────────────────────────────────────────────────┘

Each layer depends only on the layers above it. Swap serializers, transports, or backends without changing game logic.

Key Concepts

Define Shared State

[MemoryPackable, MessagePackObject]  // transport serialization (pick one or both)
[GenerateSerializer]                  // Orleans grain persistence
public partial class GameState : ISharedState
{
    [Id(0), Key(0), MemoryPackOrder(0)] public int Score { get; set; }
    [Id(1), Key(1), MemoryPackOrder(1)] public List<string> Items { get; set; } = new();
}

• [MemoryPackable] — MemoryPack serializer (default, zero-copy)
• [MessagePackObject] + [Key(n)] — MessagePack serializer (cross-platform, schema-flexible)
• [GenerateSerializer] + [Id(n)] — Orleans grain state persistence

Choose one serializer or use both. The wizard configures this automatically.

Define a Service

[MetaService("IGameService")]
public interface IGameService
{
    [MetaMethod(ExecutionMode.Optimistic)]
    void AddItem(string itemId);

    [MetaMethod(ExecutionMode.Server)]
    void GrantReward(int amount);
}

Implement the Service

[MetaServiceImpl(typeof(IGameService))]
public partial class GameServiceImpl : IGameService
{
    // Context is injected by source generator
    public void AddItem(string itemId)
    {
        State.Items.Add(itemId);
    }

    public void GrantReward(int amount)
    {
        // ServerRandom only generates on server; client replays from payload
        int bonus = Context.ServerRandom!.Next(10);
        State.Score += amount + bonus;
    }
}

Execution Modes

Deterministic Random

// Optimistic random — same algorithm & seed on both sides
int roll = Context.Random!.Next(6) + 1;

// Server random — generated on server, replayed on client
int loot = Context.ServerRandom!.Next(100);

Client Usage

var client = new MetaClient(connection, serializer);
await client.ConnectAsync("player-123", "entity-456");

// Generated typed API client
var gameApi = client.GetService<IGameServiceApiClient>();
gameApi.AddItem("sword_01");

// Subscribe to state changes
client.OnStateChanged += state => UpdateUI((GameState)state);

Examples

CardGame "The Fool"

Multiplayer turn-based card game with matchmaking lobby. Two players, attack/defend mechanics, trump suit. Demonstrates: Optimistic execution for card plays, Server mode for deck shuffle, lobby system with triggers, multi-entity game state.

Expedition

Single-player dungeon exploration with procedural map generation. Demonstrates: CrossOptimistic calls between expedition and profile entities, energy/money economy, ServerPatch mode (optional), deterministic random for map generation, session reconnection.

Project Structure

License

MIT