Shuffle and Deal Cards NetLogo Model

Produced for the book series "Exercises for Artificial Intelligence";

Author: W. J. Teahan; Publisher: Ventus Publishing Aps.

powered by NetLogo

view/download model file: Shuffle-and-Deal-Cards.nlogo

WHAT IS IT?

This model is a modification of the Shuffle Cards model. It shows how you can create a pack of cards using turtle shapes, shuffle them using the shuffle command and then deal them out.


WHAT IS ITS PURPOSE?

Its purpose is to illustrate that a lot can be done using just turtle shapes. A secondary purpose is to demonstrate how information can be stored in the environment using the hide-turtle command and then displayed when required using the show-turtle command.


HOW IT WORKS

The model uses three breeds of turtle agents to represent each card in the pack. These are: cards, suits and ranks. Each of these agents has a particular shape which is used to visually depict a card in the pack when it is shown. The card turtle agent owns a suit (e.g. clubs, spades, diamonds and hearts; this is represented by a suit turtle agent) and two ranks (e.g. Ace, King, represented by two rank turtle agents). These ranks appear at the top and bottom of a card - each of these is the 180 degrees rotation of the other.

Each card in the pack is created as separate agents (card, card-suit, card-rank-1 and card-rank-2) and this is then stored in a global list called the pack.

The cards are "dealt" by first hiding all the cards in the pack, then moving the agents to the required locations.


HOW TO USE IT

Select the slider values you want, then press the Shuffle button to display a shuffled deck of cards. The Deal button will then deal out the cards. If you then subsequently press the View pack button, this will show how the cards that have been dealt from the pack have been moved and are now overlaying some of the remaining cards in the pack.


THE INTERFACE

The model's Interface button and sliders are defined as follows:

- Shuffle: This button clears the environment, creates a new pack, then shuffles it, displaying the result in the environment.

- Deal: This button will 'deal' out the cards into a number of hands as determined by the number-of-hands and cards-in-the-hand sliders.

- Sort hands 1: This button will sort the cards in the hand by suit then type order.

- Sort hands 2: This button will sort the cards in the hand by type then suit order.

- View pack: This button will show where all of the agents are currently located in the environment (it uses the show-turtle command to show all the cards). If the cards in the pack have already been dealt out, some will have been moved and therefore overlay other cards in the pack.

- card-size: This is the size of each card.

- suit-size: This is the size of each suit depicted in the middle of each card.

- rank-size: This is the size of each rank depicted to the top left and bottom right of each card.

- number-of-hands: This is the number of hands that the cards will be dealt to.

- cards-in-the-hand: This is the number of cards in the hand.


THINGS TO NOTICE

Notice the extra shapes that have been added to the shapes library for the model by running the Turtles Shapes Editor in the Tools menu of the Interface. You will find a number of shapes added - these begin with "number: ..." and "suit: ...".

Notice how the card shape has been drawn using the shapes editor. Click on the outside of the card to verify that the thin outside line exists in the shape specification.

Notice the order that the agent positions are specified using the setxy command in the shuffle-pack-of-cards procedure for the three types of agents that are used to depict each card. The order is the card agent drawn first, followed by the card-suit, card-rank-1 and card-rank-2 agents. This ensures that the card agent appears underneath the other three agents and does not obscure them.

When the View pack button is pressed after the cards have been dealt, notice the pattern of which cards now overlay each other and which cards have been moved (i.e. there are blank spaces). Which bit of code causes this?


THINGS TO TRY

Try changing the values of the sliders to see what happens.

Try commenting out the last line of the setup procedure (set pack shuffle-pack-of-cards pack -90 30) to see what happens.

Have a go at improving the letter and number shapes used that are used to specify the card rank.

Try changing the model so that when you press the "View the pack" command it will move any cards that have been dealt back to their original locations in the shuffled pack.


EXTENDING THE MODEL

Create a model that can be used to play a card game. One trick that you can use (as with this model) is to hide the cards in the environment (using the hide-turtle command) and only show them when required.


NETLOGO FEATURES

The shuffle command in NetLogo makes shuffling the pack of cards very easy. The hide-turtle and show-turtle commands are also a powerful way of managing program state.


RELATED MODELS

See the Shuffle model.


CREDITS AND REFERENCES

To refer to this model in publications, please use:

Teahan, W. J. (2010). Shuffle and Deal NetLogo model.
Exercisaes for Artificial Intelligence. Ventus Publishing Aps.


PROCEDURES

; Shuffle and Deal Cards model.
;
; Shuffles and deals out a pack of cards.
;
; Written by William John Teahan (2010)
;
; Copyright 2010 William John Teahan. All Rights Reserved.

extensions [array]

breed [cards card]   ; a pack of cards
breed [suits suit]   ; clubs, spades, diamonds, hearts
breed [ranks rank]   ; Ace, King, Queen, Jack, Ten, ...

cards-own
[ card-suit          ; an agent: the card's suit
  card-type-1        ; an agent: the type of card shown top-left e.g. Ace, King, Queen, Jack, Ten, ...
  card-type-2        ; an agent: the type of card shown bottom-right e.g. Ace, King, Queen, Jack, Ten, ...
  card-rank-1        ; a number representing the card's rank from 1 to 52 (sorted by suit then by type)
  card-rank-2        ; another number representing the card's rank from 1 to 52 (sorted by type then by suit)
]

globals
[ pack               ; the pack of cards
  hands              ; an array containing the card hands as lists
  pack-start-x       ; x co-ordinate for starting to draw the pack of cards
  pack-start-y       ; y co-ordinate for starting to draw the pack of cards
]

to setup
; Setups the model.
  
  clear-all

  let this-card nobody
 
  ask patches
  [
    set pcolor 89 ;; make background full of light cyan coloured patches
  ]

  set pack-start-x (min-pxcor + ceiling (card-size / 2))
  set pack-start-y (max-pycor - ceiling (card-size / 2))
  set pack create-pack-of-cards pack-start-x pack-start-y ; default pack, in sorted order
  set pack shuffle-pack-of-cards pack pack-start-x pack-start-y ; put in random order

  set hands array:from-list n-values number-of-hands [[]] ; reset hands
end

to-report create-pack-of-cards [start-x start-y]
; Creates and reports a list of cards in sorted order.

  let x 0
  let y 0
  let s-1 0
  let s-2 0
  let val-1 0
  let val-2 0
  let this-suit nobody
  let this-card nobody
  let this-pack []

  set y start-y  
  foreach [["suit heart" 0 1] ["suit diamond" 13 2] ["suit spade" 26 3] ["suit club" 39 4]]
  [
    set x start-x
    set this-suit (first ?)
    set s-1 (item 1 ?)
    set s-2 (last ?)
    foreach [["card: Ace" 1 0] ["card: King" 2 4] ["card: Queen" 3 8] ["card: Jack" 4 12] ["number: Ten" 5 16]
             ["number: Nine" 6 20] ["number: Eight" 7 24] ["number: Seven" 8 28] ["number: Six" 9 32]
             ["number: Five" 10 36] ["number: Four" 11 40] ["number: Three" 12 44] ["number: Two" 13 48]]
    [
      set val-1 s-1 + (item 1 ?)
      set val-2 s-2 + (last ?)
      set this-card create-card this-suit (first ?) val-1 val-2 x y
      set this-pack fput this-card this-pack
      set x x + 15 
    ]
    set y y - 22
  ]  
  
  report this-pack
end

to-report shuffle-pack-of-cards [this-pack start-x start-y]
; Shuffles the pack of cards, and returns it.

  set pack shuffle pack ; randomise the pack

  ; also need to reset the x, y co-ordinates
  let x start-x
  let y start-y
  let p 0
  foreach pack
  [
    if (p mod 13 = 0) and (p != 0)
      [ set x start-x
        set y y - 22
      ]
    move-card ? x y ; reset x and y positions for the card
    set x x + 15
    set p p + 1
  ]
  
  report pack
end  

to dump-pack-of-cards [this-pack]
; Dumps the pack of cards (for debugging purposes).

  print this-pack
  print length this-pack
end

to view-cards [ type-of-view ]
; Views the cards - either the whole pack, or the cards in the hands
; depending on what the type-of-view parameter is set to.

  let x 0
  let y 0

  ifelse (type-of-view = "View the pack")
    [ ; views the pack of cards, hiding the hands
      ask cards
      [
        show-turtle
        ask card-suit [ show-turtle ]
        ask card-type-1 [ show-turtle ]
        ask card-type-2 [ show-turtle ]
      ]
    ]
    [ ; views the hands, hiding the pack
      ask cards
      [
        hide-turtle
        ask card-suit [ hide-turtle ]
        ask card-type-1 [ hide-turtle ]
        ask card-type-2 [ hide-turtle ]
      ]
      
      ; show the hands
      set y pack-start-y
      foreach array:to-list hands
      [
        set x pack-start-x
        foreach ?
        [
          move-card ? x y            
          set x x + 15
        ]

        set y y - 22
      ]
    ]
end

to sort-hands-1
; Sorts the hands into suit then type order.

  let x 0
  let y 0

  set y pack-start-y
  foreach array:to-list hands
  [
    set x pack-start-x
    foreach sort-by [[card-rank-1] of ?1 < [card-rank-1] of ?2]
                    ?
    [ 
      move-card ? x y            
      set x x + 15
    ]

    set y y - 22
    ]
end

to sort-hands-2
; Sorts the hands into type then suit order.

  let x 0
  let y 0

  set y pack-start-y
  foreach array:to-list hands
  [
    set x pack-start-x
    foreach sort-by [[card-rank-2] of ?1 < [card-rank-2] of ?2]
                    ?
    [ 
      move-card ? x y            
      set x x + 15
    ]

    set y y - 22
    ]
end

to-report card-colour [this-shape]
; Reports the colour of the card whose suit is specified
; by this-shape.

  ifelse (this-shape = "suit club") or (this-shape = "suit spade")
    [ report black ]
    [ report red ]
end

to-report create-card [this-card-suit this-card-type this-card-rank-1 this-card-rank-2 x y]
; Creates and returns a new card with the suit specified by this-card-suit and
; its type and rank by this-card-type and this-card-rankand places it at
; co-ordinates (x,y).

  let this-card nobody
  let this-suit nobody
  let this-rank-1 nobody
  let this-rank-2 nobody

  let this-colour card-colour this-card-suit
  
  create-suits 1
  [
    set this-suit self
    set size suit-size
    
    set shape this-card-suit
    set color this-colour
    setxy x y
  ]

  create-ranks 1
  [
    set this-rank-1 self
    set size rank-size
    
    set shape this-card-type
    set heading 0
    set color this-colour
    setxy x - 4 y + 6
  ]

  create-ranks 1
  [
    set this-rank-2 self
    set size rank-size
    
    set shape this-card-type
    set heading 180
    set color this-colour
    setxy x + 4 y - 6
  ]

  create-cards 1
  [
    set this-card self
    set size card-size
    set shape "card"
    set color white
    set card-suit this-suit
    set card-type-1 this-rank-1
    set card-type-2 this-rank-2
    set card-rank-1 this-card-rank-1
    set card-rank-2 this-card-rank-2
    setxy x y
  ]

  report this-card
end

to move-card [card x y]
; Draws the card at co-ordinates (x,y).

  ask card
  [
    setxy x y
    show-turtle
    ask card-suit
    [ setxy x y
      show-turtle ]
    ask card-type-1
    [ setxy x - 4 y + 6
      show-turtle ]
    ask card-type-2
    [ setxy x + 4 y - 6
      show-turtle ]    
  ]
end

to deal
; Deals out the pack.

  let cards-to-be-dealt number-of-hands * cards-in-the-hand
  let hand []
  let h 0
  let c 0

  set hands array:from-list n-values number-of-hands [[]] ; reset hands  
  while [c < cards-to-be-dealt]
  [
    set h c mod number-of-hands ; select which hand to deal the card to
    set hand array:item hands h ; get the current cards in the hand
    set hand fput (item c pack) hand ; deal the card from the pack into the hand
    array:set hands h hand
    set c c + 1
  ]

  view-cards "View the hands"
end
;
; Copyright 2010 by William John Teahan.  All rights reserved.
;
; Permission to use, modify or redistribute this model is hereby granted,
; provided that both of the following requirements are followed:
; a) this copyright notice is included.
; b) this model will not be redistributed for profit without permission
;    from William John Teahan.
; Contact William John Teahan for appropriate licenses for redistribution for
; profit.
;
; To refer to this model in publications, please use:
;
; Teahan, W. J. (2010).  Shuffle abd Deal NetLogo model.
;   Artificial Intelligence. Ventus Publishing Aps
;