adding documentation

src/chaosbag/BlessCurseManager.ttslua

@@ -105,14 +105,14 @@ function initializeState()
 end
 
 function broadcastCount(token)
-    local count = getTokenCount(token)
+    local count = formatTokenCount(token)
     if count == "(0/0)" then return end
     broadcastToAll(token .. " Tokens " .. count, "White")
 end
 
 function printStatus(color)
-    broadcastToColor("Curse Tokens " .. getTokenCount("Curse"), color, "White")
+    broadcastToColor("Curse Tokens " .. formatTokenCount("Curse"), color, "White")
-    broadcastToColor("Bless Tokens " .. getTokenCount("Bless"), color, "White")
+    broadcastToColor("Bless Tokens " .. formatTokenCount("Bless"), color, "White")
 end
 
 -- context menu function 1
@@ -244,7 +244,8 @@ function callFunctions(token, isRightClick)
     if success ~= 0 then tokenArrangerApi.layout() end
 end
 
-function getTokenCount(type)
+-- returns a formatted string with information about the provided token type (bless / curse)
+function formatTokenCount(type)
     if type == nil then type = mode end
     return "(" .. (numInPlay[type] - #tokensTaken[type]) .. "/" .. #tokensTaken[type] .. ")"
 end
@@ -284,7 +285,7 @@ function addToken(type)
         return 0
     end
     numInPlay[type] = numInPlay[type] + 1
-    printToAll("Adding " .. type .. " token " .. getTokenCount(type))
+    printToAll("Adding " .. type .. " token " .. formatTokenCount(type))
     return Global.call("spawnChaosToken", type)
 end
 
@@ -313,11 +314,11 @@ function takeToken(type, remove)
         callback_function = function(obj)
             if remove then
                 numInPlay[type] = numInPlay[type] - 1
-                printToAll("Removing " .. type .. " token " .. getTokenCount(type))
+                printToAll("Removing " .. type .. " token " .. formatTokenCount(type))
                 obj.destruct()
             else
                 table.insert(tokensTaken[type], obj.getGUID())
-                printToAll("Taking " .. type .. " token " .. getTokenCount(type))
+                printToAll("Taking " .. type .. " token " .. formatTokenCount(type))
             end
         end
     })
@@ -339,7 +340,7 @@ function returnToken(type)
         return 0
     end
     chaosbag.putObject(token)
-    printToAll("Returning " .. type .. " token " .. getTokenCount(type))
+    printToAll("Returning " .. type .. " token " .. formatTokenCount(type))
 end
 
 ---------------------------------------------------------
@@ -393,7 +394,7 @@ function sealToken(type, playerColor, enemy)
                     Wait.frames(function()
                         table.insert(sealedTokens[enemy.getGUID()], obj)
                         table.insert(tokensTaken[type], obj.getGUID())
-                        printToColor("Sealing " .. type .. " token " .. getTokenCount(type), playerColor)
+                        printToColor("Sealing " .. type .. " token " .. formatTokenCount(type), playerColor)
                     end, 1)
                 end
             })
@@ -417,7 +418,7 @@ function releaseToken(type, playerColor, enemy)
                 if v == guid then
                     table.remove(tokensTaken[type], j)
                     table.remove(tokens, i)
-                    printToColor("Releasing " .. type .. " token" .. getTokenCount(type), playerColor)
+                    printToColor("Releasing " .. type .. " token" .. formatTokenCount(type), playerColor)
                     return
                 end
             end

src/playercards/CardsThatSealTokens.ttslua

@@ -1,14 +1,75 @@
 --[[ Library for cards that seal tokens
 This file is used to add sealing option to cards' context menu.
 Valid options (set before requiring this file):
-SHOW_READ_BAG       -- boolean
+
-SHOW_SINGLE_RELEASE -- boolean
+SHOW_READ_BAG       --@type: boolean
-SHOW_MULTI_RELEASE  -- number (amount of tokens to release at once)
+  - enables an entry in the context menu
-VALID_TOKENS        -- table ([tokenName] = true)
+  - the "Read Bag" function reads the content of the chaos bag to update the context menu
-INVALID_TOKENS      -- table ([tokenName] = true)]]
+  - example usage: "Unrelenting" (to only display valid tokens)
+
+SHOW_SINGLE_RELEASE --@type: boolean
+  - enables an entry in the context menu
+  - this entry allows releasing a single token
+  - example usage: "Holy Spear" (to keep the other tokens and just release one)
+
+SHOW_MULTI_RELEASE  --@type: number (amount of tokens to release at once)
+  - enables an entry in the context menu
+  - this enty allows releasing of multiple tokens at once
+  - example usage: "Nephthys" (to release 3 bless tokens at once)
+
+SHOW_MULTI_SEAL     --@type: number (amount of tokens to seal at once)
+  - enables an entry in the context menu
+  - this entry allows sealing of multiple tokens at once
+  - example usage: "Holy Spear" (to seal two bless tokens at once)
+
+VALID_TOKENS        --@type: table ([tokenName] = true)
+  - this table defines which tokens should be abled to be sealed
+  - needs to be defined for each card -> even if empty
+  - example usage: "The Chthonian Stone"
+    > VALID_TOKENS = {
+    >   ["Skull"]       = true,
+    >   ["Cultist"]     = true,
+    >   ["Tablet"]      = true,
+    >   ["Elder Thing"] = true,
+    > }
+
+INVALID_TOKENS      --@type: table ([tokenName] = true)
+  - this table defines which tokens are invalid for sealing
+  - only needs to be defined if needed
+  - usually combined with empty "VALID_TOKENS" table
+  - example usage: "Protective Incantation" (not allowed to seal Auto-fail)
+
+----------------------------------------------------------
+Example 1: Crystalline Elder Sign
+This card can only seal the "+1" or "Elder Sign" token,
+it does not need specific options for multi-sealing or releasing.
+Thus it should be implemented like this:
+
+> VALID_TOKENS = {
+>   ["+1"] = true,
+>   ["Elder Sign"] = true
+> }
+> require("playercards/CardsThatSealTokens")
+----------------------------------------------------------
+Example 2: Holy Spear
+This card features the following abilities (just listing the relevant parts):
+- releasing a single bless token
+- sealing two bless tokens
+Thus it should be implemented like this:
+
+> VALID_TOKENS = {
+>   ["Bless"] = true
+> }
+> SHOW_SINGLE_RELEASE = true
+> SHOW_MULTI_SEAL = 2
+> require("playercards/CardsThatSealTokens")
+----------------------------------------------------------]]
 
 local blessCurseManagerApi = require("chaosbag/BlessCurseManagerApi")
 local tokenArrangerApi = require("accessories/TokenArrangerApi")
+local sealedTokens = {}
+local ID_URL_MAP = {}
+tokensInBag = {}
 
 function onSave() return JSON.encode(sealedTokens) end
 
@@ -32,17 +93,9 @@ function generateContextMenu()
   if SHOW_SINGLE_RELEASE then
     self.addContextMenuItem("Release token", releaseOneToken)
   elseif SHOW_MULTI_RELEASE then
-    self.addContextMenuItem("Release " .. SHOW_MULTI_RELEASE .. " token(s)", function(playerColor)
+    self.addContextMenuItem("Release " .. SHOW_MULTI_RELEASE .. " token(s)", releaseMultipleTokens)
-      if SHOW_MULTI_RELEASE >= #sealedTokens then
-        for i = 1, SHOW_MULTI_RELEASE do
-          releaseOneToken(playerColor)
-        end
   else
-        printToColor("Not enough " .. name .. " tokens sealed.", playerColor)
+    self.addContextMenuItem("Release token(s)", releaseAllTokens)
-      end
-    end)
-  else
-    self.addContextMenuItem("Release token(s)", releaseTokens)
   end
 
   -- main context menu options to seal tokens
@@ -117,7 +170,7 @@ end
 -- release the last sealed token
 function releaseOneToken(playerColor)
   if not Global.call("canTouchChaosTokens") then return end
-  if sealedTokens == {} or #sealedTokens == 0 then
+  if #sealedTokens == 0 then
     printToColor("No sealed token(s) found", playerColor)
   else
     printToColor("Releasing token", playerColor)
@@ -125,8 +178,18 @@ function releaseOneToken(playerColor)
   end
 end
 
+-- release multiple tokens at once
+function releaseMultipleTokens(playerColor)
+  if SHOW_MULTI_RELEASE >= #sealedTokens then
+    for i = 1, SHOW_MULTI_RELEASE do
+      releaseOneToken(playerColor)
+    end
+  else
+    printToColor("Not enough " .. name .. " tokens sealed.", playerColor)
+  end
+end
 -- releases all sealed tokens
-function releaseTokens(playerColor)
+function releaseAllTokens(playerColor)
   if not Global.call("canTouchChaosTokens") then return end
   if #sealedTokens == 0 then
     printToColor("No sealed token(s) found", playerColor)