Spaces:
Sleeping
Sleeping
| 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."* 🚀 | |