Class catan.logic.Game

Catan game state class.

This class implements the state of a Catan match.

Constructor

catan.logic.game:new ([players]) Create a new game from a list of players colors.

Validation

catan.logic.game:validate () Validate game state against invariants.

Serialization

catan.logic.game:clone () Clone game state.
catan.logic.game:serialize () Serialize game state.
catan.logic.game:deserialize (str) Deserialize game state.

Getters

catan.logic.game:getNumberOfVictoryPoints (player) Get the number of victory points of a player.
catan.logic.game:getNumberOfDevelopmentCards (player) Get the number of development cards of a player.
catan.logic.game:getNumberOfResourceCards (player) Get the number of resource cards of a player.
catan.logic.game:getArmySize (player) Get the size of a player's army.
catan.logic.game:getNumberOfResourceCardsToDiscard (player) Get number of resource cards a player must discard.
catan.logic.game:getLongestRoadLength (player) Get the length of the longest road of a player.
catan.logic.game:getWinner () Get the winner of the game.
catan.logic.game:getTradeRatios (player) Get the ratios with which a player can trade in harbors.
catan.logic.game:getMaritimeTradeReturn (player, mycards) Get the number of cards a player can receive from a maritime trade.
catan.logic.game:getPlayableCardOfKind (kind) Get the first playable card of a given kind from the current player's hand.

Predicates

catan.logic.game:canPlaceInitialSettlement ([vertex]) Check whether the current player can place one of its initial settlement in a given vertex.
catan.logic.game:canPlaceInitialRoad ([edge]) Check whether the current player can place one of its initial road in a given edge.
catan.logic.game:canRoll ([dice]) Check whether the current player can roll the given dice.
catan.logic.game:isNumberOfResourceCardsAboveLimit (n) Check whether a number of resource cards is above limit for discard.
catan.logic.game:mustPlayerDiscard (player) Check whether a player would have to discard half of their cards if someone rolled a 7.
catan.logic.game:canDiscard ([player[, rescards]]) Check whether a player can discard the given resource cards.
catan.logic.game:canMoveRobber ([face]) Check whether the current player can move the robber to a given face.
catan.logic.game:canChooseVictim ([player]) Check whether the current player can choose a given player as victim of the robber.
catan.logic.game:canTrade () Check whether the current player can trade.
catan.logic.game:canTradeWithPlayer ([otherplayer[, mycards[, theircards]]]) Check whether the current player can trade resource cards with a given player.
catan.logic.game:canTradeWithHarbor ([mycards[, theircards]]) Check whether the current player can trade resource cards with harbor.
catan.logic.game:canBuildRoad ([edge]) Check whether the current player can build a road on a given edge.
catan.logic.game:canBuildSettlement ([vertex]) Check whether the current player can build a settlement on a given vertex.
catan.logic.game:canBuildCity ([vertex]) Check whether the current player can build a city on a given vertex.
catan.logic.game:canBuyDevelopmentCard () Check whether the current player can buy a development card.
catan.logic.game:isCardPlayable (devcard) Check whether a development card can be played.
catan.logic.game:canPlayKnightCard () Check whether the current player can play a Knight card.
catan.logic.game:canPlayRoadBuildingCard () Check whether the current player can play a Road Building card.
catan.logic.game:canPlayYearOfPlentyCard ([rescards]) Check whether the current player can play an Year of Plenty card.
catan.logic.game:canPlayMonopolyCard ([res]) Check whether the current player can play a Monopoly card.
catan.logic.game:canEndTurn () Check whether the current player can end their turn.

Actions

catan.logic.game:placeInitialSettlement (vertex) Place a settlement in a given vertex.
catan.logic.game:placeInitialRoad (edge) Place a road in a given edge.
catan.logic.game:roll (dice) Roll dice for resource production.
catan.logic.game:discard (player, rescards) Discard half of a player's resource cards.
catan.logic.game:moveRobber (face) Move the robber to another face.
catan.logic.game:chooseVictim (player) Choose victim of the robber.
catan.logic.game:tradeWithPlayer (otherplayer, mycards, theircards) Trade resource cards with a given player.
catan.logic.game:tradeWithHarbor (mycards, theircards) Trade resource cards in the harbor.
catan.logic.game:buildRoad (edge) Build a road on a given edge.
catan.logic.game:buildSettlement (vertex) Build a settlement on a given vertex.
catan.logic.game:buildCity (vertex) Build a city on a given vertex.
catan.logic.game:buyDevelopmentCard () Buy a development card.
catan.logic.game:playKnightCard () Play a Knight card.
catan.logic.game:playRoadBuildingCard () Play a Road Building card.
catan.logic.game:playYearOfPlentyCard (rescards) Play an Year of Plenty card.
catan.logic.game:playMonopolyCard (res) Play a Monopoly card.
catan.logic.game:endTurn () End the current player's turn.


Constructor

The class constructor is responsible for creating new matches with random initial setups.
catan.logic.game:new ([players])
Create a new game from a list of players colors. The valid player colors are "red", "blue", "yellow" and "white". The list must not have repetitions or fewer than 3 colors. The list dictates the order of turns, starting with the first.

Parameters:

Returns:

    Game game

Validation

We can check that the game state is valid according to a set of invariants, to increase the chance of detecting bugs.
catan.logic.game:validate ()
Validate game state against invariants. Raises an error message if an invariant is not satisfied.

Serialization

We can store a game state in a file, and load it back up through serialization and deserialization, respectively.
catan.logic.game:clone ()
Clone game state.

Returns:

    Game identical game state
catan.logic.game:serialize ()
Serialize game state.

Returns:

    string game state serialization
catan.logic.game:deserialize (str)
Deserialize game state.

Parameters:

  • str string game state serialization

Returns:

  1. optional Game deserialized game state (or nil in case of failure)
  2. optional string error message (in case of failure)

Getters

Getters are read-only methods that provide information about the current state of the game.
catan.logic.game:getNumberOfVictoryPoints (player)
Get the number of victory points of a player.

Parameters:

Returns:

    number number of victory points
catan.logic.game:getNumberOfDevelopmentCards (player)
Get the number of development cards of a player.

Parameters:

Returns:

    number number of development cards
catan.logic.game:getNumberOfResourceCards (player)
Get the number of resource cards of a player.

Parameters:

Returns:

    number number of resource cards
catan.logic.game:getArmySize (player)
Get the size of a player's army. A player's army is composed of the knights they have used so far.

Parameters:

Returns:

    number army size
catan.logic.game:getNumberOfResourceCardsToDiscard (player)
Get number of resource cards a player must discard. If the number of resource cards is above the limit, the player must discard half of their cards (rounding down).

Parameters:

Returns:

    number number of resource cards to discard

See also:

catan.logic.game:getLongestRoadLength (player)
Get the length of the longest road of a player.

Parameters:

Returns:

    number length of the longest road of player
catan.logic.game:getWinner ()
Get the winner of the game.

Returns:

    optional string the winner (or nil if no one has won yet)
catan.logic.game:getTradeRatios (player)
Get the ratios with which a player can trade in harbors. We represent a ratio of x:1 simply by the number x.

Parameters:

Returns:

  1. table ratios trading ratios for each resource
  2. number baseRatio base trading ratio (if not in ratios)

Usage:

    local ratios, baseRatio = game:getTradeRatios(player)
local ratio = ratios[res] or baseRatio
catan.logic.game:getMaritimeTradeReturn (player, mycards)
Get the number of cards a player can receive from a maritime trade. If some resource card has a bad ratio (for example, 5:1), returns nil and an error message.

Parameters:

  • player string
  • mycards table histogram of resource cards from the player

Returns:

  1. optional number the maritime trade return
  2. optional string error message (in case of failure)
catan.logic.game:getPlayableCardOfKind (kind)
Get the first playable card of a given kind from the current player's hand.

Parameters:

Returns:

  1. boolean
  2. optional string error message (in case of failure)

Predicates

Predicates are read-only methods that allow the developer to know if they can call a given action method.
catan.logic.game:canPlaceInitialSettlement ([vertex])
Check whether the current player can place one of its initial settlement in a given vertex.

Parameters:

  • vertex {q=number,r=number,v='N' or 'S'} (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canPlaceInitialRoad ([edge])
Check whether the current player can place one of its initial road in a given edge.

Parameters:

  • edge {q=number,r=number,e='NE', 'NW' or 'W'} (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canRoll ([dice])
Check whether the current player can roll the given dice. The possible values for each die are: 1, 2, 3, 4, 5, and 6.

Parameters:

  • dice {number,number} (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:isNumberOfResourceCardsAboveLimit (n)
Check whether a number of resource cards is above limit for discard. If a player has more resource cards than the limit, and a 7 is rolled, they will have to discard half of their cards (rounding down).

Parameters:

  • n number number of resource cards

Returns:

    boolean whether number is above limit

See also:

catan.logic.game:mustPlayerDiscard (player)
Check whether a player would have to discard half of their cards if someone rolled a 7. Does not check whether someone has rolled a 7.

Parameters:

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canDiscard ([player[, rescards]])
Check whether a player can discard the given resource cards.

Parameters:

  • player string (optional)
  • rescards table histogram of resource cards from player (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canMoveRobber ([face])
Check whether the current player can move the robber to a given face.

Parameters:

  • face {q=number,r=number} (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canChooseVictim ([player])
Check whether the current player can choose a given player as victim of the robber.

Parameters:

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canTrade ()
Check whether the current player can trade.

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canTradeWithPlayer ([otherplayer[, mycards[, theircards]]])
Check whether the current player can trade resource cards with a given player.

Parameters:

  • otherplayer string player to trade with (cannot be current player) (optional)
  • mycards table histogram of resource cards from the current player (optional)
  • theircards table histogram of resource cards from the other player (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canTradeWithHarbor ([mycards[, theircards]])
Check whether the current player can trade resource cards with harbor.

Parameters:

  • mycards table histogram of resource cards from the current player (optional)
  • theircards table histogram of resource cards to receive (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canBuildRoad ([edge])
Check whether the current player can build a road on a given edge.

Parameters:

  • edge {q=number,r=number,e='NE', 'NW' or 'W'} (optional)

Returns:

  1. boolean
  2. string or boolean error message (in case of failure) or whether player would use credit gained from playing an Year of Plenty card (in case of success)
catan.logic.game:canBuildSettlement ([vertex])
Check whether the current player can build a settlement on a given vertex.

Parameters:

  • vertex {q=number,r=number,v='N' or 'S'} (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canBuildCity ([vertex])
Check whether the current player can build a city on a given vertex.

Parameters:

  • vertex {q=number,r=number,v='N' or 'S'} (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canBuyDevelopmentCard ()
Check whether the current player can buy a development card.

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:isCardPlayable (devcard)
Check whether a development card can be played.

Parameters:

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canPlayKnightCard ()
Check whether the current player can play a Knight card.

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canPlayRoadBuildingCard ()
Check whether the current player can play a Road Building card.

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canPlayYearOfPlentyCard ([rescards])
Check whether the current player can play an Year of Plenty card. The current player can receive up to 2 resource cards from the bank, depending on its availability.

Parameters:

  • rescards table histogram of resource cards to be received (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canPlayMonopolyCard ([res])
Check whether the current player can play a Monopoly card.

Parameters:

  • res string the resource to be monopolized (optional)

Returns:

  1. boolean
  2. optional string error message (in case of failure)
catan.logic.game:canEndTurn ()
Check whether the current player can end their turn.

Returns:

  1. boolean
  2. optional string error message (in case of failure)

Actions

Actions are methods that necessarily change the state of the game.
catan.logic.game:placeInitialSettlement (vertex)
Place a settlement in a given vertex. This is exclusive to the set-up phase.

Parameters:

  • vertex {q=number,r=number,v='N' or 'S'}

Returns:

    catan.logic.HexProduction any resources gained from settlement placement
catan.logic.game:placeInitialRoad (edge)
Place a road in a given edge. This is exclusive to the set-up phase.

Parameters:

  • edge {q=number,r=number,e='NE', 'NW' or 'W'}
catan.logic.game:roll (dice)
Roll dice for resource production. The possible values for each die are: 1, 2, 3, 4, 5, and 6.

Parameters:

  • dice {number,number}

Returns:

    catan.logic.HexProduction any resources gained from dice roll
catan.logic.game:discard (player, rescards)
Discard half of a player's resource cards.

Parameters:

  • player string
  • rescards table histogram of resource cards from player
catan.logic.game:moveRobber (face)
Move the robber to another face.

Parameters:

  • face {q=number,r=number}

Returns:

  1. optional string robber victim (or nil if there isn't a single victim)
  2. optional string resource stolen from victim (or nil if there is no victim, or victim has no resources)
catan.logic.game:chooseVictim (player)
Choose victim of the robber.

Parameters:

Returns:

    optional string resource stolen from victim (or nil if victim has no resources)
catan.logic.game:tradeWithPlayer (otherplayer, mycards, theircards)
Trade resource cards with a given player.

Parameters:

  • otherplayer string the player to trade with
  • mycards table the resource cards offered by the current player
  • theircards table the resource cards from the other player
catan.logic.game:tradeWithHarbor (mycards, theircards)
Trade resource cards in the harbor.

Parameters:

  • mycards table the resource cards offered by the current player
  • theircards table the resource cards from the harbor
catan.logic.game:buildRoad (edge)
Build a road on a given edge.

Parameters:

  • edge {q=number,r=number,e='NE', 'NW' or 'W'}
catan.logic.game:buildSettlement (vertex)
Build a settlement on a given vertex.

Parameters:

  • vertex {q=number,r=number,v='N' or 'S'}
catan.logic.game:buildCity (vertex)
Build a city on a given vertex.

Parameters:

  • vertex {q=number,r=number,v='N' or 'S'}
catan.logic.game:buyDevelopmentCard ()
Buy a development card.

Returns:

    string the kind of the newly-bought development card
catan.logic.game:playKnightCard ()
Play a Knight card.
catan.logic.game:playRoadBuildingCard ()
Play a Road Building card.
catan.logic.game:playYearOfPlentyCard (rescards)
Play an Year of Plenty card. The current player can receive up to 2 resource cards from the bank, depending on its availability.

Parameters:

  • rescards table histogram of resource cards to be received
catan.logic.game:playMonopolyCard (res)
Play a Monopoly card.

Parameters:

  • res string the resource to be monopolized
catan.logic.game:endTurn ()
End the current player's turn.
generated by LDoc 1.5.0 Last updated 2023-07-02 05:10:58