Spaces:

CharlieBonito
/

xcomwingman

Running

XCOM 2 is a critically acclaimed turn-based tactical strategy game. However, its high difficulty threshold and permanent character death ("permadeath") mechanics make it notoriously unforgiving. To make optimal decisions, players must know hidden game details, such as:

Hidden Aim Assist: The game secretly boosts or penalizes hit probabilities depending on the difficulty setting and previous misses.
Progressive Calendar Timelines: The monthly appearance rate of new alien enemies (e.g., Mutons, Sectopods) dictates when players must upgrade weapons or armors.
Massive Configuration Files: Core game balancing data is buried inside massive configuration files (like DefaultGameData.ini which spans over 14,000 lines).
Community Wisdom: Optimal base-building layouts, tech research queues, and soldier class builds are scattered across long-form wikis and Steam community guides.

Traditionally, players are forced to alt-tab out of the game, search web forums, or crawl raw files, which breaks military immersion and disrupts gameplay flow.

The Solution: XCOM 2 Tactical Wingman

The XCOM 2 Tactical Wingman is a localized, context-aware AI agent acting as Central Officer Bradford (the commander's right-hand advisor). The agent acts as an in-game console where players input their current campaign state (month, difficulty, resources, active research) and chat directly with their advisor.

Bradford uses Model Context Protocol (MCP) to search actual game configuration files, query official difficulty tables, and retrieve paragraphs from strategy guides in real-time. This translates raw database files into actionable military intelligence.

🏗️ 2. System Architecture & The Build

The application is built using a decoupled client-server architecture designed to run efficiently on local machines or cloud hosting providers.

graph TD
    User([Commander / User]) <--> |Streamlit Console UI| App[app.py]
    App <--> |Campaign State + User Query| Gemini[Gemini 2.5 Flash]
    Gemini <--> |Function Calling / Tools| MCPServer[mcp_server.py]
    MCPServer --> |Path Traversal Security Check| SandboxCheck{verify_sandbox_path}
    SandboxCheck --> |Authorized Read| LocalFiles[(Local Data folder)]
    LocalFiles -.-> |1. Clean Guides| XcomClear[data/XcomClear/*.txt]
    LocalFiles -.-> |2. Raw Configs| GameData[data/DefaultGameData_COMBINADO.txt]
    LocalFiles -.-> |3. Wiki Compendium| Compendium[difficulty_compendium.json]

Technology Stack

UI Interface: Streamlit designed with a retro-futuristic dark mode theme, mimicking the XCOM command center's holographic displays.
AI Core: Google Gemini 2.5 Flash accessed via the official google-genai SDK.
Tool Orchestration: A python FastMCP server in mcp_server.py defining lookups.
Local Data Stores: Raw game configurations, JSON databases of aim assist bonuses, and raw strategy guide texts compiled in a local data/ directory.

🏆 3. Hackathon Key Concepts Applied

This project demonstrates the application of five key course concepts:

Course Concept	Implementation & File References
1. Agent System (ADK)	Context-aware chat session using `google-genai` in app.py.
2. MCP Server	FastMCP server declaring read-only search tools in mcp_server.py.
3. Antigravity	Development, testing, encoding fixes, and security sandboxing assisted by Antigravity CLI.
4. Security Features	Path traversal verification in mcp_server.py.
5. Deployability	Standard UTF-8 files, in-process fallback import, and pinned environment setup in requirements.txt.

Concept 1: Agent System (ADK & Gemini API)

The agent runs in a chat session using google-genai. To make the agent context-aware, Streamlit collects the sidebar configuration parameters and formats them into a campaign state header block. This header is prepended to the user's prompt on every turn.

state_str = (
    f"[XCOM CAMPAIGN STATE STATUS:\n"
    f"- Active Difficulty: {local_context['Dificultad']}\n"
    f"- Current Month: {local_context['Mes']}\n"
    f"- Resources: Supplies={local_context['Suministros']}, Intel={local_context['Intel']}, "
    f"Engineers={local_context['Ingenieros']}, Scientists={local_context['Cientificos']}\n"
    f"- Current Research: {local_context['Investigacion_Actual']}]\n\n"
    f"Commander's query: {user_query}"
)

The model is configured with a strict system persona (Central Officer Bradford), instructing it to output tactical briefings with estimated success percentages and to summarize the campaign state in a markdown table at the start of each response.

Concept 2: Model Context Protocol (MCP) Server

Instead of overwhelming the LLM's context window with large text files, mcp_server.py implements three read-only tools:

search_strategy_guide(query): Scans guide paragraph blocks using tokenized frequency matching to retrieve the top 5 relevant advice fragments.
search_game_config(query, difficulty): Filters matching lines in the 14,000+ line config file, restricting results to the active section (e.g. [XComGame.XComGameState_CampaignStart]).
get_difficulty_mechanics(difficulty_name): Reads difficulty_compendium.json to retrieve hidden mechanics like Aim Assist values.

Concept 3: Antigravity Co-Pilot

The project was built in close collaboration with the Antigravity pair programmer. Antigravity was used to write and refactor key functions, run integration scripts (e.g., test_tools.py), diagnose encoding errors (such as converting requirements.txt from UTF-16LE to standard UTF-8), and audit the security architecture.

Concept 4: Security Features (Sandbox Path Verification)

To prevent prompt injection attacks (where a user might instruct the agent to read system files like /etc/passwd or C:/Windows/win.ini through the tool arguments), the MCP server enforces strict path verification. The verify_sandbox_path function checks that any resolved file path starts with the project's root folder:

def verify_sandbox_path(path: str, base_directory: str = PROJECT_DIR) -> bool:
    real_base = os.path.realpath(base_directory)
    real_target = os.path.realpath(path)
    return real_target.startswith(real_base)

If a tool attempts to read a file outside of the sandbox directory, the request is immediately rejected.

Concept 5: Deployability (Hugging Face Spaces)

The repository is structured for production environments. To allow standard deployment:

In-process fallback: The Streamlit dashboard imports the MCP tools directly from mcp_server.py as standard python functions. This removes the need to orchestrate separate background processes on basic cloud servers.
Deterministic environment: All packages (like streamlit==1.58.0, google-genai==2.10.0, and mcp==1.28.0) are pinned in requirements.txt to guarantee matching build environments.

⚙️ 5. Advanced UX Improvements

Context Overriding System (Chat > Menus Hierarchy Rule): If a user types "I currently have 150 supplies and 0 alloys" in the chat, the backend regex parser interceptor override_context_from_query automatically overrides the sidebar values. This resolves menu-to-chat value contradictions, prioritizing the user's immediate chat description.
Dynamic Greeting & Tactical Actions: Commanders can use 🧹 Clear Chat to reset histories or 💾 Save Report to download a fully formatted Markdown dossier (xcom2_tactical_report.md) detailing campaign stats and Bradford's tactical recommendations.
Infinite Search Prevention (Config Contents Tip): System instructions warn the LLM that specific research point costs are not stored in DefaultGameData.ini (they belong to DefaultGameCore.ini), eliminating infinite tool query loops when information is missing.

🔗 5. Project Assets

Public Code Repository: GitHub - MrWhilhelmSan/Xcom2Wingman
Working Interactive Demo: Hugging Face Space - XCOM 2 Tactical Wingman
Video Submission (YouTube): [Insert YouTube Link Here] (5 minutes or less, covering problem, agent architecture, demo, and deployment).