added comments to redraw library

src/chaosbag/BlessCurseManagerApi.ttslua

@@ -56,13 +56,13 @@ do
   end
   
   -- adds bless / curse to the chaos bag
-  -- @param type string Type of chaos token ("Bless" or "Curse")
+  ---@param type string Type of chaos token ("Bless" or "Curse")
   BlessCurseManagerApi.addToken = function(type)
     getManager().call("addToken", type)
   end
 
   -- removes bless / curse from the chaos bag
-  -- @param type string Type of chaos token ("Bless" or "Curse")
+  ---@param type string Type of chaos token ("Bless" or "Curse")
   BlessCurseManagerApi.removeToken = function(type)
     getManager().call("removeToken", type)
   end

src/chaosbag/ChaosBagApi.ttslua

@@ -72,7 +72,7 @@ do
   ---@param tokenType? string Name of token (e.g. "Bless") to be drawn from the bag
   ---@param guidToBeResolved? string GUID of the sealed token to be resolved instead of drawing a token from the bag
   ---@param takeParameters? table Position and rotation of the location where the new token should be drawn to, usually to replace a returned token
-  ChaosBagApi.drawChaosToken = function(mat, drawAdditional, tokenType, guidToBeResolved, returnedToken)
+  ChaosBagApi.drawChaosToken = function(mat, drawAdditional, tokenType, guidToBeResolved)
     return Global.call("drawChaosToken", {mat = mat, drawAdditional = drawAdditional, tokenType = tokenType, guidToBeResolved = guidToBeResolved, takeParameters = takeParameters})
   end
 

src/core/Global.ttslua

@@ -370,6 +370,7 @@ function makeButtonsToRedraw()
   end
 end
 
+-- returns a chaos token to the chaos bag and redraws another, always called by an XML button through makeButtonsToRedraw() above 
 function returnAndRedraw(_, tokenGUID)
   local takeParameters = {}
   local returnedToken = getObjectFromGUID(tokenGUID)
@@ -388,11 +389,11 @@ function returnAndRedraw(_, tokenGUID)
   end
 
   returnChaosTokenToBag(returnedToken)
-  if redrawData.redrawnTokenType == "random" then
+  local params = { mat = mat,  drawAdditional = true,  takeParameters = takeParameters }
-    chaosTokens[indexOfReturnedToken] = drawChaosToken({mat = mat, drawAdditional = true, takeParameters = takeParameters})
+  if redrawData.redrawnTokenType ~= "random" then
-  else
+    params.tokenType = redrawData.redrawnTokenType
-    chaosTokens[indexOfReturnedToken] = drawChaosToken({mat = mat, drawAdditional = true, takeParameters = takeParameters, tokenType = redrawData.redrawnTokenType})
   end
+  chaosTokens[indexOfReturnedToken] = drawChaosToken(params)
   
   chaosTokens[indexOfReturnedToken] = token
   if redrawData.triggeringCard == "FalseCovenant" then
@@ -506,6 +507,7 @@ function drawChaosToken(params)
       return token
     else
       table.insert(chaosTokens, token)
+      return token
     end
   else
     returnChaosTokens()

src/playercards/CardsThatRedrawTokens.ttslua

@@ -1,3 +1,62 @@
+--[[ Library for cards that return and redraw tokens
+This file is used to add an XML button to a card, turned on via context menu.
+Valid options modify the appearance of the XML button, as well as the
+behavior of the return and redraw function. Set options before requiring this file.
+
+originParams{}   --@type table
+  - includes parameters for the return and redraw functions. Typically set VALID_TOKENS
+    or INVALID_TOKENS, not both. If there are no restrictions on which tokens can be redrawn
+    (e.g. Wendy Adams), do not include either parameter.
+  * VALID_TOKENS --@type table
+    - keyed table which lists all tokens that can be redrawn by the card
+    - example usage: "False Covenant"
+    > VALID_TOKENS = {
+    >   ["Curse"]       = true
+    > }
+  
+  * INVALID_TOKENS  --@type table
+    - keyed table which lists all tokens that cannot be redrawn by the card
+    - example usage: "Custom Ammunition"
+    > INVALID_TOKENS = {
+    >   ["Auto-fail"]       = true
+    > }
+
+  * redrawnTokenType --@type string ("random" or name of token)
+    - determines which kind of token is drawn from the bag. Typically "random"
+      but could be a set token name (e.g. Nkosi Mabati)
+
+  * triggeringCard --@type string (name of card button is on)
+    - allows for the name of the card to be passed onto Global for any special handling
+
+The following parameters modify the appearence of the XML button and are not listed as part of a table.
+ - buttonHeight (default is 450)
+ - buttonWidth  (default is 1400)
+ - buttonPosition (default is "0 -55 -22")
+ - buttonFontSize (default is 250)
+ - buttonRotation (change if button is placed on an investigator cards)
+ - buttonValue (to change the label of the button, default is "Redraw Token")
+ - buttonIcon (to add an icon to the right)
+ - buttonColor (default is "#77674DE6")
+
+----------------------------------------------------------
+EXAMPLE: Claypool's Furs
+This card can only redraw the Frost token, and is replaced with a random token from the bag.
+As a nice reminder the XML button takes on the Frost color and icon with the text "Cancel".
+> buttonValue = "Cancel"
+> buttonIcon = "token-frost"
+> buttonColor = "#404450E6"
+> buttonFontSize = 300
+
+> originParams = {
+>   triggeringCard = "ClaypoolsFurs",
+>   redrawnTokenType = "random",
+>   VALID_TOKENS = {
+>     ["Frost"] = true
+>   }
+> }
+
+require("playercards/CardsThatRedrawTokens")
+----------------------------------------------------------]]
 local turnOnHelper
 
 function onSave()