Code Generation

Relevant source files

• .github/workflows/update-protos.yml
• Makefile
• apigen/api_generate.go
• cmd/generate/main.go

This document describes the code generation infrastructure that produces the majority of the go-dota2 codebase. The system implements a two-stage pipeline: Protobuf Generation transforms upstream .proto files into Go types, and API Generator (apigen) uses reflection over those types to generate high-level client methods and event handlers.

For details on the API generator's logic and override system, see API Generator (apigen). For information about the build system and development tools, see Build System and Tools. For the protobuf generation implementation details, see Protocol Buffer Generation.

Overview

The code generation system produces three main outputs:

Output	Location	Contents
Protocol types	protocol/*.pb.go	Generated protobuf message types
Client methods	client_generated.go	~170 type-safe API methods
Event types	events/generated.go	~50 typed event structs

The generation pipeline is orchestrated by cmd/generate/main.go and can be triggered manually via make gen.

Sources: cmd/generate/main.go1-38 Makefile27-30

Generation Pipeline Architecture

The pipeline consists of two independent stages that run sequentially:

Title: Code Generation Pipeline Flow

Sources: cmd/generate/main.go51-106 Makefile15-30

Entry Points and Execution

The generation pipeline can be invoked through multiple mechanisms:

Method	Command	Purpose
Manual (recommended)	make gen	Run full pipeline locally via cmd/generate
Manual (advanced)	cd cmd/generate && go run .	Direct execution of orchestrator
Automation	.github/workflows/update-protos.yml	Scheduled updates (every 3 days)

The main orchestrator at cmd/generate/main.go accepts flags for debugging:

• --verbose: Enable detailed output cmd/generate/main.go41
• --skip-submodule: Skip git submodule update cmd/generate/main.go42
• --skip-apigen: Skip API generation stage cmd/generate/main.go43

Sources: cmd/generate/main.go40-49 Makefile27-30 .github/workflows/update-protos.yml1-32

Stage 1: Protobuf Generation

Submodule Management

The pipeline begins by updating the generator/Protobufs git submodule, which contains upstream .proto files from the Dota 2 game coordinator. The orchestrator uses git submodule update --init to ensure the source files are present.

Sources: cmd/generate/main.go67-72 .github/workflows/update-protos.yml21-24

Preprocessing Pipeline

The preprocessing step transforms upstream .proto files into valid protobuf files compatible with the Go generator. Upstream files often lack syntax declarations or use incompatible import paths.

The preprocessProtos function applies several transformations:

1. Header injection: Prepends syntax = "proto2"; package protocol; cmd/generate/main.go227
2. Type reference normalization: Removes leading dots from type references (e.g., optional .Type → optional Type) cmd/generate/main.go228-231
3. Import path fixes: Maps google/protobuf/valve_extensions.proto to local valveextensions.proto cmd/generate/main.go232
4. Glob selection: Only specific files defined in sourceProtoGlobs are processed to minimize bloat cmd/generate/main.go22-38

Sources: cmd/generate/main.go123-191 cmd/generate/main.go226-235

Generation Execution

The system uses the aptre tool (from github.com/aperturerobotics/common/cmd/aptre) to manage the protobuf generation process. This tool handles the execution of protoc and the Go protobuf plugin across the files in the protocol/ directory.

Sources: cmd/generate/main.go18 Makefile4-5 Makefile16-17

Stage 2: API Generation

Reflection-Based Parsing

The API generator (apigen) uses Go reflection and the go/types package to analyze the generated protocol package via BuildProtoTypeMap. It builds a map of message IDs (using the EDOTAGCMsg enum) to their corresponding Go types.

Title: apigen Reflection Logic

Sources: apigen/api_generate.go19-24 apigen/api_generate.go46-78 Makefile23-25

Client Method Generation

The generator produces client methods in client_generated.go. It distinguishes between "fire-and-forget" methods (no response) and "request-response" methods (using MakeRequest).

• Fire-and-forget: Methods call internal write functions with the message ID and request body.
• Request-Response: Methods accept a context.Context and return a response pointer and an error. They call MakeRequest() using the EDOTAGCMsg identifier.
• Automation: This ensures that as Dota 2 updates its protocol, the Go client can be updated with minimal manual intervention.

Sources: apigen/api_generate.go232-241 cmd/generate/main.go92-97

Event Type Generation

For messages sent by the Game Coordinator that are not direct responses, the generator creates typed event structs in events/generated.go. These events allow the user to subscribe to specific Game Coordinator updates using type-safe handlers.

Sources: apigen/api_generate.go70-76 cmd/generate/main.go92-97

Build Reproducibility

The generation process is designed to be reproducible across environments:

• Aptre Tooling: Uses a pinned version of the aptre tool for consistent generation and linting cmd/generate/main.go18 Makefile4
• Vendoring: The pipeline explicitly vendors protobuf dependencies to ensure the generator uses the same versions as the runtime cmd/generate/main.go79-85
• Go Mod Tidy: Automated workflows ensure module files are kept clean after generation .github/workflows/update-protos.yml34-35

Sources: cmd/generate/main.go79-85 Makefile12-13 .github/workflows/update-protos.yml34-35