Update PSC (#499)

* Update personal star counter mod

Decided to modernize this mod by making it more efficient and readable. Added a ton of comments to make it much easier to understand what's going on here.

* Rename mod

* Rename mod just a bit more

mods/personal-starcount-ex.lua

@@ -1,279 +1,339 @@
--- name: Personal Star Counter EX+
+-- name: Personal Star Counter
 -- description: See how many stars you've collected!\n\nCredits:\n\\#097419\\Mr.Needlemouse\\#FFFFFF\\ - Concept\nSunk\\#dcdcdc\\ - Creator\n\\#269A91\\Demnyx\\#dcdcdc\\ - Assistance\n\\#f296af\\PeachyPeach\\#dcdcdc\\ - Global functions
 -- incompatible: gamemode arena
 
-for i = 0, (MAX_PLAYERS - 1) do
+------------------------------
+----- Localize functions -----
+------------------------------
+-- This looks strange but it makes the mod more performant
+local tonumber, mod_storage_load, mod_storage_save, tostring, djui_hud_is_pause_menu_created, djui_hud_set_color, hud_get_value, djui_hud_print_text, djui_hud_render_texture, obj_get_first_with_behavior_id, djui_hud_set_resolution, djui_hud_set_font, djui_hud_get_screen_height, djui_hud_get_screen_width, djui_hud_set_render_behind_hud, hud_set_value, network_player_set_description, djui_popup_create = 
+    tonumber, mod_storage_load, mod_storage_save, tostring, djui_hud_is_pause_menu_created, djui_hud_set_color, hud_get_value, djui_hud_print_text, djui_hud_render_texture, obj_get_first_with_behavior_id, djui_hud_set_resolution, djui_hud_set_font, djui_hud_get_screen_height, djui_hud_get_screen_width, djui_hud_set_render_behind_hud, hud_set_value, network_player_set_description, djui_popup_create
+------------------------------
+
+-- Initialize a value for the psc for everyone
+for i = 0, MAX_PLAYERS - 1 do
 	gPlayerSyncTable[i].psc = 0
 end
 
-if mod_storage_load("StarCounter") == nil then
+local psc_toggle = true
-	mod_storage_save("StarCounter", "0")
+local has_cheats_enabled = gServerSettings.enableCheats ~= 0
-end
 
-local starCheater = false
+-- If there is no value in storage, default to 0
-local TotalStarCounter = tonumber(mod_storage_load("StarCounter"))
+local TotalStarCounter = tonumber(mod_storage_load("StarCounter")) or 0
-local StarCounter = 0
+local ThisGameStarCounter = 0
 local prevNumStars = 0
-local screenHeight = 0
+
-local screenWidth = 0
-local pscToggle = 1
 local introTimer = 0
 
--- junk --
+-- When in these cutscenes, do special things like hiding or moving the star counters
-cutscenes = {
+local is_in_cutscenes = {
 	[ACT_END_PEACH_CUTSCENE] = true,
 	[ACT_CREDITS_CUTSCENE] = true,
 	[ACT_END_WAVING_CUTSCENE] = true,
 }
 
----@param m MarioState
+--- Whenever a star is collected, increment the other star counters
---Increments an independent counter if a star is collected.
+---@param m MarioState The Mario that does the interaction
-function localStarCounter(m, o, type)
+---@param obj Object The object the Mario interacted with (Unused here)
-	if (m.playerIndex == 0) and (type == INTERACT_STAR_OR_KEY) then
+---@param intType integer The interaction type
-		--This ensures that it increments ONLY if a star is collected.
+---@param interacted boolean If the interaction was successful (Unused here)
-		if get_id_from_behavior(o.behavior) ~= id_bhvBowserKey then
+---@return nil
-			--The hook happens after the star count increments, so this allows the independent counter to increment ONLY when YELLOW star is collected.
+local function star_counter_on_interact(m, obj, intType, interacted)
-			if m.numStars ~= prevNumStars then
+    if not psc_toggle then return end
-				StarCounter = StarCounter + 1
+
-				gPlayerSyncTable[0].psc = StarCounter
+	if m.playerIndex == 0 and intType == INTERACT_STAR_OR_KEY then
-				if starCheater == false then --Only if not cheating
+        -- Interactions happen before hud rendering, which is why this check can work
-					TotalStarCounter = TotalStarCounter + 1
+        -- despite prevNumStars being updated every frame
-					mod_storage_save("StarCounter", tostring(TotalStarCounter))
+        if m.numStars ~= prevNumStars then
-				end
+            ThisGameStarCounter = ThisGameStarCounter + 1 -- Red star counter
-			end
+            -- Disable total star counter if cheats are enabled
-		end
+            if not has_cheats_enabled then
+                TotalStarCounter = TotalStarCounter + 1 -- Green star counter
+                mod_storage_save("StarCounter", tostring(TotalStarCounter)) -- Save to mod storage
+            end
+        end
 	end
 end
 
--- Hud alpha stuff from Agent X
+--- Hud alpha stuff from Agent X
-function djui_hud_set_adjusted_color(r, g, b, a)
+--- Causes the hud to darken when the game is paused
+---@param r number Red
+---@param g number Green
+---@param b number Blue
+---@param a number Alpha (Transparency)
+---@return nil
+local function djui_hud_set_adjusted_color(r, g, b, a)
 	local multiplier = 1
-	if djui_hud_is_pause_menu_created() then multiplier = 0.57 end --Star Display compatibility
+	if djui_hud_is_pause_menu_created() then multiplier = 0.57 end -- Star Display compatibility
 	djui_hud_set_color(r * multiplier, g * multiplier, b * multiplier, a)
 end
 
-local function displayStarCounter()
+--- Sets the star counters onto the hud
-	local m = gMarioStates[0]
+---@param m MarioState Mario
-	if pscToggle == 0 then return end
+---@param height number Screen height (Unused)
-	if obj_get_first_with_behavior_id(id_bhvActSelector) ~= nil then
+---@param width number Screen width
-        return
+---@return nil
-	end
+local function set_hud_star_positions(m, height, width)
+    if introTimer >= 1195 or m.action ~= ACT_INTRO_CUTSCENE then
+        local star_texture = gTextures.star
+        -- Check if the timer is currently active
+        local timer_current_value = hud_get_value(HUD_DISPLAY_TIMER)
 
-    --Make HUD appear when the real one does during the intro
+        -- Offset based on if the timer is active
+        local timer_offset_X = 0
+        local timer_offset_Y = 0
+
+        -- Offset based on if each counter has less than 100 stars
+        local low_stars_offset_X = 0
+        local low_stars_offset_Y = 0
+
+        -- Based off of star texture pos
+        local star_counter_offset_X = 0
+
+        -- Y position, based off of the top of the screen
+        local top_screen_offset_Y = 0
+
+        -------------------------------
+        ----- Yellow star counter -----
+        -------------------------------
+
+        -- Don't display while in a cutscene
+        if not is_in_cutscenes[m.action] then
+            star_counter_offset_X = 76
+            top_screen_offset_Y = 15
+
+            low_stars_offset_X = 14
+
+            offsetX = 14
+            if m.numStars < 100 then
+                djui_hud_set_adjusted_color(246, 246, 246, 255)
+                djui_hud_print_text("@", width - (star_counter_offset_X - 16), top_screen_offset_Y, 1)
+                offsetX = 0
+            end
+            djui_hud_set_adjusted_color(255, 255, 255, 255)
+            djui_hud_print_text(tostring(m.numStars), width - (star_counter_offset_X - 30) - offsetX, top_screen_offset_Y, 1)
+            djui_hud_render_texture(star_texture, width - star_counter_offset_X, top_screen_offset_Y, 1, 1)
+        end
+
+        ----------------------------
+        ----- Red star counter -----
+        ----------------------------
+
+        -- Move HUD graphics away from the TIMER HUD
+        if timer_current_value ~= 0 then
+            timer_offset_X = 60
+            timer_offset_Y = 17
+        end
+
+        star_counter_offset_X = is_in_cutscenes[m.action] and 22 or 76
+        top_screen_offset_Y = is_in_cutscenes[m.action] and 15 or 15 + 17
+
+        low_stars_offset_X = 14
+
+        local left_align = is_in_cutscenes[m.action]
+        -- Render X if this counter has less than 100 stars
+        if ThisGameStarCounter < 100 then
+            djui_hud_set_adjusted_color(246, 246, 246, 255)
+            djui_hud_print_text(
+                "@", -- Text
+                (left_align and (star_counter_offset_X + 16) or -- X pos in cutscenes
+                    (width - (star_counter_offset_X - 16) - timer_offset_X)), -- X pos outside cutscenes
+                top_screen_offset_Y + timer_offset_Y, -- Y pos
+                1) -- Scale
+            low_stars_offset_X = 0
+        end
+        -- Render counter
+        djui_hud_set_adjusted_color(255, 255, 255, 255)
+        djui_hud_print_text(
+            tostring(ThisGameStarCounter), -- Text
+            (left_align and (star_counter_offset_X + 30 - low_stars_offset_X) or -- X pos in cutscenes
+                (width - (star_counter_offset_X - 30) - timer_offset_X - low_stars_offset_X)), -- X pos outside cutscenes
+            top_screen_offset_Y + timer_offset_Y, -- Y pos
+            1) -- Scale
+        djui_hud_set_adjusted_color(232, 17, 35, 255)
+        djui_hud_render_texture(
+            star_texture, -- Texture
+            (left_align and star_counter_offset_X or -- X pos in cutscenes
+                (width - star_counter_offset_X - timer_offset_X)), -- X pos outside cutscenes
+            top_screen_offset_Y + timer_offset_Y, -- Y pos
+            1, 1) -- Scale
+
+        ------------------------------
+        ----- Green star counter -----
+        ------------------------------
+
+        -- Increment a seperate counter if the total star count is over 10000
+        local perceived_total_counter = TotalStarCounter
+        local milestone_counter = 0
+        while perceived_total_counter >= 10000 do
+            perceived_total_counter = perceived_total_counter - 10000
+            milestone_counter = milestone_counter + 1
+        end
+
+        -- Move HUD graphics away from the TIMER HUD
+        if timer_current_value ~= 0 then
+            timer_offset_X = 0
+            timer_offset_Y = -10
+        end
+
+        star_counter_offset_X = 76
+        top_screen_offset_Y = is_in_cutscenes[m.action] and 15 or 15 + 17 * 2
+
+        low_stars_offset_X = 14
+        -- Render X if this counter has less than 100 stars
+        if perceived_total_counter < 100 then
+            djui_hud_set_adjusted_color(246, 246, 246, 255)
+            djui_hud_print_text(
+                "@", -- Text
+                width - (star_counter_offset_X - 16) - timer_offset_X, -- X pos
+                top_screen_offset_Y + timer_offset_Y, -- Y pos
+                1) -- Scale
+            low_stars_offset_X = 0
+        end
+        -- Render counter
+        djui_hud_set_adjusted_color(255, 255, 255, 255)
+        djui_hud_print_text(
+            tostring(perceived_total_counter), -- Text
+            width - (star_counter_offset_X - 30) - timer_offset_X - low_stars_offset_X, -- X pos
+            top_screen_offset_Y + timer_offset_Y, -- Y pos
+            1) -- Scale
+        djui_hud_set_adjusted_color(50, 176, 40, 255)
+        djui_hud_render_texture(
+            star_texture, -- Texture
+            width - star_counter_offset_X - timer_offset_X, -- X pos
+            top_screen_offset_Y + timer_offset_Y, -- Y pos
+            1, 1) -- Scale
+        if milestone_counter ~= 0 then
+            djui_hud_set_adjusted_color(255, 255, 255, 255)
+            djui_hud_print_text(
+                "@" .. milestone_counter, -- Text
+                width - star_counter_offset_X - timer_offset_X, -- X pos
+                (top_screen_offset_Y + 16) + timer_offset_Y, -- Y pos
+                0.5) -- Scale
+        end
+    end
+end
+
+--- Renders star counters onto the screen
+---@return nil
+local function hud_render_psc()
+	if not psc_toggle then return end
+    -- If the act selector is active
+	if obj_get_first_with_behavior_id(id_bhvActSelector) then return end
+
+    -- HOOK_ON_HUD_RENDER doesn't supply a MarioState, so one has to be gotten from this
+    ---@type MarioState
+    local m = gMarioStates[0]
+
+    -- Make HUD appear when the real one does during the intro
     if m.action == ACT_INTRO_CUTSCENE then
-        if introTimer ~= 1195 then
+        if introTimer < 1195 then
             introTimer = introTimer + 1
         end
     end
 
-	djui_hud_set_resolution(RESOLUTION_N64)
+    djui_hud_set_resolution(RESOLUTION_N64)
 	djui_hud_set_font(FONT_HUD)
-    --Draw over credits fades
-    if cutscenes[m.action] ~= true then
-        djui_hud_set_render_behind_hud(true)
-    else
-        djui_hud_set_render_behind_hud(false)
-    end
 
-	--I don't want to put this in a seperate function, there's not enough code for it to be worth it.
+    local screen_height = djui_hud_get_screen_height()
-	if m.playerIndex == 0 then
+	local screen_width = djui_hud_get_screen_width()
-		prevNumStars = m.numStars
+
-	else
+    -- Set prevNumStars
-		return
+    prevNumStars = m.numStars
+    -- Draw over credits fades
+    djui_hud_set_render_behind_hud(not is_in_cutscenes[m.action])
+
+    -- Force the normal star counter to be hidden
+    hud_set_value(HUD_DISPLAY_FLAGS, hud_get_value(HUD_DISPLAY_FLAGS) & ~HUD_DISPLAY_FLAG_STAR_COUNT)
+
+    set_hud_star_positions(m, screen_height, screen_width)
+end
+
+--- Display each person's star counter in the player menu
+---@return nil
+local function psc_update()
+    gPlayerSyncTable[0].psc = ThisGameStarCounter
+	for i = 0, MAX_PLAYERS - 1 do
+		network_player_set_description(gNetworkPlayers[i], "\\#FF0000\\Stars: " .. tostring(gPlayerSyncTable[i].psc), 255, 255, 255, 255)
 	end
+end
 
-	screenHeight = djui_hud_get_screen_height()
+local timer = 0
-	screenWidth = djui_hud_get_screen_width()
+--- Inform the player that they have joined a game with cheats enabled
-
+--- and won't be able to get any green stars
-	if a == nil then a = 255 end
+---@param m MarioState
-
+---@return nil
-	local timerValFrames = hud_get_value(HUD_DISPLAY_TIMER)
+local function psc_mario_update_inform_cheats(m)
-	local timerX = 0
+    if m.playerIndex ~= 0 then return end
-	local timerY = 0
+    if has_cheats_enabled then
-
+        timer = timer + 1
-	-- Move HUD graphics away from the TIMER HUD
+        if timer == 30 then
-	if timerValFrames ~= 0 then
+            djui_popup_create("This game has cheats enabled. You cannot gain any \\#00FF00\\green stars\\#DCDCDC\\ from this game.", 3)
-		timerX = 60
-		timerY = 17
-	end
-
-	--Normal vanilla star counter (The fake real one)
-	--Yes Im hiding the hardcoded one because alignment is a pain lmao
-	if cutscenes[m.action] ~= true then
-        if introTimer >= 1195
-        or m.action ~= ACT_INTRO_CUTSCENE then
-            if m.numStars >= 100 then
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(tostring(m.numStars), screenWidth - 60, screenHeight - 225, 1)
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_render_texture(gTextures.star, screenWidth - 76, screenHeight - 225, 1, 1.)
-            else
-                djui_hud_set_adjusted_color(246, 246, 246, a)
-                djui_hud_print_text("X", screenWidth - 60, screenHeight - 225, 1)
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(tostring(m.numStars), screenWidth - 46, screenHeight - 225, 1)
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_render_texture(gTextures.star, screenWidth - 76, screenHeight - 225, 1, 1)
-            end
-        end
-    end
-
-	--Normal personal star counter (The red one)
-    if cutscenes[m.action] == true then
-        if StarCounter >= 100 then
-            djui_hud_set_adjusted_color(255, 255, 255, a)
-            djui_hud_print_text(tostring(StarCounter), screenWidth%2 + 38, screenHeight - 235, 1)
-            djui_hud_set_adjusted_color(232, 17, 35, a)
-            djui_hud_render_texture(gTextures.star, screenWidth%2 + 22, screenHeight - 235, 1, 1)
-        else
-            djui_hud_set_adjusted_color(246, 246, 246, a)
-            djui_hud_print_text(tostring("X"), screenWidth%2 + 38, screenHeight - 235, 1)
-            djui_hud_set_adjusted_color(255, 255, 255, a)
-            djui_hud_print_text(tostring(StarCounter), screenWidth%2 + 54, screenHeight - 235, 1)
-            djui_hud_set_adjusted_color(232, 17, 35, a)
-            djui_hud_render_texture(gTextures.star, screenWidth%2 + 22, screenHeight - 235, 1, 1)
-        end
-    else
-        if introTimer >= 1195
-        or m.action ~= ACT_INTRO_CUTSCENE then
-            if StarCounter >= 100 then
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(tostring(StarCounter), screenWidth - 60 - timerX, screenHeight - 208 - timerY, 1)
-                djui_hud_set_adjusted_color(232, 17, 35, a)
-                djui_hud_render_texture(gTextures.star, screenWidth - 76 - timerX, screenHeight - 208 - timerY, 1, 1)
-            else
-                djui_hud_set_adjusted_color(246, 246, 246, a)
-                djui_hud_print_text(tostring("X"), screenWidth - 60 - timerX, screenHeight - 208 - timerY, 1)
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(tostring(StarCounter), screenWidth - 46 - timerX, screenHeight - 208 - timerY, 1)
-                djui_hud_set_adjusted_color(232, 17, 35, a)
-                djui_hud_render_texture(gTextures.star, screenWidth - 76 - timerX, screenHeight - 208 - timerY, 1, 1)
-            end
-        end
-    end
-	--Total star counter (The green one)
-	if timerValFrames ~= 0 then
-		timerX = 0
-		timerY = -10
-	end
-
-	local perceived_total_counter = TotalStarCounter
-	local milestone_counter = 0
-	while perceived_total_counter >= 10000 do
-		perceived_total_counter = perceived_total_counter - 10000
-		milestone_counter = milestone_counter + 1
-	end
-
-    if cutscenes[m.action] == true then
-        if perceived_total_counter >= 100 then
-            djui_hud_set_adjusted_color(255, 255, 255, a)
-            djui_hud_print_text(tostring(perceived_total_counter), screenWidth - 60, screenHeight - 235, 1)
-            djui_hud_set_adjusted_color(50, 176, 40, a)
-            djui_hud_render_texture(gTextures.star, screenWidth - 76, screenHeight - 235, 1, 1)
-            if milestone_counter ~= 0 then
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(string.format("x%d", milestone_counter), screenWidth - 76, screenHeight - 235, 0.5)
-            end
-        else
-            djui_hud_set_adjusted_color(246, 246, 246, a)
-            djui_hud_print_text(tostring("X"), screenWidth - 60, screenHeight - 235, 1)
-            djui_hud_set_adjusted_color(255, 255, 255, a)
-            djui_hud_print_text(tostring(perceived_total_counter), screenWidth - 46, screenHeight - 235, 1)
-            djui_hud_set_adjusted_color(50, 176, 40, a)
-            djui_hud_render_texture(gTextures.star, screenWidth - 76, screenHeight - 235, 1, 1)
-            if milestone_counter ~= 0 then
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(string.format("x%d", milestone_counter), screenWidth - 76, screenHeight - 235, 0.5)
-            end
-        end
-    else
-        if introTimer >= 1195
-        or m.action ~= ACT_INTRO_CUTSCENE then
-            if perceived_total_counter >= 100 then
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(tostring(perceived_total_counter), screenWidth - 60 - timerX, screenHeight - 190 - timerY, 1)
-                djui_hud_set_adjusted_color(50, 176, 40, a)
-                djui_hud_render_texture(gTextures.star, screenWidth - 76 - timerX, screenHeight - 190 - timerY, 1, 1)
-                if milestone_counter ~= 0 then
-                    djui_hud_set_adjusted_color(255, 255, 255, a)
-                    djui_hud_print_text(string.format("x%d", milestone_counter), screenWidth - 76 - timerX, screenHeight - 174 - timerY, 0.5)
-                end
-            else
-                djui_hud_set_adjusted_color(246, 246, 246, a)
-                djui_hud_print_text(tostring("X"), screenWidth - 60 - timerX, screenHeight - 190 - timerY, 1)
-                djui_hud_set_adjusted_color(255, 255, 255, a)
-                djui_hud_print_text(tostring(perceived_total_counter), screenWidth - 46 - timerX, screenHeight - 190 - timerY, 1)
-                djui_hud_set_adjusted_color(50, 176, 40, a)
-                djui_hud_render_texture(gTextures.star, screenWidth - 76 - timerX, screenHeight - 190 - timerY, 1, 1)
-                if milestone_counter ~= 0 then
-                    djui_hud_set_adjusted_color(255, 255, 255, a)
-                    djui_hud_print_text(string.format("x%d", milestone_counter), screenWidth - 76 - timerX, screenHeight - 174 - timerY, 0.5)
-                end
-            end
         end
     end
 end
 
---Turn server cheats off, silly!
+--- Toggle whether or not to display the star counter on the hud
---Will be updated immediately when individual cheats get flags.
+---@param msg string
-function cheaterStar()
+---@return boolean
-	if starCheater == true then return end
+local function toggle_psc(msg)
-	if gServerSettings.enableCheats ~= 0 then
+	if msg:lower() == "on" then
-		djui_popup_create("This server has cheats enabled.\n\\#31AF28\\Total Star Count\\#FFFFFF\\ will not change.", 2)
+		psc_toggle = true
-		play_sound_button_change_blocked()
+	elseif msg:lower() == "off" then
-		starCheater = true
+		psc_toggle = false
-	else
-		starCheater = false
-	end
-end
-
---See how many stars everyone gets!
-function updatePSC(m)
-	gPlayerSyncTable[0].psc = StarCounter
-end
-
---No star text icon yet, also the text gets removed after the second color change?
-function update()
-	for i = 0, (MAX_PLAYERS - 1) do
-		gPlayerSyncTable[i].psc = gPlayerSyncTable[i].psc
-		network_player_set_description(gNetworkPlayers[i], "\\#FF0000\\".."Stars"..--[[ "\\#FFFFFF\\".. ]]": " ..tostring(gPlayerSyncTable[i].psc), 255, 255, 255, 255)
-	end
-end
-
-function pscToggle(msg)
-	if msg == string.lower("On") or msg == "1" then
-		pscToggle = 1
-        hud_set_value(HUD_DISPLAY_FLAGS, hud_get_value(HUD_DISPLAY_FLAGS) & ~HUD_DISPLAY_FLAG_STAR_COUNT)
-		return true
-	elseif msg == string.lower("Off") or msg == "0" then
-		pscToggle = 0
         hud_set_value(HUD_DISPLAY_FLAGS, hud_get_value(HUD_DISPLAY_FLAGS) | HUD_DISPLAY_FLAG_STAR_COUNT)
-		return true
 	end
+    return true
 end
 
----------
+-----------------
---Hooks--
+----- Hooks -----
----------
+-----------------
-hook_event(HOOK_ON_INTERACT, localStarCounter)
-hook_event(HOOK_ON_HUD_RENDER, displayStarCounter)
-hook_event(HOOK_ON_LEVEL_INIT, cheaterStar)
-hook_event(HOOK_UPDATE, update)
-hook_event(HOOK_UPDATE, updatePSC)
-hook_chat_command('psc', "On|Off - Displays stars you've collected. Default is On.", pscToggle)
 
---Global functions for everyone to use!
+hook_event(HOOK_ON_INTERACT, star_counter_on_interact)
---Thank you, PeachyPeach!
+hook_event(HOOK_ON_HUD_RENDER, hud_render_psc)
+hook_event(HOOK_UPDATE, psc_update)
+hook_event(HOOK_MARIO_UPDATE, psc_mario_update_inform_cheats)
+hook_chat_command('psc', "On|Off - Displays stars you've collected. Default is On.", toggle_psc)
+
+-- Globalize functions for other mods to use
+-- Created by PeachyPeach
 _G.PersonalStarCounter = {
+    --- Get the amount of red stars collected
+    ---@return integer
 	get_star_counter = function ()
-		return StarCounter
+		return ThisGameStarCounter
 	end,
 
+    --- Get the amount of green stars collected
+    ---@return integer
 	get_total_star_counter = function ()
 		return TotalStarCounter
 	end,
 
+    --- Force show or hide the star counters
+    ---@param hide boolean
 	hide_star_counters = function (hide)
-		if hide then pscToggle = 0 else pscToggle = 1 end
+		psc_toggle = hide
 	end,
+
+    --- Modify the value of the star counters
+    ---@param red_change number How much to change the red (single game) star counter by
+    ---@param green_change number How much to change the green (total) star counter by
+    ---@param override_set boolean If true, force set the value of the star counters instead of change
+    ---@param save boolean If true, save the green star counter to mod storage
+    ---@return nil
+    change_star_counter_value = function (red_change, green_change, override_set, save)
+        ThisGameStarCounter = ThisGameStarCounter + red_change
+        if override_set then
+            ThisGameStarCounter = red_change
+        end
+        TotalStarCounter = TotalStarCounter + green_change
+        if override_set then
+            TotalStarCounter = green_change
+        end
+        if save then
+            mod_storage_save("StarCounter", tostring(TotalStarCounter))
+        end
+    end
 }