PhoenixSharp 1.2.3

<p align="center"> <img width="340" height="271" alt="phoenix-sharp-splash" src="https://github.com/user-attachments/assets/3977a485-02cb-49a4-b484-b3320d21355a" /> </p>

<p align="center"> <a href="https://github.com/Mazyod/PhoenixSharp/actions/workflows/dotnet.yml"><img src="https://github.com/Mazyod/PhoenixSharp/actions/workflows/dotnet.yml/badge.svg" alt=".NET" /></a> <a href="https://codecov.io/gh/Mazyod/PhoenixSharp"><img src="https://codecov.io/gh/Mazyod/PhoenixSharp/branch/master/graph/badge.svg" alt="codecov" /></a> <a href="https://www.nuget.org/packages/PhoenixSharp"><img src="https://img.shields.io/nuget/v/PhoenixSharp" alt="NuGet" /></a> <a href="https://openupm.com/packages/io.level3.phoenixsharp/"><img src="https://img.shields.io/npm/v/io.level3.phoenixsharp?label=openupm&registry_uri=https://package.openupm.com" alt="OpenUPM" /></a> <img src="https://img.shields.io/badge/netstandard-2.0-blue" alt="netstandard 2.0" /> </p>

<p align="center"> <strong>A C# client for Phoenix Channels.</strong><br> Unity compatible. Powering <a href="http://level3.io">Dama King</a>. </p>

Features

• Full Phoenix Channels protocol support
• Modern async/await API with cancellation support
• Automatic reconnection and channel rejoin
• Presence tracking
• Customizable WebSocket and JSON implementations
• Unity and .NET Standard 2.0 compatible

Installation

NuGet

dotnet add package PhoenixSharp

Unity (OpenUPM)

Install via openupm-cli:

openupm add io.level3.phoenixsharp

Or add manually to Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["io.level3"]
    }
  ],
  "dependencies": {
    "io.level3.phoenixsharp": "1.2.3"
  }
}

Alternatively, download the source and add it to your project, or use a Git submodule.

Quick Start

// Create and connect a socket
var socket = new Socket(
    "wss://example.com/socket",
    new Socket.Options(new JsonMessageSerializer())
);
socket.Connect();

// Join a channel
var channel = socket.Channel("room:lobby", new { userId = "123" });
channel.Join();

// Listen for events
channel.On("new_message", message => {
    var payload = message.Payload.Unbox<ChatMessage>();
    Console.WriteLine($"Received: {payload.Text}");
});

// Send messages
channel.Push("send_message", new { text = "Hello!" });

Async API

await socket.ConnectAsync();

var result = await channel.JoinAsync();
if (result.IsSuccess)
{
    var response = await channel.PushAsync<ChatMessage>(
        "send_message",
        new { text = "Hello!" }
    );
    if (response.IsSuccess)
        Console.WriteLine($"Sent with id: {response.Response.Id}");
}

await channel.LeaveAsync();

Documentation

• Migration Guide - Upgrading from older versions
• Integration Tests - Complete usage examples

WebSocket Implementation

The library requires an IWebsocket implementation. Sample implementations are available in PhoenixTests/WebSocketImpl.

var factory = new MyWebSocketFactory();
var socket = new Socket(address, null, factory, options);

Recommended implementations:

• BestHTTP (Unity) - See Reference/Unity/BestHTTP
• WebSocketSharp - Good cross-platform option
• System.Net.WebSockets - Built-in .NET option

JSON Serialization

The default JsonMessageSerializer uses Newtonsoft.Json with the Phoenix V2 serialization format. To use a different serializer, implement IMessageSerializer and IJsonBox.

var options = new Socket.Options(new MyCustomSerializer());

Presence

var presence = new Presence(channel);

presence.OnJoin += (key, current, newPresence) => {
    Console.WriteLine($"{key} joined");
};

presence.OnLeave += (key, current, leftPresence) => {
    Console.WriteLine($"{key} left");
};

// Wait for initial state (async)
await presence.WaitForInitialSyncAsync();

Unity Notes

For background on Unity's .NET support, see Microsoft's Unity scripting documentation.

Threading

By default, callbacks use System.Threading.Tasks which works with Unity's SynchronizationContext. For more control, implement IDelayedExecutor (or use UniTask for better performance):

var options = new Socket.Options(serializer)
{
    DelayedExecutor = new CoroutineDelayedExecutor()
};

See Reference/Unity for a coroutine-based implementation.

Recommended Libraries

• BestHTTP - Handles threading automatically
• Json.NET for Unity - More reliable than raw Newtonsoft.Json on mobile

API Reference

Socket

Channel

Presence

Running Tests

# All tests
dotnet test

# Unit tests only
dotnet test --filter "Category!=Integration"

# Integration tests (requires server)
dotnet test --filter "Category=Integration"

Integration tests run against phoenix-sharp.level3.io:3080. Server source: phoenix-integration-tester

Contributing

Issues and pull requests are welcome!

License

MIT

Author

Maz (Mazyad Alabduljaleel)

<p align="center"> _{Logo is a mix of Unity and Phoenix logos. Please don't sue me.} </p>