Private Rooms - BeeHex

Overview

Private rooms allow you to create custom games and invite specific friends using room codes, bypassing the public matchmaking system.

Private rooms are perfect for:

Playing with friends
Practicing specific strategies
Teaching new players
Casual games without MMR changes

Creating a Private Room

Follow these steps to set up a private game:

Navigate to Game Mode

Visit /game_mode or click “Jouer” in the bottom navigation bar.

Select Normal Game Type

Choose “Normal” as your game type.

Private rooms are not available for ranked games or offline mode. The option only appears when “Normal” is selected.

Configure Game Settings

Set your preferred game parameters:Time Limit: Choose from available options (default: 0 seconds for untimed)

TIME_LIMITS = [0]  // Untimed games

Board Size: Select from three sizes:

BOARD_SIZES = [5, 7, 9]  // Small, Medium, Large

Choose Private Room Option

Under “Avec qui jouer?” (Who to play with), select “Partie privée” instead of “Chercher une partie”.This reveals the room code input field.

Enter Room Code

Create or enter a room code in the “Code de la partie” field:

Alphanumeric codes supported
Case-sensitive
Share this code with your friend

Use memorable codes like “beehex123” or “game42” to easily share with friends!

Click Jouer to Join

Press the “Jouer” button to create/join the room. The system will:

Connect to the game server via WebSocket
Send a JOIN_ROOM packet with your room code
Wait for a second player to join with the same code
Start the game when both players are ready

Room Code System

How Room Codes Work

The private room system uses unique identifiers:

// Join room packet structure
{
  type: ServerBoundPacketType.JOIN_ROOM,
  room_id: "your_room_code",  // Custom code
  game_parameters: {
    time_limit: 0,
    board_size: 7,
    ranked: false  // Always false for private rooms
  }
}

Both players must use identical game parameters (board size, time limit) for the room to match. Mismatched settings will prevent connection.

Room Code Input

The input field includes special character conversion:

// French keyboard number row symbols auto-convert
const numbers = {
  "&": 1, "é": 2, "\"": 3, "'": 4,
  "(": 5, "-": 6, "è": 7, "_": 8,
  "ç": 9, "à": 0
};

This helps French keyboard users type numbers without holding Shift.

Joining a Friend’s Room

To join a game your friend created:

Get the Room Code

Ask your friend for the exact room code they used when creating the room.

Match Game Settings

Ensure your game parameters match theirs:

Same board size (5, 7, or 9)
Same time limit
“Normal” game type selected

Select Partie Privée

Choose “Partie privée” under “Avec qui jouer?”

Enter Room Code

Type or paste the room code exactly as provided (case-sensitive).

Join the Game

Click “Jouer” to connect. You’ll be matched with your friend instantly if settings match.

If your friend’s settings don’t match yours, you won’t connect to their room. Double-check:

Board size
Time limit
Room code spelling

Game Configuration

Available Settings

Private rooms support full customization:

Board Sizes

5×5: Quick 10-15 minute games7×7: Standard 20-30 minute matches9×9: Deep strategic games (40+ minutes)

Time Limits

0 seconds: Untimed (think as long as you need)Additional time limits may be configured in game settings

Ranked vs. Private Rooms

Feature	Ranked Games	Private Rooms
MMR Changes	Yes	No
Matchmaking	Automatic	Manual (code)
Opponent	Random	Choose friend
Game Type	Must be “Classé”	Must be “Normal”
Leaderboard	Affects rank	No effect

Use private rooms to practice strategies with friends before trying them in ranked play!

Connection Process

Understand what happens when you create/join a room:

WebSocket Connection

1. Client establishes WebSocket connection
   → new WebsocketHandler({ callbacks... })

2. Server authenticates your token
   → Verifies you're logged in

3. JOIN_ROOM packet sent with code
   → Server creates or finds matching room

4. Waiting for second player...
   → Loading page displays while waiting

5. Both players connected
   → gameFoundCallback triggered
   → Redirect to /hex/o_[gameId]

6. Game starts!
   → Normal gameplay begins

Loading Screen

While waiting for your friend:

{isSearchingGame && <LoadingPage />}

The loading page displays until:

Your friend joins with matching code
Connection error occurs
You cancel the search

If the loading screen persists, verify your friend used the exact same room code and game settings.

Troubleshooting Private Rooms

Connection Issues

“Connection ended” error: This occurs when:

Server is unreachable
Network connection lost
Invalid authentication token
Server timeout

Solutions:

Check your internet connection
Verify you’re logged in (see username in navbar)
Try refreshing the page
Log out and log back in

Room Not Found

If you can’t connect to a friend’s room:

Verify Room Code

Confirm the exact code with your friend—codes are case-sensitive.

Check Game Parameters

Both players must select identical:

Board size
Time limit

Confirm Game Type

Both players must have “Normal” selected, not “Hors-Ligne” or “Classé”.

Timing

Try clicking “Jouer” at approximately the same time to ensure the room exists when you search.

Infinite Loading

Stuck on the loading screen?

// The system waits for gameFoundCallback
function gameFoundCallback(game_id) {
  window.location.href = `/hex/o_${game_id}`;
}

If this never triggers:

No matching room exists
Settings mismatch between players
Server-side matching error

Fix: Go back, verify settings with your friend, and try again.

Game Rules in Private Rooms

Private room games follow standard Hex rules:

Turn-Based

Players alternate turns placing pieces on the hexagonal board

Victory Condition

First to connect their two edges wins:

Red: Top to bottom
Blue: Left to right

Game Features

Private rooms include all standard features:

Real-time synchronization via WebSocket
Move validation on server side
Game review mode after completion
Full move history saved to database
Automatic victory detection

Private room games are saved to your game history just like public matches, but they don’t affect your MMR or leaderboard position.

Best Practices

Creating Rooms

Pro tips for smooth private games:

Share settings first: Tell your friend the board size and time limit before sharing the code
Use simple codes: Avoid special characters that might be mistyped
Coordinate timing: Join within a few seconds of each other
Test connection: Try a quick game first to ensure settings work

During Gameplay

Stay connected: Don’t close the tab during the game
Reconnection works: If disconnected, the game will attempt to reconnect you automatically
Be patient: Allow time for moves to synchronize over the network

Convenient ways to share room codes:

Text/Chat

Send via Discord, WhatsApp, SMS, etc.

Voice Call

Spell out the code over voice chat

Screen Share

Show your game setup screen

Private Room vs. Other Modes

When to Use Private Rooms

Choose private rooms when you want to:

Play against a specific friend
Practice without affecting rank
Teach someone the game
Try experimental strategies
Have fun in a casual setting

When to Use Matchmaking

Choose “Chercher une partie” when you want to:

Find opponents quickly
Play ranked for MMR
Face players of similar skill
Discover new opponents

When to Use Offline Mode

Choose “Hors-Ligne” when you want to:

Play without internet
Pass-and-play on same device
Practice alone
No account required

Game History

After your private room game ends:

// Game saved to database with:
{
  gameId: "unique_id",
  gameParameters: {
    ranked: false,  // Private rooms are never ranked
    board_size: 7,
    time_limit: 0
  },
  firstPlayerId: "your_id",
  secondPlayerId: "friend_id",
  status: FIRST_PLAYER_WIN,  // or SECOND_PLAYER_WIN
  moves: "0 6 12 18 24..."   // Full game sequence
}

Access your private games via:

History page (/history): Browse all past games
Game mode sidebar: See last 5 matches
Direct URL: /hex/o_[gameId] to review

Share game URLs with friends to let them review your matches too!

Security & Fair Play

Room Code Privacy

Room codes are:

Not listed publicly: Only players with the code can join
Session-based: Rooms close after the game
No password: The code itself is the authentication

Don’t share room codes publicly if you want to ensure only your friend joins. Treat codes like temporary passwords.

Anti-Cheat

All moves are validated server-side:

Move legality checked: Can’t place on occupied cells
Turn order enforced: Must wait for your turn
Victory detection: Server determines winner (not client)

Next Steps

Start Playing

Learn gameplay mechanics and controls

Ranking System

Understand MMR and competitive play

Need help? If you encounter issues with private rooms, check your browser console for error messages or verify your internet connection and login status.

Get Started

Game Features

User Guide

Documentation Index

​Overview

​Creating a Private Room

​Room Code System

​How Room Codes Work

​Room Code Input

​Joining a Friend’s Room

​Game Configuration

​Available Settings

Board Sizes

Time Limits

​Ranked vs. Private Rooms

​Connection Process

​WebSocket Connection

​Loading Screen

​Troubleshooting Private Rooms

​Connection Issues

​Room Not Found

​Infinite Loading

​Game Rules in Private Rooms

Turn-Based

Victory Condition

​Game Features

​Best Practices

​Creating Rooms

​During Gameplay

​Advanced: Room Code Sharing

Text/Chat

Voice Call

Screen Share

​Private Room vs. Other Modes

​When to Use Private Rooms

​When to Use Matchmaking

​When to Use Offline Mode

​Game History

​Security & Fair Play

​Room Code Privacy

​Anti-Cheat

​Next Steps

Start Playing

Ranking System

Build docs developers (and LLMs) love

Overview

Creating a Private Room

Room Code System

How Room Codes Work

Room Code Input

Joining a Friend’s Room

Game Configuration

Available Settings

Ranked vs. Private Rooms

Connection Process

WebSocket Connection

Loading Screen

Troubleshooting Private Rooms

Connection Issues

Room Not Found

Infinite Loading

Game Rules in Private Rooms

Game Features

Best Practices

Creating Rooms

During Gameplay

Advanced: Room Code Sharing

Private Room vs. Other Modes

When to Use Private Rooms

When to Use Matchmaking

When to Use Offline Mode

Game History

Security & Fair Play

Room Code Privacy

Anti-Cheat

Next Steps