dota2-gc

A TypeScript wrapper for the Dota 2 Game Coordinator (GC). Provides a clean async/await API for interacting with Dota 2's backend services.

Installation

npm install dota2-gc

Features

• Match Data: Fetch match details, player history, and stats
• Lobby Management: Create/manage practice lobbies, invite players, add bots
• TypeScript: Full type definitions included
• Dual API: Promise-based for requests, EventEmitter for real-time updates

Quick Start

import { Dota2Client } from 'dota2-gc';

const client = new Dota2Client();

// Handle Steam Guard (if enabled on account)
client.on('steamGuard', (domain, callback, lastCodeWrong) => {
  // Get code from user input or email
  const code = '12345';
  callback(code);
});

// Login and connect to GC
await client.login({
  accountName: 'your_username',
  password: 'your_password',
});

// Wait for GC connection
client.on('ready', async () => {
  console.log('Connected to Dota 2 GC!');

  // Fetch match details
  const match = await client.match.getDetails(7234567890);
  console.log(`Match duration: ${match.duration}s`);

  // Create a lobby
  const lobby = await client.lobby.create({
    gameName: 'My Practice Lobby',
    gameMode: DOTA_GameMode.DOTA_GAMEMODE_AP,
    serverRegion: EServerRegion.USEAST,
  });
  console.log(`Lobby created: ${lobby.lobbyId}`);
});

client.on('disconnected', (reason) => {
  console.log('Disconnected:', reason);
});

API Reference

Dota2Client

The main client class that manages the Steam and GC connection.

Methods

// Login to Steam
await client.login({ accountName: string, password: string });

// Logout and disconnect
client.logout();

// Check connection status
client.ready; // true if connected to Steam and GC
client.steamReady; // true if connected to Steam

Events

client.on('ready', () => void);
client.on('disconnected', (reason: string) => void);
client.on('error', (error: Error) => void);
client.on('steamGuard', (domain, callback, lastCodeWrong) => void);

Match Handler (client.match)

Get Match Details

const match = await client.match.getDetails(matchId);

// Returns:
interface MatchDetails {
  matchId: string;
  duration: number;
  startTime: number;
  gameMode: number;
  radiantWin: boolean;
  radiantScore: number;
  direScore: number;
  players: MatchPlayer[];
  // ... and more
}

Get Player Match History

const history = await client.match.getPlayerHistory(accountId, {
  heroId?: number,           // Filter by hero
  startAtMatchId?: string,   // Pagination
  matchesRequested?: number, // Default: 20
});

// Returns:
interface PlayerMatchHistory {
  matches: PlayerMatchHistoryMatch[];
}

Get Player Stats

const stats = await client.match.getPlayerStats(accountId);

// Returns:
interface PlayerStats {
  accountId: number;
  totalWins: number;
  totalLosses: number;
  soloRank?: number;
  partyRank?: number;
  // ... and more
}

Lobby Handler (client.lobby)

Create Lobby

const lobby = await client.lobby.create({
  gameName: 'My Lobby',
  password: 'secret',
  serverRegion: EServerRegion.USEAST,
  gameMode: DOTA_GameMode.DOTA_GAMEMODE_CM,
  allowCheats: false,
  fillWithBots: false,
  allowSpectating: true,
  visibility: DOTALobbyVisibility.PUBLIC,
  dotaTvDelay: LobbyDotaTVDelay.TWO_MINUTES,
  pauseSetting: LobbyDotaPauseSetting.LIMITED,
  allChat: true,
  cmPick: DOTACMPick.CM_RANDOM,
  botDifficultyRadiant: DOTABotDifficulty.BOT_DIFFICULTY_HARD,
  botDifficultyDire: DOTABotDifficulty.BOT_DIFFICULTY_HARD,
  seriesType: 1, // Bo3
});

Update Lobby Settings

// Update any lobby settings (must be lobby leader)
client.lobby.updateSettings({
  gameName: 'New Lobby Name',
  gameMode: DOTA_GameMode.DOTA_GAMEMODE_AP,
  pauseSetting: LobbyDotaPauseSetting.DISABLED,
  allowCheats: true,
  dotaTvDelay: LobbyDotaTVDelay.FIVE_MINUTES,
  cmPick: DOTACMPick.CM_RADIANT,
  seriesType: 2, // Bo5
  radiantSeriesWins: 1,
  direSeriesWins: 0,
});

// Remove password
client.lobby.updateSettings({ password: '' });

Lobby Operations

// Leave the lobby
client.lobby.leave();

// Destroy the lobby (must be leader)
await client.lobby.destroy();

// Kick a player
client.lobby.kick(accountId);

// Set player team/slot
client.lobby.setTeam(accountId, {
  team: DOTA_GC_TEAM.DOTA_GC_TEAM_GOOD_GUYS,
  slot: 1,
});

// Add a bot
client.lobby.addBot({
  team: DOTA_GC_TEAM.DOTA_GC_TEAM_BAD_GUYS,
  difficulty: DOTABotDifficulty.BOT_DIFFICULTY_HARD,
});

// Flip teams
client.lobby.flipTeams();

// Start the game
client.lobby.launch();

Lobby Events

client.lobby.on('created', (lobby) => void);
client.lobby.on('updated', (lobby) => void);
client.lobby.on('destroyed', () => void);
client.lobby.on('playerJoined', (member) => void);
client.lobby.on('playerLeft', (accountId) => void);
client.lobby.on('stateChanged', (state) => void);

Current Lobby

// Get current lobby
const lobby = client.lobby.currentLobby;

// Check if in a lobby
if (client.lobby.inLobby) {
  // ...
}

Enums

Game Modes

import { DOTA_GameMode } from 'dota2-gc';

DOTA_GameMode.DOTA_GAMEMODE_AP    // All Pick
DOTA_GameMode.DOTA_GAMEMODE_CM    // Captain's Mode
DOTA_GameMode.DOTA_GAMEMODE_RD    // Random Draft
DOTA_GameMode.DOTA_GAMEMODE_AR    // All Random
DOTA_GameMode.DOTA_GAMEMODE_TURBO // Turbo
// ... and more

Server Regions

import { EServerRegion } from 'dota2-gc';

EServerRegion.USWEST
EServerRegion.USEAST
EServerRegion.EUROPE
EServerRegion.SINGAPORE
EServerRegion.AUSTRALIA
// ... and more

Teams

import { DOTA_GC_TEAM } from 'dota2-gc';

DOTA_GC_TEAM.DOTA_GC_TEAM_GOOD_GUYS  // Radiant
DOTA_GC_TEAM.DOTA_GC_TEAM_BAD_GUYS   // Dire
DOTA_GC_TEAM.DOTA_GC_TEAM_SPECTATOR

Bot Difficulty

import { DOTABotDifficulty } from 'dota2-gc';

DOTABotDifficulty.BOT_DIFFICULTY_PASSIVE
DOTABotDifficulty.BOT_DIFFICULTY_EASY
DOTABotDifficulty.BOT_DIFFICULTY_MEDIUM
DOTABotDifficulty.BOT_DIFFICULTY_HARD
DOTABotDifficulty.BOT_DIFFICULTY_UNFAIR

Lobby Settings

import {
  LobbyDotaTVDelay,
  LobbyDotaPauseSetting,
  DOTACMPick,
} from 'dota2-gc';

// DotaTV Delay
LobbyDotaTVDelay.NONE         // No delay
LobbyDotaTVDelay.TEN_SECONDS  // 10 second delay
LobbyDotaTVDelay.TWO_MINUTES  // 2 minute delay
LobbyDotaTVDelay.FIVE_MINUTES // 5 minute delay

// Pause Settings
LobbyDotaPauseSetting.UNLIMITED // Unlimited pauses
LobbyDotaPauseSetting.LIMITED   // Limited pauses
LobbyDotaPauseSetting.DISABLED  // No pauses

// Captain's Mode Pick Priority
DOTACMPick.CM_RANDOM  // Random first pick
DOTACMPick.CM_RADIANT // Radiant picks first
DOTACMPick.CM_DIRE    // Dire picks first

Utilities

import { steamId64ToAccountId, accountIdToSteamId64 } from 'dota2-gc';

// Convert Steam ID 64 to Account ID (32-bit)
const accountId = steamId64ToAccountId('76561198012345678');

// Convert Account ID to Steam ID 64
const steamId64 = accountIdToSteamId64(12345678);

Important Notes

• Bot Accounts: It's recommended to use dedicated bot accounts rather than personal accounts
• Rate Limits: The GC may rate limit requests; add delays between bulk operations
• VAC Risk: Using this library mimics the Dota 2 client. Use at your own risk.

License

MIT