Welcome to Battle Simulator - an interactive, real-time strategy game where you command armies in epic battles! Built with modern React and featuring a mobile-first responsive design, this project showcases advanced web development techniques while providing endless entertainment.
🎮 Play Live Demo | 📱 Mobile Optimized | 🌟 Open Source
- 🎯 Real-time Combat Simulation - Watch armies battle with intelligent AI behavior
- � Mobile-First Design - Optimized for all devices from phones to desktops
- ⚙️ Customizable Army Stats - Fine-tune health, damage, speed, morale, and more
- 🎨 Modern UI/UX - Beautiful gradients, animations, and intuitive controls
- 🚀 High Performance - Hardware-accelerated animations and optimized rendering
- ♿ Accessible - Keyboard navigation, screen reader support, and proper contrast
Get the battle simulator running on your machine in under 2 minutes:
# Clone the repository
git clone https://github.com/dimitarbez/battle-simulator.git
cd battle-simulator
# Install dependencies
npm install
# Start the development server
npm startOpen http://localhost:3000 and start commanding your armies! 🎉
- Select Army 1 (Blue) or Army 2 (Red) from the sidebar
- Click and drag on the battlefield to place soldiers
- Create strategic formations and positioning
Customize your army's capabilities:
- ❤️ Health: Hit points per soldier (1-100)
- ⚔️ Damage: Attack power (1-100)
- 🏃 Speed: Movement speed (1-100)
- 🛡️ Morale: Combat effectiveness (1-100)
- ⏱️ Attack Rate: Time between attacks (100-2000ms)
- 🎯 Range: Attack distance (1-150)
- Click "Start Battle" to begin the real-time simulation
- Watch your armies engage with intelligent combat AI
- Analyze the battle with live statistics and HUD
- Eliminate all enemy soldiers
- Force enemy retreat through morale damage
- Strategic positioning and army composition matter!
This project demonstrates modern web development best practices:
- React 18 - Latest features with concurrent rendering
- Custom Hooks - Modular state management and game logic
- React Spring - Smooth, performant animations
- Tailwind CSS - Utility-first CSS framework
- Mobile-First Responsive Design - Works on all screen sizes
- CSS Grid & Flexbox - Modern layout techniques
- Hardware Acceleration - Optimized for 60fps animations
- Custom Physics Engine - Collision detection and movement
- AI Behavior System - Intelligent soldier decision-making
- Real-time Simulation Loop - Efficient game state updates
- Performance Optimizations - Minimized re-renders and memory usage
- 📱 Mobile Optimized - Touch gestures and responsive layout
- ⌨️ Keyboard Shortcuts - Power user features
- 🎯 Intuitive Controls - Drag-to-place soldiers, easy army switching
- 📊 Live Statistics - Real-time battle analytics and army status
- 💡 Interactive Help - Built-in tutorials and guidance
- 🌈 Modern Gradients - Beautiful color schemes and visual depth
- ✨ Smooth Animations - Engaging soldier movements and battle effects
- 🎭 State-Based Animations - Soldiers react to combat situations
- 🖼️ Dynamic Backgrounds - Immersive battlefield environments
- 🎪 Victory Celebrations - Satisfying win conditions
- ⚡ High Performance - Optimized for smooth 60fps gameplay
- 🔧 Modular Architecture - Clean, maintainable code structure
- 🧪 Modern React Patterns - Hooks, context, and best practices
- 📱 PWA-Ready - Installable web app capabilities
- 🛡️ Type Safety - JSDoc annotations and prop validation
Battle Simulator is an open-source project that thrives on community contributions! Whether you're a seasoned developer or just starting out, there are many ways to get involved:
Perfect for newcomers to open source:
- 🎨 Add new army presets (Archer armies, Tank formations, etc.)
- 🌍 Improve responsive design for specific devices
- 📝 Enhance documentation and add code comments
- 🐛 Report bugs or suggest UI/UX improvements
- 🎭 Create new soldier animations or visual effects
Great for developers wanting to dive deeper:
- 🎵 Add sound effects and background music
- 🏞️ Create different battlefield terrains and environments
- 📊 Implement battle statistics and replay system
- 🎮 Add keyboard shortcuts and accessibility features
- 🎯 Improve AI behavior and battle strategies
For experienced developers looking for exciting projects:
- 🌐 Multiplayer Mode - Real-time battles between players
- 🤖 Advanced AI - Machine learning for smarter armies
- 🗺️ Campaign Mode - Story-driven battles and progression
- 🏰 Formations & Tactics - Complex military strategies
- ⚔️ Unit Types - Cavalry, archers, siege weapons, heroes
-
🍴 Fork the Repository
# Click the "Fork" button on GitHub, then: git clone https://github.com/YOUR_USERNAME/battle-simulator.git cd battle-simulator
-
🌿 Create a Feature Branch
git checkout -b feature/amazing-new-feature # or git checkout -b fix/important-bug-fix -
💻 Make Your Changes
- Write clean, commented code
- Follow the existing code style
- Test your changes thoroughly
- Update documentation if needed
-
🧪 Test Everything
npm test # Run the test suite npm run build # Test production build npm start # Test in development mode
-
📝 Commit and Push
git add . git commit -m "✨ Add amazing new feature that does X" git push origin feature/amazing-new-feature
-
🚀 Create a Pull Request
- Go to your fork on GitHub
- Click "New Pull Request"
- Describe what you changed and why
- Link any relevant issues
- Code Style: We use Prettier and ESLint - run
npm run lintto check - Commit Messages: Use descriptive messages with emojis (see examples above)
- Testing: Add tests for new features when possible
- Documentation: Update README or add comments for complex features
- Responsive: Ensure changes work on mobile and desktop
- Performance: Keep the 60fps target in mind for animations
- 🌟 Recognition - Your name in our contributors list
- 📚 Learning - Gain experience with modern React patterns
- 🤝 Community - Join our friendly developer community
- 💼 Portfolio - Great project to showcase your skills
- 🚀 Impact - Your code will be used by players worldwide!
In the project directory, you can run:
Runs the game in development mode with hot reload. Open http://localhost:3000 to view it in your browser.
Builds the app for production to the build folder. Optimized and minified for best performance.
Launches the test runner in interactive watch mode. Helps ensure game logic works correctly.
Checks code style and finds potential issues. Run this before submitting pull requests!
The game is automatically deployed to production on every push to main branch. You can deploy your own version easily:
npm run build
npm run deploy # If you have gh-pages configured- Run
npm run build - Drag the
buildfolder to Netlify Drop - Your game is live! 🎉
- Connect your GitHub repo to Vercel
- Automatic deployments on every push
- Perfect for React applications
battle-simulator/
├── 📁 public/ # Static assets and HTML template
├── 📁 src/
│ ├── 📁 components/ # React components
│ │ ├── Battlefield.js # Main game area
│ │ ├── BattlefieldControls.js # Army selection & controls
│ │ ├── ArmyStatsPanel.js # Army configuration
│ │ ├── Soldier.js # Individual soldier rendering
│ │ └── ...
│ ├── 📁 hooks/ # Custom React hooks
│ │ ├── useBattlefield.js # Battlefield state management
│ │ ├── useArmyStats.js # Army statistics
│ │ └── useBattleSimulation.js # Game simulation logic
│ ├── 📁 utils/ # Utility functions
│ │ └── battleUtils.js # Game mechanics & physics
│ ├── App.js # Main application component
│ ├── index.js # React app entry point
│ └── index.css # Global styles and animations
├── package.json # Dependencies and scripts
├── tailwind.config.js # Tailwind CSS configuration
└── README.md # You are here! 📍
- Damage Calculation: Base damage ± random variance for realism
- Morale System: Soldiers retreat when morale drops below threshold
- Range Mechanics: Different weapons have different effective ranges
- Attack Cooldowns: Balanced timing prevents spam attacks
- Target Selection: Closest enemy prioritization
- Movement AI: Pathfinding around obstacles and other soldiers
- State Machine: Idle → Moving → Attacking → Retreating → Celebrating
- Group Dynamics: Soldiers influence each other's morale
- Collision Detection: Circular collision bounds for all entities
- Boundary Checking: Soldiers stay within battlefield limits
- Smooth Movement: Interpolated animations for fluid gameplay
- Performance Optimization: Spatial partitioning for large armies
- 💬 Discussions - Ask questions in GitHub Discussions
- 🐛 Bug Reports - Create detailed issues with reproduction steps
- 💡 Feature Requests - Share your ideas for new features
- 📧 Direct Contact - Reach out to maintainers for urgent matters
- ⭐ Star this repo if you enjoyed the project
- 🐦 Share on social media - Help others discover the game
- 💝 Contribute code - Any improvement is welcome
- 📝 Write about it - Blog posts and tutorials appreciated
- React - The foundation of our UI
- Tailwind CSS - Utility-first styling
- React Spring - Smooth animations
- Create React App - Build tooling
- Classic RTS games like Age of Empires and StarCraft
- Modern web-based strategy games
- The joy of watching armies clash in epic battles! ⚔️
- All our amazing contributors 🙏
- The open-source community for tools and inspiration
- Players who provide feedback and suggestions
This project is licensed under the GPLv3 License - see the LICENSE file for details.
TL;DR: Feel free to use, modify, and distribute this code. Just give credit where it's due! 😊
Made with ❤️ by developers who love strategy games