feat: ball placement entry point (conflict-free)

demo_ball_placement.py

@@ -0,0 +1,146 @@
+"""demo_ball_placement.py — Entry point for the ball placement feature.
+
+Run:
+    pixi run python demo_ball_placement.py
+    # RSim window opens; open http://localhost:8080 in a browser
+
+What this sets up
+-----------------
+- Exhibition Road field (4 m × 3 m, ``GREAT_EXHIBITION_FIELD_DIMS``)
+- 2v2 format: two yellow robots (your team) vs two blue robots that
+  deliberately push the ball out once per side, then attack the yellow goal
+- CustomReferee pre-configured with:
+    - Goal detection enabled (issues PREPARE_KICKOFF → NORMAL_START cycle)
+    - Out-of-bounds enabled (issues STOP → BALL_PLACEMENT_YELLOW → DIRECT_FREE)
+    - Defense area and keep-out rules OFF (less noise during development)
+    - Auto-advance fully enabled so state transitions fire automatically —
+      you can watch the full placement → free-kick → restart cycle without
+      touching the GUI
+- Browser GUI at http://localhost:8080 — use "Manual Commands" to fire
+  BALL_PLACEMENT_YELLOW at any time and set the target position
+
+Workflow
+--------
+1. Run this script and open http://localhost:8080.
+2. Let the blue robots push the ball out of bounds, or use the GUI "Manual
+   Commands" panel to issue BALL_PLACEMENT_YELLOW.
+3. Watch one of your robots (yellow) drive to the ball, capture it with the
+   dribbler, and carry it to the target circle shown in the GUI.
+4. After the referee advances to NORMAL_START, yellow kicks once toward the
+   configured blue robot target.
+"""
+
+from utama_core.config.field_params import GREAT_EXHIBITION_FIELD_DIMS
+from utama_core.custom_referee import CustomReferee
+from utama_core.custom_referee.profiles.profile_loader import (
+    AutoAdvanceConfig,
+    DefenseAreaConfig,
+    GameConfig,
+    GoalDetectionConfig,
+    KeepOutConfig,
+    OutOfBoundsConfig,
+    RefereeProfile,
+    RulesConfig,
+)
+from utama_core.run import StrategyRunner
+from utama_core.strategy.examples.ball_placement_and_kick_strategy import (
+    BallPlacementAndKickStrategy,
+)
+from utama_core.strategy.examples.deliberate_out_of_bounds_strategy import (
+    DeliberateOutOfBoundsStrategy,
+)
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+GUI_PORT = 8080
+N_ROBOTS = 2
+MY_TEAM_IS_YELLOW = True
+MY_TEAM_IS_RIGHT = True
+
+
+# ---------------------------------------------------------------------------
+# Referee profile
+#
+# Out-of-bounds is the primary trigger for ball placement in a real game.
+# Defense area and keep-out rules are disabled to reduce noise while you're
+# developing the placement skill itself.
+# ---------------------------------------------------------------------------
+
+_BALL_PLACEMENT_PROFILE = RefereeProfile(
+    profile_name="ball_placement_dev",
+    rules=RulesConfig(
+        goal_detection=GoalDetectionConfig(
+            enabled=True,
+            cooldown_seconds=1.0,
+        ),
+        out_of_bounds=OutOfBoundsConfig(
+            enabled=True,
+            free_kick_assigner="last_touch",
+        ),
+        defense_area=DefenseAreaConfig(
+            enabled=False,
+            max_defenders=1,
+            attacker_infringement=False,
+        ),
+        keep_out=KeepOutConfig(
+            enabled=False,
+            radius_meters=0.3,
+            violation_persistence_frames=30,
+        ),
+    ),
+    game=GameConfig(
+        half_duration_seconds=300.0,
+        kickoff_team="yellow",
+        force_start_after_goal=False,
+        stop_duration_seconds=2.0,
+        prepare_duration_seconds=3.0,
+        kickoff_timeout_seconds=10.0,
+        auto_advance=AutoAdvanceConfig(
+            # All auto-advance enabled: state machine drives itself so you can
+            # observe the full placement → free-kick → normal-start cycle.
+            stop_to_next_command=True,
+            prepare_kickoff_to_normal=True,
+            prepare_penalty_to_normal=True,
+            direct_free_to_normal=True,
+            ball_placement_to_next=True,
+            normal_start_to_force=True,
+        ),
+    ),
+)
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    referee = CustomReferee(
+        _BALL_PLACEMENT_PROFILE,
+        n_robots_yellow=N_ROBOTS,
+        n_robots_blue=N_ROBOTS,
+        enable_gui=True,
+        gui_port=GUI_PORT,
+    )
+
+    runner = StrategyRunner(
+        strategy=BallPlacementAndKickStrategy(),
+        # Opponents create one out-of-bounds event per side, then attack yellow's goal.
+        opp_strategy=DeliberateOutOfBoundsStrategy(field_dims=GREAT_EXHIBITION_FIELD_DIMS),
+        my_team_is_yellow=MY_TEAM_IS_YELLOW,
+        my_team_is_right=MY_TEAM_IS_RIGHT,
+        mode="rsim",
+        control_scheme="pid",
+        exp_friendly=N_ROBOTS,
+        exp_enemy=N_ROBOTS,
+        full_field_dims=GREAT_EXHIBITION_FIELD_DIMS,
+        referee=referee,
+        show_live_status=True,
+    )
+
+    runner.run()
+
+
+if __name__ == "__main__":
+    main()

demo_ball_placement_real.py

@@ -0,0 +1,133 @@
+"""demo_ball_placement_real.py — Test ball placement with a single real robot.
+
+Run:
+    pixi run python demo_ball_placement_real.py
+    # Then open http://localhost:8080 in a browser
+
+What this sets up
+-----------------
+- Exhibition Road field (4 m x 3 m)
+- 1 yellow robot, no opponents
+- CustomReferee starts in HALT — the robot will not move until you issue a
+  command from the GUI
+- All automatic rule detection (out-of-bounds, goal, keep-out) is disabled so
+  the only commands come from the operator via the GUI
+
+Workflow
+--------
+1. Run this script and open http://localhost:8080.
+2. Place the ball somewhere on the field by hand.
+3. In the GUI "Manual Commands" panel, set a target position and issue
+   BALL_PLACEMENT_YELLOW.
+4. The robot drives to the ball with its dribbler on and attempts to carry it
+   to the target.
+5. Issue HALT from the GUI at any time to stop the robot immediately.
+
+Safety notes
+------------
+- The robot starts in HALT and will not move until you issue a command.
+- Keep the target position within the physical field bounds.
+- Issue HALT from the GUI before approaching the field.
+"""
+
+from utama_core.config.field_params import GREAT_EXHIBITION_FIELD_DIMS
+from utama_core.custom_referee import CustomReferee
+from utama_core.custom_referee.profiles.profile_loader import (
+    AutoAdvanceConfig,
+    DefenseAreaConfig,
+    GameConfig,
+    GoalDetectionConfig,
+    KeepOutConfig,
+    OutOfBoundsConfig,
+    RefereeProfile,
+    RulesConfig,
+)
+from utama_core.run import StrategyRunner
+from utama_core.strategy.examples.ball_placement_strategy import BallPlacementStrategy
+
+# ---------------------------------------------------------------------------
+# Configuration -- edit these to match your setup
+# ---------------------------------------------------------------------------
+
+GUI_PORT = 8080
+MY_TEAM_IS_YELLOW = True
+MY_TEAM_IS_RIGHT = True
+
+# ---------------------------------------------------------------------------
+# Referee profile
+#
+# All automatic rules are OFF. Commands come from the operator only.
+# auto_advance is also OFF so the state never transitions without you.
+# ---------------------------------------------------------------------------
+
+_REAL_TEST_PROFILE = RefereeProfile(
+    profile_name="ball_placement_real_test",
+    rules=RulesConfig(
+        goal_detection=GoalDetectionConfig(
+            enabled=False,
+            cooldown_seconds=1.0,
+        ),
+        out_of_bounds=OutOfBoundsConfig(
+            enabled=False,
+            free_kick_assigner="last_touch",
+        ),
+        defense_area=DefenseAreaConfig(
+            enabled=False,
+            max_defenders=1,
+            attacker_infringement=False,
+        ),
+        keep_out=KeepOutConfig(
+            enabled=False,
+            radius_meters=0.3,
+            violation_persistence_frames=30,
+        ),
+    ),
+    game=GameConfig(
+        half_duration_seconds=300.0,
+        kickoff_team="yellow",
+        force_start_after_goal=False,
+        stop_duration_seconds=2.0,
+        prepare_duration_seconds=3.0,
+        kickoff_timeout_seconds=10.0,
+        auto_advance=AutoAdvanceConfig(
+            stop_to_next_command=False,
+            prepare_kickoff_to_normal=False,
+            prepare_penalty_to_normal=False,
+            direct_free_to_normal=False,
+            ball_placement_to_next=False,
+            normal_start_to_force=False,
+        ),
+    ),
+)
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    referee = CustomReferee(
+        _REAL_TEST_PROFILE,
+        n_robots_yellow=1,
+        n_robots_blue=0,
+        enable_gui=True,
+        gui_port=GUI_PORT,
+    )
+
+    runner = StrategyRunner(
+        strategy=BallPlacementStrategy(),
+        my_team_is_yellow=MY_TEAM_IS_YELLOW,
+        my_team_is_right=MY_TEAM_IS_RIGHT,
+        mode="rsim",
+        exp_friendly=1,
+        exp_enemy=0,
+        full_field_dims=GREAT_EXHIBITION_FIELD_DIMS,
+        referee=referee,
+        show_live_status=True,
+    )
+
+    runner.run()
+
+
+if __name__ == "__main__":
+    main()

main.py

@@ -25,7 +25,7 @@ def main():
         strategy=RandomMovementStrategy(n_robots=2, field_bounds=custom_bounds, endpoint_tolerance=0.1, seed=42),
         my_team_is_yellow=True,
         my_team_is_right=True,
-        mode="rsim",
+        mode="grsim",
         exp_friendly=2,
         exp_enemy=0,
         replay_writer_config=ReplayWriterConfig(replay_name="test_replay", overwrite_existing=True),

utama_core/config/referee_constants.py

@@ -2,6 +2,7 @@
 
 BALL_KEEP_OUT_DISTANCE = 0.8
 BALL_PLACEMENT_DONE_DISTANCE = 0.15
+KICKER_READY_DISTANCE = 0.3
 OPPONENT_DEFENSE_AREA_KEEP_DISTANCE = 0.25
 PENALTY_BEHIND_MARK_DISTANCE = 0.4
 PENALTY_MARK_HALF_FIELD_RATIO = 0.5

utama_core/custom_referee/custom_referee.py

@@ -169,6 +169,15 @@ def set_command(self, command: RefereeCommand, timestamp: float) -> None:
         """Manual override — for operator use or test scripting."""
         self._state.set_command(command, timestamp)
 
+    def force_command(
+        self,
+        command: "RefereeCommand",
+        timestamp: float,
+        ball_placement_target=None,
+    ) -> None:
+        """God-mode override — bypasses the STOP-first guard."""
+        self._state.force_command(command, timestamp, ball_placement_target)
+
     # ------------------------------------------------------------------
     # Properties (read-only access for callers that need to inspect state)
     # ------------------------------------------------------------------