Architecture

Relevant source files

• LICENSE
• README.md
• client.go
• client_session.go
• cso/cso_types.go

This page provides an overview of the go-dota2 library's architecture, explaining its layered design, core subsystems, and how components interact to provide a type-safe Go client for the Dota 2 Game Coordinator.

For specific implementation details:

• SOCache internals and subscription mechanisms: see SOCache System
• Event types and consumption patterns: see Event System
• Request-response patterns and message routing: see Communication Flow
• Code generation process and tooling: see Code Generation Pipeline

Layered Architecture

The go-dota2 library follows a four-layer architecture that separates concerns between network communication, state management, generated code, and application logic.

Layer Architecture

Sources: client.go1-197 README.md1-81

The architecture ensures clear separation:

• Application Layer: User code that consumes the library.
• Generated API Layer: Type-safe method wrappers and event definitions created by code generation README.md40-41
• Core Library Layer: Hand-written session management, state synchronization, and caching logic client.go32-49
• Foundation Layer: External dependencies like go-steam README.md80 and protobuf-generated message types.

Core Components

Dota2 Client Structure

The Dota2 struct is the central component that coordinates all subsystems.

Dota2 Client Internals

Sources: client.go32-49 client.go52-66

Field responsibilities:

• le: Structured logging with contextual fields client.go33
• client: Reference to parent steam.Client for network I/O client.go34
• cache: SOCache instance holding all shared objects client.go35-55
• connectionCtx/connectionCtxCancel/connectionCtxMtx: Context lifecycle management for active GC session client.go37-128
• state/stateMtx: Thread-safe game state (connection status, lobby info) client.go41-62
• handlers: Message ID to handler function routing map client.go44-113
• pendReq/pendReqID/pendReqMtx: Outstanding request tracking for request-response pattern client.go46-48

Handler Map and Message Routing

The handlerMap type routes incoming GC packets to appropriate handler functions.

Message Dispatch System

Sources: client.go28-29 client.go83-113 client.go156-177 client.go186-196

The routing mechanism:

1. HandleGCPacket() receives all incoming GC packets client.go156
2. Message type (uint32) is extracted from packet client.go161
3. handlers map is queried for registered handler function client.go162
4. If found, handler is invoked with packet client.go164
5. handleResponsePacket() checks for pending request matches client.go170
6. Unhandled packets emit UnhandledGCPacket event client.go173-176

SOCache Architecture

The SOCache system provides thread-safe storage and subscription to game objects like Lobby and Party.

SOCache Component Hierarchy

Sources: client.go35-71 README.md43-70 cso/cso_types.go17-54

Key design patterns:

• Type Mapping: CSOType enumerations map numeric IDs to Protobuf message types cso/cso_types.go17-91
• Subscription model: Multiple subscribers can receive events for object changes using SubscribeType README.md55
• Hand-written state tracking: Lobby and party operations are tracked correctly through SOCache README.md34-39

Generated API Layer

The generated API provides type-safe methods for interacting with the Game Coordinator based on heuristics and manual overrides README.md72-74

Generated Method Patterns

Pattern	Example	Characteristics
Fire-and-forget	SetPlaying(bool)	Calls write(), returns void client.go14-118
Request-response	SayHello(...)	Calls write() with EMsgGCClientHello client_session.go27-38
System Handlers	handlePingRequest	Responds to GC-initiated pings automatically client.go180-183

Sources: README.md70-77 client.go112 client.go180-183 client_session.go27-38

Thread Safety and Concurrency

The library employs multiple concurrency patterns to ensure thread-safe operations.

Concurrency Patterns

Sources: client.go37-49 client.go126-142

Concurrency mechanisms:

• Mutex-protected state: stateMtx guards state field, accessed only via accessState() callback pattern client.go126-142
• Connection context lifecycle: connectionCtx managed via connectionCtxMtx and cancelled via connectionCtxCancel during session changes client_session.go98-131
• Request mutex: pendReqMtx protects outstanding request map client.go46

The accessState() callback pattern client.go126-142 ensures state changes are atomic and automatically emit state change events when mutations occur.