🧟‍♂️ ZombieEscape

An open-world, location-based zombie survival game for Android.

Note (active development): The game is playable but still actively under development. The combat system is not yet complete, and NPC collision avoidance is not fully implemented — a fallback is used for now.

Getting Started • Getting Started File • Project Structure • All Documentation • Changelog • License File • Third-Party Licenses • Contributing • Code of Conduct

---

ZombieEscape turns your real neighborhood into a post-apocalyptic world. Explore real streets and buildings, scavenge for supplies, fight zombies, and survive at all costs.

---

✨ Features

• Real-World Map: Uses OpenStreetMap to generate a game world based on your location. Buildings, roads, and landmarks become part of your adventure.
• GPS & Joystick Controls: Play outside via GPS or comfortably with the on-screen joystick.
• Dynamic Zombie Spawning: Zombies appear dynamically, with higher density in cities. Special zombie types at special locations!
• Modular NPC System: The world is populated with AI-driven NPCs from different factions (HOSTILE, NEUTRAL, FRIENDLY, TRADER). NPCs have a full life simulation cycle: they find a house, loot nearby buildings, store items at home, and defend themselves against zombies and other threats.
• Advanced Combat System: A robust combat system built around a unified ICombatEntity and IInjuryTracker interface allows for complex, type-agnostic interactions between different entity types (Player vs. AI, AI vs. AI). It features a detailed Raider system with multiple types (Scavenger, Bandit, Mercenary, Warlord), each with unique AI behaviors (Patrol, Chase, Attack, Flee, Search), and integrates comprehensive body-part specific injury tracking.
• Advanced Medical System: A detailed body part injury system with 11 distinct body parts. Combat encounters can result in various injury types (cuts, fractures, bleeding, infections), which require specific treatments (bandages, splints, disinfectants). NPCs can also heal themselves using medical items from their inventory.
• Effect System: A flexible system for applying various timed status effects to entities, including buffs (pain relief, regeneration, damage boost) and debuffs (bleeding, poison, infection, starvation).
• Loot & Scavenging: Loot real buildings with individual loot tables and cooldowns.
• Inventory System: Weight-based inventory, stackable items, many weapons, armor, and crafting materials.
• Crafting System: Allows players to craft new items from collected materials based on defined recipes, including automatic rollback for failed crafts and weight checks.
• Weapon Customization: Find and attach parts like suppressors or scopes.
• Optimized Pathfinding: The game uses a Spatial Hash Grid for highly efficient collision detection, resulting in a 10x performance improvement for NPC and zombie movement. Additionally, an Adaptive Pathfinding system uses a Python simulation to learn and transfer optimal pathfinding parameters to the game automatically.
• Persistent World: Game state, inventory, and looted buildings are saved automatically.
• Extensible Architecture: The core systems (Combat, Injury, NPC) are designed to be modular and easily extensible with new entity types, items, and features.

---

🏗️ Project Architecture (detailed project structure)

The game is modular and built in Kotlin. Key components:

• MainActivity.kt: Entry point, initializes map, UI, and systems, runs the main game loop.
• GameManager.kt: Core game logic, manages game loop, entities, and subsystems.
• /game package:
  • PlayerMovementManager: GPS & joystick controls
  • ZombieSpawnManager: Zombie spawning by location
  • ActionManager & LootManager: Interactions & loot
  • CombatSystem: Combat logic
  • InventoryManager & EquipmentSystem: Inventory & equipment
  • MedicalSystemManager: Health, hunger, effects
• /database package:
  • GameDatabase.kt: Room database
  • GameStateManager.kt: Save/load facade
• /model package:
  • Data classes like Zombie, Item, Building

---

🚀 Getting Started

Standard Android Studio project. To get started:

1. Clone the repository:

git clone https://github.com/arn-c0de/ZombieEscape

2. Open the project in Android Studio
3. Wait for Gradle sync
4. Run the app on a device or emulator

⚠️ The game requires location permissions for GPS mode.

---

📄 License

Personal & Non-Commercial Use License

You may use, fork, and modify this project for personal, non-commercial purposes only. Commercial use, redistribution, sublicensing, or selling of the code or derivative works is strictly prohibited. Distribution is only allowed for personal use and open-source collaboration (e.g., on GitHub), not for profit. The original author (arn-c0de) retains exclusive rights to commercialize and distribute the software for profit or in compiled/binary form.

See LICENSE for full terms.

---

---

Repository: https://github.com/arn-c0de/ZombieEscape
Contact: arn-c0de@protonmail.com

This README was generated based on the project's source code.