More tutorials (#3)

* Add fieldwalk and highest card

Signed-off-by: jparisu <[email protected]>

* Fix title

Signed-off-by: jparisu <[email protected]>

---------

Signed-off-by: jparisu <[email protected]>

docs/index.rst

@@ -27,11 +27,13 @@
    /src/games/tutorials/hanoi
    /src/games/tutorials/slicing
    /src/games/tutorials/nqueens
+   /src/games/tutorials/fieldwalk
    /src/games/tutorials/coins
    /src/games/tutorials/nim
    /src/games/tutorials/tictactoe
    /src/games/tutorials/mastermind
    /src/games/tutorials/prisoner
+   /src/games/tutorials/highestcard
 
 
 .. toctree::

docs/src/games/games.rst

@@ -174,6 +174,15 @@ This is a list of all the games supported and its characteristics:
      - Perfect information
      - *Min score*: 0
 
+   * - **FieldWalk**
+     - ``IArena.games.FieldWalk``
+     - :ref:`fieldwalk_tutorial`
+     - Minimum cost path search.
+     - 1
+     - Deterministic
+     - Perfect information
+     -
+
    * - **Coins**
      - ``IArena.games.Coins``
      - :ref:`coins_tutorial`
@@ -218,3 +227,12 @@ This is a list of all the games supported and its characteristics:
      - Deterministic
      - Hidden information
      -
+
+   * - **Highest card**
+     - ``IArena.games.HighestCard``
+     - :ref:`highestcard_tutorial`
+     - Highest card N player game.
+     - N
+     - Random
+     - Hidden information
+     -

docs/src/games/tutorials/fieldwalk.rst

@@ -0,0 +1,141 @@
+.. _fieldwalk_tutorial:
+
+#########
+FieldWalk
+#########
+
+.. figure:: /resources/images/fieldwalk.png
+    :scale: 60%
+
+This game represents a search in a square graph of the shortest path.
+In a square of ``NxM``, each cell has a cost that represents the cost of passing through that cell.
+From each cell, the player can go to one of the 4 adjacent cells (up, down, left, right).
+The objective is to reach the bottom-right cell ``[N-1,M-1]`` from the top-left cell ``[0,0]`` with the minimum cost.
+
+====
+Goal
+====
+
+Starting at ``[0,0]``, the goal is to reach ``[N-1,M-1]`` with the minimum cost.
+
+-----
+Score
+-----
+
+The score of the game is the sum of the values of the squares that the player has passed through (initial square does not count).
+
+
+======
+Import
+======
+
+.. code-block:: python
+
+  import IArena.games.FieldWalk.FieldWalkPosition as FieldWalkPosition
+  import IArena.games.FieldWalk.FieldWalkMovement as FieldWalkMovement
+  import IArena.games.FieldWalk.FieldWalkRules as FieldWalkRules
+
+
+========
+Movement
+========
+
+A movement is represented an ``int``: ``direction``.
+
+- ``direction``
+  - ``int``
+  - ``0 <= direction <= 3``
+  - Indicates the direction of the movement
+  - Some movements are not possible if they go out of the board
+
+---------
+Direction
+---------
+
+Enumeration of the possible directions:
+
+- ``Up``
+  - ``0``
+- ``Down``
+  - ``1``
+- ``Left``
+  - ``2``
+- ``Right``
+  - ``3``
+
+
+.. code-block:: python
+
+    # To move up
+    movement = FieldWalkMovement.up()
+    # or
+    movement = FieldWalkMovement(
+      direction=FieldWalkMovement.Direction.Up)
+
+
+
+========
+Position
+========
+
+A position is represented by 3 ``int``.
+One indicates the x axis, other the y axis and the last one the cost to arrive to the current position.
+
+
+.. code-block:: python
+
+  # position : FieldWalkPosition
+  position.x     # X axis [0, N-1]
+  position.y     # Y axis [0, M-1]
+  position.cost  # Cost to arrive to this position
+
+
+=====
+Rules
+=====
+
+This games has every methods of :ref:`IRules <infrastructure_rules>`.
+
+-----------
+Constructor
+-----------
+
+Can receive the map, or let it be created randomly.
+
+.. code-block:: python
+
+  # Initiate with a map of 2x2 with cost 1
+  rules = FieldWalkRules(initial_map=FieldWalkMap([[1,1],[1,1]]))
+
+  # Initial position board 5x4 with random cost
+  rules = FieldWalkRules(rows=5, cols=4)
+
+  # Replicable initial position board 5x4 with random cost
+  rules = FieldWalkRules(rows=5, cols=4, seed=0)
+
+
+---
+Map
+---
+
+This game counts with a class ``FieldWalkMap`` that represents the grid of the game.
+This is created from a ``List[List[int]]``.
+The method ``get_matrix()`` returns the list of lists with all the values.
+
+.. code-block:: python
+
+  # get the FieldWalkMap
+  fw_map = rules.get_map()
+
+  # Get the size
+  N, M = len(fw_map)
+  # or
+  N, M = fw_map.goal()
+
+  # Get the matrix of the map
+  fw_map.get_matrix().get_matrix()
+
+  # Get the value of the final position
+  value = fw_map.get_matrix()[N-1][M-1]
+  # or
+  value = fw_map[N-1,M-1]

docs/src/games/tutorials/highestcard.rst

@@ -0,0 +1,113 @@
+.. _highestcard_tutorial:
+
+############
+Highest Card
+############
+
+.. figure:: /resources/images/cards.jpeg
+    :scale: 80%
+
+This game is a card game with ``N`` players and ``NxM`` cards.
+The objective of the game is to guess the number of rounds that the player will win with its ``M`` cards.
+Each player guesses in secret at the begining knowing only their ``M`` cards, for how many rounds it will win.
+Then, ``M`` rounds are played in which each player plays its highest card.
+The player that gets closer to the real number of rounds that it wins without passing it, wins the game.
+
+
+====
+Goal
+====
+
+Guess the number of rounds your card will be the higher, trying not to pass it.
+
+-----
+Score
+-----
+
+The score is calculated as:
+
+- If the player guesses correctly, it gets ``-5`` point.
+- If the player guesses lower than the real number, it gets ``1`` point for each round it passes.
+- If the player guesses higher than the real number, it gets ``2`` point for each round it passes.
+
+
+======
+Import
+======
+
+.. code-block:: python
+
+  import IArena.games.HighestCard.HighestCardPosition as HighestCardPosition
+  import IArena.games.HighestCard.HighestCardMovement as HighestCardMovement
+  import IArena.games.HighestCard.HighestCardRules as HighestCardRules
+
+
+========
+Movement
+========
+
+A movement is an ``int`` with the guess of number of rounds:
+
+- ``bet``
+  - ``int``
+  - ``0 <= bet <= M``
+  - Number of rounds it guesses it will win
+
+
+.. code-block:: python
+
+  # For guessing 0 rounds win
+  movement = HighestCardMovement(bet=0)
+
+  # For guessing 3 rounds win
+  movement = HighestCardMovement(bet=3)
+
+
+========
+Position
+========
+
+Each player can get its cards from the position, and only its cards.
+
+.. code-block:: python
+
+  # position = HighestCardPosition
+
+  # For getting the cards of the player
+  cards = position.get_cards()
+
+  # Get first card
+  card = cards[0]
+
+
+=====
+Rules
+=====
+
+This games has every methods of :ref:`IRules <infrastructure_rules>`.
+
+It counts with 2 method to retrieve the values of the game
+
+- ``rules.n_players() -> int``
+- ``rules.m_cards() -> int``
+
+
+-----------
+Constructor
+-----------
+
+The rules can be created with the cards already deal or with a seed to generate random decks.
+
+  .. code-block:: python
+
+    # Default game
+    rules = HighestCardRules()
+    # or
+    rules = HighestCardRules(n_players=3, m_cards=4)
+
+    # Replicable game
+    rules = HighestCardRules(n_players=3, m_cards=4, seed=0)
+
+    # With cards already deal for 2 player game with 2 cards
+    cards_distribution = {0: [0, 1], 1: [2, 3]}
+    rules = HighestCardRules(cards_distribution=cards_distribution)

docs/src/games/tutorials/mastermind.rst

@@ -5,7 +5,7 @@ Mastermind
 ##########
 
 .. figure:: /resources/images/mastermind.png
-    :scale: 40%
+    :scale: 2%
 
 This game is the classical Mastermind game.
 The objective of the game is to guess the *secret code*, this is a sequence of *N* numbers (color pegs) chosen from *M* numbers available ``[0,M)``.
@@ -119,7 +119,7 @@ Constructor
 
 There are 2 ways to construct the rules:
 
-#. Using a secret code already defined.
+1. Using a secret code already defined.
 
   .. code-block:: python
 
@@ -130,7 +130,7 @@ There are 2 ways to construct the rules:
     rules = MastermindRules(secret=[0, 0, 0, 0, 0, 0, 0, 7], m=8)
 
 
-#. Setting arguments ``n: int`` and ``m: int`` in order to generate a random secret code.
+2. Setting arguments ``n: int`` and ``m: int`` in order to generate a random secret code.
    Using argument ``seed: int`` the random generation can be reproduced.
 
   .. code-block:: python

docs/src/games/tutorials/slicing.rst

@@ -5,7 +5,7 @@ Slicing Puzzle
 ##############
 
 .. figure:: /resources/images/slicing.jpg
-    :scale: 60%
+    :scale: 10%
 
 This game is the classical Slicing puzzle.
 In a board of ``N x N`` squares, where every square has a number between ``[0, N-2]``, there is one of the squares that is *empty* (``-1``).