# HV Unified — Design Specification (post-analysis synthesis)
## What we learned from 750KB of source code across 4 scripts

=============================================================================

## FILES IN KNOWLEDGE BASE

| File | Size | Lines | Source |
|------|------|-------|--------|
| Monsterbation 1.4.1.2 | 163KB | 2,402 | Forum attachment |
| jpx 2026.07.06 | 270KB | 6,215 | Forum attachment |
| HV Utils 4.2.3 | 416KB | 9,710 | Forum attachment |
| monsterbation-battle-patterns.md | 46KB | 967 | Our analysis |
| jpx-analysis.md | 34KB | - | Our analysis |
| HVUT_4.2.3_analysis.md | 32KB | - | Our analysis |
| **Total analyzed** | **~750KB+** | **18,327 lines** | |

Plus 4 community preset files for jpx rules.

=============================================================================

## KEY ARCHITECTURAL PATTERNS (cross-script)

### 1. DOM-clicking, NOT HTTP POSTs
ALL scripts click existing page elements. None construct raw HTTP requests.
The game's built-in onclick/onmouseover handlers do all the work.
This is the single most important pattern for staying within the rules.

### 2. Dummy Element Trick
Monsterbation and our script both use a hidden div to trigger game handlers:
```js
dummy.setAttribute('onclick', spell.getAttribute('onmouseover'));
dummy.click(); spell.click(); monster.click();
```

### 3. Page Detection by DOM, NOT URL
jpx and HV Utils both check for specific elements rather than URL patterns:
- `#textlog` → battle page
- `#navbar` + specific links → bazaar/character/shrine/etc.
- `#riddlemaster` → anti-bot popup

### 4. localStorage for Persistence
All three scripts use localStorage extensively:
- Monsterbation: `HVmbcfg`, `HVmbp`, `HVmonsterData`, etc.
- jpx: `jpx_*` prefixed keys + IndexedDB for battle history
- HV Utils: `hvut_*` + `hvuti_*` prefixed keys, namespaced per server

### 5. Battle Log MutationObserver
jpx uses a MutationObserver on `#textlog` as the primary event loop.
This fires on every server response (new HTML injected by the game engine).
Our script adopts this pattern.

### 6. Spell Detection by onmouseover Text
All scripts find spells by searching for divs whose onmouseover attribute
contains the spell name. No hardcoded spell IDs needed.

### 7. Vitals by Bar Width Ratios
HP/MP/SP all derived from `img.style.width` / base_width.
Different bases for persistent (414) vs isekai (207/496/190).

### 8. Monster Detection by onclick Attribute
Alive monsters have `onclick`; dead ones don't. Simple and reliable.

=============================================================================

## WHAT EACH SCRIPT EXCELS AT

| Feature | Monsterbation | jpx | HV Utils |
|---------|:---:|:---:|:---:|
| Hover-based attacks | ★★★★★ | ★★ | — |
| Keyboard shortcuts | ★★★★ | ★★★★ | — |
| Conditional rule engine | ★★ | ★★★★★ | — |
| Battle statistics | ★★★ | ★★★★★ | — |
| Buff/cooldown display | ★★★★★ | ★★★★ | — |
| Config/profile system | ★★★★ | ★★★ | ★★ |
| Out-of-battle shop | ★ (CrunkJuice) | ★★ | ★★★★★ |
| Shrine automation | — | — | ★★★★★ |
| Monster lab | ★ (CrunkJuice) | — | ★★★★ |
| MoogleMail | — | — | ★★★★★ |
| Training queue | — | — | ★★★★★ |
| RE timer | ★ (CrunkJuice) | ★ | ★★★★ |
| Market integration | — | ★★★ | ★★★★★ |
| Equipment management | — | — | ★★★★★ |
| Fighting style auto-detect | — | ★★★★★ | — |
| Level-progression aware | — | — | — |

The gap: NO script handles the full level 1→500 progression journey.
jpx says "Lv.300+ recommended." Monsterbation assumes you know what you're doing.
HV Utils is all out-of-battle. Our unified script fills this gap.

=============================================================================

## IMPLEMENTATION STATUS — Phase 1 (Current)

### ✅ Done:
- Page detector (battle, bazaar, arena, shrine, equipshop, etc.)
- Battle state parser (vitals, monsters, buffs, spells, skills)
- Level detection & tier auto-selection
- 4 strategy tiers: Novice (1-50), Adept (50-150), Veteran (150-300), Master (300+)
- Action system: castSpell, useItem, attackMonster, useSkill, toggleSpirit
- Monster targeting: findWeakestMonster, findStrongestMonster
- Debuff tracking: checkMonsterDebuff
- Keybinding: hotkey + modifier support, toggle hover, force cure
- Hover system: mouse enter monster → execute action
- Monster numbering in battle
- RE timer placeholder
- Equipment shop: Quick Sell (≤ quality) button
- Shrine: Bulk Shrine button
- MutationObserver on battle log
- Console API: window.HV.getState(), .getAction(), .execute()

### 🔜 Pending (Phase 2-4):
- Cooldown display on quickbar
- Buff duration counters
- Alert colours (low HP, spark, expiring buffs)
- Spirit Stance auto-management
- Elemental weakness matching from monster DB
- Monster HP database (track HP values to show numbers)
- Settings panel (press , to open)
- Profile/persona/set switching support
- Isekai mode detection
- Equipment shop: salvage vs sell comparison
- Training queue with cost calculation
- MoogleMail: search, preview
- Monster lab: crystal feeder, morale display
- Market price integration
- Battle statistics & damage tracking
- Arena completion tracking
- PXP simulator for Item World
- Import/export battle configs (like jpx presets)
- Full conditional rule engine (for master tier custom rules)

=============================================================================

## DESIGN DECISIONS

1. **Single file, no build step** — users install directly as Tampermonkey script
2. **Vanilla JS, no dependencies** — works in any browser with Tampermonkey
3. **Progressive enhancement** — features activate based on level/detected capabilities
4. **Safe-by-default** — auto-buffs only maintain, never waste MP below thresholds
5. **Opt-in automation** — out-of-battle features have explicit buttons, not auto-fire
6. **Rules-compliant** — one key press = one action. No multi-turn sequences.
7. **Console API** — power users can script via window.HV

=============================================================================

## INSTALLATION

1. Install Tampermonkey extension in your browser
2. Open Tampermonkey dashboard
3. Create new script, paste hv-unified.user.js
4. Save. Script auto-runs on hentaiverse.org

## USAGE

- **Q key**: Execute recommended action (configurable)
- **H key**: Toggle hover mode (auto-attack on mouse-over monsters)
- **C key**: Force cast Cure/Full-Cure
- **Console**: `HV.getAction()` → see what the script would do next
| Console: `HV.set('cureHP', 0.5)` → change cure threshold

=============================================================================

## FORUM-SOURCED PLAYER KNOWLEDGE (added 2026-07-20)

We now have direct access to the e-hentai forums. Key threads saved to references/forum-*.md:

### What the community actually cares about (vs what we assumed)

1. **Stats don't matter much** — Noni (mod, L500): "They barely even matter. Just do what feels right. Only INT isn't needed for melee, and STR isn't needed for mage." Our elaborate % allocation tables in KB are over-engineered.

2. **Proficiency > everything** — The single biggest differentiator between playstyle performance is weapon/armor proficiency. Not stats, not gear quality.

3. **Items before spells** — "Items are faster and safer than spells. Casting any spell costs time; items are instant, monsters don't attack after you use them." Our novice strategy prioritizes Cure before health items — should reverse.

4. **Use items first, Cure only if still low** — Player wisdom contradicts our strategy engine's priority.

### Endgame meta (from battle records)
- Mage dominates speed: Holy Mage does DwD (L300 arena) in ~800 turns vs 1H Heavy in ~4500 turns
- Fastest builds: Holy Mage > Dark Mage > Wind Mage > Cold Mage > Fire Mage > Elec Mage > 1H Mage > DW > 1H > Niten > 2H > 1H Heavy
- 1H Heavy is the tankiest but slowest endgame build
- Meta gear: Feather+Aether charms, Radiant phase for mages, Power Slaughter for melee

### IW Potency (research data)
- 1H: Butcher > Fatality > Overpower (Overpower inefficient for 1H because counters already stun)
- All other melee: Overpower > Butcher > Fatality
- Overpower only affects normal attacks (not skills/counters)

### Accuracy cap confirmed
- 150%+ after L200, 200% is useless

### Key corrections to our KB data
- Spell unlocks (KB.lv spellUnlocks): MagNet was removed in a recent patch (jpx 20260705 removed Magnet features)
- Imperil should be prioritized much higher — it's "THE most important debuff" per community
- The "Nintendo" difficulty suggestion for Veteran is wrong — players run PFUDOR at L150+ for max rewards
- Spirit Stance should activate earlier — the community consensus is OC 60-80%, not 90%