my-botty/docs/run_cows_plan.md

Run Cows Route Plan

Goal

Add a stable run_cows route that can:

• create/open Secret Cow Level portal in Act 1,
• clear cows with safe movement and loot handling,
• exit cleanly and continue normal run rotation.

Scope

This plan is for implementation and testing in this repo only.
No behavior changes to existing routes unless needed for shared helpers.

Constraints

• Keep it compatible with current config style ([routes], [char], per-build sections).
• Prioritize stability over speed for first release.
• Avoid forcing hard dependencies on OCR for core route progression.

Route Design

1. Town prep in Act 1:
   • go to stash/cube workflow position.
   • ensure cube available.
2. Cow portal creation:
   • verify Wirt's Leg + Tome of Town Portal availability.
   • transmute in Act 1 town.
   • detect red portal reliably.
3. Entry and combat:
   • enter portal.
   • execute deterministic clear pattern (clockwise + center sweep).
   • run character-specific attack loop with timeout guard.
4. Loot and exit:
   • reuse existing pickit flow.
   • return through TP or save/exit based on safety state.

Code Changes (Planned)

1. Add new run module:
   • src/run/cows.py (name = "run_cows")
   • methods: approach(), battle()
2. Wire route registration:
   • include run_cows in route loader/dispatcher used by bot.py.
3. Town/cube helpers:
   • add minimal helper(s) for cube transmute flow if missing.
4. Pathing/templates:
   • add cow portal/town waypoint templates only as needed.
   • add robust fallback checks for portal detect/select.
5. Config/docs:
   • document run_cows in config/params.ini route comments.
   • add usage notes to README.md.

Config Additions (Planned)

In [char] or dedicated route section:

• cows_clear_timeout_s (default safe value, e.g. 90-150)
• cows_use_tp_exit (1/0)
• cows_repair_before_run (1/0, default 1)

Keep defaults conservative.

Safety & Recovery

• If portal creation fails: log once, abort current cow attempt, continue next route.
• If portal click fails: retry from known anchor position once.
• If in-combat timeout reached: force exit sequence and mark run failed.
• If inventory full during cows: run pickit stop logic and exit route early.

Character Compatibility Strategy

Phase 1 support:

• Blizz Sorc
• Hammerdin
• FoHdin

Phase 2 support:

• remaining builds with route-specific combat tuning.

Telemetry / Stats

Track in game_stats:

• run_cows attempts
• success/fail count
• elapsed duration
• rune/valuable item outcomes (already covered by global item tracking)

Test Plan

1. Unit-ish tests:
   • route registration includes run_cows
   • config parsing accepts route key without crash
2. Integration smoke (manual):
   • portal creation success path
   • missing Wirt’s Leg failure path
   • missing tome failure path
   • portal click retry path
3. Stability run:
   • 25+ games mixed with existing routes
   • verify no regression in Pindle/Trav/Diablo flows

Assets / Inputs Needed

• Screenshot set for:
  • Act 1 stash/cube interaction points
  • successful cow portal in town
  • entry location inside cows
• Optional:
  • map movement recording for an efficient clear loop.

Screenshot + Coordinates SOP (Detailed)

Why this matters

Cow route reliability depends on visual matching and deterministic interaction points.
Bad captures (cursor overlap, wrong UI state, mismatched lighting) are the #1 reason for unstable routes.

Environment lock before capture

1. Use the same D2R setup that bot runtime uses:
   • same resolution,
   • same UI scale,
   • same graphics preset,
   • same window mode.
2. Apply Botty auto settings before capture.
3. Keep panel state consistent:
   • inventory closed unless the step explicitly needs it,
   • item labels in known state,
   • no obstructing chat/quest panels.

Capture tools in this repo

• screenshot_tool.py
• quest_screenshot_tool.py
• quest_debug.py
• desktop_snap.py
• Graphic debugger hotkey from config/params.ini (advanced_options.graphic_debugger_key)

Capture types required per target

For every actionable object, collect both:

1. Full-context screenshot (for debugging and reproducibility)
2. Tight template crop (for matching)

Template crop rules:

• include only the unique visual feature + small margin,
• avoid cursor overlap,
• avoid tooltip overlap unless tooltip itself is the detection target,
• avoid over-cropping edges that change with animation.

Coordinate types to record

For each target interaction, record:

1. Screen/monitor click point used when interaction succeeds.
2. Whether template-center click worked.
3. Optional fallback click point if template-center is unreliable.
4. ROI used (if narrowed in code/tests).
5. Confidence range seen in quick manual validation.

Mandatory cows capture checklist (in order)

1. Act 1 town anchor (post-spawn)
   • full screenshot
   • possible anchor templates
2. Stash interaction
   • full screenshot near stash
   • stash template crop(s)
   • successful click coordinate(s)
3. Cube interaction/transmute context
   • inventory+cube state screenshot
   • transmute UI screenshot references
4. Cow portal in town (opened)
   • full screenshot with portal visible
   • portal template crops (2-3 variants)
   • portal click success coordinates
5. Cow level entry area
   • immediate post-load screenshot(s)
   • safe first-move anchor capture
6. Exit path reference
   • screenshot where exit action is normally triggered
   • any portal/escape interaction target needed

Variants to capture for robustness

Per critical template (stash, portal, entry anchor), capture:

• 3-5 samples with slight camera/position variation,
• at least one “busy background” sample,
• one sample with nearby NPC/player clutter if possible.

Validation pass before route coding

For each template candidate:

1. Verify it matches across the sample set at intended threshold.
2. Verify it does not false-match to nearby unrelated objects.
3. Verify click-at-center triggers the intended interaction.
4. Record accepted threshold and failure notes.

Reject templates that:

• only match at very low confidence,
• require exact pixel-perfect camera alignment,
• frequently collide with non-target objects.

File naming convention

Use deterministic names aligned with route semantics, e.g.:

• A1_COW_PORTAL_0
• A1_COW_PORTAL_1
• A1_STASH_REF_0
• COW_ENTRY_ANCHOR_0

Keep source full screenshots in a dated debug folder and final template crops in the templates location used by the project.

Capture log format (what testers should write down)

For each target:

• template_name
• capture timestamp
• location/context
• successful click point(s)
• confidence range observed
• notes on failed attempts

Inputs needed from testers (you + friend)

Provide:

1. ZIP/folder of full screenshots + template crops.
2. Short markdown/text capture log using format above.
3. Character/build used during capture (Blizz Sorc / FoH / Hammerdin).
4. Any observed instability notes (miss-clicks, wrong target matches, etc.).

Acceptance criteria for capture package

Capture package is ready for implementation when:

• all mandatory checklist targets are present,
• each critical target has multi-sample variants,
• at least one tester validated successful interaction per target,
• naming is consistent and unambiguous.

Rollout

1. Land Phase 1 behind route opt-in (order=... ,run_cows).
2. Keep disabled by default in examples until 10+ stable sessions.
3. Promote to documented standard route after stability threshold.

Definition of Done

• run_cows can run repeatedly without manual intervention.
• Failure modes recover without crashing whole bot loop.
• Route is documented in params.ini and README.md.
• CI/lint/tests pass for changed files.