# StixsworldHD — UNGODLY AI OVERHAUL
### for *HYPERCHARGE: Unboxed* (+ all DLC)

An ungodly, madly, vastly enhanced overhaul of **friendly bot AI**, **friendly bot
pathfinding**, **friendly bot defensive building**, **friendly bot Core-defending & objective
play**, **friendly bot item/weapon handling**, **friendly bot credit/pickup seeking**,
**friendly bot battery seeking**, a **real-time dynamic difficulty director**, **enemy AI**,
and **enemy pathfinding** — covering **every game mode** and **every enemy type**, built as a
single performance-first UE4SS Lua mod. Every behaviour is driven from one fully-documented
config file, applied exactly once per entity at spawn (except the difficulty director, which
updates live), and amplifies the game's own per-difficulty tuning rather than overwriting it.

**Author:** StixsworldHD (StixsmasterHD4k)
**Platform:** UE4SS (Lua) · Unreal Engine 4
**Scope:** Base game **and every DLC**, automatically (targets the shared engine classes).

---

## What it does

This is a **pure AI intelligence / mobility / pathfinding** mod. It does **not** touch health,
damage, or spawn budgets — it makes the existing toys *think, see, react, and move* far better.
It works on both sides of the fight:

### Friendly bots (your teammate toys) — behaviour
- Faster, tighter aim acquisition and target tracking.
- Rock-steady fire: no recoil climb, no random spread.
- Engages airborne threats (anti-air enabled).
- Removes the developer "handicap" flags that deliberately dumb bots down — they now lead
  targets, aim-correct, target-dodge, melee, swap weapons, reload-cancel, and prey on weak
  enemies like a real player.
- Reacts faster (shorter dodge / jump / vault decision delays).
- Wider field of view, longer target memory, hears your voice commands from further away.

### Friendly bots — pathfinding / mobility
- Higher movement, acceleration, **deceleration**, and air-control input scaling so they reach
  the speeds their AI wants and change direction crisply.
- Climb taller obstacles and steeper steps (`StepHeight`/`StepAngle`), and finish off more
  wounded enemies (widened weak-prey band).
- Stronger, more frequent evasive dodges and dodge-jumps.
- **Full controller-level navigation (v1.6.0):** teammates now get the same ungodly pathfinding
  the enemy engine gets — block-detection with auto-repath, a teleport-unstick failsafe, moving-
  target interception, pathing that survives launches and falls, preserved jump-links, strafing
  while engaging, jump-chaining on landing, faster target lock-on, and longer pursuit.
- Optional movement-component tuning on each bot's body (climb clutter, raise speed cap) —
  applied only to bot bodies, never to human players.

### Friendly bots — building & defense competency (NEW in v1.1.0)
HYPERCHARGE is a build-and-defend game, so a competent teammate is a competent *builder*.
Each bot's build capability lives in its profile: three category enables (Defence/**barricade**,
Trap, Turret), three subtype lists (which specific barricades/traps/turrets it may place), and
the credits it has to spend. This overhaul makes every bot a master fortifier:
- **Every build category enabled** on every bot — no teammate is locked out of building
  barricades, traps, or turrets (raise-only, so a bot that already builds is never reduced).
- **Full buildable catalog unlocked:** the mod reads the buildable subtype lists from *every*
  bot profile in the game, unions them, and grants that complete set to all bots — so each
  teammate can build every barricade, trap, and turret type that any profile could, instead
  of a limited per-character subset. Every entry comes from the game's own shipped data, so it
  never produces an invalid buildable, and late-loading profiles automatically widen the
  catalog for everyone.
- **Unlimited build credits (optional, OFF by default):** credits gate building, repairing,
  and upgrading. This is available as a one-switch power option, but it removes the build
  economy, so it now ships **off** — bots instead *earn* their credits by hunting credit
  pickups (see credit seeking below), which is the intended, non-cheaty way to fund defenses.
- **Advanced knob:** if you determine the per-category byte is a "how many to maintain" count
  on your build, one config value forces bots to build *more* structures per category.

All of the above is config-gated and can be tuned or turned off independently.

### Friendly bots — Core defending & objective play (NEW in v1.2.0)
A competent teammate doesn't just shoot — it *defends the right thing*. This overhaul tunes
the bot hostility/target-scoring system so bots play the objective like a coordinated squad:
- **Wider Core perimeter:** bots peel off to intercept enemies heading for the Core from much
  further out, instead of only reacting once they're on top of it.
- **Faster wave reactions:** they treat freshly-spawned enemies as hostile sooner.
- **Battery-thief hunters:** enemies carrying batteries (draining your Core) get a big priority
  bonus, so bots drop everything to stop them.
- **Smarter target selection:** the instigator, the contextually important target, the round
  winner, and better-armed/more-kitted enemies are all weighted harder, so bots focus the most
  dangerous threat rather than the nearest one.
- **Objective recovery:** bots re-grab a dropped objective item (like a battery) almost
  immediately.

### Friendly bots — item & weapon handling (NEW in v1.2.0)
- **Swap to the best weapon** for the situation and **reload-cancel** (both via clearing the
  handicap flags) so bots aren't stuck mid-reload or on the wrong gun.
- **Grab-while-moving:** bots veer to scoop up ammo, health, weapons and attachments mid-dodge
  instead of running past them.
- **Optional bottomless ammo** (`IsMaxAmmo`) for uninterrupted optimal weapon usage — OFF by
  default (the one "cheaty" weapon option), one switch to enable.

### Friendly bots — credit & pickup seeking (NEW in v1.2.0)
With infinite credits off, bots fund their fortifications the honest way: they go and get the
credits. Every self-collected pickup (turret credits, ammo, health, weapons, attachments,
weapon sets, jetpacks) can be flagged "bots ignore me"; this feature clears that flag so bots
**actively seek pickups** — hunting down turret-credit pickups to pay for barricades/turrets,
and collecting ammo/health/better weapons along the way. Scope is configurable: seek
**everything**, or **credits only** to laser-focus on funding defenses. (Batteries are an
objective item with their own dedicated feature — see below.)

### Friendly bots — battery seeking / objective delivery (NEW in v1.3.0)
Batteries are the win-condition objective: a toy carries one to the Core and inserts it to
power it. Batteries can be flagged "bots ignore me", which leaves the objective entirely to
you. This feature clears that flag so teammate bots **ungodly competently seek out batteries
and haul them to the Core** — actively contributing to the objective instead of standing
around. It runs **independently of the pickup-seeking scope**, so battery seeking stays on
even when pickup seeking is set to credits-only, and it's a clean separate toggle: turn it off
and bots leave batteries alone. (How quickly a bot re-grabs a *dropped* battery is governed by
the objective re-pickup speed in the defending/objective section.)

### Friendly bots — real-time dynamic difficulty director (NEW in v1.4.0)
A live difficulty director that continuously scales the teammate bots' **Skill** inside a
`[min,max]` band you define **per vanilla difficulty**. It reads which difficulty you're
playing (Easy/Normal/Hard/Nightmare), measures how the match is going in real time (Core power
remaining + active enemy pressure), and slides bot Skill toward the band's **max** when things
get dire and toward its **min** when you're cruising — so assistance scales with need, but
**always stays within the range you allow for that difficulty**. The defaults give relaxed
teammates on Easy and elite teammates on Nightmare, each with room to flex inside the band.

- **Per-difficulty bands:** every vanilla difficulty gets its own configurable skill `min`/`max`
  (e.g. Easy 20–50, Nightmare 65–100), plus an absolute safety clamp.
- **Smoothed:** Skill eases toward its live target (configurable smoothing) so difficulty drifts
  naturally instead of snapping.
- **Live signals + direction:** Core-power and enemy-pressure weights are tunable, and the whole
  mapping can be inverted (calm → higher skill) if you'd rather the director ramp the other way.
- **Five danger signals (v1.5.0 + v1.7.0):** beyond Core power and enemy pressure, the director
  also reads **local player health**, **player count** (fewer humans alive → more teammate
  assist, so a solo player gets backed up harder), and an optional **time-survived ramp** (the
  longer a match runs, the more capable teammates gradually become — ideal for endless modes).
  Each signal has its own weight, and any that can't be read in the current mode is skipped, so
  the blend always works everywhere.
- **Intensity floor / ceiling (v1.6.0):** clamp the live intensity so teammates never drop below
  a baseline level of help, or never ramp past a chosen cap.
- **Competence follows skill (default on):** the bots' aim speed, accuracy, target-tracking and
  perception are modulated to *match* the current skill in real time, so the director's effect
  is immediately felt rather than just a hidden number. (Computed from a captured baseline, so it
  never drifts or compounds.) Turn it off to scale only the raw Skill value.
- Skill is written as an absolute value every update, so it rises and falls cleanly and never
  compounds, no matter how long the session runs.

### Live config reload & diagnostics (NEW in v1.7.0)
Tuning no longer means restarting the game. Bind an optional **reload key** (or set an automatic
reload interval) and the mod re-reads `config.lua` on the fly — the difficulty director and every
newly-spawned toy immediately use your new values, while toys already in play keep what they had.
A syntax error in an edited config on reload is caught and ignored, so a bad edit never takes the
mod down; it just keeps the last good values. An optional **status key** prints a one-shot live
readout to the UE4SS console: current mode, difficulty, director skill/intensity, player count,
and how many toys have been enhanced — handy for confirming everything is live and watching the
director work in real time. All three keys are opt-in (default off).

### All game modes & all enemy types (NEW in v1.5.0)
**Every game mode is supported automatically.** The mod targets shared engine classes, so it
works across Waves, Survival, FreeRoam, Deathmatch, Plague, Zones, SpinnerArena, TankBattle and
CTB with no per-mode setup. Wave-specific features (building, battery seeking, Core defending)
simply lie dormant in modes that don't use them, and the difficulty director falls back to
universal signals (**player health** + enemy pressure) when a mode has no Core.

**Per-side mode filters (v1.8.0):** on top of the global `mode_filter`, you can now restrict the
**friendly** side and the **enemy** side to different modes independently via `bot_mode_filter`
and `enemy_mode_filter` — e.g. sharpen enemies in every mode but only buff your teammates in
co-op, or vice-versa. All three filters default to `"all"`.

**Every enemy type is covered.** Grounded foot soldiers and ninjas, shielded enemies, breakable
and multi-breakable enemies, simple NPC hazards (bouncy balls, **spinners — now with their own
MoveSpeed/SpinSpeed tuning in v1.8.0**), bosses, and airborne/floating enemies. All hostile AI
controllers (including the simple-AI variant) are caught, and the pawn pass tunes the correct
movement component for grounded vs flying enemies. Human players are never touched in any mode.

### Optional enemy escalation — dynamic difficulty *for enemies* (NEW in v1.8.0)
A counterpart to the friendly difficulty director: when enabled (off by default), every enemy
gets a one-time capability bonus **at spawn** scaled by the director's **live intensity**, so
enemies that appear while a match is hot are tougher (sharper perception + faster) than those
that appear while it's calm. It snapshots the intensity once per enemy (no per-tick work, never
compounds) and, because that intensity is built from universal signals, it escalates correctly
in **every** game mode. The bonus range is configurable, and an invert option turns it into a
rubber-band that pushes hardest on dominant players. Requires the difficulty director to be on so
an intensity exists; until a reading is available, enemies stay neutral.

### Enemy toys (Soldiers, Ninjas, Major Evil, swarmers) — behaviour
- See further, hear further, scan more often, with a wider field of view.
- Relentless pursuit: keep chasing long after losing line of sight.
- Strafe while engaging, chain jumps on landing, acquire targets faster (skip the slow
  extra line-of-sight passes).

### Enemy toys — pathfinding (the centrepiece)
- **Stuck detection + auto-repath:** enemies notice when they've stopped making progress and
  re-route immediately, with a hard last-resort teleport-free so they never wedge on geometry.
- **Target interception:** they lead your *future* position instead of trailing your current
  one — so they cut you off and flank instead of conga-lining behind you.
- **Smarter traversal:** they keep pathing while launched or falling, preserve queued jump
  links, climb taller obstacles, turn to face faster, and move/accelerate harder.
- **Optional route diversity** (off by default — see below) that splits the swarm across
  multiple approach paths.

---

## Installation

1. Make sure **UE4SS** is installed for *HYPERCHARGE: Unboxed* (the standard
   `dwmapi.dll` / `UE4SS` setup in the game's `…/Binaries/Win64/` folder).
2. Copy the whole **`StixsworldHD_UngodlyAIOverhaul`** folder into your UE4SS mods directory:

   ```
   <HYPERCHARGE>/Unboxed/Binaries/Win64/ue4ss/Mods/StixsworldHD_UngodlyAIOverhaul/
   ```

   (On some UE4SS layouts the path is `…/Win64/Mods/`. Use whichever `Mods` folder your
   UE4SS install already uses for other Lua mods.)

   The folder must contain:
   ```
   StixsworldHD_UngodlyAIOverhaul/
   ├── enabled.txt            (empty marker that tells UE4SS to load the mod)
   ├── README.md
   ├── CHANGELOG.md
   └── scripts/
       ├── main.lua           (the engine — you do not need to edit this)
       └── config.lua         (the ONLY file you edit)
   ```

3. (Optional) Add `StixsworldHD_UngodlyAIOverhaul : 1` to your UE4SS
   `Mods/mods.txt` if your UE4SS build uses that load list. The included `enabled.txt`
   already enables the mod for the standard auto-loader.
4. Launch the game. With `verbose_logging = true` you'll see a startup banner in the UE4SS
   console confirming it loaded.

---

## Configuring it — one file, fully documented

**`scripts/config.lua` is the only file you ever touch.** Every value has an inline comment
explaining what it does and a documented **min/max range**. Nearly everything is a
**multiplier on the game's own value**:

```
final_value = game_baseline_value × multiplier
```

- A multiplier of **1.0** means "leave it exactly as the game shipped it" (instant off-switch
  for any single feature).
- **Speed / range / distance / angle / chance** fields: **bigger = stronger AI**.
- **Interval / delay / cooldown** fields (how long the AI waits, how often it thinks):
  **smaller = stronger AI** — these default below 1.0 on purpose.

There are master switches to enable/disable the friendly side and the enemy side
independently, plus an optional live toggle key. Edit, save, relaunch (or hot-reload UE4SS).

---

## Why "route diversity" is off by default

The enemy **route-diversity** feature (section 7 of the config) forces varied navigation-query
filters across the swarm so they attack from multiple directions. It's fully implemented and
ready — but it's **off by default** because a handful of maps script their own per-spawn
routing, and a blanket filter override could occasionally conflict with that intended routing.

You do **not** need it for smart enemy pathfinding: the core pathfinding upgrades
(stuck-detection, target interception, launch/fall pathing, jump-link preservation, agility)
already make enemies dramatically better navigators while fully respecting each map's design.
If you want maximum flanking chaos, set `enemy_navfilter_spread = true` and tune the pool.

---

## Performance

This mod is built to be effectively free on your frame time:

- **Event-driven:** each entity is enhanced exactly **once**, the moment it's constructed,
  via an object-construction hook — not in a per-frame loop.
- **No per-tick AI logic:** there is no custom decision-making running every frame. The
  "smarter" behaviour comes from re-tuning the game's *own* native AI components, then
  letting the engine run them.
- **Tiny safety sweep:** a low-frequency maintenance pass (default **1 Hz**, adjustable)
  only catches stragglers and finishes pawns once they're possessed. It re-applies nothing
  to already-processed entities and prunes dead references so memory stays flat over long
  sessions.
- **Self-healing & patch-tolerant:** every property write and function call is individually
  guarded, so a single field renamed by a future game update can never break the rest of the
  overhaul — it just skips that one field.

---

## How it stays correct

- **Applied once per entity** (tracked by object identity), so buffs **never compound** no
  matter how long you play or how many waves spawn. *(Verified in an off-engine harness:
  repeated maintenance sweeps leave every value unchanged after the first application.)*
- **Multipliers, not overwrites**, so per-difficulty and per-character balance is preserved —
  Nightmare still feels harder than Easy, just smarter across the board.
- **Humans are never modified** — only AI-possessed bodies and AI controllers are touched.
- **Targets the shared `/Script/Unboxed.*` engine classes**, so the same mod covers the base
  game and **all DLC** characters and maps with no per-content patching.

---

## Compatibility & notes

- Works in Co-op, Wave/Survival, and single-player-with-bots modes.
- Compatible with other UE4SS Lua mods that don't fight over the same AI components.
- The optional **toggle key** pauses applying buffs to *new* toys; toys already enhanced keep
  their buffs until they despawn (the mod intentionally never tries to "un-tune" a live AI
  mid-fight).
- If you ever feel a single tweak made the AI worse, set that one multiplier back to `1.0` —
  every field is independent.

---

## Credits

**StixsworldHD (StixsmasterHD4k)** — design & implementation.

Built for *HYPERCHARGE: Unboxed* and all of its DLC. Enjoy the carnage.