GABP (Game Agent Bridge Protocol)

GABP is a communication protocol that lets AI tools talk to games. It works like a bridge between AI agents and game modifications. This allows AI systems, testing tools, and other programs to control and interact with games in a standard way.

Status

Protocol Version: 1.0
Repository Versioning: SemVer
Wire Protocol Version: gabp/1

The protocol uses semantic versioning for repository releases. The wire protocol version gabp/1 represents the major version and will only include additive changes within the 1.x series. Breaking changes will require gabp/2 and new schema folders.

What is GABP?

GABP defines these key parts:

• Message Format: JSON messages that look like JSON-RPC with requests, responses, and events
• Transport Layer: Works with stdio, TCP connections (local only), and pipes/sockets
• Security Model: Uses tokens for authentication and only allows local connections
• Method Registry: Standard names for methods and error codes
• Capability Negotiation: Handshake process to discover what features are available

Key Terms

• Bridge: The client program that connects to the game mod (this is your AI tool)
• Mod: The server program running inside the game (the game modification)
• Agent: The AI or automation system that uses the bridge to control the game

Documentation

• Main Specification - Complete protocol rules and requirements
• Transport & Connections - How to connect and send messages
• Security Guide - Authentication and safety rules
• Method Registry - Standard method names and error codes
• Wire-Model Decisions - Canonical 1.0 wire naming and field choices
• Attention And Execution Gating Architecture - Architecture and rollout note for additive attention support within gabp/1
• AI Implementation Guide - AI-assisted development prompts and patterns

Schemas

Computer-readable definitions are in the SCHEMA/1.0/ directory:

• envelope.schema.json - Basic message structure
• methods/ - Schemas for standard method calls
• events/ - Schemas for event messages
• common/ - Shared definitions used everywhere

Examples

Working examples of GABP messages are in EXAMPLES/1.0/:

• Handshake - How to start a session
• Tools - How to find and use tools
• Events - How to subscribe to and receive events
• Attention - Optional attention inspection, lifecycle, and acknowledgement flow

Validation

You can validate GABP messages using AJV:

npm install -g ajv-cli
ajv -s SCHEMA/1.0/envelope.schema.json -d 'your-message.json'

Conformance Tests

The CONFORMANCE/1.0/ directory contains:

• valid/ - Messages that should validate successfully
• invalid/ - Messages that should fail validation

Getting Started

1. Connect: Bridge connects to mod using one of the transport methods
2. Handshake: Send session/hello and receive session/welcome messages
3. Discover: Use tools/list to see what the game can do
4. Interact: Call methods, subscribe to events, and read resources

Optional additive support within gabp/1 lets implementations expose important summarized game-side state through:

• attention/current
• attention/ack
• attention/opened
• attention/updated
• attention/cleared

Bridges MUST discover that support through capabilities.methods and capabilities.events instead of assuming it is always present.

Basic handshake example:

// Bridge -> Mod: session/hello
{
  "v": "gabp/1",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "request",
  "method": "session/hello",
  "params": {
    "token": "abc123...",
    "bridgeVersion": "1.0.0",
    "platform": "windows",
    "launchId": "game-session-123"
  }
}

// Mod -> Bridge: session/welcome
{
  "v": "gabp/1",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "response",
  "result": {
    "agentId": "minecraft-mod-v2.1",
    "app": {
      "name": "Minecraft",
      "version": "1.20.4"
    },
    "capabilities": {
      "methods": [
        "tools/list",
        "tools/call",
        "events/subscribe",
        "events/unsubscribe",
        "resources/list",
        "resources/read"
      ],
      "events": ["player/move", "world/block_change"],
      "resources": ["gabp://game/world/schematic"]
    },
    "schemaVersion": "1.0"
  }
}

Packages

The repository includes three versioned schema packages, all sourced from the canonical SCHEMA/1.0/ tree.

JavaScript/Node.js

The gabp-schemas package bundles the schema tree and exposes preloaded validators for Node.js and TypeScript consumers.

npm install gabp-schemas

const { validateRequest } = require("gabp-schemas");

const message = {
  /* your GABP request */
};
const result = validateRequest(message);
if (!result.valid) {
  console.error("Validation errors:", result.errors);
}

.NET

The Gabp.Schemas package embeds the same schema assets and exposes them through the SchemaAssets API for .NET consumers.

NuGet package ID: Gabp.Schemas

Go

The github.com/pardeike/GABP/packages/go/schemas module embeds the same versioned schema assets for Go consumers.

Module path: github.com/pardeike/GABP/packages/go/schemas

Repository releases for the npm package and NuGet package use top-level tags such as v1.1.0. The Go module uses subdirectory-prefixed tags such as packages/go/schemas/v1.1.0.

Contributing

See CONTRIBUTING.md for guidelines on contributing to the GABP specification.

Versioning

See VERSIONING.md for details on how GABP versions are managed.

License

• Specification documents (in SPEC/) are licensed under CC BY 4.0
• Code, schemas, and examples are licensed under Apache 2.0

Changelog

See CHANGELOG.md for a complete history of changes.