Skip to main content

Auto-Matching Players

Auto-matching automatically finds and connects players for Standard Rooms based on your configured criteria. This feature eliminates the need for manual invitation codes and creates a seamless multiplayer experience.

How Auto-Matching Works​

  1. Room Creation: Create a room with auto-match parameters
  2. Player Pool: Your room enters the global player pool
  3. Matching Algorithm: System matches players based on skill, availability, and room criteria
  4. Room Formation: Once minimum players are found, room transitions to connecting state
  5. Game Start: All players connect and the room becomes active

Auto-Match Parameters​

When creating a room with auto-matching, configure these parameters:

ParameterTypeDescription
min_automatch_playersnumberMinimum players required to start (default: 2)
max_automatch_playersnumberMaximum players allowed in room (default: 2)
variantnumberGame mode variant for matching (0-255)
exclusive_bitmaskstring8-bit mask for role-based matching

Examples​

Basic 2-Player Auto-Match​

Create a room for 1v1 matchmaking:

MoitribeSDK('my-game-id', 'createstandardroom', {
  variant: 0,  // Standard 1v1 mode
  min_automatch_players: 2,
  max_automatch_players: 2,
  onRoomCreated: (status, room) => {
    if (status) {
      console.log('Auto-match room created:', room.roomID);
      console.log('Waiting for opponent...');
      showMatchmakingScreen();
    }
  },
  onRoomConnected: (status, room) => {
    if (status) {
      console.log('All players connected!');
      hideMatchmakingScreen();
      startGame(room);
    }
  },
  onMessageReceived: (messageData, senderID, isReliable) => {
    handleGameMessage(messageData, senderID);
  },
  onPeerJoined: (room, participantList) => {
    console.log('Player joined:', participantList.length, '/ 2');
    updateMatchmakingStatus(`Found ${participantList.length}/2 players`);
  },
  onPeerLeft: (room, participantList) => {
    console.log('Player left matchmaking');
    if (room.status === 1) { // Still auto-matching
      updateMatchmakingStatus('Player left, searching again...');
    }
  },
  onLeftRoom: (status, roomID) => {
    console.log('Left matchmaking room');
    returnToLobby();
  }
}, (result) => {
  console.log('Auto-match request sent:', result);
});

Multi-Player Auto-Match (2-4 Players)​

Create a flexible room for 2-4 players:

MoitribeSDK('my-game-id', 'createstandardroom', {
  variant: 1,  // Multiplayer mode
  min_automatch_players: 2,  // Start with 2 players
  max_automatch_players: 4,  // Allow up to 4 players
  onRoomCreated: (status, room) => {
    if (status) {
      console.log('Multiplayer room created');
      console.log('Auto-match range: 2-4 players');
      showMatchmakingScreen('2-4 Players');
    }
  },
  onRoomConnected: (status, room) => {
    if (status) {
      console.log(`Game starting with ${room.participants.length} players`);
      startMultiplayerGame(room);
    }
  },
  onPeerJoined: (room, participantList) => {
    const count = participantList.length;
    const max = room.max_automatch_players;
    
    console.log(`Player joined: ${count}/${max}`);
    updateMatchmakingStatus(`${count}/${max} players found`);
    
    // Show countdown when room is nearly full
    if (count >= max - 1) {
      startGameCountdown();
    }
  },
  onMessageReceived: (messageData, senderID, isReliable) => {
    handleMultiplayerMessage(messageData, senderID);
  },
  onPeerLeft: (room, participantList) => {
    console.log('Player left during matchmaking');
    cancelGameCountdown();
  },
  onLeftRoom: (status, roomID) => {
    console.log('Left multiplayer matchmaking');
    returnToLobby();
  }
}, (result) => {
  console.log('Multiplayer auto-match started:', result);
});

Role-Based Auto-Match​

Use exclusive bitmask for role-based matching:

// Define roles using bitmask
const ROLES = {
  TANK: '00000001',    // Bit 0
  HEALER: '00000010',  // Bit 1
  DPS: '00000100',     // Bit 2
  SUPPORT: '00001000'  // Bit 3
};

// Create room requiring specific team composition
MoitribeSDK('my-game-id', 'createstandardroom', {
  variant: 2,  // Team-based mode
  min_automatch_players: 4,
  max_automatch_players: 4,
  exclusive_bitmask: '00000111',  // Require Tank, Healer, DPS
  onRoomCreated: (status, room) => {
    if (status) {
      console.log('Team-based room created');
      console.log('Required roles: Tank, Healer, DPS');
      showTeamMatchmakingScreen();
    }
  },
  onRoomConnected: (status, room) => {
    if (status) {
      console.log('Team assembled!');
      displayTeamComposition(room.participants);
      startTeamGame(room);
    }
  },
  onPeerJoined: (room, participantList) => {
    console.log(`Team member joined: ${participantList.length}/4`);
    updateTeamStatus(participantList.length);
  },
  onMessageReceived: (messageData, senderID, isReliable) => {
    handleTeamMessage(messageData, senderID);
  },
  onPeerLeft: (room, participantList) => {
    console.log('Team member left - re-matching may be needed');
  },
  onLeftRoom: (status, roomID) => {
    console.log('Left team matchmaking');
    returnToLobby();
  }
}, (result) => {
  console.log('Team auto-match started:', result);
});

Room Status During Auto-Matching​

Auto-matching rooms go through these status changes:

  1. AUTO_MATCHING (1): Room is in the matchmaking pool
  2. CONNECTING (2): Minimum players found, establishing connections
  3. ACTIVE (3): All players connected, game can start
onRoomCreated: (status, room) => {
  console.log('Initial status:', room.status); // 1 (AUTO_MATCHING)
},

onRoomConnected: (status, room) => {
  console.log('Connected status:', room.status); // 3 (ACTIVE)
}

Wait Time Management​

Monitor and display auto-match wait times:

onRoomCreated: (status, room) => {
  if (status) {
    const waitTime = room.autoMatchWaitSeconds;
    console.log(`Estimated wait time: ${waitTime} seconds`);
    
    // Show countdown or progress indicator
    startWaitTimer(waitTime);
  }
}

Best Practices​

Set Realistic Player Ranges​

  • 1v1 Games: Use min: 2, max: 2
  • Small Groups: Use min: 2, max: 4 for faster matching
  • Large Groups: Use min: 4, max: 8 for party games

Use Variants Wisely​

  • Different variants create separate matchmaking pools
  • Use variants for different game modes, not skill levels
  • Keep variant numbers consistent across your game

Handle Timeouts Gracefully​

  • Show estimated wait times
  • Provide cancel option for long waits
  • Implement reconnection logic for network issues

Monitor Room Status​

  • Track status changes for UI updates
  • Handle transitions between matchmaking states
  • Show appropriate feedback for each phase
tip

Auto-matching works best when you have a reasonable player range. Too narrow (exact player counts) can result in long wait times, while too wide may create unbalanced games.

Next Steps​