PyCatan
A Library for simulating a game of The Settlers of Catan
Run
Download from pip3
pip3 install pycatan
Run tests from source
Easy way
Run the bash file test.sh `.test.sh'
Hard Way
- Install virtualenv and virtualenvwrapper
- Create a new virtual environment (
mkvirtualenv test
) - Install pytest
- Run (from root directory)
python -m pytest tests
Contents
- Documentation
CatanGame
CatanBoard
CatanPlayer
- Etc
- Example game
- Something
Documentation
CatanGame
module
Represents a game of Catan
Atttributes
board
- The
CatanBoard
in the game
- The
players
- An array of
CatanPlayer
s (representing the players)
- An array of
longest\_road\_owner
- The index of the player who has the longest road
Functions
CatanGame.__init__(self, num_of_players=3, on_win=None, starting_board=False)
Creates a new CatanGame
num_of_players
: The number of players playing the gameon_win
: Optional function to run when the game is wonstarting_board
: Whether or not to use the beginner's board
CatanGame.add_settlement(self, player, r, i, is_starting=False)
Builds a new settlement
player
: The index of the player who is building the settlementr
: The row at which to build the settlementi
: The index at which to build the settlementis_starting
: Whether or not the settlement is being build during the building phase, and thus should be build for free
Returns a CatanStatus
value.
CatanGame.add_road(self, player, start, end, is_starting=False)
Builds a new road
player
: The index of the player building the roadstart
: An array with the coordinate of one the the road's points (given[row, index]
)end
: An array with the coordinate of the road's other point (given[row, index]
)is_starting
: Whether or not the road is being built during the building phase and thus should be build for free
Returns a CatanStatus
value
CatanGame.add_city(self, r, i, player)
Builds a city on top of a settlement
r
: The row at which to build the cityi
: The index at which to build the cityplayer
: The index of the player who is building the city
Returns a CatanStatus
value
CatanGame.build_dev(self, player)
Builds a new developement card
player
: The player who is building the developement card
Returns a CatanStatus
value
CatanGame.use_dev_card(self, player, card, args)
Uses a developement card
player
: The player who is using the cardcard
: TheCatanCard
value representing the type of cardargs
: Variable arguments in a dictionary depending on which type of developement card is playedCatanCards.DEV_ROAD
:args
contains'road_one'
and'road_two'
values, both of which are arrays of arrays coresponding to the point which the roads should be builtroad_one
: An array representing the first road in arrays representing points- Ex:
[[0, 0], [0, 1]]
would represent a road going from0, 0
to0, 1
- Ex:
road_two
: Same asroad_one
, but for the other road
CatanCards.DEV_KNIGHT
:args
contains'robber_pos'
and'victim'
values.robber_pos
: The position for the robber to be placed as an array, given as[row, index]
victim
: The index of the player to take the card from. Can beNone
if the player playing the knight card doesn't want to take a card from anybody.
CatanCards.DEV_MONOPOLY
:args
contains a'card_type'
value.card_type
: TheCatanCards
value representing the card the player wants to take
CatanCards.DEV_YOP
:args
contains'card_one'
and'card_two'
values.card_one
: TheCatanCards
value of the first card the player wants to takecard_two
: TheCatanCards
value of the second card
CatanCards.DEV_VP
: Do not callCatanGame.use_dev_card
onCatanCards.DEV_VP
, as players do not play VP cards, but keep them until the end of the game.
CatanGame.add_yield_for_roll(self, roll)
Distributes cards based on a dice roll
roll
: The dice roll
Returns nothing
CatanGame.get_roll(self)
Optional. Simulates 2 dice rolls added together.
Returns a number
CatanGame.trade(self, player_one, player_two, cards_one, cards_two)
Trades cards between players
player_one
: The first player in the tradeplayer_two
: The second player in the tradecards_one
: The cards the first player is givingcards_two
: The cards the second player is giving
Returns a CatanStatus
value
CatanGame.trade_to_bank(self, player, cards, request)
Trades 4 cards to the bank for 1 card. Also will trade only 2 cards if the player is connected to the right harbor
player
: The player who is trading the cardscards
: An array of numbers (CatanCard
values) to trade from the player to the bankrequest
: TheCatanCard
value the player will receive
Returns a CatanStatus
value
CatanBoard
Represents a Catan game board.
Static values
CatanBoard.HEX_FOREST
- Represents a forest hex
CatanBoard.HEX_Hills
- Represents a hills hex
CatanBoard.HEX_MOUNTAINS
- Represents a mountains hex
CatanBoard.HEX_PASTURE
- Represents a pasture hex
CatanBoard.HEX_FIELDS
- Represents a fields hex
CatanBoard.HEX_DESERT
- Represents a desert hex
Attributes
hexes
- An array representing the hexes on the board
hex_nums
- An array representing the number tokens on the board
points
- An array representing the intersections between hexes (where settlements are placed)
roads
- An array of
CatanBuildings
representing all the roads in the game
- An array of
harbors
- An array of
CatanHarbors
representing all the harbors on the board
- An array of
robber
- An array representing the robber's position (given as
[row, index]
)
- An array representing the robber's position (given as
Functions
CatanBoard.get_card_from_hex(hex)
Gets a CatanCards
value for a corresponding CatanBoard
Hex value
hex
: TheCatanBoard
hex value to get the card for
Ex: CatanBoard.get_card_from_hex(CatanBoard.HEX_HILLS)
would return CatanCards.CARD_BRICK
Returns a CatanCards
value
CatanBuilding
Represents a Catan Building
Static Values
CatanBuilding.BUILDING_ROAD
Represents a road
CatanBuilding.BUILDING_SETTLEMENT
Represents a settlement
CatanBuilding.BUILDING_CITY
Represents a city
CatanCards
Contains values representing different resource and developement cards
Static Values
CatanCards.CARD_WOOD
Represents a wood resource card.
CatanCards.CARD_BRICK
Represents a brick resource card.
CatanCards.CARD_SHEEP
Represents a sheep resource card.
CatanCards.CARD_ORE
Represents a ore resource card.
CatanCards.CARD_WHEAT
Represents a wheat resource card.
CatanCards.DEV_ROAD
Represents a road building developement card.
CatanCards.DEV_VP
Represents a victory point developement card.
CatanCards.DEV_MONOPOLY
Represents a monopoly developement card.
CatanCards.DEV_YOP
Represents a year of plenty developement card.
CatanCards.DEV_KNIGHT
Represents a knight developement card.
CatanHarbor
Represents a harbor.
Static values
CatanHarbor.TYPE_WOOD
Represents a 2:1 Wood harbor
CatanHarbor.TYPE_BRICK
Represents a 2:1 Brick harbor
CatanHarbor.TYPE_WHEAT
Represents a 2:1 Wheat harbor
CatanHarbor.TYPE_ORE
Represents a 2:1 Ore harbor
CatanHarbor.TYPE_SHEEP
Represents a 2:1 Sheep harbor
Functions
CatanHarbor.get_type(self)
Returns a string representation of the harbor's type
CatanPlayer
Represents a player in the game.
Functions
CatanPlayer.get_VP(self, include_dev=False)
Returns the number of victory points the player has.
include_dev
: Whether to include victory points from developement cards, which are only counted if the player wins and should be hidden otherwise.
CatanStatuses
Interger representation of different statuses returned by functions.
Static values
CatanStatuses.ALL_GOOD
The function ran successfully
CatanStatuses.ERR_CARDS
The player trying to perform an action lacks the necessary cards.
CatanStatuses.ERR_BLOCKED
A building is blocking the action.
CatanStatuses.ERR_BAD_POINT
The point being used does not exist.
CatanStatuses.ERR_NOT_CON
The player is trying to build a building which is not connected to any of their roads.
CatanStatuses.ERR_HARBOR
The player is trying to use a harbor which they are not connected to
CatanStatuses.ERR_NOT_EXIST
The player is trying to use a building which does not exist
CatanStatuses.ERR_BAD_OWNER
The player is trying to use a building which belongs to another player
CatanStatuses.ERR_UPGRADE_CITY
The player is trying to build a city on an invalid location
CatanStatuses.ERR_DECK
There are not enough cards in the deck to perform this action
CatanStatuses.ERR_INPUT
The input given is missing mandatory information
CatanStatuses.ERR_TEST
When running the test module, an error was encountered
Example game
We're going to make an example text-game of Catan using PyCatan
First, create a new file.
game.py
def main():
print("Playing Catan!")
if __name__ == "__main__":
main()
Now let's set up a new game of Catan
game.py
from PyCatan import CatanGame
def main():
num_of_players = int(input("How many players are playing? "))
game = CatanGame(num_of_players)