FirstGodPerfect

A highly configurable Hades II mod that upgrades god boons to higher rarities. Supports multiple modes: upgrade the first god in each region, or upgrade only when you have a matching god's keepsake equipped.

Description

This mod enhances your god encounters with flexible configuration options:

• Mode 1 - Always: Upgrades the first god you encounter in each region to your chosen rarity
• Mode 2 - Keepsake Only: Upgrades god boons only when you have that god's keepsake equipped
• Rarity Options: Choose between Heroic (safe, no extra mods) or Perfect (requires BoonBuddy + Perfectionist)
• Keepsake Scaling: Optionally scale boon rarity based on your keepsake level (1-3)

Requirements

Required Dependencies

These are automatically installed by r2modman:

• Hell2Modding (v1.0.71+) - Core mod loader
• SGG_Modding-ENVY (v1.2.0+) - Environment isolation
• SGG_Modding-ModUtil (v4.0.1+) - Modding utilities
• SGG_Modding-Chalk (v2.1.1+) - Configuration management
• SGG_Modding-ReLoad (v1.0.2+) - Hot-reload support

Optional Dependencies

For Perfect rarity support (auto-detected by mod):

• Jowday-Perfectoinist (v0.1.8+) - Adds Perfect rarity functionality
• Jowday-BoonBuddy (v0.3.14+) - Required alongside Perfectoinist

Note: If you set target_rarity = "Perfect" but these mods aren't installed, the mod will automatically fall back to Heroic rarity.

Installation

Method 1: r2modman (Recommended)

1. Open r2modman
2. Select Hades II as your game
3. Search for "FirstGodPerfect" in the mod browser
4. Click Install
5. (Optional) Install Perfectoinist + BoonBuddy for Perfect rarity support
6. Click "Start Modded" to launch the game

Method 2: Manual Installation

1. Download the latest release
2. Extract to: [Hades II Install]/ReturnOfModding/plugins/shadowofdoom-FirstGodPerfect/
3. Ensure all dependencies are installed
4. Launch Hades II through r2modman or with mod loader

Configuration

Configuration file location: ReturnOfModding/config/FirstGodPerfect.cfg

You can edit the config file directly or use r2modman's config UI (recommended).

Available Settings

The config uses simple TRUE/FALSE checkboxes in r2modman. Each setting is self-contained - no contradicting pairs!

[config]
# Basic Settings
enabled = true                        # Enable/disable the mod
debug = false                         # Enable debug logging

# === UPGRADE MODE ===
# TRUE = Only with keepsake | FALSE = Always first god in biome
use_keepsake_mode = false

# === TARGET RARITY ===
# TRUE = Perfect (cyan) | FALSE = Heroic (blue)
use_perfect_rarity = true

# === KEEPSAKE SCALING (only applies when use_keepsake_mode = true) ===
# TRUE = Scale with level (Lv1/2/3) | FALSE = Always max rarity
keepsake_scale_with_level = false

Configuration Options Explained

Basic Settings

• enabled: Master on/off switch for the entire mod
• debug: Enable detailed logging (check ReturnOfModding/LogOutput.log)

use_keepsake_mode

Controls which mode the mod operates in:

FALSE (Default - Always First God Mode)

• Upgrades the first god you encounter in each region
• Works like the classic FirstGodPerfect behavior
• No keepsake required
• Example: First god in Oceanus gets upgraded, first god in Rift gets upgraded, etc.

TRUE (Keepsake Only Mode)

• Upgrades god boons only when you have that specific god's keepsake equipped
• Example: Zeus boons only upgraded if you're wearing Zeus's keepsake (Cloud Bangle)
• Gives you complete control over which god gets boosted
• Works every time you encounter that god (not just first)

use_perfect_rarity

Controls the target upgrade rarity:

FALSE (Heroic Rarity - Safe Mode)

• Upgrades boons to Heroic rarity (blue tier)
• Safe option that works without additional mods
• One level above Epic, two below Perfect

TRUE (Default - Perfect Rarity)

• Upgrades boons to Perfect rarity (cyan tier)
• Requires BoonBuddy + Perfectionist mods installed
• Two levels above Heroic, highest standard rarity
• Auto-falls back to Heroic if required mods not detected

keepsake_scale_with_level

Only applies when use_keepsake_mode = true. Controls how keepsake level affects rarity:

FALSE (Default - Always Max Rarity)

• Always upgrades to target rarity regardless of keepsake level
• Keepsake level 1, 2, or 3 all give the same max rarity
• Simple and powerful

TRUE (Progressive Scaling)

• Scales the upgrade based on your keepsake level:
  • Level 3 (Epic rarity keepsake): Full rarity (Perfect or Heroic)
  • Level 2 (Rare rarity keepsake): -1 level (Perfect→Heroic, Heroic→Epic)
  • Level 1 (Common rarity keepsake): -2 levels (Perfect→Epic, Heroic→Rare)
• Rewards investing in keepsake upgrades

Usage Examples

Example 1: Classic Mode (First God Perfect) - DEFAULT

use_keepsake_mode = false           # Always first god
use_perfect_rarity = true           # Perfect rarity
keepsake_scale_with_level = false   # N/A in always mode

Result: First god in each region gets Perfect boons (requires Perfectionist + BoonBuddy)

Example 2: Safe Classic Mode (No Extra Mods)

use_keepsake_mode = false           # Always first god
use_perfect_rarity = false          # Heroic rarity (safe)

Result: First god in each region gets Heroic boons (no extra mods needed)

Example 3: Keepsake-Controlled Perfect

use_keepsake_mode = true            # Only with keepsake
use_perfect_rarity = true           # Perfect rarity
keepsake_scale_with_level = false   # Always max

Result: Only get Perfect boons from gods whose keepsake you're wearing. Always max rarity.

Example 4: Progressive Keepsake System

use_keepsake_mode = true            # Only with keepsake
use_perfect_rarity = true           # Perfect rarity
keepsake_scale_with_level = true    # Scale with keepsake level

Result:

• Level 3 keepsake → Perfect boons
• Level 2 keepsake → Heroic boons
• Level 1 keepsake → Epic boons

Example 5: Safe Progressive System

use_keepsake_mode = true            # Only with keepsake
use_perfect_rarity = false          # Heroic rarity (safe)
keepsake_scale_with_level = true    # Scale with keepsake level

Result:

• Level 3 keepsake → Heroic boons
• Level 2 keepsake → Epic boons
• Level 1 keepsake → Rare boons

God Keepsakes Supported

The mod detects the following god keepsakes for keepsake_only mode:

• Zeus: Cloud Bangle
• Hera: Iridescent Fan
• Poseidon: Immortal Shell
• Aphrodite: Aromatic Phial
• Demeter: Barley Sheaf
• Apollo: Golden Lyre
• Hephaestus: Adamant Shard
• Hestia: Eternal Ember
• Ares: Blood-Filled Vial

Gameplay Scenarios

Scenario 1: Classic First God (Always Mode)

1. Start a run in Oceanus
2. Meet Zeus first → All Zeus boons are Perfect
3. Later meet Aphrodite → Normal rarity (not first)
4. Enter the Rift
5. Meet Hestia first → All Hestia boons are Perfect

Scenario 2: Keepsake Build (Keepsake Only Mode)

1. Equip Zeus's Cloud Bangle before starting run
2. Encounter Zeus → All Zeus boons are Perfect
3. Encounter Poseidon → Normal rarity (no keepsake)
4. Switch keepsake to Hera's Iridescent Fan in the Crossroads
5. Encounter Hera → All Hera boons are Perfect

Scenario 3: Progressive Keepsake (Scale with Level)

1. Equip Level 1 Apollo keepsake
2. Encounter Apollo → All boons are Epic (2 levels below Perfect)
3. Level up keepsake to Level 2
4. Next Apollo encounter → All boons are Heroic (1 level below Perfect)
5. Level up keepsake to Level 3
6. Next Apollo encounter → All boons are Perfect

Compatibility

• ✅ Compatible with most gameplay mods
• ✅ Optional Perfectoinist + BoonBuddy (for Perfect rarity)
• ✅ Compatible with PonyQOL2, BoonBuddy, and other quality-of-life mods
• ⚠️ May conflict with other mods that heavily modify boon rarity systems

Troubleshooting

Boons aren't being upgraded:

1. Check that enabled = true in config
2. Verify you're meeting the mode conditions:
   • Always Mode (use_keepsake_mode = false): Are you encountering the FIRST god in the region?
   • Keepsake Mode (use_keepsake_mode = true): Do you have that god's keepsake equipped?
3. Enable debug = true to see console logs
4. Check console output or ReturnOfModding/LogOutput.log

Perfect rarity shows as Heroic:

• This means Perfectoinist or BoonBuddy isn't installed/detected
• The mod automatically falls back to Heroic for safety
• Install both mods to enable Perfect rarity

Keepsake mode not working:

• Verify you have the correct god's keepsake equipped
• Check if the keepsake is in the supported list above
• Enable debug mode to see detection logs

Debug Mode: Set debug = true in config to see detailed console output:

• Which upgrade mode is active
• What target rarity is being used
• When keepsakes are detected
• Which boons are being upgraded
• Any fallback behavior (Perfect→Heroic)

Known Issues

• None currently reported

Development

Hot Reload

This mod supports hot-reload for development:

1. Make changes to core.lua or config.lua
2. Press the reload hotkey in-game (configured in Hell2Modding)
3. Changes take effect immediately without restart

File Structure

shadowofdoom-FirstGodPerfect/
├── manifest.json    # Mod metadata and dependencies
├── main.lua        # Entry point and initialization
├── core.lua        # Core logic (upgrade system, keepsake detection)
├── config.lua      # Default configuration with all options
├── README.md       # This file
└── icon.png        # Mod icon

Credits

• Author: shadowofdoom
• Framework: Hell2Modding / ReturnOfModding
• Perfect Rarity: Jowday (Perfectoinist mod)
• BoonBuddy: Jowday (Helper mod for Perfect rarity)
• Inspiration: The Hades II modding community

License

This mod is provided as-is for the Hades II community. Feel free to modify and share!

Changelog

v2.1.1 (2025-11-08)

• CHANGED: Changed mod's icon

v2.1.0 (2025-10-30)

• IMPROVED: Simplified config - no more contradicting option pairs!
  • Before: mode_always_first_god = true/false AND mode_keepsake_only = true/false (confusing!)
  • After: use_keepsake_mode = true/false (simple!)
  • Reduced from 7 config options to just 5
  • Each option is self-contained with clear TRUE/FALSE meaning
  • Much more intuitive to configure
• Config Changes:
  • use_keepsake_mode: TRUE = keepsake only, FALSE = always first god
  • use_perfect_rarity: TRUE = Perfect, FALSE = Heroic
  • keepsake_scale_with_level: TRUE = scale with level, FALSE = always max
• IMPROVED: Clearer config descriptions in r2modman UI
  • Shows both TRUE and FALSE meanings directly in the label
  • No more guessing what FALSE means!

v2.0.1 (2025-10-30)

• CRITICAL BUGFIX: Fixed keepsake detection not working
  • Keepsakes are stored in TraitDictionary, not Traits
  • Updated HasGodKeepsake and GetKeepsakeLevel functions
  • Mode 2 (keepsake_only) now works correctly
• IMPROVED: Config now uses TRUE/FALSE checkboxes instead of string values
  • Much easier to configure in r2modman's config UI
  • No more typing errors with string values
  • Clear dropdown-style boolean options
• IMPROVED: Better debug logging for keepsake detection
  • Shows when keepsakes are found
  • Shows keepsake rarity level
  • Helps troubleshoot configuration issues

v2.0.0 (2025-10-30)

• MAJOR UPDATE: Complete configuration system overhaul
• NEW FEATURE: Added "keepsake_only" upgrade mode
  • Only upgrades boons when matching god keepsake equipped
  • Supports all 9 Olympian god keepsakes
• NEW FEATURE: Keepsake level scaling system
  • Option to scale rarity based on keepsake level (1-3)
  • Level 3 = max rarity, Level 2 = -1 level, Level 1 = -2 levels
• NEW FEATURE: Configurable target rarity (Heroic or Perfect)
  • Choose between safe Heroic or powerful Perfect
• NEW FEATURE: Auto-detection of BoonBuddy + Perfectionist
  • Automatically falls back to Heroic if Perfect mods not installed
  • No more hard dependency on Perfect mods
• IMPROVED: Removed hard dependencies on Perfectionist/BoonBuddy
  • Mod now works standalone with Heroic rarity
  • Perfect rarity requires both mods (auto-detected)
• IMPROVED: Enhanced configuration UI in r2modman
  • Clear descriptions for all settings
  • Multiple configuration examples documented
• IMPROVED: Better debug logging with mode/rarity information

v1.0.9 (2025-10-30)

• Minor bug fixes and stability improvements

v1.0.8 (2025-10-30)

• Performance optimizations

v1.0.7 (2025-10-30)

• CRITICAL ARCHITECTURE CHANGE: Completely rewrote mod to use UseLoot wrapper
• Fixed fatal crashes during game startup and room loading
• Following BoonBuddy's pattern for better compatibility

v1.0.0 - v1.0.6

• See previous changelog entries in git history
• Initial releases with Perfect rarity for first god per region