Merge pull request #166 from AresSC2/docs/add-more-docs

docs: add more docs

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
           ref: ${{ github.head_ref }}
       # install poetry
       - name: Install poetry
-        run: pipx install poetry==1.6.1
+        run: pipx install poetry
       # set-up python with cache
       - name: Setup Python 3.11
         uses: actions/setup-python@v5

README.md

@@ -35,7 +35,7 @@ self.register_behavior(
     )
 )
 ```
-![formation](https://github.com/raspersc2/oops/assets/63355562/946686eb-cc75-4271-ae1e-3b9f5c424e47)
+![protoss](https://github.com/user-attachments/assets/31a2cbf1-a95b-492c-89eb-563013cc6b75)
 
  - Various grids with populated enemy influence.
 

docs/api_reference/index.md

@@ -2,13 +2,12 @@
 title: API Reference
 ---
 
+Explore the menu to access the available features, organized into two main sections:
 
-Utilize the menu to delve into the available functionalities, currently organized into three primary sections:
-
- - `Behaviors` - Discover the art of crafting personalized combat maneuvers or macro plans. 
-Each Behavior can be executed individually, tailored to your specific requirements.
- - `Manager mediator` - Seamlessly orchestrating numerous managers in the background, the mediator serves 
-as the recommended approach to access data and functions within these managers.
+ - Behaviors: Learn how to create custom combat strategies or macro plans. Each behavior can be run 
+independently, allowing you to adapt them to your specific needs.
+ - Manager Mediator: This tool coordinates multiple managers in the background and is the preferred 
+method for accessing the data and functions within these managers.
 
 Convenient methods globally available:
 ::: ares.main

docs/index.md

@@ -4,6 +4,10 @@
 Please feel free to contribute or raise an issue for anything that is missing or broke.
 
 ## Get Started Quickly with `ares-sc2`
+
+We recommend all users to take a read of the [gotcha's tutorial](./tutorials/gotchas.md) once
+they begin developing their `ares` bot.
+
 ### New bot author
 For authors eager to establish a local bot development environment right away, we 
 recommend using the [ares-sc2-bot-template](https://github.com/AresSC2/ares-sc2-bot-template) and
@@ -19,10 +23,13 @@ usual within the blank starter bot, making it a good option for learning the bas
 Migrating your existing bot made with [python-sc2](https://github.com/BurnySc2/python-sc2) to `ares-sc2`,
 is a fairly straight forward process in most instances. Check out the [migration tutorial](tutorials/migrating.md).
 
+
+
 In any case glancing through the [tutorials](tutorials/index.md) and
 the [api docs](api_reference/index.md) should give you an idea of what `ares-sc2` can offer.
 
 
+
 ## About
 `Ares-sc2` is a library that extends the capabilities of the
 [python-sc2](https://github.com/BurnySc2/python-sc2) framework. The fundamental principle driving the evolution of 
@@ -39,8 +46,6 @@ Feel free to add your own bot here
  - [Aristaeus (P)](https://github.com/august-k/Aristaeus)
  - [Nani-Z (Z) micro ladder bot](https://github.com/DrekkSama/Nani-Z)
  - [oops (R) micro ladder bot](https://github.com/raspersc2/oops)
-
-[//]: # ( - [Phobos (T)](https://github.com/AresSC2/phobos))
  - [QueenBot (Z)](https://github.com/AresSC2/QueenBot)
  - [12PoolBot (Z)](https://github.com/vschmidt91/12PoolBot)
 

docs/tutorials/chat_debug.md

@@ -0,0 +1,65 @@
+`ares` features an in game chat debug system, this is especially handy for quickly testing different scenarios.
+
+## Activating chat debug
+In your `config.yml` set the following options to `True`:<br/>
+
+ * `Debug: True`
+ * `ChatDebug: True` (found under `DebugOptions`)
+
+## Using chat debug
+The chat debug feature should be used in the SC2 game window only.
+The chat debug service in `ares` will parse chat messages
+and check for valid debug commands.
+
+### Spawning units
+Spawn new units directly where the in game camera is.
+To trigger the first word should be `make` or `create`, the second word is the amount of units/structures 
+to create,
+the third is a valid `UnitTypeId` type, and the fourth should be the player for which units should be spawned 
+(there is a default value of `1` for this, so omit if spawning for player 1).
+
+Here are some valid commands you can try:
+
+`make 4 marine` - Spawns 4 marines for player 1 at camera location.<br/>
+
+`make 3 mothership 1` - Spawns 3 motherships for player 1 at camera location. <br/>
+
+`make 1 hive 2` - Spawn a hive for the enemy at camera location. Note
+the 2 in the chat command, this spawns units for the enemy. <br/>
+
+`create 4 banshee 2` - Spawn four banshees for the enemy at camera location. <br/>
+
+`create 2 ultralisk 1` - Spawn two ultralisks for player one at camera location. Specifying player one in
+this command even though it's not required.
+
+![mothership](https://github.com/user-attachments/assets/4b9bb602-d05d-419a-86b3-53215c4de555)
+
+### Destroying units
+Destroy units using the same syntax for creating units, but for the first word use
+`kill` or `destroy`. The destroy commands do not take into account camera location
+and will kill units off camera if needed.
+
+Here are some valid commands you can try:
+
+`kill 4 marine` - Destroys 4 marines for player 1.<br/>
+
+`kill 125 mothership 2` - Destroys 125 motherships. Note
+the 2 in the chat command, this kills units for the enemy. <br/>
+
+`kill 1 hive` - Destroys a hive for player one. <br/>
+
+`destroy 4 banshee` - Destroys three banshees for player one. <br/>
+
+`destroy 2 ultralisk 1` - Destroys two ultralisks for player one. Specifying player one in
+this command even though it's not required.
+
+### Additional options
+You can toggle cheats with the following chat commands:
+
+* `cooldown` - Disables cooldowns of unit abilities for the bot
+* `food` - Disable food usage (not sure this one works)
+* `god` - Units and structures no longer take damage
+* `resources` - Get 5000 minerals and 5000 vespene
+* `show` - Reveal map
+* `tech` - Remove all tech requirements
+* `upgrades` - Research all currently available upgrades

docs/tutorials/gotchas.md

@@ -0,0 +1,206 @@
+## Selecting a worker
+If you're using the [Mining behavior](../api_reference/behaviors/macro_behaviors.md#ares.behaviors.macro.mining.Mining) 
+and need to select workers
+to perform tasks, then you should request `ares` to release workers from mining.
+
+#### Problem
+
+Behind the scenes, Ares designates workers to `UnitRole.GATHERING` and automatically assigns 
+specific resources to each worker. If you try to steal these workers without informing `ares`
+the `Mining` task will send the worker back to mining again.
+
+#### Solution
+Opting to 
+[select a worker through the mediator](../api_reference/manager_mediator.md#ares.managers.manager_mediator.ManagerMediator.select_worker)
+is recommended. 
+This not only simplifies internal bookkeeping by removing the worker from mining and assigned resource
+but also prioritizes a worker 
+that isn't currently involved in mining or holding resources. The selection process even extends to workers at 
+distant mineral patches whenever possible. 
+Additionally, it's worth considering assigning a fresh role to the worker to preempt potential 
+reassignment by the Mining task. Here's an example:<br/>
+```python
+from ares.consts import UnitRole
+
+if worker := self.mediator.select_worker(
+        target_position=self.start_location
+    ):
+    self.mediator.assign_role(tag=worker.tag, role=UnitRole.DEFENDING)
+```
+And to retrieve workers with a `DEFENDING` role: <br/>
+```python
+from sc2.ids.unit_typeid import UnitTypeId
+from sc2.units import Units
+
+defending_workers: Units = self.mediator.get_units_from_role(
+    role=UnitRole.DEFENDING, unit_type=UnitTypeId.SCV
+)
+```
+
+## Mixing `python-sc2` and `ares-sc2`
+
+If starting with a blank ares bot, all `python-sc2` logic will work as intended.
+However, you may start working with `ares` behaviors or methods that may interfere with common `python-sc2`
+convenience methods or functions.
+
+### Mining behavior
+If you're using the `ares` [Mining behavior](../api_reference/behaviors/macro_behaviors.md#ares.behaviors.macro.mining.Mining),
+then this breaks the functionality of the following `python-sc2` convenience methods.
+
+* [`self.build()`](https://github.com/BurnySc2/python-sc2/blob/develop/sc2/bot_ai.py#L894) <br/>
+<b>Problem</b> <br/>
+Since the `Mining` behavior takes control of all spare workers by default it does not relinquish
+control of the worker this method is trying to select. <br/><br/>
+<b>Solution</b> <br/>
+There are two solutions:<br/>
+    * Avoid `python-sc2` methods and use `ares-sc2` build structure functionalities. See: <br/>
+    [`BuildStructure`](../api_reference/behaviors/macro_behaviors.md#ares.behaviors.macro.build_structure.BuildStructure) behavior and <br/>
+    [`self.mediator.build_with_specific_worker`](../api_reference/manager_mediator.md#ares.managers.manager_mediator.ManagerMediator.build_with_specific_worker) <br/>
+    Additionally the build runner uses `ares` build functionality if you're using that.
+    * If you want to stay with `python-sc2` for now, the `self.build()` accepts a `build_worker` argument, we can ask `ares` to select a worker and then pass that into the method:
+```python
+# building_pos is the area you want to build in
+building_pos: Point2 = self.start_location
+
+if worker := self.mediator.select_worker(target_position=building_pos):
+    # ares has given us a worker, assign it a role so ares doesn't
+    # steal it for mining
+    self.mediator.assign_role(tag=worker.tag, role=UnitRole.BUILDING)
+    # now we are free to use this worker with `self.build())
+    await self.build(
+        building=UnitTypeId.BARRACKS, 
+        near=building_pos, 
+        build_worker=worker
+    )
+
+```
+
+* [`self.expand_now()`](https://github.com/BurnySc2/python-sc2/blob/develop/sc2/bot_ai.py#L216) <br/>
+<b>Problem</b> <br/>
+Same scenario as `self.build()` but we do not have the same option to pass the worker
+into the `expand_now()` as we did with `self.build()`.<br/><br/>
+<b>Solution</b> <br/>
+However, we can combine `python-sc2` and
+`ares-sc2` alternative convenience methods for a similar effect. Example: <br/>
+```python
+# Use `python-sc2` get_next_expansion to get a new base location
+if next_expand_loc := await self.get_next_expansion():
+    # ask ares for a worker
+    if worker := self.mediator.select_worker(
+            target_position=next_expand_loc,
+            force_close=True,
+    ):
+        # use ares build_with_specific_worker worker to build base
+        # this will assign worker a new role
+        # additionally by using this method, you get some extra functionality!
+        # Such as replacing dead building workers and pathing control or worker
+        self.mediator.build_with_specific_worker(
+            worker=worker,
+            structure_type=UnitTypeId.NEXUS,
+            pos=next_expand_loc,
+        )
+```
+Note, you could use this solution for other buildings too, if you already calculated
+exactly where you will place the structure.
+
+* [`self.distribute_workers()`](https://github.com/BurnySc2/python-sc2/blob/develop/sc2/bot_ai.py#L268) - This
+one is obviously broken if you're using `Mining` behavior but added for completion’s sake!
+
+* [`self.select_build_worker()`](https://github.com/BurnySc2/python-sc2/blob/develop/sc2/bot_ai.py#L580) <br/>
+<b>Problem</b> <br/>
+Similar to previous problems, `python-sc2` will not be able to select a 
+worker without `ares-sc2` trying to steal it back. <br/><br/>
+<b> Solution</b><br/>
+Ask `ares` for a worker <br/>
+```python
+from ares.consts import UnitRole
+
+if worker := self.mediator.select_worker(
+        target_position=self.start_location
+    ):
+    self.mediator.assign_role(tag=worker.tag, role=UnitRole.BUILDING)
+```
+
+
+### Building structures
+This section covers breaking `python-sc2` functionality if you interact with `ares` custom build
+tracker in any way. You're maybe using the building tracker if you use the following `ares` features:
+
+* `BuildStructure` macro behavior
+
+* `self.mediator.request_building_placement()`
+
+* Using the `ares` `BuildRunner` system in your bot
+
+#### [`self.already_pending()`](https://github.com/BurnySc2/python-sc2/blob/develop/sc2/bot_ai.py#L838) breaks for pending structures
+
+##### Problem
+Due to the custom tracking of workers that are currently on route to construct structures, the
+`already_pending()` method in `python-sc2` has no knowledge of these pending structures.
+
+##### Solution
+`ares` has an alternative function for pending structures:
+```python
+# checks workers on route and in progress structures
+num_pending_barracks: int = self.structure_pending(UnitTypeId.BARRACKS)
+```
+You could also check how many workers are on route to build a structure if desired.
+For Terran this will return same value as `structure_pending` as worker is always present.
+For Protoss or Zerg this will only count workers on route.
+```python
+# checks workers on route, doesn't include gateways in construction
+num_on_route_to_build_gateways: int = self.mediator.get_building_counter[UnitTypeId.GATEWAY]
+```
+
+
+#### Mixing `ares-sc2` and `python-sc2` build methods
+There are no known breakages here, but a word of warning that mixing building structures via
+`ares` building methods and `python-sc2` find placement queries could have
+unintended consequences.
+If possible try to stick with one system or the other, or limit mixing.
+`ares` in the background will check if position is available before building so mixing may
+be fine in most cases.
+
+Example `ares-sc2` functions and methods that may interfere with `python-sc2` convenience methods:<br/>
+
+  * `BuildStructure` behavior <br/>
+  * `self.mediator.request_building_placement()`<br/>
+  * Using `ares` `BuildRunner` system in your bot<br/>
+
+These could interfere with following `python-sc2` methods:<br/>
+
+  * `self.build()`<br/>
+  * `self.find_placement()`<br/>
+  * Your own calculated placements
+
+## Selecting a unit already assigned to a `UnitSquad`
+If you are using `ares-sc2` [unit squad system](../api_reference/manager_mediator.md#ares.managers.manager_mediator.ManagerMediator.get_squads),
+and you want to select a unit already assigned to a squad then you should take care to remove the unit to ensure
+accurate squad calculations. You can do so by making the following mediator request:
+
+```python
+from sc2.unit import Unit
+
+# pretend this unit is already assigned to a unit squad
+unit: Unit = self.units[0]
+self.mediator.remove_tag_from_squads(tag=unit.tag)
+
+```
+
+Note if you're using the `ares` role system, when assigning a unit a new role,
+units are removed from squads automatically. So this should work too:
+```python
+from ares.consts import UnitRole
+from sc2.unit import Unit
+
+# pretend this unit is already assigned to a unit squad
+unit: Unit = self.units[0]
+# switches unit to new role, and removes from any squad
+self.mediator.assign_role(tag=unit.tag, role=UnitRole.DEFENDING)
+
+```
+
+## Other gotchas?
+Found something not listed here? Please feel free to contribute to the docs or raise an issue
+in the `ares-sc2` github repo.
+