README.md

metadata

title: RTS Commander
emoji: 🎮
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit

🎮 RTS Commander - Command & Conquer Web Edition

A modern web-based Real-Time Strategy game inspired by Command & Conquer: Tiberium Dawn, featuring AI-powered tactical analysis and natural language command interface.

🌐 Play Now | 📚 Documentation | 🧪 Tests

---

✨ Key Features

🎯 Classic RTS Gameplay

• Resource Management: Harvest Tiberium to fund your war machine
• Base Building: Construct power plants, refineries, barracks, and war factories
• Unit Production: Train infantry, build tanks, and deploy helicopters
• Real-Time Combat: Command your forces against an aggressive AI opponent
• Fog of War: Explore the battlefield and reveal enemy positions
• Power System: Manage energy production and consumption (Red Alert-style)

🤖 AI-Powered Tactical Analysis

• Real-time battlefield analysis powered by Qwen2.5-Coder-1.5B LLM
• Strategic recommendations based on current game state
• Resource management tips and economic guidance
• Threat assessment and defensive positioning advice
• Multi-language support (English, French, Chinese)
• Updates every 60 seconds with fresh tactical insights

💬 Natural Language Command Interface

• Talk to your units in plain language (any language!)
• Examples:
  • "Move my tanks to the north base" → Parsed to move commands
  • "Construire une centrale électrique" → Build power plant
  • "生產三個步兵" → Train 3 infantry units
• Powered by LLM with MCP-style command translation
• Fallback examples provided in multiple languages
• Real-time translation from natural language to game commands

🌐 Multi-Language Support

• 🇬🇧 English - Full interface and AI analysis
• 🇫🇷 Français - Interface complète et analyse IA
• 🇹🇼 繁體中文 - 完整界面和AI分析
• Switch languages instantly during gameplay

🎨 Modern Web Technologies

• No installation required - Play directly in browser
• Cross-platform - Works on desktop, tablet, and mobile
• Real-time multiplayer ready - WebSocket architecture
• Responsive UI - Adapts to different screen sizes
• Canvas-based rendering - Smooth 60 FPS gameplay

---

🚀 Quick Start

Play Online

Visit https://huggingface.co/spaces/Luigi/rts-commander to play instantly!

Local Development

# Clone the repository
git clone <repository-url>
cd rts/web

# Install dependencies
pip install -r requirements.txt

# Start the server
python start.py

# Open in browser
# http://localhost:8000

---

🎮 How to Play

Basic Controls

Action	Control
Select units/buildings	Left Click
Move units	Right Click on ground
Attack enemies	Right Click on enemy unit/building
Box select multiple units	Click + Drag
Build structure	Click building button in sidebar
Place building	Click on construction grid
Cancel building	Press Escape
Pan camera	Arrow Keys or WASD
Use NL interface	Type in left sidebar input

Getting Started

1. Build a Power Plant - Required for all other structures
2. Build a Refinery - Process Tiberium for credits
3. Wait for Harvester - Automatically deployed with refinery
4. Build a Barracks - Train infantry units
5. Defend your base - Enemy attacks start quickly!
6. Expand and conquer - Build more structures and units

Using AI Analysis

The AI Analysis Panel (right side) provides:

• Battlefield Overview: Current situation assessment
• Economic Status: Credits, production, and resource flow
• Military Assessment: Unit counts and combat readiness
• Strategic Advice: What to do next
• Tactical Tips: How to improve your position

Using Natural Language Commands

The NL Command Interface (left side) lets you:

1. Type commands in natural language (any supported language)
2. View example commands for inspiration
3. See command history and results
4. Get instant feedback on command execution

Example Commands:

• "Build 5 infantry units"
• "Déplacer mes tanks vers le nord"
• "攻擊敵人的基地"

---

🏗️ Architecture

Tech Stack

Backend:

• FastAPI - Modern async web framework
• WebSockets - Real-time bidirectional communication
• llama-cpp-python - LLM inference engine
• Qwen2.5-Coder-1.5B - Shared model for NL and AI analysis

Frontend:

• Vanilla JavaScript - No heavy frameworks
• HTML5 Canvas - High-performance rendering
• CSS3 - Modern responsive UI
• WebSocket Client - Real-time state synchronization

AI/ML:

• Shared Model Manager - Single LLM instance for efficiency
• Thread-safe queue system - Sequential request processing
• Optimized for 2 vCPU - HuggingFace Free tier compatible
• Fallback mechanisms - Graceful degradation if LLM unavailable

Key Components

web/
├── app.py                  # FastAPI server & game loop
├── model_manager.py        # Shared LLM instance manager
├── nl_translator.py        # Natural language → MCP commands
├── ai_analysis.py          # Tactical analysis engine
├── localization.py         # Multi-language support
├── mcp_server.py           # MCP protocol server
├── static/
│   ├── game.js            # Game engine & rendering
│   ├── nl_interface.js    # NL command interface
│   └── styles.css         # UI styling
├── backend/
│   ├── constants.py       # Game constants
│   └── app/              # Core game logic
├── docs/                  # 📚 Documentation (28+ files)
└── tests/                 # 🧪 Test scripts

---

🤖 AI Features Deep Dive

Shared Model Architecture

To optimize memory usage and CPU resources, both the AI Analysis and NL Translator share a single LLM instance:

• Model: Qwen2.5-Coder-1.5B (Q4_0 quantized, ~1GB RAM)
• Thread-safe: Queue-based request handling
• Memory efficient: 50% reduction vs. dual instances
• CPU optimized: 1 thread (HuggingFace 2 vCPU environment)
• Fast response: 128-256 token limits, 10-15s timeouts

Natural Language Translation Pipeline

1. User Input → Natural language command in any language
2. LLM Processing → Qwen2.5 translates to MCP-style JSON
3. Validation → Command structure verified
4. Execution → Converted to game actions
5. Feedback → Success/error notification to user

Supported Command Types:

• MOVE_UNIT - Move units to position
• BUILD_UNIT - Train units from buildings
• BUILD_BUILDING - Construct new structures
• ATTACK_UNIT - Attack enemy units
• ATTACK_BUILDING - Attack enemy structures

AI Tactical Analysis

The AI analyzer provides strategic insights by:

1. State Analysis: Evaluates current game situation
2. Threat Detection: Identifies immediate dangers
3. Resource Assessment: Checks economic health
4. Strategic Planning: Suggests next moves
5. Localization: Presents analysis in user's language

Update Frequency: Every 60 seconds (configurable)

---

🔧 Performance Optimizations

Optimized for HuggingFace Free Tier (2 vCPUs, 16GB RAM):

LLM Optimizations

• Threads: 1 (instead of 4) to avoid CPU contention
• Batch size: 128 for faster response times
• Context size: 4096 tokens (balanced)
• Token limits: 128-256 (fast responses)
• Timeouts: 10-15s (prevents freezing)

Game Loop Optimizations

• Tick rate: 20 FPS (50ms per frame)
• State broadcast: Only when connections exist
• AI analysis: Every 60s (reduced from 30s)
• Debug logging: Periodic (not per-frame)

Memory Management

• Shared model: Single LLM instance (~1GB)
• Model caching: Loads once, reused forever
• Process isolation: Fallback if shared model busy
• Thread cleanup: Automatic resource management

---

📊 Project Status

Current Version: 2.1
Status: ✅ Production Ready
Deployment: Live on HuggingFace Spaces

Recent Updates (October 2025)

✅ Fixed critical bugs:

• Game loop now runs continuously (60 FPS maintained)
• Unit movement working correctly
• Production system functional
• NL translator loads properly from /tmp/rts/

✅ Performance improvements:

• LLM optimized for 2 vCPU environment
• Reduced thread count (4→1)
• Shorter timeouts (30s→15s)
• Smaller token limits (512→256)

✅ New features:

• Shared model manager (50% memory reduction)
• Auto-retry for NL translator connection
• Comprehensive debug logging
• Periodic game tick confirmation

Known Limitations

⚠️ Single-player only (multiplayer infrastructure ready but not enabled)
⚠️ GDI faction only (Nod not implemented)
⚠️ Limited unit types (infantry, tanks, helicopters, harvesters)
⚠️ Basic AI opponent (follows build queue, trains units, attacks)

---

📚 Documentation

Complete documentation is available in docs/ (28+ files):

Essential Docs

• QUICKSTART.md - Detailed getting started guide
• ARCHITECTURE.md - System design and structure
• FEATURES_RESTORED.md - All implemented features
• DEPLOYMENT.md - Deployment instructions
• MCP_INTEGRATION.md - Model Context Protocol

Recent Docs

• NL_INTEGRATION_SUCCESS.md - NL interface implementation
• NL_UI_ARCHITECTURE_FIX.md - Shared model architecture
• CODE_CHANGES_NL_FIX.md - Bug fixes summary

Full Index

See docs/README.md for complete documentation catalog.

---

🧪 Testing

Test scripts in tests/ directory:

# Run main test suite
./tests/test.sh

# Test specific features
./tests/test_features.sh

# Test NL integration
python tests/scripts/test_nl_integration.py

# Test shared model
python tests/test_shared_model.py

# Docker deployment test
./tests/docker-test.sh

See tests/README.md for detailed testing guide.

---

🐳 Docker Deployment

Quick Deploy

# Build image
docker build -t rts-commander .

# Run container
docker run -p 7860:7860 rts-commander

# Access at http://localhost:7860

HuggingFace Spaces

This project is configured for automatic deployment to HuggingFace Spaces:

1. Model auto-downloads to /tmp/rts/ on first run
2. Optimized for 2 vCPU environment
3. Automatic restart on push to main branch
4. Health checks and monitoring included

---

🛠️ Development Tools

Scripts in tools/ directory:

• local_run.sh - Quick local development server
• debug_ai.py - AI debugging utilities
• deploy_hf_spaces.sh - Deploy to HuggingFace Spaces

---

🤝 Contributing

Contributions welcome! Areas for improvement:

• New unit types (aircraft, advanced vehicles)
• Nod faction (buildings, units, technologies)
• More map variety (different terrains, objectives)
• Multiplayer mode (lobby, matchmaking)
• Campaign mode (missions, story)
• Better AI (strategic planning, tactics)

---

📜 License

MIT License - See LICENSE file for details.

---

🙏 Credits

Inspired by: Command & Conquer: Tiberium Dawn (Westwood Studios, 1995)

Powered by:

• FastAPI - Web framework
• Qwen2.5-Coder - LLM model
• llama-cpp-python - LLM inference
• HuggingFace Spaces - Hosting platform

Special Thanks: To all contributors and players who provided feedback!

---

📞 Support

• Bug Reports: Open an issue on the repository
• Feature Requests: Start a discussion
• Questions: Check the docs/ first, then ask!

---

🎮 Ready to command your forces? Play Now!

"In the grim darkness of the Tiberium future, there is only war... and natural language commands." 🚀