Tutorial 97: Network Sessions on the Local Network

CNA — C++ XNA 4.0 reimplementation

CNA ships an XNA-compatible networking API

You do not need to bolt a third-party socket library onto your CNA game. CNA implements Microsoft::Xna::Framework::Net — the same namespace XNA 4.0 exposed — as a real implementation, not a stub. It is covered by unit tests including a genuine two-process loopback test that spawns a host and a client as separate OS processes and makes them exchange packets.

What travels where depends on the session type. Local and LocalWithLeaderboards sessions live in one process. SystemLink sessions are peer-to-peer ENet over UDP on the local network: CNA vendors ENet and wraps it behind the XNA API surface, LAN session discovery is a real broadcast protocol on UDP port 61190, and the QualityOfService attached to a discovered session carries a measured round-trip time and measured upstream and downstream bandwidth. SystemLink needs no server and works offline. Online PlayerMatch and Ranked sessions go through the optional CNA Gamer Services server instead (see Online sessions below). This tutorial is about the local network.

Enabling networking in your build

The CMake option CNA_ENABLE_NET defaults to ON, so networking is built unless you explicitly turn it off. Link your game against the networking libraries:

target_link_libraries(MyGame PRIVATE
    CNA
    CNA_GamerServices   # SignedInGamer, Guide, GamerServicesComponent
    CNA_Net             # NetworkSession, PacketReader/Writer, ...
    SHARP_RUNTIME)

CNA_GamerServices is not optional: every session is created for one or more SignedInGamer instances, and those come from the GamerServices layer. Voice chat is built when libopus 1.3 or newer is found; CNA_ENABLE_VOICE (AUTO, ON or OFF) controls that, and voice is never built in a cross-compiled build (Emscripten, Android, iOS, or Windows built from Linux).

Signing in a local gamer

With no server configured — the default — CNA’s gamers are local offline profiles, as on an Xbox 360 without Xbox LIVE, and nobody is signed in until the player picks or creates a profile in the Guide’s sign-in page (Guide::ShowSignIn) or the auto-sign-in setting signs one in. Add GamerServicesComponent exactly as in XNA, and keep a GraphicsDeviceManager so the Guide can draw:

#include "Microsoft/Xna/Framework/Game.hpp"
#include "Microsoft/Xna/Framework/GraphicsDeviceManager.hpp"
#include "Microsoft/Xna/Framework/GamerServices/GamerServicesComponent.hpp"
#include "Microsoft/Xna/Framework/GamerServices/Gamer.hpp"
#include "Microsoft/Xna/Framework/GamerServices/Guide.hpp"
#include "Microsoft/Xna/Framework/GamerServices/SignedInGamerCollection.hpp"
#include <memory>

using namespace Microsoft::Xna::Framework;
using namespace Microsoft::Xna::Framework::GamerServices;

class LanGame : public Game {
    GraphicsDeviceManager graphics_{this};          // the Guide draws through it
public:
    LanGame() {
        getComponentsProperty().Add(std::make_shared<GamerServicesComponent>(*this));
    }
protected:
    void Update(GameTime& gameTime) override {
        Game::Update(gameTime);                      // runs GamerServicesDispatcher::Update
        SignedInGamer* player = (*Gamer::getSignedInGamersProperty())[PlayerIndex::One];
        if (player == nullptr && !Guide::getIsVisibleProperty())
            Guide::ShowSignIn(1, false);             // pick or create a local profile
        // ... once player is not null, host or join a session (below)
    }
};

A local profile has IsSignedInToLive false and no online-session privilege, but it plays Local and SystemLink sessions. Profiles are stored per user on the machine (profiles.json under the user’s data directory, or under CNA_GAMER_SERVICES_PROFILES_DIR). For unattended runs and CI, set CNA_GAMER_SERVICES_AUTO_SIGN_IN to up to four comma-separated profile names: they are created when missing and signed in when gamer services start, and appear at the first Update.

Hosting a session

NetworkSession::Create() returns a raw NetworkSession* that you own. Dispose() tears down the ENet host and frees every gamer object the session created, but it does not free the session object itself: call Dispose(), then delete the pointer.

#include "Microsoft/Xna/Framework/Net/NetworkSession.hpp"
#include "Microsoft/Xna/Framework/Net/LocalNetworkGamer.hpp"

using namespace Microsoft::Xna::Framework::Net;

// sessionType, maxLocalGamers, maxGamers -- the signed-in profile becomes the local gamer
NetworkSession* session =
    NetworkSession::Create(NetworkSessionType::SystemLink, 1, 8);

LocalNetworkGamer* me = session->getLocalGamersProperty()[0];

// ... later, exactly once:
session->Dispose();
delete session;

There are richer Create() overloads taking privateGamerSlots and a NetworkSessionProperties to advertise, plus an overload taking an explicit std::vector<SignedInGamer*>. Each has a matching BeginCreate()/EndCreate() asynchronous pair. The XNA limits are available as NetworkSession::MaxSupportedGamers (31) and NetworkSession::MaxPreviousGamers (100), and the gamer limit you request is preserved. Local, LocalWithLeaderboards and SystemLink sessions need no server; asking for PlayerMatch or Ranked without one throws (see below).

Finding and joining a session

NetworkSession::Find() performs the real LAN broadcast and returns an AvailableNetworkSessionCollection. Discovery is a UDP request/reply exchange, so a single call can legitimately return nothing — poll it. On macOS the query also goes to every network interface’s own broadcast address and the replies arrive on a socket of the search’s own, because Darwin refuses the global broadcast address; CNA records two-process discovery on one Mac, not yet between two Macs.

#include "Microsoft/Xna/Framework/Net/AvailableNetworkSessionCollection.hpp"
#include "Microsoft/Xna/Framework/Net/NetworkSessionProperties.hpp"
#include <chrono>
#include <thread>

AvailableNetworkSessionCollection available = NetworkSession::Find(
    NetworkSessionType::SystemLink, 1, NetworkSessionProperties{});

for (int attempt = 0; attempt < 100 && available.getCountProperty() == 0; ++attempt) {
    std::this_thread::sleep_for(std::chrono::milliseconds(50));
    available = NetworkSession::Find(
        NetworkSessionType::SystemLink, 1, NetworkSessionProperties{});
}

if (available.getCountProperty() == 0) {
    // No host is running on this LAN.
    return;
}

const AvailableNetworkSessionCollection& found = available;   // const overload
NetworkSession* session = NetworkSession::Join(&found[0]);

Every AvailableNetworkSession exposes HostGamertag, CurrentGamerCount, OpenPublicGamerSlots, OpenPrivateGamerSlots, its advertised SessionProperties, and a QualityOfService. Use them to build a server browser:

const AvailableNetworkSession& s = found[i];
const QualityOfService& qos = s.getQualityOfServiceProperty();

double pingMs = qos.getAverageRoundtripTimeProperty()
                   .getTotalMillisecondsProperty();

// "Host (2/8) - 3 ms"
std::printf("%s (%d/%d) - %.0f ms\n",
            s.getHostGamertagProperty().c_str(),
            s.getCurrentGamerCountProperty(),
            s.getCurrentGamerCountProperty() + s.getOpenPublicGamerSlotsProperty(),
            pingMs);

NetworkSession::Join() deliberately has no overload taking an explicit gamer list — matching real XNA, it always draws from Gamer::SignedInGamers. Only Create() accepts an explicit list.

Sending and receiving packets

PacketWriter derives from System::IO::BinaryWriter and adds overloads for the XNA math types: Color, Matrix, Quaternion, Vector2, Vector3, Vector4, plus float and double. All of BinaryWriter's other Write() overloads remain available. PacketReader is the symmetric BinaryReader. Every one of these round-trips is covered by cna_demo_packet_roundtrip.

You send through a LocalNetworkGamer, not through the session, and you pump the session once per frame with Update():

#include "Microsoft/Xna/Framework/Net/PacketReader.hpp"
#include "Microsoft/Xna/Framework/Net/PacketWriter.hpp"

void MyGame::Update(GameTime& gameTime) {
    Game::Update(gameTime);      // gamer services first
    session_->Update();          // pumps ENet, raises queued events

    // Broadcast our position to everyone else in the session.
    PacketWriter writer;
    writer.Write(localPosition_);                    // Vector2 overload
    local_->SendData(writer, SendDataOptions::InOrder);

    // Drain everything that arrived since the last frame.
    PacketReader reader;
    NetworkGamer* sender = nullptr;
    while (local_->getIsDataAvailableProperty()) {
        local_->ReceiveData(reader, sender);
        if (sender != nullptr && !sender->getIsLocalProperty()) {
            remotePositions_[sender] = reader.ReadVector2();
        }
    }
}

The sender out-parameter can point at your own local gamer — a broadcast is delivered to every gamer in the session including the originator — so the getIsLocalProperty() check above is not optional. ReceiveData(PacketReader&, ...) returns the packet’s size and sizes the reader to it.

SendDataOptions has five members:

XNA marks this enum [Flags] and its values (0–4) do compose: ReliableInOrder (3) is Reliable | InOrder, and Chat (4) is a separate bit that XNA lets you combine with the others. CNA ports it as a plain enum class with no bitwise operators, so those combinations cannot be written: pass exactly one of the five members (Chat on its own is sent reliably and in order).

SendData() also has overloads taking a raw std::vector<SharpRuntime::bytecs>, an offset/count pair, and a target NetworkGamer* recipient for point-to-point delivery instead of broadcast.

Session events

NetworkSession exposes GamerJoined, GamerLeft, GameStarted, GameEnded, HostChanged, and SessionEnded. Events are raised from Update(), never spontaneously; the one exception is that subscribing to GamerJoined replays the gamers already in the session (see the note below).

#include "Microsoft/Xna/Framework/Net/GamerJoinedEventArgs.hpp"
#include "Microsoft/Xna/Framework/Net/GamerLeftEventArgs.hpp"
#include "Microsoft/Xna/Framework/Net/NetworkSessionEndedEventArgs.hpp"

session->GamerJoined += [this](System::Object*, const GamerJoinedEventArgs& e) {
    NetworkGamer* g = e.getGamerProperty();
    if (!g->getIsLocalProperty()) {
        remotePositions_[g] = Vector2(300.0f, 300.0f);
    }
};

session->GamerLeft += [this](System::Object*, const GamerLeftEventArgs& e) {
    remotePositions_.erase(e.getGamerProperty());
};

session->SessionEnded += [](System::Object*, const NetworkSessionEndedEventArgs&) {
    // Host quit, you were removed, or the connection dropped.
};

session->Update();   // pump events each frame; the += on GamerJoined above already replayed the gamers present

Lobby, game start, and game end

A session is in one of three NetworkSessionState values: Lobby, Playing, or Ended. Gamers signal readiness with NetworkGamer::IsReady; the host polls IsEveryoneReady and calls StartGame().

if (session->getIsHostProperty() && session->getIsEveryoneReadyProperty()) {
    session->StartGame();
    session->Update();           // raises GameStarted, moves to Playing
}

// ... when the round is over:
session->EndGame();
session->Update();               // raises GameEnded
session->ResetReady();           // clears every gamer's IsReady flag

Note that EndGame() returns the session to Lobby, not to Ended. Ended is reached when the local gamer actually leaves the session.

Online sessions: PlayerMatch and Ranked

Online sessions use the same API, but they go through the optional CNA Gamer Services server (cna-gamer-services-server), which the game finds through configuration outside its code (environment variables, a cna-title.json manifest or a settings file). Without a configured server, Create/Find for PlayerMatch or Ranked throw GamerServicesNotAvailableException. With one:

• Only signed-in server accounts can take part; local offline profiles and guests are refused.
• Sessions are created and found through the server’s session directory, and every datagram, game data and voice alike, travels through the server’s authenticated WebSocket relay over TLS. There is no peer-to-peer path and no NAT traversal, so expect TCP’s head-of-line latency when packets are lost.
• The asynchronous Begin* calls complete during GamerServicesDispatcher::Update, which the GamerServicesComponent runs from Game::Update.
• Invitations work (players invite from the Guide; the invited game hears InviteAccepted and calls JoinInvited), host migration is decided by the server, and Ranked does not allow joining a game in progress.
• The server is not Xbox LIVE and no public instance is provided: you run your own. Its public-Internet deployment has not been independently qualified.

The Gamer Services page covers configuration, the server and the security model.

What works, and what does not

The networking layer is real, but it is not complete. These limits are all verified against the source, and it is better to design around them now than to discover them mid-project.

In short: build LAN multiplayer on SystemLink, prototype single-process session logic (lobby, readiness, state transitions) on Local, test your netcode against the real SimulatedLatency/SimulatedPacketLoss dials, treat host migration as best-effort (it needs AllowHostMigration and a rebuilt roster), and plan online play around a server you operate.

Lockstep vs client-server

Lockstep: all clients simulate the same game state using the same inputs, synchronized frame by frame. Simple to implement but sensitive to latency — one slow client stalls everyone. Best for turn-based or slow-paced games. Client-server: one machine is authoritative; clients send inputs and receive state updates. More complex but handles latency and cheating better. Best for action games.

Serialization of game state

Do not reinterpret-cast packed structs across the wire. PacketWriter already gives you a portable, length-prefixed encoding for every type you need, and PacketReader reads them back in the same order. Write a small, explicit encode/decode pair per message type:

#include "Microsoft/Xna/Framework/Net/PacketReader.hpp"
#include "Microsoft/Xna/Framework/Net/PacketWriter.hpp"
#include "Microsoft/Xna/Framework/Vector2.hpp"

using namespace Microsoft::Xna::Framework;
using namespace Microsoft::Xna::Framework::Net;

enum class MessageId : SharpRuntime::bytecs { PlayerState = 1, Fired = 2 };

struct PlayerState {
    Vector2 position;
    Vector2 velocity;
    SharpRuntime::intcs sequenceNumber;
};

void WritePlayerState(PacketWriter& w, const PlayerState& s) {
    w.Write(static_cast<SharpRuntime::bytecs>(MessageId::PlayerState));
    w.Write(s.position);          // Vector2 overload
    w.Write(s.velocity);
    w.Write(s.sequenceNumber);    // BinaryWriter's int overload
}

PlayerState ReadPlayerState(PacketReader& r) {
    PlayerState s;
    s.position       = r.ReadVector2();
    s.velocity       = r.ReadVector2();
    s.sequenceNumber = r.ReadInt32();
    return s;
}

Reading the leading MessageId byte first lets one packet stream carry several message types. Because a broadcast is delivered to the sender too, dispatch only after checking sender->getIsLocalProperty().

Latency hiding

Techniques to hide network latency: Client-side prediction — apply your own input immediately, reconcile with server state when it arrives. Interpolation — render remote players at a slightly delayed time using the last two received positions. Dead reckoning — extrapolate remote player positions using last known velocity.

// Simple interpolation between two received positions
Vector2 InterpolateRemote(const Vector2& prev, const Vector2& next,
                           float alpha) {
    return Vector2::Lerp(prev, next, alpha);
}

Working code to read next

Everything on this page is drawn from CNA's own networking demos. They live in CNA's own tree and are built with it (when CNA_ENABLE_NET is on and the target is not Emscripten), so they are the authoritative reference when this page and the code disagree (one exception: some of them call Dispose() on exit without deleting the session object; your code should do both, as shown above):