Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
84 commits
Select commit Hold shift + click to select a range
cbdff1d
Strategy branches can't change their opponents or reach outside their…
isaac0804 Oct 3, 2026
0c1654c
Strategy branches may add new tactics
isaac0804 Oct 3, 2026
ee0e727
Note that strategy branches can be worked on in parallel
isaac0804 Oct 3, 2026
f462ffe
GiveAndGo carrier gives up its no-receiver hold once per possession
isaac0804 Oct 3, 2026
1c29a4e
Support runs hold their target once reached; round-robins play full 6…
isaac0804 Oct 4, 2026
b4f8e50
Decoy-and-overload lets go once the enemy has the ball; frozen stalls…
isaac0804 Oct 4, 2026
5f97199
mirror_swap targets move off the defense-area edge; fpp passes every …
isaac0804 Oct 4, 2026
ed5868f
Free kicks can't be held forever by a defender standing too close
isaac0804 Oct 4, 2026
add0529
Strategy catalog: results from the first full-length (600s) round-robin
isaac0804 Oct 4, 2026
269447e
A ball over a goal line restarts in the corner, not in front of goal
isaac0804 Oct 5, 2026
fe347a2
Robots clearing a free kick go round the ball, not into the box margin
isaac0804 Oct 5, 2026
66e366f
go_to_ball: drop the no-op dribbler-back flip; the dribbler is on the…
isaac0804 Oct 5, 2026
4b48b51
GiveAndGo keeps its memory when robots join or leave its slot
isaac0804 Oct 5, 2026
52a1de8
In the sim, a no_progress restart waits for robots to clear the ball
isaac0804 Oct 5, 2026
53a5c36
ShadowAndMark markers stand goal-side of their opponent
isaac0804 Oct 5, 2026
b26f5b3
The side the replay doesn't record skips acceleration estimation
isaac0804 Oct 5, 2026
75fa3e6
Round-robin results for strategy-guard at b26f5b37
isaac0804 Oct 5, 2026
5664b9a
Round-robins measure the chances each side creates and concedes
isaac0804 Oct 5, 2026
ac2629c
One catalog of strategy signals: docs/signals.md
isaac0804 Oct 5, 2026
48cf9a0
Signal report: the main strategy signals of the final round-robin, in…
isaac0804 Oct 5, 2026
a89bfdf
README is a front page; docs get an index
isaac0804 Oct 6, 2026
721e7b1
System diagrams in Mermaid, matching the code
isaac0804 Oct 6, 2026
37fb06d
Keep the original system diagram
isaac0804 Oct 6, 2026
265670b
A stoppage ends the possession spell, so a restart's shot isn't credi…
isaac0804 Oct 6, 2026
a13e6f1
Strategy-branch guard closes the gaps Copilot found
isaac0804 Oct 6, 2026
314d472
Round-robin matches are 600 s of continuous play, not two halves
isaac0804 Oct 6, 2026
9a31d76
Scenario bench reports the strategy signals of each start
isaac0804 Oct 6, 2026
720ca8e
SwitchOfPlayTactic: a lone carrier plays the ball instead of holding it
isaac0804 Oct 6, 2026
cf6e102
Scenario bench: --play one start and watch what happened
isaac0804 Oct 6, 2026
df6ff8d
docs/pitch_zones.md: one set of names for the parts of the pitch
isaac0804 Oct 6, 2026
9627c08
Scenario bench: find starts by situation (--where, tags in --list-sce…
isaac0804 Oct 6, 2026
b6cb920
Hand-authored starts are played from the candidate's side
isaac0804 Oct 6, 2026
620d24e
Replay sidecar: a stage clock stopped at 0 is not a change
isaac0804 Oct 6, 2026
3221d7d
SwitchOfPlayTactic: a lone robot fetches the ball before playing it
isaac0804 Oct 6, 2026
4b5d0d4
keeps_mem_on_robot_change: an empty slot starts afresh
isaac0804 Oct 6, 2026
2f59d21
Strategy-branch guard: classmethods, wildcard imports, defaults, in-p…
isaac0804 Oct 6, 2026
1551d78
Danger is team possession, passes and shots in flight included
isaac0804 Oct 6, 2026
ba44058
Referee: the match clock counts playing time, and halves end
isaac0804 Oct 6, 2026
bac911c
Round-robins play two halves to full time
isaac0804 Oct 6, 2026
09fabac
Replay sidecar: the stage clock stands still in a stoppage
isaac0804 Oct 6, 2026
de3b352
three_slot: the robot on the ball attacks instead of clearing it blind
isaac0804 Oct 6, 2026
5059ee3
man_mark: stand goal-side of the opponent, as ShadowAndMarkTactic does
isaac0804 Oct 6, 2026
191752f
docs: record that kick_upfield clears at fixed power and leaves the p…
isaac0804 Oct 6, 2026
6fb2cf6
The teams change ends at half-time
isaac0804 Oct 6, 2026
1df2dfa
test_change_of_ends: check the keepers reach their new goals, not whe…
isaac0804 Oct 6, 2026
984d3ba
Referee: a kick-off waits for every robot to be in its own half
isaac0804 Oct 6, 2026
61dccbe
test_change_of_ends: say what the referee did and where every robot w…
isaac0804 Oct 6, 2026
ea041e4
The sim carries the robots to their new half at half-time
isaac0804 Oct 6, 2026
01cf486
A HALT resumes into the restart it interrupted
isaac0804 Oct 6, 2026
4461581
Roadmap: real-robot profiles and calibration plan
isaac0804 Oct 9, 2026
25f0790
Every goal kick is placed at the same spot
isaac0804 Oct 9, 2026
1b0f931
Referee: an aimless kick restarts where it was kicked (§6.2.3)
isaac0804 Oct 9, 2026
0776e48
round_robin: comments say the teams change ends at half-time
isaac0804 Oct 9, 2026
426be8a
overload_flow: each strategy counts its own possession streak
isaac0804 Oct 9, 2026
1bfb3b7
A ball out of bounds is charged to the robot that last touched it
isaac0804 Oct 9, 2026
8c2bfe5
Merge remote-tracking branch 'origin/main' into strategy-guard
isaac0804 Oct 9, 2026
24ef2c3
Remove unused files: start_test_env.sh, a dead module, old banks, the…
isaac0804 Oct 9, 2026
b3464e5
Motion-planning benchmark: the cited run lives in docs/, raw output i…
isaac0804 Oct 9, 2026
a8eac9c
Media and patches live with their kind: assets/clips/, vendor/rSim/pa…
isaac0804 Oct 9, 2026
f951483
rsoccer_simulator: remove upstream leftovers we never use
isaac0804 Oct 9, 2026
1604a79
pixi run main watches one match between two strategies
isaac0804 Oct 9, 2026
a804e05
Roadmap: strategy evaluation v2 (ladder, sampled worlds, one runner)
isaac0804 Oct 9, 2026
bfb0492
Remove dead real-robot scripts and the unused FIR filter
isaac0804 Oct 9, 2026
a6041dc
Real-mode receivers: game-controller packets arrive, geometry packets…
isaac0804 Oct 9, 2026
82914dd
Roadmap 10d: vision filter for real cameras
isaac0804 Oct 9, 2026
37da9de
round_robin --reuse stores each match as it finishes
isaac0804 Oct 10, 2026
6570bca
Merge branch 'vision-referee-fixes' into strategy-guard
isaac0804 Oct 10, 2026
ebee144
ladder.py: one candidate against a reference pool (evaluation v2, ste…
isaac0804 Oct 10, 2026
cc60454
referee_receiver_test: stop the receive thread spinning after its packet
isaac0804 Oct 10, 2026
db0137f
Evaluation tools: tools/tournament -> tools/evaluation, retire the ol…
isaac0804 Oct 10, 2026
50d00e9
Retire the bottom ten strategies from round-robins; drop the status l…
isaac0804 Oct 10, 2026
85ccdf7
Stale strategy references: match.py comment, tool examples, old resul…
isaac0804 Oct 10, 2026
f93d3c8
Sim PVP: refine each tick's vision once, mirror it for the opponent
isaac0804 Oct 10, 2026
e5af544
Merge branch 'repo-cleanup' into strategy-guard
isaac0804 Oct 10, 2026
1a4302a
round_robin --reuse keeps spot-check mismatches in summary.json
isaac0804 Oct 10, 2026
cea82a7
ProximityLookup: build on the first query
isaac0804 Oct 10, 2026
9a26f17
strategies.md: blind kick_upfield clearances measured, not the main o…
isaac0804 Oct 10, 2026
96148f6
Close roadmap 10a and the kick_upfield bug note
isaac0804 Oct 10, 2026
b80784f
GameHistory.add_game_frame: one key lookup per object
isaac0804 Oct 10, 2026
49885a2
VelocityRefiner: robots' acceleration reads the history in place
isaac0804 Oct 10, 2026
7903474
Merge branch 'frame-once' into strategy-guard
isaac0804 Oct 10, 2026
a17e279
Half-time: a robot past a line is carried onto the far one
isaac0804 Oct 10, 2026
e62c0b4
strategies.md, signal_report.md: the 2026-10-10 round-robin of the 12…
isaac0804 Oct 10, 2026
d7925b2
Motion-planning benchmark: four crowd scenarios from real match situa…
isaac0804 Oct 10, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ concurrency:
cancel-in-progress: true

jobs:
# A strategy branch may change strategy code only (tools/check_strategy_branch.py).
# A strategy branch may change only strategy code, not its opponents (tools/check_strategy_branch.py).
# Runs the base branch's copy of the checker, so the branch under test can't loosen it.
strategy-branch:
if: github.event_name == 'pull_request' && startsWith(github.head_ref, 'strategy/')
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,7 @@ replays
renders/
scratch/
scenario_bench_results/
benchmark_results/

# local agent-tool config dirs
.codex/
Expand Down
22 changes: 15 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ exists yet: say so in your change rather than guessing.
| Area | Paths | Doc | Notes |
|---|---|---|---|
| Strategy / tactics | `utama_core/engine/`, `strategy/`, `tactics/`, `skills/` | `docs/STRATEGY_DEVELOPMENT.md` | Engine changes are rare: a new primitive, not a new strategy |
| Strategy evaluation | `tools/tournament/`, `tools/scenario_bench.py`, `utama_core/scenario_bench/`, `utama_core/replay/`, `utama_core/analysis/` | `docs/STRATEGY_DEVELOPMENT.md` | Change evaluation and strategy in separate commits, so results stay comparable |
| Strategy evaluation | `tools/evaluation/`, `tools/scenario_bench.py`, `utama_core/scenario_bench/`, `utama_core/replay/`, `utama_core/analysis/` | `docs/STRATEGY_DEVELOPMENT.md`, `docs/signals.md` | Change evaluation and strategy in separate commits, so results stay comparable |
| Referee | `utama_core/custom_referee/` | `docs/custom_referee.md` | |
| Motion planning | `utama_core/motion_planning/`, `tools/motion_planning_benchmark.py` | `docs/motion_planning_comparison.md` | |
| Simulation | `utama_core/rsoccer_simulator/`, `vendor/rSim/` | `vendor/rSim/FORK_NOTES.md` | `vendor/rSim` is the C++ physics fork; `rsoccer_simulator` is the Python env on top of it |
Expand All @@ -28,7 +28,7 @@ exists yet: say so in your change rather than guessing.
One term per thing; reuse these instead of coining new ones.

- **Round-robin / tournament run** — every strategy config plays every other once
(`tools/tournament/round_robin.py`); writes `replays/tournament_<id>/summary.json`. The ground truth for
(`tools/evaluation/round_robin.py`); writes `replays/tournament_<id>/summary.json`. The ground truth for
"which strategy is better". Slow in full; with `--reuse` only matches whose code changed rerun.
- **Standings** — a round-robin's ranking. `round_robin.py` prints wins and draws;
`bench_vs_standings.py` uses points per match (3 a win, 1 a draw) and goal difference.
Expand All @@ -43,7 +43,11 @@ One term per thing; reuse these instead of coining new ones.
how far the bench and cheap proxy metrics agree with round-robin standings.
- **Motion planning benchmark** — `tools/motion_planning_benchmark.py`: the planner alone on
fixed scenarios. Unrelated to the scenario bench or any strategy.
- **Pitch zones** — defensive / middle / attacking third, left wing / centre / right wing, the
box, danger: defined once, with a diagram, in `docs/pitch_zones.md`. Use those names.
- **Catch rate** — a diagnostic reported from the bank, never a gate (±4–8 pts between runs).
- **Signal** — an interpretable measure of how a strategy plays (shots, danger conceded, real
ball losses, stalls ...), for explaining results, never a target. All listed in `docs/signals.md`.

## Repo map

Expand Down Expand Up @@ -74,7 +78,7 @@ One term per thing; reuse these instead of coining new ones.
for planner, simulator, vision and hardware work: see the Work areas table above.

**Before touching `utama_core/engine/`, `utama_core/tactics/`, `utama_core/strategy/`,
`utama_core/skills/`, or `tools/tournament/`/`docs/strategies.md`, read
`utama_core/skills/`, or `tools/evaluation/`/`docs/strategies.md`, read
[`docs/STRATEGY_DEVELOPMENT.md`](docs/STRATEGY_DEVELOPMENT.md)** — the tactic-kernel model,
referee-restart handling, lessons from past tactic bugs, and the observability tooling
(`MatchLog.trace()`, `render_window()`, the strategy catalog) all live there, scoped to
Expand Down Expand Up @@ -123,6 +127,9 @@ declarations) — check there before reintroducing one of them.

## Where things live

`docs/README.md` indexes every doc by kind and `docs/tools.md` every script; the ones agents
need most:

- `docs/STRATEGY_DEVELOPMENT.md` — tactic-kernel model, referee handling, writing a
`Tactic`, observability tooling. Read before any strategy-layer change.
- `docs/tactic_model_design_decisions.md` — kernel/Tactic/Partitioner design rationale.
Expand All @@ -132,10 +139,11 @@ declarations) — check there before reintroducing one of them.
- `docs/custom_referee_design_decisions.md` — referee rule-by-rule design decisions.
- `docs/roadmap.md` — running list of larger, not-yet-scheduled workstreams; check before
assuming a doc's claim about "not yet built" is still accurate — these drift.
- `docs/STRATEGY_DEVELOPMENT.md#reading-a-tournament-run` — every signal a tournament run
already records (loss kinds per strategy, pass receptions, fouls by robot and tactic, stall
diagnoses) and where it lives in `summary.json`. Check there before adding a metric; they
are diagnostics, not objectives.
- `docs/signals.md` — every signal we record about how a strategy plays (stalls, fouls, chances
created and conceded, ball losses, pass receptions, restarts), grouped by the question it
answers, with where it lives in `summary.json`, a reference range and what an off value means.
Read it when designing or debugging a strategy, and before adding a metric; they are
diagnostics, not objectives.
- `docs/strategies.md` — strategy catalog: status, description, and real round-robin
results per `build_*_kernel_strategy` factory.
- `utama_core/tests/engine/` and `utama_core/tests/strategy_runner/` — the real
Expand Down
Loading
Loading