ba-auto-daily

Personal automation for Blue Archive JP daily tasks (mailbox, cafe, ...), driven by desktop control (xdotool/scrot) against the real PC/Steam/Proton client.

How it's wired together

Two machines are involved:

• nik-macbookair (this Mac) — where the code is edited. The game does not run here and none of this can be tested locally.
• nik-gpu (Linux) — where the actual Blue Archive client runs under Steam/Proton, and where every command below actually executes.

Call path once deployed to nik-gpu:

~/ba_dailies.sh [command]      <- thin Bash launcher, no game logic
      |
      v
~/ba_daily.py [command]        <- Python CLI, dispatches to a task
      |
      v
~/ba_auto/tasks/<command>.py   <- the actual click/verify logic

ba_dailies.sh only picks the venv Python and execs ba_daily.py. All real logic — clicking, screenshotting, verifying game state — lives in Python under ba_auto/.

Current task status:

Command	Implementation
mailbox	Real Python (ba_auto/tasks/mailbox.py). Verifies the mailbox panel actually opened (via a pixel-color probe, driver.color_at) before clicking "claim all" or pressing any further keys. Retries the open-click up to 3 times before giving up safely.
cafe	Real Python (ba_auto/tasks/cafe.py). Verifies each room/dialog transition the same way as mailbox before acting; sparkle detection runs in-process via ba_auto/detector.py instead of shelling out per click. See "Fixed: the exit-game dialog bug" below for what this replaced, and plan.md Phase 6 follow-up for the multi-scale detection + persistent-polling changes made after a "farming affection doesn't happen" report.
stamina	Real Python (ba_auto/tasks/stamina.py). Opens the Mission panel and claims via its bulk "一括受取" button (Enter key) when enabled. Does not touch the Pyroxene Purchase (青輝石購入) menu's free-AP claim — that's a real-money purchase screen and was deliberately left unautomated; see plan.md Phase 8.
story_sweep	Real Python (ba_auto/tasks/story_sweep.py). Spends AP — opt-in only, not part of the default flow. Sweeps a config-driven list of exact (region, stage, count) targets (config.STORY_SWEEP_TARGETS — edit this before running for real, it ships with a placeholder), navigating to each via OCR (region-number readout + stage-label matching) rather than a random pick. Verifies the MAX/+ click actually raised the count before starting the sweep, clicks through the AP-usage-confirmation dialog, and closes the stage-info modal via its own X button afterward (Escape doesn't close it — confirmed live). See plan.md Phase 10.
shop_common	Real Python (ba_auto/tasks/shop_common.py). Spends credits — opt-in only, not part of the default flow. Buys a config-driven list of exact (row, col, name, expected_price) targets (config.COMMON_SHOP_TARGETS) from the 通常アイテム tab: OCR-verifies each item's price before checking its box, then clicks the bulk 購入 button and confirms through the purchase dialog. Live-tested with real purchases. See plan.md Phase 11.
shop_tactical	Real Python (ba_auto/tasks/shop_tactical.py). Spends tactical coin — opt-in only, not part of the default flow. Same flow as shop_common against the 戦術対抗戦 tab and config.TACTICAL_SHOP_TARGETS. Live-tested with real purchases. See plan.md Phase 11.
lesson	Real Python (ba_auto/tasks/lesson.py). Spends lesson tickets — opt-in only, not part of the default flow. Sweeps every unlocked region's schedule grid, picking the highest-affection available lesson each time (via detector.read_int_on_heart_badge OCR on each portrait's heart-shaped badge) until tickets or lessons run out. Live-tested with real tickets spent. See plan.md Phase 12.

Prerequisites on nik-gpu

One-time, or after a dependency change:

ssh nik-gpu
which xdotool scrot tesseract   # all three must be installed

tesseract (the OCR engine story_sweep uses for region/stage-label reads) needs sudo apt install tesseract-ocr — setup.sh checks for it but can't install it for you, since sudo needs an interactive password. setup.sh (see below) creates the Python venv (including pytesseract) and checks all three tools for you.

Deploying your changes

From nik-macbookair, in the repo root:

rsync -av --delete \
  --exclude='.git/' --exclude='__pycache__/' --exclude='*.pyc' \
  --exclude='.claude/settings.local.json' --exclude='graphify-out/' \
  --exclude='screenshots/' \
  ./ nik-gpu:~/repo/ba-auto-daily/

ssh nik-gpu "cd ~/repo/ba-auto-daily && ./setup.sh"

setup.sh copies the synced files into the fixed runtime paths (~/ba_dailies.sh, ~/ba_daily.py, ~/ba_auto/, ~/ba_assets/) and (re)installs the venv. Re-run both commands any time you change code — there is no auto-deploy.

Running it

The game must already be running on nik-gpu (window titled BlueArchive). Then, on nik-gpu:

~/ba_dailies.sh                # default: mailbox, cafe, then stamina
~/ba_dailies.sh mailbox        # just mailbox
~/ba_dailies.sh cafe           # just cafe
~/ba_dailies.sh stamina        # just the Mission-panel bulk claim
~/ba_dailies.sh story_sweep    # spends AP -- not in the default flow, run explicitly
~/ba_dailies.sh shop_common    # spends credits -- not in the default flow, run explicitly
~/ba_dailies.sh shop_tactical  # spends tactical coin -- not in the default flow, run explicitly
~/ba_dailies.sh lesson         # spends lesson tickets -- not in the default flow, run explicitly

You can also run these remotely without a separate ssh login step:

ssh nik-gpu "~/ba_dailies.sh mailbox"

Tab completion

setup.sh installs bash tab-completion for the phase argument (~/ba_dailies.sh sto<TAB> -> story_sweep) automatically: it copies completions/ba_dailies.bash to ~/.ba_dailies_completion.bash and adds a source line to ~/.bashrc (skipped if already present, so re-running setup.sh doesn't duplicate it). Open a new shell (or source ~/.bashrc) on nik-gpu to pick it up. The completion list is queried live from ba_daily.py --list-commands rather than duplicated in the completion script, so it can't drift when a task is added or renamed.

Exit code 0 means the script ran to completion without a Python exception — it does not by itself guarantee the in-game action succeeded. mailbox, cafe, and stamina all log what they actually detected and did (or why they safely aborted), so check the log output, not just the exit code.

How to watch/verify it

• Easiest: watch it live. If you have Moonlight (or similar) streaming nik-gpu's desktop, just open that and run the command from another terminal — you'll see the clicks happen in real time.
• No stream handy: pull a screenshot after the fact.

  ssh nik-gpu "DISPLAY=:0 XAUTHORITY=/run/user/1000/gdm/Xauthority scrot -o /tmp/check.png"
  scp nik-gpu:/tmp/check.png .
  open check.png
  

• Read the log output. Each task prints what it's doing, e.g. mailbox prints panel not detected after click (attempt N/3) if a click misses, and nothing to claim vs claiming all depending on what it found.

Fixed: the exit-game dialog bug

Live-testing both mailbox and cafe surfaced the same real bug in the original, unverified click sequences (see plan.md Phases 5–6 for the full writeup): a slightly-off icon coordinate occasionally caused a missed click, and the fixed sequence blindly kept going — clicking, pressing Enter, pressing Escape — with no idea whether any of it landed. The trailing Escape ended up hitting the bare home screen, which triggers Blue Archive's own "Exit the game?" confirmation dialog. cafe's sequence is much longer than mailbox's (open → pat loop ×15 → switch room → pat loop ×15 → claim income → exit), so a missed click there had more room to cascade.

Both mailbox.py and cafe.py now guard against this: they verify state via pixel-color probes before acting, retry a bounded number of times on a missed click, and abort safely (no further keypresses) instead of guessing. This was verified against the live game, including an actual income claim (gold and AP increased as expected) and a real sparkle detect-and-click.

That said, this is one round of live testing, not exhaustive coverage — see plan.md Phase 6 "Not verified" for open risks (rank-up popups mid-loop, long-run camera zoom/pan drift). If you ever see an unexpected confirmation dialog while running either command, press Escape/Cancel, never Enter/OK, until you've confirmed what it's asking.

Local checks (nik-macbookair)

The game can't run here, so this only catches syntax errors, not behavior:

bash -n ba_dailies.sh
python3 -m py_compile ba_daily.py ba_auto/*.py ba_auto/tasks/*.py

Real verification only happens by actually running against the live game on nik-gpu, per "How to watch/verify it" above.

More detail

• CLAUDE.md — architecture rules and conventions for this repo.
• plan.md — feature-by-feature migration status and backlog, including the mailbox/cafe exit-game-dialog bug writeup.
• ba_auto/reference_notes/mapping.md — maps each feature to its baas-reference source.