# AzerothAngler — Comprehensive User Guide

## Quick Start

1. **Open the addon**: `/aa` or `/angler`
2. **View the main dashboard** with Overview tab showing current fishing zone, equipment, and session stats
3. **Set up your fishing gear** via the Equipment tab (see [Gear Sets](#gear-sets) below)
4. **Cast and fish** — the addon will handle lure attachment and tracking

---

## Core Features

### Double-Click Cast (Important!)

**⚠️ Requires Active Fishing Gear Set**

The **double-click cast** feature (right-click twice to cast) only works when you have a **fishing gear set equipped in the Equipment Manager**.

#### How It Works

1. Navigate to the **Equipment tab** in AzerothAngler
2. **Select or create a fishing gear set** from your Equipment Manager
   - This set should contain your fishing pole/tool, appropriate attire, and any enchants
   - Set must be saved in Blizzard's native Equipment Manager
3. Once a gear set is selected, the addon has the **fishing tool in scope** and can bind the double-click keystroke
4. **Right-click twice rapidly** (within ~300ms) to cast fishing line
5. The addon will:
   - Automatically attach the best available lure (if "Auto-Attach Lure" is enabled and lure is available in bags)
   - Display remaining lure duration in the lure card countdown
   - Track catches in the Session tab

#### Why a Gear Set Is Required

- The addon must **verify that a fishing tool is actually equipped** before enabling the double-click binding
- Equipment Manager gear sets provide a **reliable way to confirm** your fishing pole/rod is in the correct slot
- This prevents accidental casting with a dagger or staff equipped
- If no gear set is selected, the double-click binding is **disabled for safety**

#### Troubleshooting Double-Click

If double-click isn't working:

1. **Check Equipment tab** — Is a fishing gear set selected? (Green checkmark or highlight indicates active set)
2. **Verify the set contents** — Must contain a fishing pole or modern profession fishing tool
3. **Equip the set manually** — Click the set name in Equipment Manager to activate it in-game
4. **Check the key binding** — The double-right-click binding is automatic; no manual key setup needed
5. **Try again** — Cast should work once the gear set is confirmed equipped

---

### Lure Management

#### Auto-Attach Lure

When enabled, the addon automatically attaches the best available fishing lure to your equipped fishing tool when you cast.

**Requirements:**
- At least one fishing lure in your bags (consumable bait items)
- "Auto-Attach Lure" toggle is enabled in Settings or Tackle tab
- A gear set is equipped (for double-click; manual cast works without a gear set)

#### Manual Lure Selection

Use the **Tackle tab** to:
- **Prefer a specific lure** — Select your favorite from the list (addon remembers your choice)
- **View lure inventory** — See all available lures and their quantities
- **Toggle auto-attach** — Enable/disable automatic lure attachment on cast

#### Lure Duration

The **main dashboard lure card** displays:
- **Status**: "Active" (lure attached) or "Missing" (no lure, or timer expired)
- **Countdown**: Remaining time on the lure (e.g., "9:58" for 10-minute lures)
- **Compact tracker**: Also shows "Lure: Active" status

---

### Gear Sets

#### Setting Up Fishing Gear Set

1. Open **Equipment Manager** (Blizzard native UI: `Ctrl+E` or spellbook → equipment)
2. Create a new set:
   - Name: "Fishing", "Fishing Gear", or similar
   - Drag equipment into the set:
     - **Fishing rod/tool** (main hand slot)
     - **Appropriate gear** (cloak, ring, trinkets for fishing bonus if desired)
     - **Enchantments** (rod enchants for better skill)
3. **Save the set**
4. In AzerothAngler **Equipment tab**, select this set from the dropdown
5. **Equip the set** by clicking it in Equipment Manager or the addon's Equipment tab

#### Switching Gear Sets

If you use multiple equipment sets (e.g., PvP, dungeon, fishing):
- **Always equip your fishing set before double-click casting**
- The addon detects the currently equipped set
- If you switch to a PvP set without equipping fishing set first, double-click is disabled

---

## Dashboard & UI

### Main Tabs

| Tab | Purpose |
|-----|---------|
| **Overview** | Current zone, lure status, equipment, quick stats |
| **Equipment** | Fishing gear set selection and verification |
| **Tackle** | Lure selection, preferred bait, auto-attach settings |
| **Watcher** | Zone-specific fish availability and hotspot tracking |
| **Session** | Cast/catch history, statistics, voyage archive |
| **Atlas** | Zone rates, pool density, recipes, market data |
| **Settings** | Audio, UI visibility, debug, reset options |

### Compact Tracker

Float a compact frame showing:
- **Fishing zone** (e.g., "Dornogal")
- **Lure status** (e.g., "Lure: Active")
- **Recent catch** (most recent fish caught)

Toggle with `/angler compact`

---

## Commands Reference

| Command | Function |
|---------|----------|
| `/aa` | Open main dashboard |
| `/angler` | Open main dashboard |
| `/angler options` | Open Settings tab |
| `/angler equipment` | Show Equipment tab (gear set selection) |
| `/angler tackle` | Show Tackle tab (lure selection) |
| `/angler compact` | Toggle compact tracker frame |
| `/angler watcher` | Show Watcher tab (zone fish data) |
| `/angler atlas` | Show Atlas tab (zone rates & recipes) |
| `/angler session` | Show Session tab (catch history) |
| `/angler sleep` | Pause casting helpers (Sleep mode) |
| `/angler wake` | Resume casting helpers (Wake mode) |
| `/angler scan` | Show bobber scan guide |
| `/angler scan mode` | Cycle scan mode (XY, Elevation, etc.) |
| `/angler scan wider` | Increase scan width |
| `/angler scan narrower` | Decrease scan width |
| `/angler mini` | Toggle minimap button |
| `/angler debug` | Open debug console |
| `/angler debug clear` | Clear debug log |
| `/angler reset` | Reset addon to defaults |
| `/angler restore` | Restore UI frames to default positions |

---

## Advanced Settings

### Audio Options

Toggle fishing-related sounds:
- **Cast sound** — Play a sound effect when you cast
- **Catch alert** — Play a sound or show alert when you catch a fish
- **Access Settings → Enhancement** to configure

### Sleep / Wake Mode

Temporarily disable casting helpers without unloading:

```
/angler sleep   # Disables double-click, auto-lure, auto-cast
/angler wake    # Re-enables catching helpers
```

Useful when:
- AFK or tabbed out (prevent accidental casts)
- Switching to non-fishing activities temporarily
- Testing or troubleshooting

### Debug Console

Access detailed logs and errors:

```
/angler debug       # Open debug console
/angler debug clear # Clear error log
```

Shows:
- Protected function call errors
- Event firing logs
- Lure attachment attempts
- Gear set changes

---

## Troubleshooting

### "Fishing unavailable" message

**Cause**: No fishing rod/tool equipped, or fishing skill not learned

**Solution**:
1. Equip a fishing rod or modern profession fishing tool
2. Select your gear set in Equipment tab
3. Verify fishing skill is learned (check spellbook)

### "Active" lure not displaying countdown

**Cause**: Lure data not synced with UI refresh (rare race condition)

**Solution**:
1. Cast again to refresh lure state
2. Switch zones and return
3. Toggle `/angler sleep` then `/angler wake`

### Double-click not working

**Cause**: No fishing gear set equipped (see [Double-Click Cast](#double-click-cast) section)

**Solution**:
1. Open **Equipment tab** in AzerothAngler
2. Select your fishing gear set from dropdown
3. **Equip the set** (click it in Equipment Manager or addon UI)
4. Try double-right-click again

### Auto-attach not working

**Cause**: Protected function restrictions (Blizzard API safety)

**Note**: WoW restricts lure attachment to secure user-input contexts. The addon applies lures automatically on **direct player input** (double-click cast) and from **specific hardened events**. Deferred timers cannot apply lures.

**Workaround**:
1. Ensure a fishing lure is in your bags
2. Double-click to cast (triggers auto-attach)
3. If lure still doesn't attach, manually apply via Tackle tab

### Gear set not being detected

**Cause**: Gear set created in-game but not visible to addon

**Solution**:
1. Verify set exists in Equipment Manager (Ctrl+E in-game)
2. Close and reopen AzerothAngler
3. Select the set again from Equipment tab dropdown

---

## Tips & Best Practices

### Maximize Fishing Efficiency

1. **Set up a fishing gear set** with your best fishing skill-boosting gear
2. **Select a preferred lure** in Tackle tab (addon remembers it)
3. **Enable Auto-Attach** in Settings
4. **Use double-click casting** — hold `Down` on mouse wheel or button to rapid-fire casts
5. **Monitor the Watcher tab** for zone-specific rare catches

### Batch Fishing Sessions

1. Open **Session tab** to track catches
2. Session auto-records all casts and catches
3. Review "Recent Voyage" for past sessions
4. Addon calculates skill-up per hour and cost-per-fish

### Integration with Auctionator

The Atlas tab shows **market pricing** if Auctionator is installed:
- Fish value per unit
- Lure cost ROI
- Relative profitability by zone

---

## FAQ

**Q: Can I double-click cast without a gear set?**  
A: No. The addon requires a gear set to verify a fishing tool is equipped. This is a safety feature to prevent accidental casts with wrong equipment. However, you can still manually cast the fishing spell without double-click.

**Q: Why does the addon need Equipment Manager?**  
A: Equipment Manager is the most reliable way to confirm a fishing tool is in the correct slot. It avoids false positives and accidental casts.

**Q: Can I use a legacy fishing pole (like from older expansions)?**  
A: Yes! The addon supports legacy rods, modern profession fishing tools, and spell-based fishing.

**Q: What if I don't have any lures?**  
A: The lure card will show "Missing" and auto-attach is disabled. Buy lures from the auction house or craft them if you have fishing recipes.

**Q: Does the addon work with Engineering lures?**  
A: Yes, all consumable fishing bait items are supported. Select your preferred lure in the Tackle tab.

---

## Support & Feedback

For bugs, feature requests, or feedback:
- Check the **debug console** (`/angler debug`) for error details
- Review **CHANGELOG** files for version history
- Verify you're using the latest addon version

---

**Last Updated**: v2.1.15  
**Addon**: AzerothAngler  
**Game**: World of Warcraft (Retail)
