Hugging Face's logo

Spaces:
Luigi
/
rts-commander
Sleeping

App Files Community
rts-commander / docs /MCP_GAME_CONTROL_DETAILS.md
Luigi's picture
Luigi
Initial commit: Complete RTS project with MCP evaluation
551ad28
preview code
|
raw
history blame
9.34 kB

Detailed Game Control via MCP Interface

Overview

The MCP interface we've implemented provides comprehensive control over the RTS Commander game, allowing AI agents to both observe and manipulate the game state through standardized tools. This document details exactly what aspects of the game can be controlled via the MCP interface.

Game State Observation

Full Game State Access

The get_game_state() tool provides complete visibility into the game:

  1. Units Information

    • All units on the map (player and enemy)
    • Unit types (infantry, tanks, helicopters, harvesters)
    • Current positions, health, and status
    • Cargo capacity for harvesters
    • Movement targets and combat targets
    • Manual control status

  2. Buildings Information

    • All buildings (HQ, power plants, barracks, etc.)
    • Building types and positions
    • Health status
    • Production queues and progress
    • Defensive targeting for turrets

  3. Player Information

    • Resources (credits)
    • Power production and consumption
    • Superweapon charge status
    • Language preferences
    • AI vs human player status

  4. Map Information

    • Terrain types (grass, ore, gems, water)
    • Fog of war visibility
    • Map dimensions

  5. Game Status

    • Current game tick
    • Game started/over status
    • Winner information
    • Last AI analysis

Game Actions (Control)

Unit Control

  1. Movement

    • move_units(unit_ids, target_x, target_y): Move any units to specific coordinates
    • Supports single unit or group movement
    • Automatic formation spreading for multiple units

  2. Combat

    • attack_unit(attacker_ids, target_id): Command units to attack specific enemies
    • Works for both unit-vs-unit and unit-vs-building combat
    • Sets manual order flags to override AI behavior

Building Control

  1. Construction

    • build_building(building_type, position_x, position_y, player_id): Construct any building type
    • Enforces game rules (cost, positioning, requirements)
    • Handles all building types: HQ, power plants, barracks, war factories, refineries, defense turrets

  2. Unit Production

    • send_game_command(command_type="build_unit", ...): Produce units in appropriate buildings
    • Validates production requirements (barracks for infantry, etc.)
    • Manages production queues

Strategic Actions

  1. Superweapon

    • Launch nukes when charged
    • Prepare and cancel nuke targeting
    • Automatic charge management

  2. Game Management

    • send_game_command(command_type="change_language", ...) : Change player language
    • send_game_command(command_type="request_ai_analysis", ...) : Request tactical analysis

AI Integration

Tactical Analysis

The get_ai_analysis(language) tool provides:

  • Strategic situation summary
  • Tactical recommendations (4 tips)
  • Motivational coaching line
  • Language-specific output (EN/FR/ZH-TW)

This connects to the same Qwen2.5-0.5B LLM that powers the in-game AI analysis panel.

Detailed Tool Breakdown

1. get_game_state()

Purpose: Retrieve complete current game state Returns: JSON object with all game information Use Cases:

  • Understanding current tactical situation
  • Planning strategic moves
  • Monitoring resource levels
  • Tracking unit positions and health

2. get_ai_analysis(language)

Purpose: Get tactical analysis from built-in AI Parameters:

  • language (optional, default="en"): Language for output Returns: JSON with summary, tips, and coach message Use Cases:
  • Getting strategic advice
  • Understanding tactical priorities
  • Learning from AI recommendations

3. move_units(unit_ids, target_x, target_y)

Purpose: Move units to specific location Parameters:

  • unit_ids: List of unit IDs to move
  • target_x: X coordinate destination
  • target_y: Y coordinate destination Returns: Success/failure message Use Cases:
  • Positioning units for attack
  • Moving harvesters to ore
  • Relocating defensive units
  • Executing tactical maneuvers

4. attack_unit(attacker_ids, target_id)

Purpose: Command units to attack an enemy Parameters:

  • attacker_ids: List of unit IDs to attack with
  • target_id: ID of enemy unit to attack Returns: Success/failure message Use Cases:
  • Engaging enemy forces
  • Targeting high-priority units
  • Executing coordinated attacks
  • Defending against enemy advances

5. build_building(building_type, position_x, position_y, player_id)

Purpose: Construct a building at specific location Parameters:

  • building_type: Type of building to construct
  • position_x: X coordinate for placement
  • position_y: Y coordinate for placement
  • player_id: Player ID (typically 0 for human player) Returns: Success/failure message Use Cases:
  • Expanding base infrastructure
  • Building production facilities
  • Constructing defensive positions
  • Managing power supply

6. send_game_command(command_type, **kwargs)

Purpose: Send any supported game command Parameters:

  • command_type: Type of command to send
  • **kwargs: Command-specific parameters Returns: Success/failure message Supported Commands:
  • "move_unit": Move units (same as move_units tool)
  • "attack_unit": Attack units (same as attack_unit tool)
  • "attack_building": Attack buildings
  • "build_unit": Produce units
  • "build_building": Build structures (same as build_building tool)
  • "stop_units": Stop unit movement
  • "prepare_nuke": Prepare superweapon
  • "cancel_nuke": Cancel superweapon preparation
  • "launch_nuke": Launch superweapon at target
  • "change_language": Change player language
  • "request_ai_analysis": Request AI tactical analysis

Game Systems Accessible via MCP

1. Economic System

  • Resource Management: Monitor and control credits
  • Production: Build structures and units
  • Power System: Manage power production and consumption

2. Military System

  • Unit Control: Full movement and combat control
  • Formation Management: Group unit movements
  • Combat Tactics: Target selection and engagement

3. Base Building System

  • Construction: Build all structure types
  • Placement Rules: Respects game constraints
  • Production Queues: Manage unit production

4. Strategic Systems

  • Superweapon: Nuke launch capability
  • AI Analysis: Tactical situation assessment
  • Language: Multi-language support

5. Game State Management

  • Progress Tracking: Current tick and game status
  • Victory Conditions: Monitor win/lose state
  • Fog of War: Visibility information

Limitations and Security

Current Limitations

  1. Player ID Restriction: All actions are restricted to player ID 0 (human player)
  2. No Direct Enemy Control: Cannot directly control enemy AI units
  3. Game Rules Enforcement: All actions must comply with game rules

Security Features

  1. Port Isolation: MCP server runs on separate port (8001) from game server (7860)
  2. Input Validation: All commands are validated by existing game logic
  3. Cost Checking: Resource costs are enforced for all building/unit actions

Example AI Strategies Enabled

1. Resource Management AI

An AI could:

  1. Use get_game_state() to check current credits
  2. Identify optimal harvester positions with get_game_state()
  3. Move harvesters using move_units()
  4. Build refineries with build_building()
  5. Request analysis with get_ai_analysis() to confirm strategy

2. Military Tactics AI

An AI could:

  1. Assess enemy positions with get_game_state()
  2. Move forces into position with move_units()
  3. Coordinate attacks with attack_unit()
  4. Build defensive structures with build_building()
  5. Get tactical advice with get_ai_analysis()

3. Base Expansion AI

An AI could:

  1. Monitor power status with get_game_state()
  2. Build power plants when needed with build_building()
  3. Expand to new areas with move_units()
  4. Construct new production facilities with build_building()
  5. Verify expansion success with get_game_state()

Integration with Existing Systems

The MCP interface seamlessly integrates with all existing game systems:

  • Connection Manager: Uses the same handle_command method as human players
  • AI Analysis: Connects to the same Qwen2.5 LLM system
  • Game Rules: All actions respect the same rules as human gameplay
  • Notifications: AI actions trigger the same UI notifications
  • State Sync: Game state updates are broadcast to all clients the same way

Future Enhancement Possibilities

While the current implementation is comprehensive, potential future enhancements could include:

  1. Advanced Unit Control: Formation patterns, patrol routes
  2. Economic AI: Automated resource optimization
  3. Diplomacy System: Multiplayer interaction controls
  4. Scenario Management: Custom game setup tools
  5. Replay System: Game recording and playback controls

Conclusion

The MCP interface provides complete control over all strategic and tactical aspects of the RTS Commander game. AI agents can observe the full game state, make informed decisions using AI analysis, and execute any action available to human players. The implementation maintains all existing game balance and rules while providing a standardized interface for AI integration.