Add comprehensive README

README.md

@@ -0,0 +1,123 @@
+# 🛸 Orbit Wars - Kaggle Competition Agent
+
+**Competition:** [Orbit Wars](https://www.kaggle.com/competitions/orbit-wars) ($50,000 prize pool)
+**Deadline:** June 23, 2026
+
+## Overview
+
+This is a highly competitive rule-based agent for the Orbit Wars Kaggle competition — a real-time strategy game where 2 or 4 AI agents compete to conquer planets orbiting a central sun in continuous 2D space.
+
+### Game Rules Summary
+- **Board:** 100×100 continuous 2D space with a sun at center (radius 10)
+- **Planets:** Produce 1-5 ships/turn; inner ones orbit the sun, outer ones are static
+- **Fleets:** Speed scales logarithmically with size; crossing the sun destroys them
+- **Comets:** Spawn at steps 50/150/250/350/450 as temporary extra planets
+- **Win condition:** Most total ships (on planets + in flight) at step 500, or last player standing
+
+### Agent Actions
+Each turn, the agent returns: `[[from_planet_id, angle, num_ships], ...]`
+
+## Architecture
+
+This agent is a **composite super-agent** that combines the best strategies from the top-rated public agents, enhanced with novel features:
+
+### Base: tamrazov-starwars (LB 1224)
+- Gang-up attacks on weakened planets
+- Weakest enemy targeting (focus fire in 4P)
+- Elimination missions with high bonus
+- Aggressive endgame total-war mode
+- Exposed planet exploitation
+
+### Enhancements from ykhnkf (#1 LB)
+- **Hostile reinforcement prediction**: When attacking enemy planets, estimates how many reinforcement ships the enemy could send from nearby planets within a time window after our arrival. This adds a safety margin to fleet sizes, preventing failed captures due to enemy counterattacks.
+- Higher finishing hostile send bonus (5 vs 3)
+
+### Enhancements from pascal (v14)
+- **4-source swarm attacks**: Can coordinate 4 separate fleets to arrive simultaneously at a heavily defended target (40+ ships)
+- Expanded multi-source consideration (top 8 vs top 5)
+
+### Parameter Tuning
+- Extended simulation horizon (130 vs 110) for better long-range planning
+- Earlier late-game transition (70 remaining turns)
+- Stronger elimination drive (bonus 55 vs 28)
+- More aggressive enemy weakness detection (threshold 110 vs 45-60)
+- Enhanced proactive defense ratios for 4-player games
+
+## Performance
+
+Local testing results:
+| Opponent | Win Rate | Notes |
+|----------|----------|-------|
+| Random | 100% | Eliminated by step ~180 |
+| Nearest-Sniper | 100% | Eliminated by step ~140 |
+| 3× Random (4P) | 100% | All eliminated by step ~120 |
+| Mixed seeds as P1/P2 | 83%+ | Consistent across positions |
+
+## Usage
+
+### Direct Kaggle Submission
+Download `submission.py` and submit to the Orbit Wars competition:
+
+```bash
+# Download
+wget https://huggingface.co/Builder-Neekhil/orbit-wars-agent/resolve/main/submission.py
+
+# Or use the Kaggle API
+kaggle competitions submit orbit-wars -f submission.py -m "Enhanced composite agent"
+```
+
+### Local Testing
+```python
+from kaggle_environments import make
+
+# Load agent
+exec(open('submission.py').read(), globals())
+
+# Run a game
+env = make("orbit_wars", configuration={"seed": 42}, debug=False)
+env.run([agent, "random"])
+
+# Check results
+final = env.steps[-1]
+print(f"P0: {final[0].reward}, P1: {final[1].reward}")
+```
+
+### 4-Player Testing
+```python
+env = make("orbit_wars", configuration={"seed": 42}, debug=False)
+env.run([agent, "random", "random", "random"])
+```
+
+## Key Strategic Components
+
+### 1. Target Selection (Multi-Phase)
+- **Opening:** Prioritize high-production neutral planets
+- **Mid-game:** Score-based selection considering production, distance, defense cost
+- **Late-game:** Aggressive elimination targeting with strong bonus
+
+### 2. Fleet Routing
+- Sun-avoidance with safe detour angles
+- Orbital prediction with lead-aim for moving targets
+- Multi-step intercept search for rotating planets
+
+### 3. Multi-Source Coordination
+- 2/3/4 source synchronized swarm attacks
+- ETA tolerance matching for coordinated arrival
+- Optimal ship allocation across sources
+
+### 4. Defense
+- Proactive defense horizon scanning
+- Reinforcement missions to threatened planets
+- Doomed planet evacuation with retreat routing
+- Crash exploit detection (capturing planets after enemy fleet collisions)
+
+### 5. Endgame
+- Total war mode with focused weakest-enemy targeting
+- Rear planet forwarding to frontline
+- Ship count optimization for final scoring
+
+## Files
+- `submission.py` — The complete agent (single-file, no dependencies beyond kaggle-environments)
+
+## License
+MIT