402db6bb2f
- 23 source files in src/ (build via scripts/build.sh) - Forum-sourced player knowledge in references/ - DESIGN.md with architecture and corrections - References to existing scripts (Monsterbation, jpx, HV Utils)
196 lines
8.7 KiB
Markdown
196 lines
8.7 KiB
Markdown
# 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%
|