Lobby System Documentation

Overview

The BlinkBox Lobby System is a robust, multiplayer lobby solution designed for Unity games. It bridges the gap between Unity clients and a centralized backend to manage parties, matchmaking, and real-time state synchronization.

Installation & Setup

1. Unity Client Setup

1. Ensure Photon PUN2 is installed and configured in your project.
2. Import the ODIN SDK for voice chat functionality.
3. Drag the LobbyManager prefab into your startup scene (or initialize it via script).
4. Ensure LobbySettings and LobbyVoiceSettings are present in a Resources folder.

2. Server Setup

The backend is a Node.js application located in Assets/Addons/BlinkBox/LobbySystem/Server.

# Navigate to server directory
cd Assets/Addons/BlinkBox/LobbySystem/Server

# Install dependencies
npm install

# Configure environment
cp .env.example .env

# Start the server
npm start

Environment Variables (.env)

Architecture

The system uses a Client-Server architecture where Unity clients communicate with a Node.js WebSocket server for lobby state, while using Photon PUN for the actual gameplay networking.

• Unity Client (C#): Handles UI, input, and local state. Uses NativeWebSocket to talk to the Node server.
• Lobby Server (Node.js): Manages the "source of truth" for parties, member lists, and invites.
• Voice Server (ODIN): Handles audio streaming between clients.

Lobby Manager

The bl_LobbyManager class is the heart of the client-side system. It is a singleton that persists across scenes.

Key Responsibilities

• Connection Management: Handles WebSocket connection, reconnection logic, and heartbeat.
• State Synchronization: Keeps local dictionaries (partyMembers, readyStates, playerCharacters) in sync with the server.
• Event Dispatching: Fires C# events when server messages are received.

Public Properties

UI System

Managed by bl_LobbySystemUI.cs. The UI is state-driven and reacts to events from the Lobby Manager.

Key Panels

• ConnectingPanel: Shown while establishing WebSocket connection.
• PartyPanel: The main lobby view. Shows player nameplates, character models, and "Ready" button.
• JoinPartyPanel: Input field for entering a party code.
• DisconnectedPanel: Shown if connection to server fails.

Player Nameplates

The bl_PlayerNameplate script handles individual player slots. It displays:

• Player Nickname
• Ready Status (Green/Red indicator)
• Leader Icon (Crown)
• Voice Activity (Speaker icon)

Voice Chat

Powered by the ODIN SDK and managed by bl_LobbyVoiceManager.cs.

Features

• Spatial Audio: 3D positional audio support (configurable).
• Push-to-Talk: Configurable key (Default: V) to activate microphone.
• Voice Activity Detection (VAD): Automatically detects speaking when not using PTT.

Configuration

Voice settings are stored in a LobbyVoiceSettings ScriptableObject.

Settings

The system is highly configurable via the bl_LobbySettings ScriptableObject (Right-click > BlinkBox > LobbySystem > Lobby Settings).

Server Settings

• Server Url: WebSocket endpoint (e.g., ws://localhost:3000/ws).
• Reconnect Delay: Time in seconds to wait before retrying connection.

UI Settings

• Show Voice Indicators: Toggle microphone icons on nameplates.
• Colors: Customize Ready/Not Ready and Speaking/Muted colors.

Logging

Toggle debug logs for Server messages, Party events, and Voice chat independently.

Node.js Server

The server logic resides in server.js. It uses the ws library for WebSockets and express for the HTTP server.

Features

• Rate Limiting: Protects the API from spam (100 reqs / 15 min by default).
• Security: Uses helmet for headers and strict CORS policies.
• Logging: Rotates log files in the /logs directory automatically.

Socket API

Communication protocol between Unity Client and Node.js Server. All messages are JSON formatted.

Client -> Server Messages

Server -> Client Messages

Web Monitor

The server includes a built-in web dashboard for monitoring server status.

URL: http://your-server-url/

The public/ folder contains the frontend for this dashboard, visualizing:

• Active connections count
• Current parties and their members
• Real-time server logs

C# API Reference

Primary methods available in bl_LobbyManager.

Events

public event Action<string> OnMemberJoined;
public event Action<string> OnMemberLeft;
public event Action<string, bool> OnMemberReadyChanged;
public event Action<string, int> OnMemberCharacterSelected;
public event Action<string> OnPartyLeaderChanged;
public event Action OnPartyLeft;
public event Action OnGameStarted;
public event Action<string> OnPartyCreated;
public event Action OnConnected;
public event Action OnDisconnected;

Methods

// Create a new party
public void CreateParty(int maxSize = 4);

// Join an existing party
public void JoinParty(string code);

// Leave current party
public void LeaveParty();

// Kick a player (Leader only)
public void KickMember(string playerId);

// Set local ready state
public void SetReadyState(bool isReady);

// Select a character
public void SelectCharacter(int characterId);

File Structure