hv-unified/docs/DESIGN.md

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:

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%