Merge pull request #40 from Bgeninatti/dev

.github/workflows/ci.yml

@@ -3,9 +3,11 @@ on:
   push:
     branches:
       - main
+      - dev
   pull_request:
     branches:
       - main
+      - dev
 
 jobs:
   build:

MANIFEST.in

@@ -0,0 +1 @@
+recursive-include pythonium *.ttf

README.md

@@ -1,80 +1,32 @@
-# pythonium
+# Pythonium
 
-Pythonium is a space turn-based strategy game where each player leads an alien race
-that aims to conquer the galaxy.
+Pythonium is a space turn-based strategy game where each player leads an alien race that aims to conquer the galaxy.
 
 You must explore planets to search and extract a valuable mineral: the `pythonium`.
-This precious material allows you to build cargo and combat spaceships, mines to get
-more pythonium for your planets.
+This precious material allows you to build cargo and combat spaceships, or mines to get
+more pythonium.
 
-Manage the economy on your planets, and collect taxes to your people to found your
-constructions, but be careful! Keep your clans happy if you want to avoid unrest
-in your planets.
+Manage the economy on your planets, and collect taxes on your people to finance your
+constructions, but be careful! Keep your clans happy if you want to avoid unrest in your planets.
 
 Put your space helmet on, set your virtualenv, and start coding.
-Battle for pythonium is waiting for you.
 
+Battle for pythonium is waiting for you!
 
-## Installation
+## About the game
 
-You can install Pythonium cloning the repository and running
+Pythonium is a [programming game](https://en.wikipedia.org/wiki/Programming_game), which means you need to code a player to play.
 
-```
-$ python setup.py install
-```
+You can choose by playing alone in single-player mode, in multi-player mode against some of the available bots, or your friend's bots.
 
-To test your installation run
+The game generates several outputs that will help you to evaluate the performance of your player and make improvements on those.
 
-```
-$ pythonium --version
-Running 'pythonium' version x.y.z
-```
+If you want to know more and learn how to play, check out the [official documentation](https://pythonium.readthedocs.io/en/latest/).
 
-## Getting started
+## Acknowledge
 
-Pythonium allows for different game modes. The default is the **classic mode**, where each player starts with 1 planet and 2 carriers in a random galaxy of 300 planets.
-The first player that conquers 210 planets (70% of the total) wins.
+This game is strongly inspired by [VGA Planets](https://en.wikipedia.org/wiki/VGA_Planets), a space strategy war game from 1992 created by Tim Wisseman.
 
-## Single player mode
+The modern version of VGA Planets is [Planets.nu](https://planets.nu/), and that project has also influenced the development of Pythonium.
 
-Once you have Pythonium installed you can test it in single-player mode with some of the available bots.
-i.e: the ``standard_player`` bot.
-
-```
-$ pythonium --players pythonium.bots.standard_player
-```
-
-Once the command finishes you should have a ``<sector>.gif`` file and a ``<sector>.log``, where ``<sector>`` is a unique code generated for the game.
-
-* ``<sector>.gif``: This is an animation showing how the planet's ownership, ship movements, and score along with the game.
-
-* ``<sector>.log``: Logs with all the relevant events during the game.
-
-
-## Multiplayer mode
-
-Pythonium allows to play up to two players in a single game. You can test it by providing two bots to the ``--players`` argument.
-
-
-```
-$ pythonium --players pythonium.bots.standard_player pythonium.bots.pacific_player
-```
-
-The output will be similar to the single-player mode: one ``.gif`` and one ``.log`` file.
-
-
-## Metrics
-
-By providing the ``--metrics`` arguments pythonium creates a report with several metrics of the game.
-This is especially useful to evaluate the performance of your players, and know their strengths and weaknesses.
-
-```
-$ pythonium --metrics --players pythonium.bots.standard_player pythonium.bots.pacific_player
-```
-
-In adition to the ``.gif`` and ``.log`` now you will se a ``report_<sector>.png`` with several charts.
-
-
-## Code your own player.
-
-Tutorial coming soon.
+To all of them, thank you.

docs/source/about.rst

@@ -1,70 +1,58 @@
 About Pythonium
 ================
 
-Pythonium is a space turn-based strategy game where each player lead an alien race
-that aim to conquer the galaxy.
+Pythonium is a space turn-based strategy game where each player leads an alienrace that aims to conquer the galaxy.
 
 You must explore planets to search and extract a valuable mineral: the `pythonium`.
-This precious material allows you to build cargo and combat spaceships, mines to get
-more pythonium or defenses for your planets.
+This precious material allows you to build cargo and combat spaceships, or mines to get
+more pythonium.
 
-Manage the economy on your planets, and collect taxes to your people to found your
-constructions, but be careful! Keep your clans happy if you want to avoid unrests
-in your planets.
+Manage the economy on your planets, and collect taxes on your people to finance your
+constructions, but be careful! Keep your clans happy if you want to  avoid unrest in your planets.
 
 Put your space helmet on, set your virtualenv, and start coding.
-Battle for pythonium is waiting for you.
+
+Battle for pythonium is waiting for you!
 
 Installation
 ================
 
-You can install Pythonium using PIP.
-
-::
-
-    $ pip install pythonium
-
-or cloning the repository and running
+You can install Pythonium by cloning `the repository <https://github.com/Bgeninatti/pythonium>`_ and running
 
 ::
 
     $ python setup.py install
 
-You can test your installation by running
+and then test your installation by running
 
 ::
 
     $ pythonium --version
     Running 'pythonium' version x.y.z
 
 
-Getting started
-================
-
-Pythonium allows different game modes. The default is the **classic mode**, where each player starts with 1 planet and 2 carriers in a random galaxy of 300 planets.
-The first player in conquer 210 planets (70% of the total) wins.
-
-Single player mode
+Single-player mode
 ==================
 
-Once you have Pythonium installed you can test it for a single player mode with some of the available bots.
-i.e: the ``standard_player`` bot.
+Once you have Pythonium installed you can test it for a single-player mode with some of the available bots.
+For example, the ``standard_player`` bot.
 
 ::
 
     pythonium --players pythonium.bots.standard_player
 
-Once the command finishes you should have a ``<sector>.gif`` file and a ``<sector>.log``, where ``<sector>`` is a unique code generated for the game.
+Once the command finishes you should have a ``<galaxy_name>.gif`` file and a ``<galaxy_name>.log``,
+where ``<galaxy_name>`` is a unique code generated for the game.
 
-* ``<sector>.gif``: This is an animation showing how the galaxy ownership changed along the game,
-  which planets belongs to each player, ships movements, combats and the score on each turn.
+* ``<galaxy_name>.gif``: This is an animation showing how the galaxy ownership changed along with the game,
+  which planets belong to each player, ships movements, combats, and the score on each turn.
 
-* ``<sector>.log``: Contain the logs with all the relevant events during the game.
+* ``<galaxy_name>.log``: Contain the logs with all the relevant events during the game.
 
 Here's an example of the gif
 
-.. image:: https://ik.imagekit.io/jmpdcmsvqee/single_player_ywFgXK732.gif
-   :target: https://ik.imagekit.io/jmpdcmsvqee/single_player_ywFgXK732.gif
+.. image:: https://ik.imagekit.io/jmpdcmsvqee/single_player_kOfI32YJ6sW.gif
+   :target: https://ik.imagekit.io/jmpdcmsvqee/single_player_kOfI32YJ6sW.gif
    :width: 300pt
 
 Multiplayer mode
@@ -76,20 +64,39 @@ Pythonium allows up to two players per game, and you can test it by providing tw
 
     pythonium --players pythonium.bots.standard_player pythonium.bots.pacific_player
 
-The output will be similar to the single player mode: one ``.gif`` and one ``.log`` file.
+The output will be similar to the single player mode: one ``.log`` and one ``.gif`` file.
+
+
+.. image:: https://ik.imagekit.io/jmpdcmsvqee/multi_player_COZwjdq3nKB.gif
+   :target: https://ik.imagekit.io/jmpdcmsvqee/multi_player_COZwjdq3nKB.gif
+   :width: 300pt
 
 
 Metrics
 =======
 
 Providing the ``--metrics`` arguments, pythonium creates a report with several metrics of the game.
-This is specially useful to evaluate the performance of your players, and know their strengths and wekenesses.
+This is especially useful to evaluate the performance of your players, and know their strengths and weaknesses.
 
 ::
 
     pythonium --metrics --players pythonium.bots.standard_player pythonium.bots.pacific_player
 
-In adition to the ``.gif`` and ``.log`` now you will se a ``report_<sector>.png`` with several charts.
+In addition to the ``.gif`` and ``.log`` now you will se a ``report_<galaxy_name>.png`` with several charts.
+
+
+.. image:: https://ik.imagekit.io/jmpdcmsvqee/sample_report_rm-fTWhSa.png
+   :target: https://ik.imagekit.io/jmpdcmsvqee/sample_report_rm-fTWhSa.png
+   :width: 300pt
+
+Acknowledge
+===========
+
+This game is strongly inspired by `VGA Planets <https://en.wikipedia.org/wiki/VGA_Planets>`_, a space strategy war game from 1992 created by Tim Wisseman.
+
+The modern version of VGA Planets is `Planets.nu <https://planets.nu/>`_, and that project has also influenced the development of Pythonium.
+
+To all of them, thank you.
 
 
 What next?

docs/source/api.rst

@@ -14,10 +14,10 @@ You shouldn't expect any useful information from those methods and attributes. M
     :members: known_races, compute_distance, distances_to_planets, nearby_planets, get_player_planets, get_player_ships, get_ships_in_deep_space, get_ships_in_position, search_ship, search_planet, get_ships_by_position, get_ships_in_planets, get_ships_conflicts, get_ocuped_planets, get_planets_conflicts
 
 .. autoclass:: pythonium.Planet
-    :members: pid, position, temperature, underground_pythonium, concentration, pythonium, mine_cost, player, megacredits, clans, mines, max_happypoints, happypoints, new_mines, new_ship, max_mines, taxes, rioting_index, dpythonium, dmegacredits, dhappypoints, dclans, can_build_mines, can_build_ship
+    :members: id, position, temperature, underground_pythonium, concentration, pythonium, mine_cost, player, megacredits, clans, mines, max_happypoints, happypoints, new_mines, new_ship, max_mines, taxes, rioting_index, dpythonium, dmegacredits, dhappypoints, dclans, can_build_mines, can_build_ship
 
 .. autoclass:: pythonium.Ship
-    :members: nid, player, type, position, max_cargo, max_mc, attack, megacredits, pythonium, clans, target, transfer
+    :members: id, player, type, position, max_cargo, max_mc, attack, megacredits, pythonium, clans, target, transfer
 
 .. autoclass:: pythonium.ShipType
     :members: name, cost, max_cargo, max_mc, attack
@@ -27,3 +27,9 @@ You shouldn't expect any useful information from those methods and attributes. M
 
 .. autoclass:: pythonium.Explosion
     :members:
+
+.. autoclass:: pythonium.core.Position
+    :members:
+
+.. autoclass:: pythonium.core.StellarThing
+    :members:

docs/source/tutorial.rst

@@ -5,7 +5,9 @@ Tutorial
 
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :caption: Contents:
 
     tutorial/01_first_player
+    tutorial/02_understanding_the_unknown
+    tutorial/03_random_walker

docs/source/tutorial/01_first_player.rst

@@ -1,7 +1,7 @@
-.. _First Player:
+.. _Tutorial Chapter 01:
 
-Coding your first player
-========================
+Chapter 1 - The beginning of the road
+======================================
 
 Welcome player!
 
@@ -11,12 +11,12 @@ a space explorer, and a strategist. All with the power of your terminal and text
 
 In this section, you will learn how to create a player to play Pythonium.
 
-Yes, you read correctly. You will not play Pythonium. You will build a player that will play Pythonium
-for you, and all your strategy needs to be implemented on that player.
+Yes, you read correctly. You will not play Pythonium. You will build a player that to play Pythonium
+for you, and all your strategy must be implemented on that player.
 
-This is a turn-based game, which means the player will receive a set of information (or state of the game)
-at the beginning of turn 0, and it will make decisions based on that information to influence the state of
-the game at turn 1. This sequence will be repeated again and again in an iterative process until the
+This is a turn-based game, which means each player receives a set of information (or state of the game)
+at the beginning of turn `t`, and makes decisions based on that information to influence the state of
+the game at turn `t+1`. This sequence is repeated again and again in an iterative process until the
 game finishes.
 
 Your player then is not more than a `python class <https://docs.python.org/3/tutorial/classes.html>`_ implementing a
@@ -44,23 +44,27 @@ Put this code inside a python file:
 There are a few things to note from here.
 
 In the first place, the ``Player`` class inherits from an ``AbstractPlayer``.
-Second, there is one attribute and one method that needs to be defined in the player class.
+Second, there is one attribute and one method that needs to be defined in this class.
 
-* ``name``: This is the name of your player. Try to make it short or your reports and gif will look buggy.
-* ``next_turn``: A method that will be executed every turn. This is where your strategy will be implemented.
+* ``name``: The name of your player. Try to make it short or your reports and gif will look buggy.
+* ``next_turn``: A method that will be executed every turn. This is where your strategy is implemented.
 
-Let's save now this file as ``my_player.py`` and execute the following command:
+.. _Executing your player:
+
+Executing your player
+----------------------
+
+Let's save now this file as ``my_player.py`` (or whatever name you like) and execute the following command:
 
 .. code-block:: bash
 
     $ pyhtonium --player my_player
     ** Pythonium **
-    Running battle in Sector #PBA5V2
+    Running battle in Galaxy #PBA5V2
     Playing game.....................................
     Nobody won
-    Game ran in 5.38 seconds
 
-The output will show the name of the *sector* (some place in the galaxy) where the game occurs, and some other
+The output will show the name of the galaxy where the game occurs, and some other
 self-explained information.
 
 Once the command finishes, you will find in your working directory two files:
@@ -70,22 +74,22 @@ Once the command finishes, you will find in your working directory two files:
 
 .. note::
 
-    Notice that the name of both files is the sector name. Each game is generated with a random (kinda unique)
-    sector name.
+    Notice that the name of both files is the galaxy name. Each game is generated with a random (kinda unique)
+    galaxy name.
 
 As a gif you will see something similar to this:
 
-.. image:: https://ik.imagekit.io/jmpdcmsvqee/first_player_tT9jZvrre.gif
-   :target: https://ik.imagekit.io/jmpdcmsvqee/first_player_tT9jZvrre.gif
+.. image:: https://ik.imagekit.io/jmpdcmsvqee/chapter_01_pwIQAPgxD.gif
+   :target: https://ik.imagekit.io/jmpdcmsvqee/chapter_01_pwIQAPgxD.gif
    :width: 300pt
 
 Reading from the top to the bottom:
 
-* You are in sector `#PBA5V2`
+* You are in the galaxy `#PBA5V2`
 * You are Han Solo (your player's name)
 * The turn at each frame is displayed at the left of the player name
 * You have one planet and two ships
-* Your planet and ships are in the blue dot. The rest of the dots are the others 299 planets in the sector.
+* Your planet and ships are in the blue dot. The rest of the dots are the others 299 planets in the galaxy.
 
 .. note::
 
@@ -94,7 +98,8 @@ Reading from the top to the bottom:
 
 
 Do you see it? Nothing happens. You just stay on your planet and do nothing for all eternity.
-If you check again on the player's code, this is precisely what it does: returns the galaxy without changing anything.
+By reviewing the player's code closely you will notice that this is precisely what it does: returns the galaxy without
+changing anything.
 
 Congratulations! You just reproduced your miserable human life on earth, as a Pythonium player.