added "return mini card" function and prelude detection

src/accessories/CleanUpHelper.ttslua

@@ -6,6 +6,7 @@
 local blessCurseManagerApi      = require("chaosbag/BlessCurseManagerApi")
 local chaosBagApi               = require("chaosbag/ChaosBagApi")
 local guidReferenceApi          = require("core/GUIDReferenceApi")
+local mythosAreaApi             = require("core/MythosAreaApi")
 local playAreaApi               = require("core/PlayAreaApi")
 local playmatApi                = require("playermat/PlaymatApi")
 local searchLib                 = require("util/SearchLib")
@@ -27,6 +28,12 @@ options["importTrauma"]         = true
 options["tidyPlayermats"]       = true
 options["removeDrawnLines"]     = false
 
+-- don't clean playmats for preludes
+local scenarioName
+local preludeList = {
+  ["Prelude: Welcome to Hemlock Vale!"] = true
+}
+
 local buttonParameters          = {}
 buttonParameters.function_owner = self
 
@@ -109,6 +116,7 @@ function cleanUp(_, color)
   printToAll("Clean up started!", "Orange")
   printToAll("Resetting counters...", "White")
 
+  getScenarioName()
   soundCubeApi.playSoundByName("Vacuum")
   ignoreCustomDataHelper()
   getTrauma()
@@ -119,6 +127,7 @@ function cleanUp(_, color)
   resetDoomCounter()
   blessCurseManagerApi.removeAll(color)
   removeLines()
+  returnMiniCards()
   discardHands()
   chaosBagApi.returnChaosTokens()
   chaosBagApi.releaseAllSealedTokens(color)
@@ -132,8 +141,13 @@ end
 -- modular functions, called by other functions
 ---------------------------------------------------------
 
+function getScenarioName()
+  local tokenData = mythosAreaApi.returnTokenData()
+  scenarioName = tokenData.currentScenario
+end
+
 function updateCounters()
-  if not options["tidyPlayermats"] then return end
+  if not getOptionValue() then return end
 
   playmatApi.updateCounter("All", "ResourceCounter", 5)
   playmatApi.updateCounter("All", "ClickableClueCounter", 0)
@@ -228,9 +242,33 @@ function removeLines()
   end
 end
 
+-- returns the mini cards back to the owning mat
+function returnMiniCards()
+  -- stop if playermats get tidied anyway
+  if getOptionValue() then return end
+
+  -- get mini cards in play
+  local miniCardIndex = {}
+  for _, obj in ipairs(getObjectsWithTag("Minicard")) do
+    local notes = JSON.decode(obj.getGMNotes())
+    if notes ~= nil and notes.id then
+      miniCardIndex[notes.id] = obj
+    end
+  end
+
+  -- move mini cards
+  for _, mat in pairs(guidReferenceApi.getObjectsByType("Playermat")) do
+    local miniId = mat.getVar("activeInvestigatorId") .. "-m"
+    if miniCardIndex[miniId] then
+      local pos = mat.positionToWorld(Vector(-1.36, 0, -0.625)):setAt("y", 1.67)
+      miniCardIndex[miniId].setPosition(pos)
+    end
+  end
+end
+
 -- discard all hand objects
 function discardHands()
-  if not options["tidyPlayermats"] then return end
+  if not getOptionValue() then return end
   for i = 1, 4 do
     local trash = guidReferenceApi.getObjectByOwnerAndType(COLORS[i], "Trash")
     if trash == nil then return end
@@ -255,6 +293,11 @@ end
 
 -- clean up for play area
 function tidyPlayareaCoroutine()
+  -- small wait to allow other operations to finish
+  for k = 1, 10 do
+    coroutine.yield(0)
+  end
+
   local trash = guidReferenceApi.getObjectByOwnerAndType("Mythos", "Trash")
   local playAreaZone = guidReferenceApi.getObjectByOwnerAndType("Mythos", "PlayAreaZone")
 
@@ -288,7 +331,7 @@ function tidyPlayerMatCoroutine()
 
   for i = 1, 5 do
     -- only continue for playermat (1-4) if option enabled
-    if options["tidyPlayermats"] or i == 5 then
+    if getOptionValue() or i == 5 then
       -- delay for animation purpose
       for k = 1, 30 do
         coroutine.yield(0)
@@ -387,3 +430,13 @@ function getTekeliliHelper()
     end
   end
 end
+
+-- get value with respect to override value
+function getOptionValue()
+  -- don't clean up playermats if playing a prelude from the list
+  if preludeList[scenarioName] then
+    return false
+  else
+    return options["tidyPlayermats"]
+  end
+end

src/core/MythosAreaApi.ttslua

@@ -10,13 +10,13 @@ do
   MythosAreaApi.returnTokenData = function()
     return getMythosArea().call("returnTokenData")
   end
-  
+
   ---@return any: Object reference to the encounter deck
   MythosAreaApi.getEncounterDeck = function()
     return getMythosArea().call("getEncounterDeck")
   end
 
-  -- draw an encounter card for the requesting mat to the first empty spot from the right 
+  -- draw an encounter card for the requesting mat to the first empty spot from the right
   ---@param matColor string Playermat that triggered this
   ---@param position tts__Vector Position for the encounter card
   MythosAreaApi.drawEncounterCard = function(matColor, position)
@@ -27,6 +27,6 @@ do
   MythosAreaApi.reshuffleEncounterDeck = function()
     getMythosArea().call("reshuffleEncounterDeck")
   end
-  
+
   return MythosAreaApi
 end