--- 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 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."* ๐Ÿš€