README.md

---
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](https://huggingface.co/spaces/Luigi/rts-commander)** | **📚 [Documentation](docs/)** | **🧪 [Tests](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](https://huggingface.co/spaces/Luigi/rts-commander)** to play instantly!

### Local Development

```bash
# 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/](docs/)** (28+ files):

### Essential Docs
- **[QUICKSTART.md](docs/QUICKSTART.md)** - Detailed getting started guide
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System design and structure
- **[FEATURES_RESTORED.md](docs/FEATURES_RESTORED.md)** - All implemented features
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment instructions
- **[MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md)** - Model Context Protocol

### Recent Docs
- **[NL_INTEGRATION_SUCCESS.md](docs/NL_INTEGRATION_SUCCESS.md)** - NL interface implementation
- **[NL_UI_ARCHITECTURE_FIX.md](docs/NL_UI_ARCHITECTURE_FIX.md)** - Shared model architecture
- **[CODE_CHANGES_NL_FIX.md](docs/CODE_CHANGES_NL_FIX.md)** - Bug fixes summary

### Full Index
See **[docs/README.md](docs/README.md)** for complete documentation catalog.

---

## 🧪 Testing

Test scripts in **[tests/](tests/)** directory:

```bash
# 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](tests/README.md)** for detailed testing guide.

---

## 🐳 Docker Deployment

### Quick Deploy

```bash
# 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/](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](LICENSE) file for details.

---

## 🙏 Credits

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

**Powered by**:
- [FastAPI](https://fastapi.tiangolo.com/) - Web framework
- [Qwen2.5-Coder](https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct) - LLM model
- [llama-cpp-python](https://github.com/abetlen/llama-cpp-python) - LLM inference
- [HuggingFace Spaces](https://huggingface.co/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/](docs/) first, then ask!

---

**🎮 Ready to command your forces? [Play Now!](https://huggingface.co/spaces/Luigi/rts-commander)**

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