merge

src/playermat/PlayermatApi.ttslua

@@ -0,0 +1,356 @@
+do
+  local PlayermatApi = {}
+  local guidReferenceApi = require("core/GUIDReferenceApi")
+  local searchLib = require("util/SearchLib")
+  local localInvestigatorPosition = { x = -1.17, y = 1, z = -0.01 }
+
+  -- Convenience function to look up a mat's object by color, or get all mats.
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  ---@return table: Single-element if only single playermat is requested
+  local function getMatForColor(matColor)
+    if matColor == "All" then
+      return guidReferenceApi.getObjectsByType("Playermat")
+    else
+      return { matColor = guidReferenceApi.getObjectByOwnerAndType(matColor, "Playermat") }
+    end
+  end
+
+  -- Returns the color of the closest playermat
+  ---@param startPos table Starting position to get the closest mat from
+  PlayermatApi.getMatColorByPosition = function(startPos)
+    local result, smallestDistance
+    for matColor, mat in pairs(getMatForColor("All")) do
+      local distance = Vector.between(startPos, mat.getPosition()):magnitude()
+      if smallestDistance == nil or distance < smallestDistance then
+        smallestDistance = distance
+        result = matColor
+      end
+    end
+    return result
+  end
+
+  -- Returns the color of the player's hand that is seated next to the playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.getPlayerColor = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.getVar("playerColor")
+    end
+  end
+
+  -- Returns the color of the playermat that owns the playercolor's hand
+  ---@param handColor string Color of the playermat
+  PlayermatApi.getMatColor = function(handColor)
+    for matColor, mat in pairs(getMatForColor("All")) do
+      local playerColor = mat.getVar("playerColor")
+      if playerColor == handColor then
+        return matColor
+      end
+    end
+  end
+
+  -- Instructs a playermat to check for DES
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.checkForDES = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("checkForDES")
+    end
+  end
+
+  -- Returns if there is the card "Dream-Enhancing Serum" on the requested playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  ---@return boolean: whether DES is present on the playermat
+  PlayermatApi.hasDES = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.getVar("hasDES")
+    end
+  end
+
+  -- gets the slot data for the playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.getSlotData = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.getTable("slotData")
+    end
+  end
+
+  -- sets the slot data for the playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  ---@param newSlotData table New slot data for the playermat
+  PlayermatApi.loadSlotData = function(matColor, newSlotData)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.setTable("slotData", newSlotData)
+      mat.call("redrawSlotSymbols")
+      return
+    end
+  end
+
+  -- Performs a search of the deck area of the requested playermat and returns the result as table
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.getDeckAreaObjects = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.call("getDeckAreaObjects")
+    end
+  end
+
+  -- Flips the top card of the deck (useful after deck manipulation for Norman Withers)
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.flipTopCardFromDeck = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.call("flipTopCardFromDeck")
+    end
+  end
+
+  -- Returns the position of the discard pile of the requested playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.getDiscardPosition = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.call("returnGlobalDiscardPosition")
+    end
+  end
+
+  -- Returns the position of the draw pile of the requested playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.getDrawPosition = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.call("returnGlobalDrawPosition")
+    end
+  end
+
+  -- Transforms a local position into a global position
+  ---@param localPos table Local position to be transformed
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.transformLocalPosition = function(localPos, matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.positionToWorld(localPos)
+    end
+  end
+
+  -- Returns the rotation of the requested playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.returnRotation = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.getRotation()
+    end
+  end
+
+  -- Returns a table with spawn data (position and rotation) for a helper object
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  ---@param helperName string Name of the helper object
+  PlayermatApi.getHelperSpawnData = function(matColor, helperName)
+    local resultTable = {}
+    local localPositionTable = {
+      ["Hand Helper"] = {0.05, 0, -1.182},
+      ["Search Assistant"] = {-0.3, 0, -1.182}
+    }
+    
+    for color, mat in pairs(getMatForColor(matColor)) do
+      resultTable[color] = {
+        position = mat.positionToWorld(localPositionTable[helperName]),
+        rotation = mat.getRotation()
+      }
+    end
+    return resultTable
+  end
+
+
+  -- Triggers the Upkeep for the requested playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  ---@param playerColor string Color of the calling player (for messages)
+  PlayermatApi.doUpkeepFromHotkey = function(matColor, playerColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("doUpkeepFromHotkey", playerColor)
+    end
+  end
+
+  -- Handles discarding for the requested playermat for the provided list of objects
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  ---@param objList table List of objects to discard
+  PlayermatApi.discardListOfObjects = function(matColor, objList)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("discardListOfObjects", objList)
+    end
+  end
+
+  -- Returns the active investigator id
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.returnInvestigatorId = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.getVar("activeInvestigatorId")
+    end
+  end
+
+  -- Returns the class of the active investigator
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.returnInvestigatorClass = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.getVar("activeInvestigatorClass")
+    end
+  end
+
+  -- Returns the position for encounter card drawing
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  ---@param stack boolean If true, returns the leftmost position instead of the first empty from the right
+  PlayermatApi.getEncounterCardDrawPosition = function(matColor, stack)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return Vector(mat.call("getEncounterCardDrawPosition", stack))
+    end
+  end
+
+  -- Sets the requested playermat's snap points to limit snapping to matching card types or not.  If
+  -- matchTypes is true, the main card slot snap points will only snap assets, while the
+  -- investigator area point will only snap Investigators.  If matchTypes is false, snap points will
+  -- be reset to snap all cards.
+  ---@param matchCardTypes boolean Whether snap points should only snap for the matching card types
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.setLimitSnapsByType = function(matchCardTypes, matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("setLimitSnapsByType", matchCardTypes)
+    end
+  end
+
+  -- Sets the requested playermat's draw 1 button to visible
+  ---@param isDrawButtonVisible boolean Whether the draw 1 button should be visible or not
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.showDrawButton = function(isDrawButtonVisible, matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("showDrawButton", isDrawButtonVisible)
+    end
+  end
+
+  -- Shows or hides the clickable clue counter for the requested playermat
+  ---@param showCounter boolean Whether the clickable counter should be present or not
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.clickableClues = function(showCounter, matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("clickableClues", showCounter)
+    end
+  end
+
+  -- Toggles the use of class textures for the requested playermat
+  ---@param state boolean Whether the class texture should be used or not
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.useClassTexture = function(state, matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("useClassTexture", state)
+    end
+  end
+
+  -- Removes all clues (to the trash for tokens and counters set to 0) for the requested playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.removeClues = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("removeClues")
+    end
+  end
+
+  -- Reports the clue count for the requested playermat
+  ---@param useClickableCounters boolean Controls which type of counter is getting checked
+  PlayermatApi.getClueCount = function(useClickableCounters, matColor)
+    local count = 0
+    for _, mat in pairs(getMatForColor(matColor)) do
+      count = count + mat.call("getClueCount", useClickableCounters)
+    end
+    return count
+  end
+
+  -- Updates the specified owned counter
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  ---@param type string Counter to target
+  ---@param newValue number Value to set the counter to
+  ---@param modifier number If newValue is not provided, the existing value will be adjusted by this modifier
+  PlayermatApi.updateCounter = function(matColor, type, newValue, modifier)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("updateCounter", { type = type, newValue = newValue, modifier = modifier })
+    end
+  end
+
+  -- Triggers the draw function for the specified playermat
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  ---@param number number Amount of cards to draw
+  PlayermatApi.drawCardsWithReshuffle = function(matColor, number)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("drawCardsWithReshuffle", number)
+    end
+  end
+
+  -- Returns the resource counter amount
+  ---@param matColor string Color of the playermat - White, Orange, Green or Red (does not support "All")
+  ---@param type string Counter to target
+  PlayermatApi.getCounterValue = function(matColor, type)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      return mat.call("getCounterValue", type)
+    end
+  end
+
+  -- Returns a list of mat colors that have an investigator placed
+  PlayermatApi.getUsedMatColors = function()
+    local usedColors = {}
+    for matColor, mat in pairs(getMatForColor("All")) do
+      local searchPos = mat.positionToWorld(localInvestigatorPosition)
+      local searchResult = searchLib.atPosition(searchPos, "isCardOrDeck")
+      if #searchResult > 0 then
+        table.insert(usedColors, matColor)
+      end
+    end
+    return usedColors
+  end
+
+  -- Returns investigator name
+  ---@param matColor string Color of the playmat - White, Orange, Green or Red (does not support "All")
+  PlayermatApi.getInvestigatorName = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      local searchPos = mat.positionToWorld(localInvestigatorPosition)
+      local searchResult = searchLib.atPosition(searchPos, "isCardOrDeck")
+      if #searchResult == 1 then
+        return searchResult[1].getName()
+      end
+    end
+    return ""
+  end
+
+  -- Resets the specified skill tracker to "1, 1, 1, 1"
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.resetSkillTracker = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("resetSkillTracker")
+    end
+  end
+
+  -- Redraws the XML for the slot symbols based on the slotData table
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.redrawSlotSymbols = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("redrawSlotSymbols")
+    end
+  end
+
+  -- Finds all objects on the playermat and associated set aside zone and returns a table
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  ---@param filter string Name of the filte function (see util/SearchLib)
+  PlayermatApi.searchAroundPlayermat = function(matColor, filter)
+    local objList = {}
+    for _, mat in pairs(getMatForColor(matColor)) do
+      for _, obj in ipairs(mat.call("searchAroundSelf", filter)) do
+        table.insert(objList, obj)
+      end
+    end
+    return objList
+  end
+
+  -- Discard a non-hidden card from the corresponding player's hand
+  ---@param matColor string Color of the playermat - White, Orange, Green, Red or All
+  PlayermatApi.doDiscardOne = function(matColor)
+    for _, mat in pairs(getMatForColor(matColor)) do
+      mat.call("doDiscardOne")
+    end
+  end
+
+  -- Triggers the metadata sync for all playermats
+  PlayermatApi.syncAllCustomizableCards = function()
+    for _, mat in pairs(getMatForColor("All")) do
+      mat.call("syncAllCustomizableCards")
+    end
+  end
+
+  return PlayermatApi
+end