Fated Encounters

Install on Thunderstore →

Before installing: Back up your Hades II profile saves (on Windows: %USERPROFILE%\Saved Games\Hades II\Profile*.sav) in case a mod update or unknown issue affects your progress. Mod settings are stored separately and persist after uninstall—see Settings reference.

A Hades II mod that makes sure you do not miss important encounters on a run: combat meetings with Nemesis, Artemis, Heracles, Icarus, and Athena; and after the True Ending, Zagreus's Infernal Contract and reformed Chronos in the hub between Erebus and Oceanus. Change everything from an in-game settings window or r2modman Config.

How it works

• Allies (Nemesis, Artemis, Heracles, Icarus, Athena): Turn on each character you want in Allies (in-game settings or r2modman). Each enabled ally is guaranteed once per run. The mod makes their encounter happen in an eligible region after you enter that region, then stops tracking them for the rest of the run.
  • Default: The region is whichever eligible one you reach first on your route.
  • Optional shuffle: At run start, assign each enabled ally one random eligible region—they only appear there (you must still visit that region). Dream Dives ignore this—their four regions are picked one at a time at biome transitions, so allies always appear in the first eligible region visited.
• After True Ending — Zagreus: Guarantee the Infernal Contract once per run when that content is unlocked on your save.
• After True Ending — Chronos: Guarantee reformed Chronos for a conversation in the hub room between Erebus and Oceanus (the transition area after the Erebus guardian). Once per run. This is not the event where Chronos sends you to Asphodel.
• Chaos Trials and Dream Dives: On a normal run, the options above apply as usual. Packaged Chaos Trials and Hypnos Dream Dives are off by default—turn them on if you want ally guarantees in those modes too. Infernal Contract during Dream Dives is a separate optional toggle. Reformed Chronos never applies in Chaos Trials or Dream Dives.

Examples

• All allies, nothing after True Ending: enable all allies; turn off both After True Ending options.
• Only Nemesis and Artemis: enable just those two under Allies; disable the rest.
• Random region each run: turn on Random region per ally at run start with the allies you want; enable Debug log in r2modman (see Settings reference) to see assigned regions in the console.
• Chronos only (no allies): disable all allies; enable Guarantee reformed Chronos in the Erebus–Oceanus hub (requires True Ending on your save).
• Chaos Trials allies: under Chaos Trials & Dream Dives, enable Apply ally guarantees in Chaos Trials and pick allies under Allies.
• Dream Dives allies: enable Apply ally guarantees in Dream Dives and pick allies under Allies.
• Disable everything temporarily: turn off Mod enabled.

Settings reference

Open Fated Encounters from the mod overlay menu bar, or pick the floating panel in the mod list. The table below maps each in-game section and label to its r2modman config key. Both edit the same file—in r2modman, click Refresh All Edits after in-game changes; in-game picks up r2modman saves within a couple of seconds.

Settings are stored with Chalk in your profile as ReturnOfModding/config/MarcoAntolini-FatedEncounters.cfg. Config files persist even if you uninstall the mod—delete or reset MarcoAntolini-FatedEncounters.cfg manually for a clean slate.

When changes take effect in gameplay:

• Mod enabled (on/off): reload your mod profile (or restart the game) so guarantee hooks register or unregister.
• Allies and random region shuffle: mostly apply on your next run. The current run keeps whichever allies were already pending.
• Chaos Trials and Dream Dives toggles: can apply on the current run once synced.
• After True Ending options (Zagreus, Chronos): pending flags are set at run start, like allies.

Support

Found a problem or have an idea?

• Report a bug — use the template so we can reproduce it.
• Request a feature — describe the behavior you want.

Enable Debug log in r2modman (see Settings reference) before reporting issues—it helps a lot.

Contributing

Code and docs PRs are welcome. See CONTRIBUTING.md for dev setup and what to include in a pull request.

License

MIT — see LICENSE.

Changelog

0.4.0 - 2026-05-26

Added

• In-game settings UI: ImGui panel and menu bar entry (Fated Encounters) for all options; stays available when Mod enabled is off; syncs with r2modman Config (same .cfg file).
• Chaos Trials support: Apply ally guarantees in Chaos Trials (off by default) guarantees each enabled ally once in that trial's region—curated bounties and randomized Underworld/Surface trials at Difficulty 1 and 2—bypassing base-game bounty and depth gates when forcing encounters.
• Dream Dives support: Apply ally guarantees in Dream Dives (off by default) for Hypnos Dream Dives. Random region per ally at run start is ignored—the route picks four regions as you progress, so each enabled ally is guaranteed in the first eligible region you actually visit on that path.
• Dream Dive Infernal Contract: Guarantee Infernal Contract in Dream Dives (off by default) when Guarantee Zagreus Infernal Contract is on—separate from ally guarantees.
• Debug log: run-start summary of pending guarantees; in Dream Dives, a line per region entered (visited regions, remaining pool, eligible pending allies); console lines when guarantees are skipped or a pending ally could not be forced—useful when reporting bugs.

Changed

• Config reorganized into Allies, After True Ending, and Chaos Trials & Dream Dives sections (schema version 6; existing .cfg files migrate automatically, including legacy flat keys).
• Reformed Chronos and Infernal Contract guarantees no longer run on Chaos Trials or Dream Dives (except the optional Dream Dive contract toggle).
• README: Settings reference maps in-game section names to config keys; adds Examples, a settings panel screenshot, sync notes (Refresh All Edits in r2modman after in-game changes), and when each option takes effect in gameplay.
• Contributing guide: New Documentation section with module map and Lua/EmmyLua conventions for pull requests.
• GitHub issue and PR templates mention the in-game Fated Encounters settings window, Chaos Trials, and Dream Dives.
• Thunderstore description highlights in-game settings and optional Chaos Trials / Dream Dives support.

Fixed

• In-game settings now save reliably to the shared .cfg file; pre-v6 flat keys are cleaned up on upgrade instead of fighting nested settings.
• Fixed duplicate MarcoAntolini-FatedEncounters entries in r2modman Config after repeated in-game saves.

0.3.3 - 2026-05-25

Changed

• Thunderstore description, README, and r2modman config text use plain in-game language (regions, allies, True Ending) instead of internal terms like field NPC, biome, or clearing.
• Chronos is documented as the reformed Chronos conversation in the hub between Erebus and Oceanus after True Ending—not the Asphodel send event.
• GitHub issue and PR templates use the same plain-language terms.

0.3.2 - 2026-05-20

Fixed

• GitHub release notes were empty when CHANGELOG.md had a duplicate version heading before the section with content.

Changed

• Release workflow no longer runs ChangeLogger; cut CHANGELOG.md and bump thunderstore.toml locally before dispatch (see CONTRIBUTING).
• Release workflow skips the bot commit when CHANGELOG.md and thunderstore.toml are already updated for the tag.
• Changelog compare links added for 0.3.0 and 0.2.0.
• README: removed troubleshooting for legacy plugin folder names (superseded by the FatedEncounters package rename in 0.3.0).

0.3.1 - 2026-05-20

Fixed

• Thunderstore package icon must be 256×256; optimized root icon.png.
• Thunderstore README banner did not load (markdown image for release URL rewrite; images/ kept out of Git LFS for GitHub raw hotlinking).

Changed

• README header uses images/banner.png (512×512); release workflow also rewrites HTML img src paths.
• Thunderstore package page links added across README, CONTRIBUTING, and GitHub issue templates.
• GitHub Release workflow populates release notes from the matching CHANGELOG.md section.

0.3.0 - 2026-05-20

Added

• config_migrate.lua to upgrade existing user configs when the config schema version changes.
• Contributing guide, README contributing section, and GitHub issue/PR templates.

Changed

• Thunderstore package name is now FatedEncounters (plugin folder MarcoAntolini-FatedEncounters); docs and templates updated from the old hyphenated slug.
• Internal config version is no longer described in r2modman; it is still updated automatically for migrations.
• Removed guaranteeFieldNPCs master switch; fieldNPCs.* toggles are now the only control for field NPC guarantees.
• Config schema version bumped to 4; migrating from v3 disables all fieldNPCs.* if guaranteeFieldNPCs was false (preserves Chronos-only setups).
• README configuration table, examples, and troubleshooting for correct plugin folder naming.

Fixed

• StartNewRun wrapper now returns the run table from vanilla code. Without this, starting a run from the hub crashed with attempt to index local 'currentRun' (a nil value) in DeathLoopLogic.lua.

0.2.0 - 2026-05-18

Added

• Field NPC encounter guarantees (Nemesis, Artemis, Heracles, Icarus, Athena): once per run, forced in an eligible biome after you enter it.
• Postgame guarantees after True Ending: Zagreus Infernal Contract (when unlocked) and Neo-Chronos clearing.
• Per-NPC toggles under fieldNPCs, with guaranteeFieldNPCs as a master switch.
• randomizeFieldNPCBiome: assign each enabled field NPC a random eligible biome at run start instead of the first biome you visit.
• Chalk-backed config with descriptions for r2modman’s config editor.
• README: configuration guide, options table, and examples.

Changed

• Thunderstore description and README clarify once per run behavior (not once per biome).
• Config schema version 3 (Chalk merges new keys into existing user .cfg files).