Run Planner Plan Executor

Plan Executor is the Hades II mod that carries out plans created by Run Planner.

Run Planner owns authoring, simulation, and validation. Its desktop app publishes a game-ready execution plan; Plan Executor loads that plan when a new run begins and steers the corresponding rooms, rewards, offers, and other modeled outcomes in Hades II. If the game and plan diverge, the executor records the discrepancy and stops steering the remaining plan without blocking normal gameplay.

How it connects to Run Planner

1. Create and validate a run in the Run Planner desktop app.
2. Use Publish to Game to write the active execution plan to the ReturnOfModding configuration.
3. Start a new Hades II run. Plan Executor loads the published plan at run startup.

The browser version of Run Planner cannot publish directly to the game. Plan Executor consumes the published execution plan only; it does not read or reinterpret an editable Run Planner project.

Repository layout

• src/ — the active Hades II module.
• fixtures/ — execution plans shared with Run Planner for compatibility testing.
• tests/ — Lua unit and integration tests.

Within src/mods/, code is grouped by its runtime responsibility: host and protocol integration, route navigation, room behavior, timeline interactions, and modeled traits or keepsakes.

Development

Run the Lua test suite from the repository root:

lua tests/all.lua

Check the active module with Luacheck:

luacheck src/

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[Unreleased]

[0.3.0] - 2026-09-07

Added

• executor: realize Hermes Shrine commerce ( da4a6f)
• executor: realize Stygian Well commerce ( 7f8e73)
• executor: realize Purging Pool menus ( 938cfe)
• executor: realize World Shop commerce ( b84161)
• executor: realize volatile keepsake replays ( 607e53)
• executor: close keepsake effect conformance ( 2acc9e)
• executor: realize Echo volatile outcomes ( ae74f0)
• executor: realize Icarus latest model (

• executor: realize Circe stateful outcomes ( 54a7c6)
• executor: steer Sea Star duplication ( cf7344)
• executor: observe Path acquisition ( ea60ed)
• executor: steer Spell Hex acquisition ( 5bfb91)
• executor: steer Concave Stone residuals ( b53eb1)
• executor: steer Natural Selection distribution ( fbb696)
• executor: steer All Together grants ( 93e724)
• executor: realize F/G encounter keepsakes ( b2aaab)
• executor: realize Artificer transformations ( 0ae5fa)
• executor: realize npc acquisitions ( de5f75)
• executor: settle direct pickup acquisitions ( 7936a0)
• executor: realize level acquisitions ( 18037e)
• executor: realize ordinary trait offers ( 9550cc)
• executor: verify starting loadout contract ( 668a36)
• executor: replace trace runtime with room sessions ( b78d3f)
• executor: close live F and G realization ( 3fe7aa)
• executor: consume protocol v7 state frames ( e86776)
• executor: realize G special encounters ( a9033e)
• executor: realize Chaos and additional exits ( 3891f8)
• executor: realize F and G room interactions ( 67a173)
• executor: execute room trace programs ( 69148a)
• executor: realize F and G topology ( 684e53)
• executor: execute F opening plan ( bb292a)
• executor: checkpoint room reward prototype ( b7c3b7)
• executor: route compiled room batches ( a5149c)
• executor: freeze and observe run sessions ( 9fa578)
• executor: decode published plan slot ( 6f525f)

Fixed

• ci: extending luacheck line limit (54003a6)
• traits: realize carried acquisition outcomes ( 78bbc3)
• executor: validate declared encounter carriers ( d3e001)
• decouple room exit from transition state ( dbb5b0)
• executor: check elements at room exit ( 91de49)
• executor: realize protected resource outcomes ( 61fb14)
• executor: defer shop purchases until interaction ( bc26cf)
• executor: read live conformance state ( 718b37)
• executor: harden live execution contacts ( 1b433d)
• executor: stabilize room session ownership ( ba9e68)
• executor: preserve anomaly entry presentation ( 2ac13f)
• executor: unify random Arcana steering ( 69aa0e)
• executor: realize exact embryo outcomes ( 4a5d12)
• executor: cover consequential native acquisition contacts ( b7ebef)
• executor: preserve native required boss rewards ( cfb52f)
• executor: stabilize live F route realization ( 0ef03e)
• executor: accept published protocol values (

• executor: close F and G execution boundary ( 558b8a)

Changed

• executor: move anvil steering into commerce ( d17a6e)
• executor: split room feature interactions ( fb81bb)
• executor: finish repository housekeeping ( 8662e0)
• executor: organize host and runtime modules ( 3b6aea)
• executor: rehome shared spell and trait adapters ( 094ea7)
• executor: unify native bindings ( 4f145f)
• executor: consolidate protocol decoding ( 33c37e)
• executor: consolidate keepsake adapters ( 00c84a)
• executor: unify NPC trait menus ( 90c0d6)
• executor: retire broad trait fallback ( c2d094)
• executor: enforce exact authored outcomes ( 160fd2)
• executor: isolate Chaos acquisitions ( e90d5a)
• executor: stabilize hook identities (

• executor: consolidate encounter timeline ( e502a9)
• executor: establish room timeline skeleton ( 4a30cb)
• executor: close declaration-driven room structure ( d6edaf)
• executor: align startup with native run lifecycle ( 2c1c15)

Changed

• Ported the template to the current ModpackLib module host, draw, state, action, and fallback UI APIs.
• Removed module-local Chalk/config scaffolding and legacy Setup deployment scripts.