=======================================================================================
 StixUngodlyLUSDirectors v1.0.0
 Ungodly Madly Vastly Enhanced FAIR AI Director + Random Generation Director +
 FAIR Difficulty Director  -  for "Lovecraft's Untold Stories" (lus.exe) + all DLC
 BepInEx 5 (x86) plugin  |  Author: StixsworldHD (StixsmasterHD4k)
=======================================================================================

WHAT THIS IS
------------
Three fully-implemented directors watching over every run, all configurable from a
solid-background in-game panel (default key: F1) and from a heavily documented config
file where every single setting lists its min/max range and exactly what it does to
your gameplay.

 1) FAIR AI DIRECTOR
    - Per-role monster shaping applied the instant anything spawns: HP, chase speed,
      sight radius, attack speed, attack damage, attack range - separately tunable for
      regular monsters, mini-bosses and zone bosses, plus enemy projectile speed and
      turret/nest/trap durability.
    - ELITES: any regular monster can roll into an Elite (your chance %), gaining
      extra HP/damage/speed and appearing bigger with a crimson tint so the threat
      reads instantly. Bosses never roll - no surprise stat-stacked bosses.
    - FAIR ATTACK SLOTS: the heart of the fairness system. Only a limited number of
      monsters may actually be mid-attack on you at the same moment (separate melee
      and ranged caps). Everyone else keeps hunting, flanking and surrounding you -
      big packs feel terrifying yet every hit stays readable and dodgeable. This
      gates all 26 attack behaviours in the game code, covering every enemy family
      and all DLC creatures automatically (discovered by reflection at load).
    - REACTION GRACE: the first time a monster spots you it falters for a configurable
      beat (speed dip) before charging - the human "huh?!" moment - so aggro is
      always telegraphed, never teleported into your face.
    - Room-entry wake delay multiplier: stretch or shrink the built-in "monsters
      haven't noticed you yet" window when you walk through a door.

 2) RANDOM GENERATION DIRECTOR
    - SEED CONTROL: force an exact layout seed (share dungeons with friends, practise
      routes, race identical maps), with optional +1-per-zone so a whole run is
      deterministic instead of one repeated floor. Seeds are always printed to log.
    - ZONE SIZE: multipliers + flat adds + hard caps for main-path rooms, side rooms,
      secret rooms and bonus zero-layer set-piece rooms.
    - MONSTER VARIETY: vanilla picks ONE themed monster list per zone; Merge-All mode
      pools every monster the zone can legally host, so cultists, beasts and horrors
      mix in the same rooms. Reads the zone's own data, so DLC lists merge too.
    - PACK MULTIPLIER: rooms spawn cloned pack-mates next to regular monsters
      (1.5x-5x) under a hard per-room enemy cap. Bosses, turrets, nests, traps and
      quest specials are never cloned. Pairs beautifully with Fair Attack Slots.
    - MONEY & KNOWLEDGE multipliers scale the zone's honest loot budgets, and LOOT
      QUALITY BIAS shifts value toward Rare/Epic chests while conserving the total -
      fewer, juicier finds instead of mandatory cupboard-smashing.

 3) FAIR DIFFICULTY DIRECTOR
    - Static dials: all damage you deal, all damage you take (health AND sanity),
      a separate boss-damage dial, and flat run-start hero bonuses (max HP / max
      energy / flat damage - the same stats the in-game difficulty grants).
    - ANTI-SPIKE CAPS: no single hit may remove more than your chosen % of max HP,
      and no single scare more than your chosen % of max sanity. Deaths are earned
      across a fight, never donated by one overlapping crit.
    - MERCY RULES: below your HP threshold you take reduced damage and (optionally)
      the horde drops to a single melee + single ranged attacker - a real, visible,
      fair escape window when you're bleeding out.
    - DYNAMIC DDA BRAIN: samples your health, sanity, damage-taken rate, deaths and
      room-clear pace on a smooth interval, blends them into one intensity value,
      and gently steers: damage-in, damage-out, NEW-spawn HP (never live monsters -
      that would be cheating), wake delay and bonus attack slots. Assist strength
      and challenge strength are independently capped by YOU, movement is smoothed,
      and the whole brain's state is displayed live in the GUI Status tab. No hidden
      rubber-banding - you can literally watch it think.

INSTALLATION
------------
The game executable (lus.exe) is 32-bit, so you need the x86 build of BepInEx 5:

 1. Download "BepInEx_win_x86_5.4.23.3.zip" (or any 5.4.x x86 build) from
    https://github.com/BepInEx/BepInEx/releases
 2. Extract it directly into your game folder - the folder that contains lus.exe
    (e.g. ...\Steam\steamapps\common\Lovecraft's Untold Stories\).
    You should end up with a "BepInEx" folder and "winhttp.dll" next to lus.exe.
 3. Run the game once and quit - BepInEx creates its folder structure.
 4. From THIS zip, copy the "BepInEx" folder into the game folder (merge it).
    That places:
      BepInEx\plugins\StixUngodlyLUSDirectors\StixUngodlyLUSDirectors.dll
 5. Play. You'll see "StixUngodlyLUSDirectors v1.0.0 by StixsworldHD
    (StixsmasterHD4k) loaded" in BepInEx\LogOutput.log, with the number of gated
    attack states (26 on the current game build).

IN-GAME PANEL
-------------
 * Press F1 (rebindable via "Toggle Key" in the cfg) to open the panel.
 * Solid opaque window; tabs: AI Director / Fairness / Generation / Loot /
   Difficulty / DDA / Status. Every slider shows its value, allowed range and a
   plain-English gameplay explanation.
 * Changes to damage, difficulty, DDA, fairness and generation apply INSTANTLY.
   Monster body stats (HP/speed/etc.) apply to all NEW spawns immediately; press
   "Re-apply To Live Monsters" to push them onto the room you're standing in.
 * "Pause Game While GUI Open" (default ON) freezes time while you tune.
 * "Save Config" writes to disk (also auto-saved when you close the panel).
 * The Status tab shows live telemetry: tracked monsters, melee/ranged attack slots
   in use, DDA intensity bar (green = assisting you, red = challenging you) and all
   current DDA multipliers.

CONFIG FILE
-----------
 BepInEx\config\StixUngodlyLUSDirectors.cfg - 79 settings in 10 sections, every one
 with "Min / Max" bounds and a GAMEPLAY: line describing the real in-game effect.
 The shipped file contains all defaults (pure vanilla values: everything x1.0, elites
 off, fairness systems ON with gentle defaults, DDA ON in mostly-assist mode).

SUGGESTED STARTING RECIPES
--------------------------
 * "Fair but fiercer":  Common Speed 1.25, Common Damage 1.25, Elite Chance 12,
   Pack Size 1.5, keep all fairness defaults.
 * "Horde mode":        Pack Size 3, Max Enemies Per Room 40, Common HP 0.7,
   Melee Slots 4, Ranged Slots 3, Money 1.5.
 * "Roguelike marathon":Main Path Rooms x2, Side Rooms x2, Monster Variety 1,
   Use Custom Seed ON + share your seed.
 * "Story stroll":      Player Damage Taken 0.6, Max Single Hit 40%, DDA Max
   Challenge 0, Wake Delay x2.

PERFORMANCE NOTES
-----------------
 * Zero per-frame allocations while the panel is closed; all registries prune on a
   slow timer; the DDA brain samples every 0.75s by default.
 * The heavy knobs are Pack Size and Max Enemies Per Room (pathfinding scales with
   crowd size) and extreme zone-size multipliers (longer level builds). Hard caps
   exist on all of them for a reason.

COMPATIBILITY & COVERAGE
------------------------
 * Works with every DLC and every enemy: shaping hooks the universal enemy
   constructor, generation hooks read each zone's own data, and the attack-slot
   scan discovers attack behaviours by reflection - new content is covered
   automatically as long as it uses the game's own systems.
 * Saves are untouched: all changes are runtime-only (asset values that must be
   tweaked during generation are snapshotted and restored the same frame).
 * Master Enable OFF (or removing the DLL) returns the game to 100% vanilla.

CREDITS
-------
 Design, reverse engineering, code, docs: StixsworldHD (StixsmasterHD4k)
 Game: "Lovecraft's Untold Stories" by LLC Blini Games. This mod ships no game
 assets and requires the game you already own.
=======================================================================================
