Shuffle Bags (ssk.shufflebag.*)

This library is used to create Shuffle Bags.

A Shuffle Bag is a technique for controlling randomness to create the distribution we desire. envatotuts+

In short, if you want to create a random set of 'things' and control the random distribution of each 'thing' in that set, this is the answer.

Tip: 'Things' can be strings, numbers, object references, table reference, function referenes, ... pretty much any Lua referable entity.

Creating a Shuffle Bag

Creating a new shuffle bag is as easy as:


local bag = ssk.shuffleBag.new()

Tip: The new() function takes an optional list of 'things' to add directly to the new bag.


local bag = ssk.shuffleBag.new( "jack.png", "king.png", "queen.png", "ace.png" )

Shuffle Bag Methods (bag:*)

| | |:-------------:|:-------------:|:-------------:| | get | getCounts | insert | | putBack | shuffle | take |

insert

Add 'thing' to shuffle bag.

bag:insert( thing )

thing - 'Thing' to add to bag.


local cards = shuffleBag.new()

cards:insert( "jack.png" )
cards:insert( "king.png" )
cards:insert( "queen.png" )
cards:insert( "ace.png" )

shuffle

Randomize the bag.

bag:shuffle( )


cards:shuffle()

get

Get one random entry from bag.

Tip: By default, bags autoshuffle. This way, if you try to get an entry from the bag and it is empty, the bag will automatically re-fill and shuffle, then return a new object.

bag:get( [autoShuffle] )

autoShuffle (true) - If true, and out of entries, automatically shuffle the bag.


local file = cards:get()

getCounts

Return count of Unused, Used, and Out entries

Unused Entry - An entry in the bag that has not been 'gotten' since the last shuffle.
Used Entry - An entry in the bag that has been 'gotten' since the last shuffle. Can't be gotten again till a new shuffle occurs.
Out Entry - A used entry that can't be gotten till it is putBack and a shuffle is done. Taken entries are marked as out.

bag:getCounts( )


local unused, used, out = cards:getCounts()

print("Unused entries: ", unused )
print("  Used entries: ", used )
print("   Out entries: ", out )

take

Same as a get(), but entry is marked as Out. This entry will not be takeable again until:

It is putBack(), and
The bag is re-shuffled.

Tip: By default, bags autoshuffle. This way, if you try to get an entry from the bag and it is empty, the bag will automatically re-fill and shuffle, then return a new object.

bag:take( [autoShuffle] )

autoShuffle (true) - If true, and out of entries, automatically shuffle the bag.


local file = cards:take()

putBack

Used to return an Out entry.

Warning: When you put back an entry it must be a valid entry that exactly matches a previously taken entry. You are responsible for tracking references to entries you take().

bag:putBack( [entry] )

entry (nil) - The exact entry you removed from the bag previously with take().
- Tip:: If you pass nil (call with no argument), the last Out entry will be put back.


cards:putBack( file )

Complete Shuffle Bag Examples


local bag1

local bag2

local shuffleBag = ssk.shuffleBag

local test = {}

function test.run( group, params )
   group = group or display.currentStage
   params = params or {}

   -- Run tests
   bag1(group)

   bag2(group)   

end


-- ==========================================================
-- === Shuffle Bag Example 1
-- ==========================================================
bag1 = function( group )  

    local cardGroup = display.newGroup()
    group:insert( cardGroup )

   local cards = shuffleBag.new( "jack.png", "king.png", "queen.png", "ace.png" )

   cards:shuffle()

   local function showCards( button )
      display.remove(cardGroup)
      cardGroup = display.newGroup()
      group:insert( cardGroup )

      for i = 1, 4 do
         local file = cards:get()         
         local card = display.newImageRect( cardGroup, "images/kenney/" .. file, 140, 190 )
         card.x = button.x + 160 * i
         card.y = button.y
      end
   end

   --
   -- Basic button to 'run' showCards() when touched.
   --   
   local function onDeal( event )
    showCards( event.target )
   end
   easyIFC:presetPush( group, "default", 
                       left + 75, centerY - 110, 100, 40, 
                       "Deal", onDeal, { strokeWidth = 3 } )
end


-- ==========================================================
-- === Shuffle Bag Example 2 - Insert +  Auto Reshuffle
-- ==========================================================
bag2 = function( group )  

    local cardGroup = display.newGroup()
    group:insert( cardGroup )

   local cards = shuffleBag.new()

   cards:insert( "jack.png" )
   cards:insert( "king.png" )
   cards:insert( "queen.png" )
   cards:insert( "ace.png" )

   cards:shuffle()

   local group = display.newGroup()

   local function showCards( button )
      display.remove(cardGroup)
      cardGroup = display.newGroup()
      group:insert( cardGroup )

      for i = 1, 5 do
         local file = cards:get()         
         local card = display.newImageRect( cardGroup, "images/kenney/" .. file, 140, 190 )
         card.x = button.x + 160 * i
         card.y = button.y
      end
   end

   --
   -- Basic button to 'run' showCards() when touched.
   --   
   local function onDeal( event )
    showCards( event.target )
   end
   easyIFC:presetPush( group, "default", 
                       left + 75, centerY + 110, 100, 40, 
                       "Deal", onDeal, { strokeWidth = 3 } )
end

return test