Skip to content

ADVANCED_USAGE.md

Latest commit

 

History

History
470 lines (364 loc) · 11 KB

ADVANCED_USAGE.md

File metadata and controls

470 lines (364 loc) · 11 KB

Advanced Usage Guide

This guide covers advanced GABS features for power users and complex setups.

Prerequisites: Make sure you've read the Configuration Guide and AI Integration Guide first. For production deployments, see the Deployment Guide.

Multiple Game Instances

You can run multiple copies of the same game with different configurations:

# Configure multiple Minecraft servers
gabs games add minecraft-survival
gabs games add minecraft-creative
gabs games add minecraft-test

# Start GABS server
gabs server

AI can then control each instance separately:

  • "Start the creative server but keep survival server running"
  • "Check status of all minecraft instances"
  • "Stop the test server and start survival"

Use Cases

  • Testing: Run test servers alongside production
  • Multiple worlds: Different game modes or worlds
  • Load balancing: Switch between servers based on player count

Advanced Launch Configurations

Custom Commands with Arguments

For complex launch setups:

gabs games add complex-server
# When prompted, choose CustomCommand and enter:
# java -Xmx8G -Xms4G -jar server.jar --world=survival --port=25565 --nogui

Environment Variables

Set environment variables in custom commands:

# Custom command example:
# export JAVA_HOME=/usr/lib/jvm/java-17 && java -jar server.jar

Batch Scripts and Shell Scripts

Point to scripts that handle complex startup logic:

# DirectPath pointing to a script:
# /home/user/game-scripts/start-minecraft.sh

HTTP Mode Deep Dive

GABS can run as an HTTP server for integration with web tools and services.

Starting HTTP Mode

# Local only
gabs server --http localhost:8080

# All interfaces (careful with security!)
gabs server --http :8080

# Specific interface
gabs server --http 192.168.1.100:8080

API Endpoints

MCP Protocol Endpoint

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "games.list",
    "arguments": {}
  }
}

Health Check

GET /health

Returns basic server metadata such as status, server, and version.

Integration Examples

curl Commands

# List games
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"games.list","arguments":{}}}'

# Start a game
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"games.start","arguments":{"gameId":"minecraft"}}}'

Python Integration

import requests
import json

class GABSClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({"Content-Type": "application/json"})
    
    def call_tool(self, tool_name, arguments=None):
        if arguments is None:
            arguments = {}
            
        payload = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments
            }
        }
        
        response = self.session.post(f"{self.base_url}/mcp", json=payload)
        return response.json()
    
    def list_games(self):
        return self.call_tool("games.list")
    
    def start_game(self, game_id):
        return self.call_tool("games.start", {"gameId": game_id})
    
    def stop_game(self, game_id):
        return self.call_tool("games.stop", {"gameId": game_id})

# Usage
client = GABSClient()
games = client.list_games()
print("Available games:", games)

result = client.start_game("minecraft")
print("Start result:", result)

JavaScript/Node.js Integration

const axios = require('axios');

class GABSClient {
    constructor(baseUrl = 'http://localhost:8080') {
        this.baseUrl = baseUrl;
        this.requestId = 1;
    }
    
    async callTool(toolName, arguments = {}) {
        const payload = {
            jsonrpc: '2.0',
            id: this.requestId++,
            method: 'tools/call',
            params: {
                name: toolName,
                arguments: arguments
            }
        };
        
        try {
            const response = await axios.post(`${this.baseUrl}/mcp`, payload);
            return response.data;
        } catch (error) {
            console.error('GABS API error:', error.response?.data || error.message);
            throw error;
        }
    }
    
    async listGames() {
        return await this.callTool('games.list');
    }
    
    async startGame(gameId) {
        return await this.callTool('games.start', { gameId });
    }
    
    async stopGame(gameId) {
        return await this.callTool('games.stop', { gameId });
    }
    
    async getGameStatus(gameId) {
        return await this.callTool('games.status', { gameId });
    }
}

// Usage
const client = new GABSClient();

async function manageGames() {
    try {
        const games = await client.listGames();
        console.log('Available games:', games);
        
        await client.startGame('minecraft');
        console.log('Started minecraft');
        
        const status = await client.getGameStatus('minecraft');
        console.log('Minecraft status:', status);
        
    } catch (error) {
        console.error('Error managing games:', error);
    }
}

manageGames();

Configuration File Advanced Features

Tool Normalization for AI Compatibility

For advanced AI integrations, especially with OpenAI's API, you can configure tool name normalization:

The top-level "version" field below is the GABS config schema version, not the GABP protocol version.

{
  "version": "1.0",
  "toolNormalization": {
    "enableOpenAINormalization": true,
    "maxToolNameLength": 64,
    "preserveOriginalName": true
  },
  "games": {
    // ... your game configurations
  }
}

This feature:

  • Converts dotted names (minecraft.inventory.get) to underscored names (minecraft_inventory_get)
  • Enforces character limits for API compatibility
  • Preserves original names in descriptions for user clarity

See OpenAI Tool Normalization Guide for complete configuration details.

Multiple Config Directories

GABS uses a configuration directory, not a single standalone config file. This is useful when you want separate local, test, or CI environments.

# Use a custom config directory
GABS_CONFIG_DIR=/path/to/custom-gabs gabs server

# Or specify it directly
gabs server --configDir /path/to/custom-gabs
gabs games --configDir /path/to/custom-gabs list

Typical contents include config.json, per-game directories, bridge.json, and the internal runtime.json ownership file.

Configuration Inspection

Use the built-in game inspection commands instead of a separate config subcommand:

gabs games list
gabs games show minecraft

Security Considerations

Local vs Remote Access

  • Local only (default): GABS only accepts connections from localhost
  • Remote access: Use --http :8080 carefully, consider firewall rules

Authentication

  • GABP connections use token authentication automatically
  • HTTP mode can enforce Bearer authentication when apiKey is set in config.json; otherwise use a reverse proxy or keep it bound to localhost

Network Security

For remote deployments:

# Use a reverse proxy with authentication
nginx -> GABS HTTP mode

Example nginx config:

location /gabs/ {
    auth_basic "GABS Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://localhost:8080/;
}

Performance Tuning

Resource Limits

GABS is lightweight, but for many games consider:

# Linux: Set process limits
ulimit -n 4096  # File descriptors
ulimit -u 2048  # Process count

# Then start GABS
gabs server

Monitoring

Monitor GABS performance:

# Check process stats
ps aux | grep gabs

# Check network connections
netstat -tulpn | grep gabs

# If you want a persistent log file, redirect stderr yourself
gabs server --log-level debug 2> gabs-debug.log
tail -f gabs-debug.log

Scripting and Automation

Bash Scripts

#!/bin/bash
# start-game-servers.sh

# Start GABS
gabs server --http :8080 &
GABS_PID=$!

# Wait for GABS to start
sleep 5

# Start games via API
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"games.start","arguments":{"gameId":"minecraft"}}}'

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"games.start","arguments":{"gameId":"rimworld"}}}'

echo "Game servers started. GABS PID: $GABS_PID"

Systemd Service (Linux)

# /etc/systemd/system/gabs.service
[Unit]
Description=GABS Game Server Manager
After=network.target

[Service]
Type=simple
User=gameserver
WorkingDirectory=/home/gameserver
ExecStart=/usr/local/bin/gabs server --http :8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable gabs
sudo systemctl start gabs

Troubleshooting Advanced Issues

Port Conflicts

# Check what's using a port
lsof -i :8080
netstat -tulpn | grep :8080

# Use a different port
gabs server --http :8081

Memory Issues

# Monitor GABS memory usage
top -p $(pgrep gabs)

# Check game process memory
ps aux | grep -E "(minecraft|rimworld|gabs)"

Network Issues

# Test connectivity
telnet localhost 8080

# Check firewall (Linux)
sudo iptables -L | grep 8080

# Check firewall (macOS)
sudo pfctl -s rules | grep 8080

Debug Mode

# Run with debug logging
GABS_LOG_LEVEL=debug gabs server

# Or specify it directly
gabs server --log-level debug

Integration with CI/CD

Automated Testing

# GitHub Actions example
name: Game Server Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install GABS
        run: |
          wget https://github.com/pardeike/GABS/releases/latest/download/gabs-linux-amd64
          chmod +x gabs-linux-amd64
          sudo mv gabs-linux-amd64 /usr/local/bin/gabs
      
      - name: Configure test game
        run: |
          gabs games add test-game
          # Configure with test parameters
      
      - name: Start GABS
        run: |
          gabs server --http :8080 &
          sleep 5
      
      - name: Test game management
        run: |
          # Test API endpoints
          curl -X POST http://localhost:8080/mcp \
            -H "Content-Type: application/json" \
            -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"games.list","arguments":{}}}'

This advanced guide covers the more complex features of GABS. For basic usage, start with the main README and other guides first.