Fated Encounters

A Hades II mod that guarantees NPC encounters you would normally miss on a run—field combats (Nemesis, Artemis, Heracles, Icarus, Athena) and, after True Ending, Zagreus’s Infernal Contract and the Neo-Chronos clearing.

Install with r2modman or Thunderstore. Requires Hell2Modding and the dependencies listed on the package page.

How it works

• Field NPCs: Turn on each NPC under fieldNPCs in config. Each enabled NPC is guaranteed once per run. The mod forces their field encounter in an eligible biome after you enter that biome, then stops tracking them for the rest of the run.
  • Default: The biome is whichever eligible region you reach first on your route.
  • Optional (randomizeFieldNPCBiome): At run start, each NPC is assigned one random eligible biome and is only forced there (you must still visit that biome).
• Zagreus: After True Ending, can guarantee the Infernal Contract once per run where that content is unlocked.
• Chronos: After True Ending, can guarantee the Neo-Chronos clearing encounter once per run.

Configuration

Settings are managed with Chalk and appear in r2modman → Config (or in your profile’s ReturnOfModding/config/ as MarcoAntolini-FatedEncounters.cfg).

Note: Config files persist even if you uninstall the mod. Delete or reset MarcoAntolini-FatedEncounters.cfg manually for a clean slate.

Options

Examples

• All field NPCs, no postgame: enabled = true, all fieldNPCs.* = true, guaranteeZagContract = false, guaranteeChronosClearing = false.
• Only Nemesis and Artemis: enable only those two under fieldNPCs, disable the rest.
• Random biomes each run: randomizeFieldNPCBiome = true with the NPCs you want enabled; use debugLog to see assigned biomes in the console.
• Chronos only (no field NPCs): all fieldNPCs.* = false, guaranteeChronosClearing = true (requires True Ending on your save).
• Disable everything temporarily: enabled = false.

Troubleshooting

Bad folder name ... Should be AuthorName-ModName

Hell2Modding expects exactly one hyphen in the plugin folder name: MarcoAntolini-FatedEncounters (namespace + - + name from the Thunderstore package).

Common wrong names from older installs or r2modman quirks:

• MarcoAntolini-Fated-Encounters — extra hyphen in the package name (pre-0.3.0 builds)
• Marco Antolini-FatedEncounters — space in the Thunderstore team display name

The mod may still load with a truncated id, but you should fix the folder name:

1. Close the game and r2modman.
2. Rename the plugin folder under ReturnOfModding/plugins/ to MarcoAntolini-FatedEncounters.
3. In the same profile’s mods.yml, set name: MarcoAntolini-FatedEncounters if present.
4. If you had an old config file, rename MarcoAntolini-Fated-Encounters.cfg → MarcoAntolini-FatedEncounters.cfg under ReturnOfModding/config/.

To avoid bad folder names on fresh installs, set your Thunderstore team display name to MarcoAntolini (no space), matching the package namespace.

Contributing

Contributions are welcome—bug reports, feature ideas, docs, and code.

• Contributing guide — dev setup (r2modman symlink), change expectations, and releases.
• Report a bug — use the template so we can reproduce issues.
• Request a feature — describe behavior and config ideas.
• Open a pull request — see the PR checklist in .github/pull_request_template.md.

For general Hades II modding help (loader, dependencies, other mods), the Hades II Modding Discord is a good place to ask.

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).