Metadata-Version: 2.1
Name: tank-wars-iit
Version: 1.0.0
Summary: Tank Wars framework for Scarlet HackNiite
Author-email: Association for Computing Machinery at the Illinois Institute of Technology <acm@iit.edu>, Tommy Vadakumchery <t.vadakumchery1@gmail.com>
Project-URL: Homepage, https://github.com/acm-iit/robot-wars
Project-URL: Bug Tracker, https://github.com/acm-iit/robot-wars/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE

# Robot Wars

Engine for the Robot Wars hack night.

## Requirements

* Python 3.10
* pygame 2.3.0 (SDL 2.24.2, Python 3.10.2)

## How do I run it?

Run `init.py` in Python. (This is a testing script and will be changed/moved in the future.)

## Structure

* `engine` - Package containing full Robot Wars engine.
    * `entity` - Package containing all `Entity` classes supported by the engine.
        * `bullet.py` - Contains the `Bullet` class (inherits `Entity`); represents a bullet that moves in the direction it faces, bounces off walls, and collides with `Robot`s.
        * `entity.py` - Contains the `Entity` abstract class, which represents a geometric object in an `Arena`.
        * `robot.py` - Contains the `Robot` class (inherits `Entity`); represents a robot that can move, turn, turn its turret, and shoot `Bullet`s.
        * `wall.py` - Contains the `Wall` class (inherits `Entity`); represents a static, unmovable barrier.
    * `maps` - Directory containing map JSON files which can be used to easily instantiate an `Arena` with `Wall`s and spawn locations.
        * `basic.json` - A small, wide map with five `Wall`s and two spawns.
        * `circles.json` - A medium, square map with two concentric circles of `Wall`s and four spawns.
        * `stress_test.json` - A large, square map with no `Wall`s and 64 spawns, meant for stress testing the engine.
    * `util` - Package containing engine utility modules.
        * `draw.py` - Contains helper functions for drawing gradients on screen.
        * `geometry.py` - Contains helper functions for collision detection between two convex polygons.
    * `arena.py` - Contains the `Arena` class, which represents a battle arena for one or more `Robot`s.
    * `map.py` - Contains type definitions and guards for the map JSON format.
    * `quadtree.py` - Contains the `Quadtree` class, which is a data structure used to optimize collision filtering.
* `tools` - Useful scripts to automate workflows.
    * `generate_circles.py` - Generates the `engine/maps/circles.json` map.
    * `generate_stress_test.py` - Generates the `engine/maps/stress_test.json` map.
* `init.py` - Loads an `Arena` from a map, spawns a user-controlled `Robot` and several NPC `Robot`s, and runs the simulation with visuals. Used for testing.

## To Do

* Map Creation
    * **[IMPLEMENTED]** *1v1 Map* - For now, we can use `engine/maps/circles.json`.
    * *Battle Royale Map* - Extra-large map with adequate `Wall`s spread across the map.
    * *Zoom-In* - Useful for observing the battle royale map!
* Optimization
    * **[IMPLEMENTED]** *Quadtree Collision Filtering* - Use a `Quadtree` data structure to filter which collisions to check for as opposed to checking every pair of `Entity`s.
    * *Parallelize `Entity.update`* - Invoke all calls of `Entity.update` in parallel since they operate mostly independently (exception is modification of shared `Arena` state, like spawning `Bullet`s via `Robot.shoot`).
    * *Parallelize `Entity.handle_collision`* - Invoke all calls of `Entity.handle_collision` in parallel; modify the method to return new `position` and `rotation` properties that will be applied in parallel.
* Game Rules
    * **[IMPLEMENTED]** *`Robot` Destruction* - Incorporate health in `Robot` and damage in `Bullet`.
    * *Win Condition* - Destroy the other `Robot`.
    * *Stalemate Condition* - Both `Robot`s are still alive after *n* seconds of simulation.
    * **[IMPLEMENTED]** *Coins* - Place `Coin` entities around the `Arena`; whichever `Robot` collects the most wins in case of stalemate.
* `Robot` Programmability
    * **[IMPLEMENTED]** *`Robot` Manipulation* - Expose API to move and turn the `Robot` and shoot `Bullet`s.
    * **[IMPLEMENTED]** *Enemy `Robot` Detection* - Expose API to find the nearest `Robot` to a given `Robot`.
    * **[IMPLEMENTED]** *Pathfinding* - Expose API for `Robot`s to navigate their way to a location around `Wall`s.
    * *`RobotControl` Class* - Incorporate all programmable/personalizable `Robot` features into one class which each team extends with their implementation. For now, it's semi-implemented as the `Robot.on_update` callback, which is unideal because it doesn't secure the engine from unwanted modifications.
    * *Engine Encapsulation* - Prevent raw access to any `Entity`s or the `Arena`; the only accessible component is the `RobotControl` class.
* `Robot` Personalization
    * **[IMPLEMENTED]** *Color* - Set `Robot` colors via properties `color` and `head_color`.
    * *Size* - Set `Robot` size; larger size increases health and decreases speed.
* `Robot` Examples
* Unit Tests
* Prepare for Distribution
