feat: add cards argument to use_consumable

stirby · S1M0N38 · commit 17759523b97c · 2025-10-03T12:13:30.000+02:00
diff --git a/src/lua/api.lua b/src/lua/api.lua
@@ -1105,6 +1105,66 @@ API.functions["use_consumable"] = function(args)
     return
   end
 
+  -- If cards parameter is provided, handle card selection
+  if args.cards then
+    -- Validate current game state is SELECTING_HAND when cards are provided
+    if G.STATE ~= G.STATES.SELECTING_HAND then
+      API.send_error_response(
+        "Cannot use consumable with cards when not in selecting hand state",
+        ERROR_CODES.INVALID_GAME_STATE,
+        { current_state = G.STATE, required_state = G.STATES.SELECTING_HAND }
+      )
+      return
+    end
+
+    -- Validate cards is an array
+    if type(args.cards) ~= "table" then
+      API.send_error_response(
+        "Invalid parameter type for cards. Expected array, got " .. tostring(type(args.cards)),
+        ERROR_CODES.INVALID_PARAMETER,
+        { parameter = "cards", expected_type = "array" }
+      )
+      return
+    end
+
+    -- Validate number of cards is between 1 and 5 (inclusive) for consistency with play_hand_or_discard
+    if #args.cards < 1 or #args.cards > 5 then
+      API.send_error_response(
+        "Invalid number of cards. Expected 1-5, got " .. tostring(#args.cards),
+        ERROR_CODES.PARAMETER_OUT_OF_RANGE,
+        { cards_count = #args.cards, valid_range = "1-5" }
+      )
+      return
+    end
+
+    -- Convert from 0-based to 1-based indexing
+    for i, card_index in ipairs(args.cards) do
+      args.cards[i] = card_index + 1
+    end
+
+    -- Check that all cards exist and are selectable
+    for _, card_index in ipairs(args.cards) do
+      if not G.hand or not G.hand.cards or not G.hand.cards[card_index] then
+        API.send_error_response(
+          "Invalid card index",
+          ERROR_CODES.INVALID_CARD_INDEX,
+          { card_index = card_index - 1, hand_size = G.hand and G.hand.cards and #G.hand.cards or 0 }
+        )
+        return
+      end
+    end
+
+    -- Clear any existing highlights before selecting new cards
+    if G.hand then
+      G.hand:unhighlight_all()
+    end
+
+    -- Select cards for the consumable to target
+    for _, card_index in ipairs(args.cards) do
+      G.hand.cards[card_index]:click()
+    end
+  end
+
   -- Validate that consumables exist
   if not G.consumeables or not G.consumeables.cards or #G.consumeables.cards == 0 then
     API.send_error_response(
diff --git a/src/lua/types.lua b/src/lua/types.lua
@@ -77,6 +77,10 @@
 ---@class SellConsumableArgs
 ---@field index number The index of the consumable to sell (0-based)
 
+---@class UseConsumableArgs
+---@field index number The index of the consumable to use (0-based)
+---@field cards? number[] Optional array of card indices to target (0-based)
+
 ---@class LoadSaveArgs
 ---@field save_path string Path to the save file relative to Love2D save directory (e.g., "3/save.jkr")
 
diff --git a/test_use_consumable.py b/test_use_consumable.py
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Test script for the enhanced use_consumable endpoint with cards parameter."""
+
+import time
+
+from balatrobot import BalatroClient
+from balatrobot.enums import Actions
+
+
+def test_use_consumable():
+    """Test the use_consumable functionality with and without cards parameter."""
+    with BalatroClient() as client:
+        print("Connected to Balatro")
+
+        # Get initial game state
+        state = client.send_message("get_game_state")
+        print(f"Current state: {state['G']['STATE']}")
+
+        # Start a new run if needed
+        if state["G"]["STATE"] == Actions.MENU:
+            print("Starting new run...")
+            state = client.send_message("start_run", {"stake": "white", "deck": "red"})
+            print(f"Run started, new state: {state['G']['STATE']}")
+
+        # Navigate to a state where we can test consumables
+        if state["G"]["STATE"] == Actions.BLIND_SELECT:
+            print("Selecting blind...")
+            state = client.send_message("skip_or_select_blind", {"action": "select"})
+            time.sleep(1)
+
+        # Check if we have consumables
+        consumables = state["G"].get("consumeables", {}).get("cards", [])
+        print(f"Consumables available: {len(consumables)}")
+
+        if consumables:
+            # Try using first consumable without cards (e.g., planet cards)
+            print(f"Using consumable at index 0 (no cards)...")
+            try:
+                result = client.use_consumable(0)
+                print("Successfully used consumable without cards")
+            except Exception as e:
+                print(f"Error using consumable without cards: {e}")
+
+        # Check hand cards
+        hand_cards = state["G"].get("hand", {}).get("cards", [])
+        print(f"Hand cards available: {len(hand_cards)}")
+
+        if consumables and len(hand_cards) >= 3:
+            # Try using a consumable with specific cards selected
+            print(f"Using consumable at index 0 with cards [0, 1, 2]...")
+            try:
+                result = client.use_consumable(0, cards=[0, 1, 2])
+                print("Successfully used consumable with selected cards")
+            except Exception as e:
+                print(f"Error using consumable with cards: {e}")
+
+        # Test error cases
+        print("\nTesting error cases...")
+
+        # Test invalid index
+        try:
+            print("Testing invalid consumable index...")
+            result = client.use_consumable(99)
+            print("Unexpected success with invalid index")
+        except Exception as e:
+            print(f"Expected error with invalid index: {e}")
+
+        # Test invalid card indices
+        if consumables:
+            try:
+                print("Testing invalid card indices...")
+                result = client.use_consumable(0, cards=[99, 100])
+                print("Unexpected success with invalid card indices")
+            except Exception as e:
+                print(f"Expected error with invalid card indices: {e}")
+
+        print("\nTest completed!")
+
+
+if __name__ == "__main__":
+    test_use_consumable()
diff --git a/tests/lua/endpoints/test_use_consumable.py b/tests/lua/endpoints/test_use_consumable.py
@@ -194,5 +194,218 @@ def test_use_consumable_no_consumables_available(
         )
 
 
-# TODO: add test for other types of consumables
-class TestUseConsumableOtherType: ...
+class TestUseConsumableWithCards:
+    """Test use_consumable with cards parameter for consumables that target specific cards."""
+
+    @pytest.fixture(autouse=True)
+    def setup_and_teardown(
+        self, tcp_client: socket.socket
+    ) -> Generator[dict, None, None]:
+        # Start a run and get to SELECTING_HAND state with a consumable
+        send_and_receive_api_message(
+            tcp_client,
+            "start_run",
+            {
+                "deck": "Red Deck",
+                "stake": 1,
+                "seed": "TEST123",
+            },
+        )
+        send_and_receive_api_message(
+            tcp_client, "skip_or_select_blind", {"action": "select"}
+        )
+
+        # Play a hand to get to shop
+        send_and_receive_api_message(
+            tcp_client,
+            "play_hand_or_discard",
+            {"action": "play_hand", "cards": [0, 1, 2, 3]},
+        )
+        send_and_receive_api_message(tcp_client, "cash_out", {})
+
+        # Buy a consumable
+        send_and_receive_api_message(
+            tcp_client,
+            "shop",
+            {"action": "buy_card", "index": 2},
+        )
+
+        # Start next round to get back to SELECTING_HAND state
+        send_and_receive_api_message(tcp_client, "shop", {"action": "next_round"})
+        game_state = send_and_receive_api_message(
+            tcp_client, "skip_or_select_blind", {"action": "select"}
+        )
+
+        yield game_state
+        send_and_receive_api_message(tcp_client, "go_to_menu", {})
+
+    def test_use_consumable_with_cards_success(
+        self, tcp_client: socket.socket, setup_and_teardown
+    ) -> None:
+        """Test successfully using a consumable with specific cards selected."""
+        game_state = setup_and_teardown
+
+        # Verify we're in SELECTING_HAND state
+        assert game_state["state"] == State.SELECTING_HAND.value
+
+        # Skip test if no consumables available
+        if len(game_state["consumables"]["cards"]) == 0:
+            pytest.skip("No consumables available in this test run")
+
+        # Use the consumable with specific cards selected
+        response = send_and_receive_api_message(
+            tcp_client,
+            "use_consumable",
+            {"index": 0, "cards": [0, 2, 4]},  # Select cards 0, 2, and 4
+        )
+
+        # Verify response is successful
+        assert "error" not in response
+
+    def test_use_consumable_with_invalid_cards(
+        self, tcp_client: socket.socket, setup_and_teardown
+    ) -> None:
+        """Test using consumable with invalid card indices."""
+        game_state = setup_and_teardown
+
+        # Skip test if no consumables available
+        if len(game_state["consumables"]["cards"]) == 0:
+            pytest.skip("No consumables available in this test run")
+
+        # Try to use consumable with out-of-range card indices
+        response = send_and_receive_api_message(
+            tcp_client,
+            "use_consumable",
+            {"index": 0, "cards": [99, 100]},  # Invalid card indices
+        )
+        assert_error_response(
+            response,
+            "Invalid card index",
+            expected_error_code=ErrorCode.INVALID_CARD_INDEX.value,
+        )
+
+    def test_use_consumable_with_too_many_cards(
+        self, tcp_client: socket.socket, setup_and_teardown
+    ) -> None:
+        """Test using consumable with more than 5 cards."""
+        game_state = setup_and_teardown
+
+        # Skip test if no consumables available
+        if len(game_state["consumables"]["cards"]) == 0:
+            pytest.skip("No consumables available in this test run")
+
+        # Try to use consumable with more than 5 cards
+        response = send_and_receive_api_message(
+            tcp_client,
+            "use_consumable",
+            {"index": 0, "cards": [0, 1, 2, 3, 4, 5]},  # 6 cards - too many
+        )
+        assert_error_response(
+            response,
+            "Invalid number of cards",
+            expected_error_code=ErrorCode.PARAMETER_OUT_OF_RANGE.value,
+        )
+
+    def test_use_consumable_with_empty_cards(
+        self, tcp_client: socket.socket, setup_and_teardown
+    ) -> None:
+        """Test using consumable with empty cards array."""
+        game_state = setup_and_teardown
+
+        # Skip test if no consumables available
+        if len(game_state["consumables"]["cards"]) == 0:
+            pytest.skip("No consumables available in this test run")
+
+        # Try to use consumable with empty cards array
+        response = send_and_receive_api_message(
+            tcp_client,
+            "use_consumable",
+            {"index": 0, "cards": []},  # Empty array
+        )
+        assert_error_response(
+            response,
+            "Invalid number of cards",
+            expected_error_code=ErrorCode.PARAMETER_OUT_OF_RANGE.value,
+        )
+
+    def test_use_consumable_with_invalid_cards_type(
+        self, tcp_client: socket.socket, setup_and_teardown
+    ) -> None:
+        """Test using consumable with non-array cards parameter."""
+        game_state = setup_and_teardown
+
+        # Skip test if no consumables available
+        if len(game_state["consumables"]["cards"]) == 0:
+            pytest.skip("No consumables available in this test run")
+
+        # Try to use consumable with invalid cards type
+        response = send_and_receive_api_message(
+            tcp_client,
+            "use_consumable",
+            {"index": 0, "cards": "invalid"},  # Not an array
+        )
+        assert_error_response(
+            response,
+            "Invalid parameter type",
+            expected_error_code=ErrorCode.INVALID_PARAMETER.value,
+        )
+
+    def test_use_planet_without_cards(
+        self, tcp_client: socket.socket, setup_and_teardown
+    ) -> None:
+        """Test that planet consumables still work without cards parameter."""
+        game_state = setup_and_teardown
+
+        # Skip test if no consumables available
+        if len(game_state["consumables"]["cards"]) == 0:
+            pytest.skip("No consumables available in this test run")
+
+        # Use consumable without cards parameter (original behavior)
+        response = send_and_receive_api_message(
+            tcp_client,
+            "use_consumable",
+            {"index": 0},  # No cards parameter
+        )
+
+        # Should still work for consumables that don't need cards
+        assert "error" not in response
+
+    def test_use_consumable_with_cards_wrong_state(
+        self, tcp_client: socket.socket
+    ) -> None:
+        """Test that using consumable with cards fails in non-SELECTING_HAND states."""
+        # Start a run and get to shop state
+        send_and_receive_api_message(
+            tcp_client,
+            "start_run",
+            {"deck": "Red Deck", "stake": 1, "seed": "OOOO155"},
+        )
+        send_and_receive_api_message(
+            tcp_client, "skip_or_select_blind", {"action": "select"}
+        )
+        send_and_receive_api_message(
+            tcp_client,
+            "play_hand_or_discard",
+            {"action": "play_hand", "cards": [0, 1, 2, 3]},
+        )
+        send_and_receive_api_message(tcp_client, "cash_out", {})
+        game_state = send_and_receive_api_message(
+            tcp_client,
+            "shop",
+            {"action": "buy_card", "index": 1},
+        )
+
+        # Verify we're in SHOP state
+        assert game_state["state"] == State.SHOP.value
+
+        # Try to use consumable with cards while in SHOP state (should fail)
+        response = send_and_receive_api_message(
+            tcp_client, "use_consumable", {"index": 0, "cards": [0, 1, 2]}
+        )
+        assert_error_response(
+            response,
+            "Cannot use consumable with cards when not in selecting hand state",
+            expected_error_code=ErrorCode.INVALID_GAME_STATE.value,
+        )
+
+        send_and_receive_api_message(tcp_client, "go_to_menu", {})
