Private Rooms

Create and join private games to play with friends using custom room codes

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:

1. Navigate to Game Mode

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

2. 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.

3. 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
   
4. 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.

5. 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!

6. Click Jouer to Join

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

   1. Connect to the game server via WebSocket
   2. Send a JOIN_ROOM packet with your room code
   3. Wait for a second player to join with the same code
   4. 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:

1. Get the Room Code

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

2. Match Game Settings

   Ensure your game parameters match theirs:

   • Same board size (5, 7, or 9)
   • Same time limit
   • “Normal” game type selected
3. Select Partie Privée

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

4. Enter Room Code

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

5. 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 games

7×7: Standard 20-30 minute matches

9×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:

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

Room Not Found

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

1. Verify Room Code

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

2. Check Game Parameters

   Both players must select identical:

   • Board size
   • Time limit
3. Confirm Game Type

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

4. 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:

1. Share settings first: Tell your friend the board size and time limit before sharing the code
2. Use simple codes: Avoid special characters that might be mistyped
3. Coordinate timing: Join within a few seconds of each other
4. 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

Advanced: Room Code Sharing

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.