my-botty/docs/auto_build_plan.md

Auto Skill + Attribute Allocation Plan

Goal

Add an optional system that automatically assigns:

• skill points
• attribute points

based on:

• active character profile (blizz_sorc, fohdin, hammerdin, etc.)
• current character level

without breaking existing manual setups.

Scope

• Planning and architecture for Botty repo.
• No forced behavior changes: feature must be opt-in.

Requirements

1. Determine current level reliably at runtime.
2. Select a build template by character profile.
3. Apply points safely only when unspent points exist.
4. Record every allocation in logs/events for audit/replay.
5. Abort safely on uncertainty (wrong UI state, OCR mismatch, missing templates).

Current Level Detection Strategy

Primary path

Use player_bar.get_experience() (already used in game_stats.log_exp) to derive level from XP table.

Secondary fallback

Open character panel (C) and OCR level/name line directly from upper-left panel region.

Tertiary fallback

If OCR fails repeatedly:

• keep previous known good level for session,
• do not allocate points until confidence is restored.

Confidence rules

• Require two consistent reads before first allocation in a session.
• Reject impossible jumps (e.g., +5 levels at once).
• Persist last_known_level in session stats snapshot.

Build Template Model

Add config-backed build templates, e.g.:

• config/auto_builds/blizz_sorc.ini
• config/auto_builds/hammerdin.ini
• config/auto_builds/fohdin.ini

Each template defines per-level targets:

• desired skill totals by level milestone
• desired attribute distribution (str/dex/vit/ene)

Example concept:

• Level 1-17: early progression targets
• Level 18-29: mid-game unlock path
• Level 30+: core skill maxing order

Runtime Flow

1. Enter town and open character/skill UI.
2. Detect level and unspent points.
3. Load template for Config().char["type"].
4. Compute delta between current allocation and target-at-level.
5. Apply points stepwise:
   • attributes first (optional toggle),
   • skills second.
6. Verify post-apply state.
7. Log allocation summary and persist snapshot.

Safety Guards

• Only run in town.
• Require stash/vendor windows closed.
• Hard cap per cycle (e.g., max 10 clicks per stat/skill group).
• On mismatch/timeout:
  • stop allocation immediately,
  • screenshot + structured error event,
  • continue bot without crashing.

Config Additions (Planned)

In [char] or new [auto_build] section:

• auto_assign_skills=0/1
• auto_assign_attributes=0/1
• auto_build_profile= (defaults to char.type)
• auto_build_check_every_x_games=
• auto_build_safe_mode=1 (extra verification)

Logging / Telemetry

Add structured events:

• auto_build_check_started
• auto_build_level_detected
• auto_build_points_detected
• auto_build_applied
• auto_build_skipped
• auto_build_error

Include:

• profile
• level
• points spent
• before/after snapshots

UI / Input Dependencies

Need stable template references for:

• character panel level region
• unspent attribute points indicator
• unspent skill points indicator
• individual plus-buttons for stats/skills

Test Plan

1. Unit tests:
   • level-to-target mapping
   • delta computation
   • guard conditions
2. Integration dry-run mode:
   • compute and log planned actions without clicking.
3. Live smoke tests per profile:
   • blizz_sorc, hammerdin, fohdin
4. Regression:
   • ensure normal runs unaffected with feature disabled.

Inputs Needed From You

1. Screenshots for each supported class at:
   • character panel open,
   • skill tree open,
   • visible unspent points.
2. Preferred leveling templates:
   • exact skill priority order by level range.
   • attribute rules (e.g., str to gear breakpoint, then vit).
3. Whether respec-aware logic is needed in v1.

Rollout Phases

1. Phase 1: Level detection + dry-run planner only.
2. Phase 2: Attribute auto-assign (safer, fewer UI branches).
3. Phase 3: Skill auto-assign with full verification.
4. Phase 4: Expanded profile templates + docs.

Definition of Done

• Feature is opt-in and stable for blizz_sorc, hammerdin, fohdin.
• Level detection is reliable with fallback behavior.
• No crash on detection/allocation failure.
• Full logs available for every auto-allocation decision.