> For the complete documentation index, see [llms.txt](https://docs.menanak47.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.menanak47.com/multi-framework/ak47_drugmanagerv3/addition.md).

# Addition

Ak47 Drug Manager V3 includes a comprehensive addiction and physical tolerance lifecycle featuring withdrawal stages, sensory impairments, detox medications, and medical exports.

### 📈 1. Addiction vs. Tolerance

Every time a player consumes a usable drug, two distinct values are incremented:

* **Addiction (Physical Dependence)**: Increases dependence on the substance. If the player goes too long without consuming the drug, withdrawal symptoms kick in.
* **Tolerance (Substance Adaptation)**: Reduces the likelihood of negative side-effects (such as coughing, vomiting, or passing out) while under the influence of the drug.

Both values range from `0` to `100` and are saved in the database under `ak47_drugmanagerv3_addiction` by player identifier.

***

### ⚠️ 2. Withdrawal Stages (When Clean)

When an addicted player is **not** actively under the influence of any drug (`not isInAnyDrug()`), the script evaluates their highest addicted drug level and applies withdrawal stages:

| Tier     | Addiction Level |    Grace Period   |   Health Drain  |  Passout & Vomit Chance | Warning Alert          |
| -------- | :-------------: | :---------------: | :-------------: | :---------------------: | ---------------------- |
| **Low**  |      `> 30`     |     15 minutes    | -5 HP every 30s | 10% Passout / 30% Vomit | `_U('addiction_low')`  |
| **Mid**  |      `> 50`     |     10 minutes    | -5 HP every 15s | 20% Passout / 50% Vomit | `_U('addiction_mid')`  |
| **High** |      `> 75`     | 0 min (Immediate) |  -5 HP every 3s | 30% Passout / 70% Vomit | `_U('addiction_high')` |

***

### 🤢 3. Physical & Visual Impairments During Withdrawal

When health loss begins, the player also experiences physical withdrawal symptoms (`Config.AddictionEffect`):

* **Visual Shaders**: Distorted screen haze (`Drug_gas_huffin`).
* **Camera Shake**: Shakes the gameplay camera (`DRUNK_SHAKE`).
* **Motion Blur**: Blurs rapid camera turns.
* **Stumble Walk**: Forces an impaired drunk walking style (`MOVE_M@DRUNK@SLIGHTLYDRUNK`).
* **Blackouts & Passouts**: Triggers progressive blackout screen fade sequences (`DoScreenFadeOut`) and ragdoll passout animations.
* **Vomiting**: Triggers vomiting animations on foot (`missfam5_blackout`) or leaning out the vehicle door if driving (`oddjobs@taxi@tie`).

***

### 💊 4. Prescription Anti-Addiction Items

Configured in `configs/usable.lua` under `Config.AntiAddiction`:

| Item ID       | Item Label  |     Type    | Use Case & Effect                                                                                                                                                           |
| ------------- | ----------- | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `acamprosate` | Acamprosate | Usable Pill | **Prescription Detox Medicine**: Consumed via pill animation (`mp_suicide:pill`). Reduces addiction by **20 points** and tolerance by **6 points** across all substances.   |
| `lofexidine`  | Lofexidine  | Usable Pill | **High-Strength Detox Medicine**: Consumed via pill animation (`mp_suicide:pill`). Reduces addiction by **50 points** and tolerance by **16 points** across all substances. |

***

### ⏳ 5. Natural Body Decay (Passive Recovery)

A player's body naturally recovers and reduces addiction and tolerance over time:

* **Addiction Decay**: Naturally decreases by **2 points every 3 minutes** (`Config.AddictionReduce`).
* **Tolerance Decay**: Naturally decreases by **2 points every 6 minutes** (`Config.ToleranceReduce`).

***

### 🔌 6. Developer & Hospital Integration Export

Third-party hospital beds, rehabilitation centers, and medical scripts can reduce addiction levels programmatically:

```lua
-- Reduces the player's active addiction levels across all drugs by the specified amount
exports['ak47_drugmanagerv3']:ReduceAddiction(30)
```

***

### 👑 7. Admin Management Commands

Admins (or server console) can clear addictions and tolerances using the following commands:

| Command            | Syntax                         | Description                                                                                    |
| ------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `/removeaddiction` | `/removeaddiction [player_id]` | Instantly wipes all drug addictions and tolerances for self or target player.                  |
| `/cleardrugs`      | `/cleardrugs [player_id]`      | Complete wipe: clears all addictions, tolerances, overdoses, and screen shaders in one action. |

***

### ⚙️ 8. Configuration Reference (`configs/usable.lua`)

```lua
Config.AddAddiction = 5 -- Default addiction points added per drug use
Config.AddTolerance = 4 -- Default tolerance points added per drug use

Config.AddictionLevel = {
    low  = { level = 30, health_lose = 5, tick = 30, period = 15, passout_chance = 10, vomit_chance = 30 },
    mid  = { level = 50, health_lose = 5, tick = 15, period = 10, passout_chance = 20, vomit_chance = 50 },
    high = { level = 75, health_lose = 5, tick = 3,  period = 0,  passout_chance = 30, vomit_chance = 70 },
}

Config.AddictionReduce = { tick = 3, amount = 2 } -- -2 points every 3 minutes
Config.ToleranceReduce = { tick = 6, amount = 2 } -- -2 points every 6 minutes

Config.AntiAddiction = {
    acamprosate = 20, -- Reduces addiction by 20
    lofexidine = 50,  -- Reduces addiction by 50
}
```