Merge branch 'sk/reroll-shop'

Author: S1M0N38

docs/logging-systems.md

@@ -16,7 +16,7 @@ The system hooks into these game functions:
 - `skip_or_select_blind`: blind selection actions
 - `play_hand_or_discard`: card play actions
 - `cash_out`: end blind and collect rewards
-- `shop`: shop interactions
+- `shop`: shop interactions (`next_round`, `buy_card`, `reroll`)
 - `go_to_menu`: return to main menu
 
 The JSONL files are automatically created when:

docs/protocol-api.md

@@ -109,16 +109,16 @@ The BalatroBot API provides core functions that correspond to the main game acti
 
 ### Overview
 
-| Name                   | Description                                                                                 |
-| ---------------------- | ------------------------------------------------------------------------------------------- |
-| `get_game_state`       | Retrieves the current complete game state                                                   |
-| `go_to_menu`           | Returns to the main menu from any game state                                                |
-| `start_run`            | Starts a new game run with specified configuration                                          |
-| `skip_or_select_blind` | Handles blind selection - either select the current blind to play or skip it                |
-| `play_hand_or_discard` | Plays selected cards or discards them                                                       |
-| `rearrange_hand`       | Reorders the current hand according to the supplied index list                              |
-| `cash_out`             | Proceeds from round completion to the shop phase                                            |
-| `shop`                 | Performs shop actions: proceed to next round (`next_round`) or purchase a card (`buy_card`) |
+| Name                   | Description                                                                                                          |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `get_game_state`       | Retrieves the current complete game state                                                                            |
+| `go_to_menu`           | Returns to the main menu from any game state                                                                         |
+| `start_run`            | Starts a new game run with specified configuration                                                                   |
+| `skip_or_select_blind` | Handles blind selection - either select the current blind to play or skip it                                         |
+| `play_hand_or_discard` | Plays selected cards or discards them                                                                                |
+| `rearrange_hand`       | Reorders the current hand according to the supplied index list                                                       |
+| `cash_out`             | Proceeds from round completion to the shop phase                                                                     |
+| `shop`                 | Performs shop actions: proceed to next round (`next_round`), purchase a card (`buy_card`), or reroll shop (`reroll`) |
 
 ### Parameters
 
@@ -130,7 +130,21 @@ The following table details the parameters required for each function. Note that
 | `skip_or_select_blind` | `action` (string): Either "select" or "skip"                                                                                                                                                                                                                              |
 | `play_hand_or_discard` | `action` (string): Either "play_hand" or "discard"<br>`cards` (array): Card indices (0-indexed, 1-5 cards)                                                                                                                                                                |
 | `rearrange_hand`       | `cards` (array): Card indices (0-indexed, exactly `hand_size` elements)                                                                                                                                                                                                   |
-| `shop`                 | `action` (string): Shop action ("next_round" or "buy_card")<br>`index` (number, required when `action` = "buy_card"): 0-based card index to purchase                                                                                                                      |
+| `shop`                 | `action` (string): Shop action ("next_round", "buy_card", or "reroll")<br>`index` (number, required when `action` = "buy_card"): 0-based card index to purchase                                                                                                           |
+
+### Shop Actions
+
+The `shop` function supports multiple in-shop actions. Use the `action` field inside the `arguments` object to specify which of these to execute.
+
+| Action       | Description                                                   | Additional Parameters                                    |
+| ------------ | ------------------------------------------------------------- | -------------------------------------------------------- |
+| `next_round` | Leave the shop and proceed to the next blind selection.       | —                                                        |
+| `buy_card`   | Purchase the card at the supplied `index` in `shop_jokers`.   | `index` _(number)_ – 0-based position of the card to buy |
+| `reroll`     | Spend dollars to refresh the shop offer (cost shown in-game). | —                                                        |
+
+!!! note "Future actions"
+
+Additional shop actions `buy_and_use_card`, `open_pack`, and `redeem_voucher` will be added soon.
 
 ### Errors
 

src/lua/api.lua

@@ -695,13 +695,50 @@ API.functions["shop"] = function(args)
         API.send_response(game_state)
       end,
     }
+  elseif action == "reroll" then
+    -- Capture the state before rerolling for response validation
+    local dollars_before = G.GAME.dollars
+    local reroll_cost = G.GAME.current_round and G.GAME.current_round.reroll_cost or 0
+    local expected_dollars = dollars_before - reroll_cost
+
+    local times_rerolled_before = 0
+    if G.GAME.round_scores and G.GAME.round_scores.times_rerolled then
+      times_rerolled_before = G.GAME.round_scores.times_rerolled.amt or 0
+    end
+
+    if dollars_before < reroll_cost then
+      API.send_error_response(
+        "Not enough dollars to reroll",
+        ERROR_CODES.INVALID_ACTION,
+        { dollars = dollars_before, reroll_cost = reroll_cost }
+      )
+      return
+    end
+
+    -- no UI element required for reroll
+    G.FUNCS.reroll_shop(nil)
+
+    ---@type PendingRequest
+    API.pending_requests["shop"] = {
+      condition = function()
+        return utils.COMPLETION_CONDITIONS.shop_idle()
+          and G.GAME.round_scores
+          and G.GAME.round_scores.times_rerolled
+          and G.GAME.round_scores.times_rerolled.amt == times_rerolled_before + 1
+          and G.GAME.dollars == expected_dollars
+      end,
+      action = function()
+        local game_state = utils.get_game_state()
+        API.send_response(game_state)
+      end,
+    }
 
-  -- TODO: add other shop actions [buy_and_use | reroll | open_pack | redeem_voucher]
+  -- TODO: add other shop actions [buy_and_use | open_pack | redeem_voucher]
   else
     API.send_error_response(
       "Invalid action for shop",
       ERROR_CODES.INVALID_ACTION,
-      { action = action, valid_actions = { "next_round" } }
+      { action = action, valid_actions = { "next_round", "buy_card", "reroll" } }
     )
     return
   end

src/lua/log.lua

@@ -237,6 +237,21 @@ function hook_buy_card()
   sendDebugMessage("Hooked into G.FUNCS.buy_card for logging", "LOG")
 end
 
+-- -----------------------------------------------------------------------------
+-- reroll_shop Hook
+-- -----------------------------------------------------------------------------
+
+---Hooks into G.FUNCS.reroll_shop
+function hook_reroll_shop()
+  local original_function = G.FUNCS.reroll_shop
+  G.FUNCS.reroll_shop = function(e)
+    local function_call = { name = "shop", arguments = { action = "reroll" } }
+    LOG.schedule_write(function_call)
+    return original_function(e)
+  end
+  sendDebugMessage("Hooked into G.FUNCS.reroll_shop for logging", "LOG")
+end
+
 -- -----------------------------------------------------------------------------
 -- hand_rearrange Hook
 -- -----------------------------------------------------------------------------
@@ -369,6 +384,8 @@ function LOG.init()
   hook_discard_cards_from_highlighted()
   hook_cash_out()
   hook_toggle_shop()
+  hook_buy_card()
+  hook_reroll_shop()
   hook_hand_rearrange()
 
   sendInfoMessage("Logger initialized", "LOG")

src/lua/types.lua

@@ -53,7 +53,7 @@
 ---@field cards number[] Array of card indices for every card in hand (0-based)
 
 ---@class ShopActionArgs
----@field action "next_round" | "buy_card" The action to perform
+---@field action "next_round" | "buy_card" | "reroll" The action to perform
 ---@field index? number The index of the card to act on (buy, buy_and_use, redeem, open) (0-based)
 
 -- TODO: add the other actions "reroll" | "buy" | "buy_and_use" | "redeem" | "open"
@@ -139,6 +139,8 @@
 ---@field discards_used number Number of discards used
 ---@field hands_left number Number of hands remaining
 ---@field hands_played number Number of hands played
+---@field reroll_cost number Current dollar cost to reroll the shop offer
+---@field free_rerolls number Free rerolls remaining this round
 ---@field voucher table Vouchers for this round
 
 -- Selected deck info (G.GAME.selected_back)

src/lua/utils.lua

@@ -110,6 +110,10 @@ function utils.get_game_state()
         -- "free_rerolls": int, (default 0) -- Number  of free rerolls in the shop?
         hands_left = G.GAME.current_round.hands_left, -- Number of hands left for this round
         hands_played = G.GAME.current_round.hands_played, -- Number of hands played in this round
+
+        -- Reroll information (used in shop state)
+        reroll_cost = G.GAME.current_round.reroll_cost, -- Current cost for a shop reroll
+        free_rerolls = G.GAME.current_round.free_rerolls, -- Free rerolls remaining this round
         -- "idol_card": { -- what's a idol card?? maybe some random used by some joker/effect? idk
         --   "rank": "Ace" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "Jack" | "Queen" | "King",
         --   "suit": "Spades" | "Hearts" | "Diamonds" | "Clubs",

tests/lua/endpoints/test_shop.py

@@ -244,6 +244,57 @@ def test_shop_buy_card(self, tcp_client: socket.socket) -> None:
         assert purchase_response["game"]["dollars"] == 4
         assert purchase_response["jokers"]["cards"][0]["cost"] == 6
 
+    # ------------------------------------------------------------------
+    # reroll shop
+    # ------------------------------------------------------------------
+
+    def test_shop_reroll_success(self, tcp_client: socket.socket) -> None:
+        """Successful reroll keeps us in shop and updates cards / dollars."""
+
+        # Capture shop state before reroll
+        before_state = send_and_receive_api_message(tcp_client, "get_game_state", {})
+        assert before_state["state"] == State.SHOP.value
+        before_keys = [
+            c["config"]["center_key"] for c in before_state["shop_jokers"]["cards"]
+        ]
+        dollars_before = before_state["game"]["dollars"]
+        reroll_cost = before_state["game"]["current_round"]["reroll_cost"]
+
+        # Perform the reroll
+        after_state = send_and_receive_api_message(
+            tcp_client, "shop", {"action": "reroll"}
+        )
+
+        # verify state
+        assert after_state["state"] == State.SHOP.value
+        assert after_state["game"]["dollars"] == dollars_before - reroll_cost
+        after_keys = [
+            c["config"]["center_key"] for c in after_state["shop_jokers"]["cards"]
+        ]
+        assert before_keys != after_keys
+
+    def test_shop_reroll_insufficient_dollars(self, tcp_client: socket.socket) -> None:
+        """Repeated rerolls eventually raise INVALID_ACTION when too expensive."""
+
+        # Perform rerolls until an error is returned or a reasonable max tries reached
+        max_attempts = 10
+        for _ in range(max_attempts):
+            response = send_and_receive_api_message(
+                tcp_client, "shop", {"action": "reroll"}
+            )
+
+            # Break when error encountered and validate
+            if "error" in response:
+                assert_error_response(
+                    response,
+                    "Not enough dollars to reroll",
+                    ["dollars", "reroll_cost"],
+                    ErrorCode.INVALID_ACTION.value,
+                )
+                break
+        else:
+            pytest.fail("Rerolls did not exhaust dollars within expected attempts")
+
     # ------------------------------------------------------------------
     # buy_card validation / error scenarios
     # ------------------------------------------------------------------