diff --git a/AGENTS.md b/AGENTS.md index 5c520fb92..524c6c3f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -127,7 +127,7 @@ declarations) — check there before reintroducing one of them. those parameters today, so both levels run the same tests. CI runs `--level quick` on PRs, `--level full` on push to a branch, both with `--ignore-glob "**/*grsim*"` (grsim tests need an external grsim process CI can't provide). -- The root `conftest.py` turns off `StrategyRunner`'s browser vision stream for every test. +- `StrategyRunner`'s browser vision stream is off unless `enable_vision_stream=True`. In rsim, `run_test`'s `episode_timeout` is game time (rsim runs several times faster than real time), so a test's budget doesn't depend on machine load. - A known defect is a `strict=True` xfail on exactly the cases that hit it (see diff --git a/conftest.py b/conftest.py index 0f83608ee..0ec4f8c0a 100644 --- a/conftest.py +++ b/conftest.py @@ -86,17 +86,8 @@ def headless(pytestconfig): @pytest.fixture(autouse=True) -def _no_vision_stream(monkeypatch): - """Every StrategyRunner starts a browser vision stream by default: a frame rendered - each step and about 0.4 s to shut its HTTP server down. No test watches it, and it was - a third of the suite's time.""" - from utama_core.run.strategy_runner import StrategyRunner +def _reset_picker_state(): + """Pickers keep module-level state between calls; each test starts without it.""" from utama_core.strategy.pickers import reset_closer_to_ball_state reset_closer_to_ball_state() - - def _skip(self, http_port): # noqa: ARG001 - self.vision_stream = None - self._vision_stream_renderer = None - - monkeypatch.setattr(StrategyRunner, "_start_vision_stream", _skip) diff --git a/docs/README.md b/docs/README.md index 100fdee13..b09709a07 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,6 +14,7 @@ Every doc in this folder, by kind. New to the repo: the [README](../README.md) f - [visual_guide.md](visual_guide.md): the game drawn on the pitch from real replays (how each strategy plays, one match over time, a restart, the motion planner), what each picture has shown us, and how to draw it. - [setup_external.md](setup_external.md): grSim, the official GameController and AutoReferee. - [real_robot_setup.md](real_robot_setup.md): a test day with real robots: ssl-vision on its own laptop, WSL networking and USB, the radio, and the checks before a robot moves. +- [field_logs.md](field_logs.md): real robot game logs: format, record types, calibration analysis, dead-time trimming, and release packaging. - [contributing.md](contributing.md): editor setup, commits, pull requests and releases. ## Design rationale @@ -36,6 +37,7 @@ Every doc in this folder, by kind. New to the repo: the [README](../README.md) f - [roadmap.md](roadmap.md): larger open workstreams, and one-line pointers to finished ones. - [sim_realism.md](sim_realism.md): how far rsim is from real matches, the realism scorecard, and the plan to close the gap with measured, randomized physics. - [in_house_vision.md](in_house_vision.md): our own vision stack for lab days (per-session tag calibration, tags on robots), the experiments that decide it, and the 2026-10-22 test day's vision findings. +- [field_log_replay.md](field_log_replay.md): design for finding a moment in a field log and rerunning the decision code on its recorded inputs, and the physical setup's own errors (tag yaw and offset, kicker offset, cameras) as per-robot profiles. - [testing_gaps.md](testing_gaps.md): kinds of testing gap that let bugs through, numbered (code cites them by number). - [investigation_default_vs_lowblock_stalemate.md](investigation_default_vs_lowblock_stalemate.md): why `default` vs `low_block` stays 0-0; partly fixed. - [investigation_ball_contact_orientation_divergence.md](investigation_ball_contact_orientation_divergence.md): a robot pinned against the ball rotates away from contact; localized, not fixed. diff --git a/docs/STRATEGY_DEVELOPMENT.md b/docs/STRATEGY_DEVELOPMENT.md index 4b820a9c3..df41ca6bf 100644 --- a/docs/STRATEGY_DEVELOPMENT.md +++ b/docs/STRATEGY_DEVELOPMENT.md @@ -367,7 +367,11 @@ whoever runs it. value)` yourself from a `Tactic` or skill (guard with `if ctx.match_log is not None:`; it's `None` on tournament/CI runs, so traces can stay in). Examples: `skills/src/go_to_ball.py`, `tactics/give_and_go.py`. Enable with `match_log_path=` or `match.run_match(..., - run_dir=...)`; read back with `load_jsonl(path)`. + run_dir=...)`; read back with `load_jsonl(path)`. A run with a dashboard or a game log keeps one + in memory too: a plain value traced under a key naming a robot (`ctx.trace(game, f"shoot[{rid}]", + "turning to shoot")`) shows under that robot in the Live tab's Tactics panel and is noted in the + game log, so name the step a robot is on in words a tester reads (`AbstractStrategy.debug_status`). + While a restart or HALT drives a robot, the panel shows `referee · ` instead of its tactic. - **`render_window()` / `render_around_event()`** (`analysis/render_window.py`) — PNG of robot/ball trails over a window, optionally anchored on a `MatchLog` event. **Default to this over `load_frames_in_range()`**: a coordinate dump is expensive in context and easy to misread @@ -513,6 +517,8 @@ state to edit. Moments are not a gate on strategies: they pin shared-code bugs. | Same moment still failing after the fix | robot driving in | `keeps_clear` counted the ball placed onto a robot standing still | `20ca1974` | `test_moments.py` | | keep_out foul on their free kick | robot driving in | referee: the kicker moved the ball 0.75 m in the preparation stage; it was in play | `12b46412` | `test_free_kick_taken.py` | | Our placement times out (hand-made moment) | slow placer | placer drove through the ball toward a point behind it (planner ignores the ball in our placement) | `78685f79` (goes round it) | `test_referee_unit.py` (TestBallPlacementOursApproachAroundBall) | +| Real placer brushes the ball going round it; chases a ball rolling out with its back to it (field day 2026-10-27) | clumsy placer | detour kept only robot plus ball radius (~1 cm); faced the spot from the start; aimed behind a rolling ball | field-day-20261027 branch: 5 cm clearance (`_BALL_DETOUR_RADIUS_M`, also free kicks and penalties), faces the ball, meets a rolling ball on its path | `test_referee_unit.py` (TestBallPlacementOursApproachAroundBall) | +| STOP with the ball just out over the goal line: our robot drives into their keeper (field day 2026-10-27) | robot ignoring a robot | the clear-of-the-ball target, clamped back onto the pitch, was 0.23 m from the keeper standing on its line | field-day-20261027 branch: clearing targets keep `_ROBOT_SPACING_M` (2 robot radii + 10 cm) from every robot, moving on round the ball | `test_referee_unit.py` (TestClearingTargetsKeepOffRobots) | The last row matters on real robots only: in sim matches `StrategyRunner` teleports a placed ball to its target (`docs/custom_referee_design_decisions.md`, Ball placement), so our placer never diff --git a/docs/custom_referee.md b/docs/custom_referee.md index a1aac478e..5568f2110 100644 --- a/docs/custom_referee.md +++ b/docs/custom_referee.md @@ -45,7 +45,7 @@ Built in `_build_active_rules` (`custom_referee.py`), in this priority order; de | `OutOfBoundsRule` | live play | Free kick to the team that didn't touch last, placed 0.25m infield; over a goal line, a corner or goal kick in the corner, or, for a ball last touched in the kicker's own half that crossed the opponent's goal line untouched, a free kick from where it was touched (aimless kick, §6.2.3, Division B; `out_of_bounds.aimless_kick`, on in both profiles). Last touch: `rules/last_touch.py`'s colour-blind `infer_last_touch_team` (both teams' contact data; closest robot only when there is no prior attribution; unresolved rather than a default colour). | | `BallSpeedRule` | live play | Ground speed > 6.5 m/s, edge-detected; same last-touch attribution. Non-stopping (§8.4.2). | | `DoubleTouchRule` | `NORMAL_START` after a restart | Only the restart kicker (first toucher after arming) is barred; disarms when any other robot touches. Open-play release-and-reacquire dribbling is legal. Keeps `_prev_command` across `reset()` because `reset()` runs on the very transition it must observe. | -| `DefenseAreaRule` | live play | An extra defender (> `max_defenders`) touching the ball in its own area: penalty. An attacker touching the ball while at least partly in ours: non-stopping, 2 s re-raise (§8.4.2). | +| `DefenseAreaRule` | live play | An extra defender (> `max_defenders`) touching the ball in its own area: penalty. An attacker touching the ball while at least partly in ours: non-stopping, 2 s re-raise (§8.4.2). With `defense_area.enabled: false` (`human`, and the real examples' profiles) our robots also stop keeping out of the boxes: `StrategyRunner` sets `Field.defense_area_rules` from it, for the planners, tactics and restart positioning; a ball resting in our own box stays the keeper's. | | `KeepOutRule` | `DIRECT_FREE_*`, `PREPARE_KICKOFF_*` | Defending team within 0.5m for 30 consecutive frames: non-stopping, 2 s re-raise, restarts the free kick's 10 s clock (§8.4.3). Not during bare `STOP` or penalties, nor once a free kick is taken (stage 3 of the state machine: the ball moved 0.05m, so it is live). | | `PenaltyTimeLimitRule` | `NORMAL_START`/`FORCE_START` after `PREPARE_PENALTY_*` | Penalty still in play 10 s after its normal start: goal kick for the defenders (§5.3.5). | | `NoProgressRule` | live play | Ball hasn't moved 0.05 m in 10 s: `STOP` then `FORCE_START` where it lies, moved out of the opponent's defense area if it is inside it (`legal_restart_position`, §8.1). The clock waits for the ball to be in play (a `NORMAL_START` restart: 0.05 m of movement or the 10 s auto-in-play) and is held while the ball is inside either defense area. Last in the list, so a real foul on the same tick wins. | diff --git a/docs/custom_referee_gui.md b/docs/custom_referee_gui.md index 48fd7a5a8..52ae6b854 100644 --- a/docs/custom_referee_gui.md +++ b/docs/custom_referee_gui.md @@ -60,7 +60,7 @@ strategy_view.attach(server, runner, The Live tab then lists the choices per side with a Run button; Run on the one running restarts it. `StrategyRunner.replace_strategy` takes the new strategy at the next tick and only while -halted, so the page refuses otherwise. `examples/real_attacker_defender.py` offers its attacker +halted, so the page refuses otherwise. `examples/shooting_drill.py` offers its attacker and defender tactics this way. ## Commands and what robots do diff --git a/docs/field_log_replay.md b/docs/field_log_replay.md new file mode 100644 index 000000000..6487f10e7 --- /dev/null +++ b/docs/field_log_replay.md @@ -0,0 +1,144 @@ +# Field logs: finding a moment and replaying it offline (design) + +Status: design, 2026-10-28. Nothing here is built yet except what "Today" lists. + +## Why + +On the 2026-10-27 field day every bug was found the same way: a symptom someone saw ("it drives +sideways and back", "blue misses passes", "placement throws the ball away"), then a throwaway +script to find the moment in the log, then another to rebuild what the robot saw and decided at +that moment. The second step found every cause. Running the recorded camera packets through the +same refiners and tactic offline showed blue's receive point clamped to x 0.43, and the +attacker's hold point at (0.43, +0.07) wherever the ball was. Each script took 10-30 minutes +to write, and all of them were lost when `/tmp` was cleared. This doc designs one tool for the +whole loop, so a field symptom becomes a cause, and then a regression test, in minutes. + +## Today + +- Every real run records `replays/field/