Skip to content

Commit

Permalink
updated Amazons tutorials
Browse files Browse the repository at this point in the history
  • Loading branch information
@DennisSoemers
DennisSoemers committed Feb 10, 2021
1 parent 98ca3c6 commit 74e987c
Show file tree
Hide file tree
Showing 9 changed files with 197 additions and 239 deletions.
198 changes: 87 additions & 111 deletions docs/tutorial_amazons.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,78 +23,55 @@ from that place. The last player able to make a move wins.
Step 1: A Minimum Legal Game Description
----------------------------------------

We start out with the minimum description that results in a legal game description
that may be loaded in Ludii:
We start out with the minimum description that results in a legal game description that
may be loaded in Ludii by defining the number of players, the board by its shape and
its size, the most used playing rules, and a basic ending rule.

.. code-block:: python
:linenos:
(game "Amazons")
This description will load the default game (*Tic-Tac-Toe*), but it will be named
"Amazons".

Step 2: Defining the Players and the Board
------------------------------------------

We extend the game description listed above by defining the number of players,
and the board by its shape and its size:

.. code-block:: python
:linenos:
:emphasize-lines: 2-7
(game "Amazons"
(players 2)
(equipment
{
(board (square 10))
}
)
(rules
(play
(forEach Piece)
)
(end
(if
(no Moves Next)
(result Mover Win)
)
)
)
)
Line 2 defines that we wish to play a two-player game, where it is implied by
default to be an alternating-move game. Line 3 defines the equipment, and is
used to list all the items used in the game. Line 5 defines that we wish to use
a square board of size 10. By default, the square board is tiled by squares.
Line 2 defines that we wish to play a two-player game, where it is implied by default
to be an alternating-move game. Line 3 defines the equipment, and is used to list all
the items used in the game. Line 5 defines that we wish to use a square board of size
10. By default, the square board is tiled by squares. Line 8 is used to define the
rules of the game; the minimum rules to compile are the playing and the ending rules.
Lines 9-11 describe the playing rules by using one of the simplest ``play`` rules
available in Ludii; ``(forEach Piece)``, which simply defines that Ludii should
loop through all pieces owned by a player, and extract legal moves from the piece types
to generate the list of legal moves for a mover. Finally, lines 13-18 describe the ending
rules. Here we want the player who last made a move to win the game whenever the next
player has no move.

Step 3: Defining the Pieces
---------------------------
Step 2: Defining the Pieces
------------------------------------------

In this step, we add the pieces to the equipment.

.. code-block:: python
:linenos:
:emphasize-lines: 6,7
(game "Amazons"
(players 2)
(equipment
{
(board (square 10))
(piece "Queen" Each)
(piece "Dot" Neutral)
}
)
)
Line 6 defines that each player should have a piece type labelled "Queen".
Ludii will automatically label these as ``"Queen1"`` and ``"Queen2"`` for
players 1 and 2, respectively. Additionally, in line 7 we define a "Dot" piece
type, which is not owned by any player. This is the piece type that we will use
in locations that players block by shooting their arrows.

Step 4: Defining the Playing and Ending rules
---------------------------------------------

In this step, we add the minimum rules (other than the default, implicit
*Tic-Tac-Toe* rules) that result in a legal game description that may be loaded
in Ludii:
.. code-block:: python
:linenos:
:emphasize-lines: 10-21
(game "Amazons"
(players 2)
(equipment
Expand All @@ -103,12 +80,12 @@ in Ludii:
(piece "Queen" Each)
(piece "Dot" Neutral)
}
)
)
(rules
(play
(forEach Piece)
)
(end
(if
(no Moves Next)
Expand All @@ -118,23 +95,20 @@ in Ludii:
)
)
Line 10 is used to define the rules of the game; the minimum rules to compile
are the playing and the ending rules. Lines 11-13 describe the playing rules by
using one of the simplest ``play`` rules available in Ludii; ``(forEach Piece)``,
which simply defines that Ludii should loop through all pieces owned by a player,
and extract legal moves from the piece types to generate the list of legal moves
for a mover. Finally, lines 15-20 describe the ending rules. Here we want the
player who last made a move to win the game whenever the next player has no move.
Line 6 defines that each player should have a piece type labelled ``Queen''.
Ludii will automatically label these as ``"Queen1"`` and ``"Queen2"`` for players
1 and 2, respectively. Additionally, in line 7 we define a ``Dot'' piece type,
which is not owned by any player. This is the piece type that we will use in
locations that players block by shooting their arrows.
Step 5: Defining the Starting Rules
-----------------------------------
Step 3: Defining the Starting Rules
---------------------------
We extend the game description listed above by adding ``start`` rules to place
the pieces on the board:
We extend the game description listed above by adding ``start`` rules to place the pieces on the board:

.. code-block:: python
:linenos:
:emphasize-lines: 11-16
:emphasize-lines: 11-16,
(game "Amazons"
(players 2)
Expand All @@ -155,31 +129,31 @@ the pieces on the board:
(play
(forEach Piece)
)
(end
(if
(no Moves Next)
(result Mover Win)
)
)
)
)
)
Lines 11--16 ensure that any game is started by placing objects of the two
different types of queens in the correct starting locations. The labels used to
specify these locations can be seen in Ludii by enabling "Show Coordinates" in
Ludii's *View* menu.
Lines 11-16 ensure that any game is started by placing objects of the two
different types of queens in the correct starting locations. The labels
used to specify these locations can be seen in Ludii by enabling
"Show Coordinates" in Ludii's *View* menu.

Step 6: Adding the Final Rules for *Amazons*
--------------------------------------------
Step 4: Step 4: Adding the Final Rules for *Amazons*
---------------------------------------------

To complete the game of *Amazons*, we need to allow players to move their queens
and to shoot an arrow after moving a queen. This is implemented in the following
game description:
To complete the game of *Amazons*, we need to allow players to move
their queens and to shoot an arrow after moving a queen. This is implemented
in the following game description:

.. code-block:: python
:linenos:
:emphasize-lines: 6,18-21
:emphasize-lines: 6,7,17-22
(game "Amazons"
(players 2)
Expand All @@ -203,7 +177,7 @@ game description:
(move Shoot (piece "Dot0"))
)
)
(end
(if
(no Moves Next)
Expand All @@ -212,34 +186,36 @@ game description:
)
)
)
To make the queens able to move, inside the queen pieces, we have added the
following: ``(move Slide (then (moveAgain))))``. By default, the ``(move Slide)``
ludeme defines that the piece is permitted to slide along any axis of the used board,
as long as we keep moving through locations that are empty. No additional
restrictions -- in terms of direction or distance, for example -- are required
for queen moves. We have appended ``(then (moveAgain))`` in the queen moves.
This means that, after any queen move, the same player gets to make another move.
following: ``(move Slide (then (moveAgain))))``. By default, the ``(move Slide)``
ludeme defines that the piece is permitted to slide along any axis of the used
board, as long as we keep moving through locations that are empty. No additional
restrictions -- in terms of direction or distance, for example -- are required for
queen moves. We have appended ``(then (moveAgain))`` in the queen moves. This means
that, after any queen move, the same player gets to make another move.

In lines 18-21, the ``play`` rules have been changed to no longer exclusively
extract their moves from the pieces. Only at even move counts (0, 2, 4, etc.)
do we still make a queen move (using ``(forEach Piece)``. At odd move counts,
the moves are defined by ``(move Shoot (piece "Dot0"))``. This rule lets us
shoot a piece of type ``"Dot0"`` into any empty position, starting from the
location that we last moved to -- this is the location that our last queen move
ended up in. This game description implements the full game of *Amazons* for
Ludii.
In lines 18-21, the ``play`` rules have been changed to no longer exclusively extract
their moves from the pieces. Only at even move counts (0, 2, 4, etc.) do we still make
a queen move (using ``(forEach Piece)``. At odd move counts, the moves are defined by
``(move Shoot (piece "Dot0"))``. This rule lets us shoot a piece of type ``"Dot0"`` into
any empty position, starting from the location that we last moved to -- this is the location
that our last queen move ended up in. This game description implements the full game of *Amazons*
for Ludii.

Once pieces are defined, their names are internally appended with the index of the owning player.
For example, the above description defines a "Queen" piece for players 1 and 2, then the subsequent description refers to "Queen1" for "Queen" pieces belonging to Player 1 and "Queen2" for "Queen" pieces belonging to Player 2. The "Dot" piece is referred to as "Dot0", indicating that this is a neutral piece not owned by any player.
Note that pieces can also be referred to by their undecorated names in the game description, e.g. "Queen" or "Dot", in which case the reference applies to all pieces with that name belonging to any player.
For example, the above description defines a "Queen" piece for players 1 and 2, then the subsequent
description refers to "Queen1" for "Queen" pieces belonging to Player 1 and "Queen2" for "Queen"
pieces belonging to Player 2. The "Dot" piece is referred to as "Dot0", indicating that this is a
neutral piece not owned by any player. Note that pieces can also be referred to by their undecorated
names in the game description, e.g. "Queen" or "Dot", in which case the reference applies to all
pieces with that name belonging to any player.

Step 7: Improving Graphics
--------------------------
Step 5: Improving Graphics
-----------------------------------

The game description above plays correctly, but does not look appealing because
it uses Ludii's default colours for the board. This can be easily improved by
adding graphics metadata:
The game description above plays correctly, but does not look appealing because it uses Ludii's
default colours for the board. This can be easily improved by adding graphics metadata:

.. code-block:: python
:linenos:
Expand All @@ -249,35 +225,35 @@ adding graphics metadata:
(players 2)
(equipment
{
(board (square 10))
(board (square 10))
(piece "Queen" Each (move Slide (then (moveAgain))))
(piece "Dot" Neutral)
}
)
(rules
)
(rules
(start
{
(place "Queen1" {"A4" "D1" "G1" "J4"})
(place "Queen2" {"A7" "D10" "G10" "J7"})
}
)
(play
(if (is Even (count Moves))
(forEach Piece)
(move Shoot (piece "Dot0"))
)
)
(end
(if
(no Moves Next)
(result Mover Win)
)
)
(if
(no Moves Next)
(result Mover Win)
)
)
)
)
(metadata
(graphics
{
Expand Down
25 changes: 22 additions & 3 deletions resources/luds/walkthrough_amazons/Step1.lud
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,25 @@
// Step 1 in the tutorial for writing Amazons in .lud format from scratch
//
// This file is actually just loaded as Tic-Tac-Toe, except that it will
// be named "Amazons".
// This is a minimal legal game description, with some basic equipment,
// playing rules, and ending rules.

(game "Amazons")
(game "Amazons"
(players 2)
(equipment
{
(board (square 10))
}
)
(rules
(play
(forEach Piece)
)

(end
(if
(no Moves Next)
(result Mover Win)
)
)
)
)
27 changes: 20 additions & 7 deletions resources/luds/walkthrough_amazons/Step2.lud
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,26 @@
// Step 2 in the tutorial for writing Amazons in .lud format from scratch
//
// This file loads a game with a 10x10 board, but otherwise still the rules
// of Tic-Tac-Toe since we did not specify any other rules.
// In this step we specify the piece types used to play Amazons.

(game "Amazons"
(players 2)
(equipment
{
(board (square 10))
(game "Amazons"
(players 2)
(equipment
{
(board (square 10))
(piece "Queen" Each)
(piece "Dot" Neutral)
}
)
(rules
(play
(forEach Piece)
)

(end
(if
(no Moves Next)
(result Mover Win)
)
)
)
)

0 comments on commit 74e987c

Please sign in to comment.