HELIX | Sanity System

Bring psychological horror + juicy gameplay tension to your Helix server.

Turn light, loneliness, hunger (optional), combat and meds into a living sanity loop. As players slip, the world pushes back: whispers, silhouettes, trembling aim, and withdrawal. Everything is server-configurable.

✨ Core Features

🌓 Dynamic Sanity

1. Live sanity shifts from light level, nearby players, combat, and (optionally) hunger/thirst.
2. Optional Regen Lock: below a threshold, non-medic regen (light, social, etc.) is blocked → players must seek meds & safety.
3. Tunable tick rate + multipliers.

👁 Visual Immersion

1. Pulsing, color-shifting HUD brain that mirrors mental state.
2. Screen FX that intensify as sanity drops (desaturation, motion blur).
3. Darkness monologues: atmospheric typewriter text in low light.
4. Real Aim Shake (optional): low-sanity + raised firearm + ADS → subtle, physical view jitter (raised/safety/ironsight checks; firearm detection for common bases).

🔊 Audio Atmosphere

1. Ramping global echo/reverb at low sanity.
2. Random whispers and “familiar” voices calling from nowhere.

👤 Hallucinations (client-side)

1. Human silhouettes spawn under a sanity threshold.
2. At very low sanity they chase and can hurt on contact.
3. Disperse by shooting near them—no strict hitreg needed.
4. Smooth spawn/despawn; fully configurable.

💊 Psychotropics, Tolerance & Addiction

1. One tag per substance (e.g., Benzodiazepine, Opioid) drives both tolerance and addiction.
2. Tolerance lowers item effectiveness with use; decays over time; capped per profile.
3. Addiction builds with use; after a crave delay, withdrawal begins → periodic sanity loss scaling with severity.
4. Optional Fallover: during withdrawal, a growing chance to faint (resets after faint).
5. Smart tooltips: Effectiveness %, Tolerance Level/Reduction/Cap, Group info, and Addicted / Withdrawal Active.
6. Ships with example items (Xanax, Opium) + ready-to-tune profiles; adding yours is one file.

🌐 Survival Integration (optional)

Auto-detects ZeMysticalTaco’s survival plugin — sanity drains below thresholds and softly regens when well-fed/hydrated. No setup needed.

⚙ Fully Configurable (in-game)

1. Toggle: hallucinations, echoes, whispers, monologues, aim shake.
2. Enable/disable tolerance and addiction independently.
3. Tune darkness/light, social, PvP penalties, regen lock, withdrawal, fallover, and profile caps/levels.
4. Faction exclusions to ignore the system for specific roles.

🛡 Safe by Default

1. Survival hooks auto-disable when the plugin isn’t installed.
2. Noclip players are fully excluded.
3. Clean shutdown on spawn/disconnect/char-swap.
4. Networking is server-validated; client visuals are sandboxed.

🎮 Gameplay Impact

1. Mild Loss – subtle HUD changes, soft whispers/echoes, reduced regen.
2. Moderate Loss – silhouettes visible, aim tremor, stronger AV distortion.
3. Severe Loss – hostile silhouettes, contact damage, heavy whispers, withdrawal pressure and possible fainting.
4. Meds work… but tolerance and addiction force trade-offs and planning.

🧪 Psychotropics 101 (quick dev notes)

1. Item defines:
2. ITEM.sanityAdd (±), ITEM.psychoTag, ITEM.toleranceBuild, ITEM.addictionBuild.
3. Profile defines (one place):
4. threshold, craveDelay, withdrawalTick/Loss/Scale, decayInterval/Step,
5. Tolerance: tolCap, tolMaxLevel (auto computes tolStep), tolBuild, tolDecayInterval/Step,
6. Fallover: fallover, falloverChanceStart/Step/Max, falloverCheckInterval, falloverTimeMin/Max.

Tooltips preview current effectiveness; admin command ix_sanity_factors shows live per-minute math (incl. withdrawal breakdown).

🔧 Admin & Debug

1. Client (admin):
2. ix_sanity_debuglight – reported vs raw light + threshold overlay.
3. ix_sanity_factors – prints darkness/light/social/survival/withdrawal and total per minute.
4. Server (admin):
5. SetSanity, AddSanity for direct control.

📦 What’s New in v1.1

1. Psychotropics overhaul: unified tag system, readable tooltips, profile-driven tolerance & addiction.
2. Withdrawal + Fallover: scaling sanity loss with optional fainting loop.
3. Real Aim Shake for low sanity while aiming firearms.
4. Regen Lock option for low-sanity gating of non-medic regen.
5. Stability/UX: safer netting, effectiveness prediction, richer debug.

✅ Requirements & Installation

Requires: Helix (HL2RP branch recommended)

Workshop: https://steamcommunity.com/sharedfiles/filedetails/?id=3548890675

Install: Drop the sanity folder into gamemodes/ixhl2rp/plugins/, restart, tweak configs in-game.

Optional: Survival plugin (auto-detected):

https://github.com/ZeMysticalTaco/ffi-hl2rp/blob/master/ixhl2rp/plugins/survival_system.lua

💬 Perfect for HL2RP… and anything Helix

Subtle psychological pressure or full survival horror—you set the tone. The system adapts to your server’s theme and balance.