Programmatical play API now supports buying metro lines

Author: yanfengliu

PROGRESS.md

@@ -55,3 +55,4 @@
 - Updated game rules docs for purchase-based line unlocks and the new locked-button hover/click behavior.
 - Changed UI font usage to `courier` via shared `font_name` config.
 - Expanded `README.md` programmatic play docs to list the `MiniMetroEnv` API, action schemas, valid input constraints, and observation/step return fields.
+- Added programmatic `buy_line` action to purchase metro lines through `env.step(...)`, with optional `path_index` targeting and validation.

README.md

@@ -64,6 +64,13 @@ obs, reward, done, info = env.step({"type": "remove_path", "path_index": 0})
   - Valid only when `0 <= k < len(observation["structured"]["paths"])`.
 - `{"type": "remove_path", "path_id": "..."}` 
   - Removes an existing path by path id string from `observation["structured"]["paths"][*]["id"]`.
+- `{"type": "buy_line"}`
+  - Buys the next locked line if affordable.
+  - Price follows configured incremental unlock costs (derived from `path_unlock_milestones`).
+- `{"type": "buy_line", "path_index": k}`
+  - Attempts to buy a specific locked line button index.
+  - Must be the next purchasable locked index (sequential purchase rule); otherwise fails.
+  - `path_index` must be an integer in `[0, num_paths - 1]`.
 - `{"type": "pause"}`
   - Pauses simulation updates.
 - `{"type": "resume"}`

src/mediator.py

@@ -206,6 +206,17 @@ def try_purchase_path_button(self, button: PathButton) -> bool:
         self.update_unlocked_num_paths()
         return True
 
+    def try_purchase_path_button_by_index(
+        self, button_idx: int | None = None
+    ) -> bool:
+        if button_idx is None:
+            button_idx = self.get_next_path_button_idx_to_purchase()
+        if button_idx is None:
+            return False
+        if button_idx < 0 or button_idx >= len(self.path_buttons):
+            return False
+        return self.try_purchase_path_button(self.path_buttons[button_idx])
+
     def step_time(self, dt_ms: int) -> None:
         self.increment_time(dt_ms)
 
@@ -524,6 +535,11 @@ def apply_action(self, action: Dict) -> bool:
             stations = action.get("stations", [])
             loop = bool(action.get("loop", False))
             return self.create_path_from_station_indices(stations, loop) is not None
+        if action_type == "buy_line":
+            button_idx = action.get("path_index")
+            if button_idx is not None and not isinstance(button_idx, int):
+                return False
+            return self.try_purchase_path_button_by_index(button_idx)
         if action_type == "remove_path":
             if "path_id" in action:
                 return self.remove_path_by_id(action["path_id"])

test/test_env.py

@@ -264,6 +264,39 @@ def test_path_unlock_progression_uses_score_purchases(self):
         self.assertTrue(env.mediator.try_purchase_path_button(second_button))
         self.assertEqual(env.mediator.unlocked_num_paths, 2)
 
+    def test_step_buy_line_purchases_next_locked_line(self):
+        env = MiniMetroEnv()
+        env.reset(seed=17)
+        env.mediator.score = env.mediator.path_purchase_prices[0]
+
+        _, _, _, info = env.step({"type": "buy_line"})
+
+        self.assertTrue(info["action_ok"])
+        self.assertEqual(env.mediator.unlocked_num_paths, 2)
+        self.assertFalse(env.mediator.path_buttons[1].is_locked)
+        self.assertEqual(env.mediator.score, 0)
+
+    def test_step_buy_line_supports_path_index(self):
+        env = MiniMetroEnv()
+        env.reset(seed=18)
+        env.mediator.score = env.mediator.path_purchase_prices[0]
+
+        _, _, _, info = env.step({"type": "buy_line", "path_index": 1})
+
+        self.assertTrue(info["action_ok"])
+        self.assertEqual(env.mediator.unlocked_num_paths, 2)
+
+    def test_step_buy_line_invalid_index_returns_false(self):
+        env = MiniMetroEnv()
+        env.reset(seed=19)
+        env.mediator.score = 10_000
+
+        _, _, _, info = env.step({"type": "buy_line", "path_index": "1"})
+        self.assertFalse(info["action_ok"])
+
+        _, _, _, info = env.step({"type": "buy_line", "path_index": 99})
+        self.assertFalse(info["action_ok"])
+
     def test_reward_increments_on_passenger_delivery(self):
         env = MiniMetroEnv()
         env.reset(seed=13)