diff --git a/src/core/Global.ttslua b/src/core/Global.ttslua
index 48816685..0baf0e9d 100644
--- a/src/core/Global.ttslua
+++ b/src/core/Global.ttslua
@@ -1164,6 +1164,7 @@ function onClick_toggleUi(player, windowId)
   changeWindowVisibilityForColor(player.color, windowId)
 end
 
+-- wrapper for the real function to unpack arguments
 function changeWindowVisibilityForColorWrapper(params)
   changeWindowVisibilityForColor(params.color, params.windowId, params.overrideState, params.owner)
 end
diff --git a/src/core/GlobalApi.ttslua b/src/core/GlobalApi.ttslua
index 77145235..d19235d0 100644
--- a/src/core/GlobalApi.ttslua
+++ b/src/core/GlobalApi.ttslua
@@ -1,6 +1,10 @@
 do
   local GlobalApi = {}
 
+  -- downloads an object from the library and optionally replaces an existing object
+  ---@param url string Path to JSON file (without .json extension) in the library
+  ---@param player tts__Player Player that initiated this
+  ---@param replace string GUID of the object to replace
   function GlobalApi.placeholderDownload(url, player, replace)
     Global.call("placeholder_download", {
       url = url,
@@ -9,29 +13,41 @@ do
     })
   end
 
+  -- splashes the scenario title (used when placing a scenario) and plays a sound
+  ---@param scenarioName string Name of the scenario
   function GlobalApi.titleSplash(scenarioName)
     Global.call("titleSplash", scenarioName)
   end
 
-  function GlobalApi.changeWindowVisibility(playerColor, windowId, owner)
+  -- toggles the visibility of the specific window for the specified color
+  ---@param playerColor string Player color to toggle the visibility for
+  ---@param windowId string ID of the XML element
+  ---@param overrideState? boolean Forcefully sets the new visibility
+  ---@param owner? tts__Object Object that owns the XML (or nil if Global)
+  ---@return boolean visible Returns the new state of the visibility
+  function GlobalApi.changeWindowVisibility(playerColor, windowId, overrideState, owner)
     Global.call("changeWindowVisibilityForColorWrapper", {
       color = playerColor,
       windowId = windowId,
+      overrideState = overrideState,
       owner = owner
     })
   end
 
-  function GlobalApi.updateGlobalXml(globalXml)
-    Global.call("updateGlobalXml", globalXml)
+  -- this helper function updates the global XML while preserving the visibility of windows
+  ---@param newXml table Complete new XmlTable for the Global UI
+  function GlobalApi.updateGlobalXml(newXml)
+    Global.call("updateGlobalXml", newXml)
   end
 
   -- loads saved options
   ---@param options table Set a new state for the option table
   function GlobalApi.loadOptionPanelSettings(options)
-    return Global.call("loadSettings", options)
+    Global.call("loadSettings", options)
   end
 
-  ---@return any: Table of option panel state
+  -- gets the current state of the option panel
+  ---@return table: option panel state
   function GlobalApi.getOptionPanelState()
     return Global.getTable("optionPanel")
   end
diff --git a/src/playermat/Playermat.ttslua b/src/playermat/Playermat.ttslua
index 34fc7e88..fb2b3b72 100644
--- a/src/playermat/Playermat.ttslua
+++ b/src/playermat/Playermat.ttslua
@@ -917,7 +917,7 @@ function createXML()
 end
 
 function onClick_hideOrShowOptions(player)
-  GlobalApi.changeWindowVisibility(player.color, "optionPanelMain", self)
+  GlobalApi.changeWindowVisibility(player.color, "optionPanelMain", _, self)
 end
 
 function onClick_textureSelect(player)
@@ -947,8 +947,8 @@ function onClick_handColorSelect(player)
     handZone.setValue(newColor)
 
     -- update visibility for old and new color
-    GlobalApi.changeWindowVisibility(playerColor, "optionPanelMain", self)
-    GlobalApi.changeWindowVisibility(newColor, "optionPanelMain", self)
+    GlobalApi.changeWindowVisibility(playerColor, "optionPanelMain", _, self)
+    GlobalApi.changeWindowVisibility(newColor, "optionPanelMain", _, self)
     navigationOverlayApi.copyVisibility(playerColor, newColor)
 
     -- if there was a seated player, reseat to the new color