# FS25_HumanFactors — README

## Overview
HumanFactors adds lightweight player needs and work realism to Farming Simulator 25.

Core features:
- Fatigue and Hunger systems
- Optional Thirst system with 1.0L water bottle
- Eat menu with multiple food choices
- Drinks menu for water and coffee
- Rest action
- Monthly wages based on hours worked
- Fatigue-based driving and working penalties
- Fatigue-based screen dimming and warning popups
- Native in-game settings toggles

---

## Controls (rebindable in Controls menu)
Category: **Human Factors**

- **Eat Menu:** Right Ctrl + K
  - Opens the standard eat menu for **Small meal** / **Light snack**
- **Full Meal:** Right Ctrl + L
  - Full meal only works when standing in a **sleep trigger**
- **Drinks Menu:** Right Ctrl + U
  - Opens the drinks menu for **Water** / **Coffee**
- **Rest:** Right Ctrl + R
- **Refill Bottle:** Right Ctrl + I

---

## Fatigue
Fatigue is based on **in-game time**.

### Fatigue gain rates
- **Idle / on foot / not working:** +**2% per in-game hour**
- **Working:** +**10% per in-game hour**
- **Sleeping:** fatigue resets to **0%**

### Hunger interaction with fatigue
When **Hunger reaches 80% or more**, fatigue gains an additional penalty of:
- **+5% per in-game hour**

This makes the total fatigue gain:
- **Idle while hungry (80%+ hunger):** +**7% per in-game hour**
- **Working while hungry (80%+ hunger):** +**15% per in-game hour**

### Fatigue warning thresholds
When Fatigue is enabled, the mod shows one-time warning popups as you cross these levels:
- **90%:** “You are tired, find a sleep trigger!”
- **95%:** “You are exhausted, find a sleep trigger!”
- **100%:** “You are dangerously tired, sleep now!”

These warnings re-arm if your fatigue drops back below the threshold and rises again later.

### Fatigue penalties at 90%+
Once fatigue reaches **90% or higher**:
- Your **vehicle maximum forward speed** is limited to **50%**
- If an implement is attached, the **working speed limit** is reduced to **50%**

These penalties are only applied while:
- Fatigue is enabled
- You are in a vehicle
- You are actively working
- You are not sleeping

### Screen dimming
When fatigue reaches **90% or higher**, a black full-screen overlay is rendered to simulate tiredness.

Dimming strength increases with fatigue:
- **90–95% fatigue:** light dimming
- **95–100% fatigue:** strong dimming
- **100% fatigue:** very heavy dimming

The dimming effect is capped so the screen never becomes completely black, but visibility is significantly reduced at very high fatigue.

---

## Hunger
Hunger is based on **in-game time**.

### Hunger gain rate
- **+10% per in-game hour**

### Hunger warning
When Hunger reaches **100%**, the mod shows:
- “You are hungry, you should eat something!”

This warning re-arms after hunger drops below the threshold and reaches 100% again later.

---

## Thirst (optional)
Thirst can be enabled or disabled in the in-game settings.

### Thirst gain rate
- **+10% per in-game hour**

### Water bottle system
- Bottle capacity: **1.0L**
- Each drink uses: **0.25L**
- Bottle can only be refilled while standing in a **sleep trigger**

### Drinking water
- Cooldown per sip: **0.5 in-game hours**
- Each sip reduces thirst by **25% of current thirst**

### Refill bottle
- Refill is only available in a **sleep trigger**
- Refill instantly restores the bottle to **1.0L**

If Thirst is disabled:
- The thirst HUD line is hidden
- Thirst actions are blocked

---

## Eating

### Eat menu cooldown
The eat menu uses a difficulty-based cooldown measured in **in-game hours**.

- **Easy:** 2.0 hours
- **Normal:** 3.0 hours
- **Hard:** 4.0 hours

If you try too soon, the game shows the remaining cooldown time.
If hunger is effectively zero, eating is blocked.

### Food options
- **Full meal** — **£20**
  - Sets **Hunger to 0%**
  - Sets **Thirst to 0%**
  - Reduces **Fatigue by 50%**
  - Only available in a **sleep trigger**

- **Small meal** — **£10**
  - Reduces Hunger to **50% of current value**

- **Light snack** — **£5**
  - Reduces Hunger to **80% of current value**

---

## Coffee
Coffee is accessed from the **Drinks Menu**.

### Coffee cooldown
Difficulty-based cooldown:
- **Easy:** 2.0 hours
- **Normal:** 3.0 hours
- **Hard:** 4.0 hours

### Coffee effects
- Cost: **£2.50**
- Reduces Fatigue by:
  - **Easy:** 20
  - **Normal:** 15
  - **Hard:** 10
- Also reduces Thirst by **10%** when Thirst is enabled

---

## Rest

### Rest cooldown
- **Easy / Normal / Hard:** **4.0 hours**

### Rest effects
- Rest reduces Fatigue by:
  - **Easy:** 20
  - **Normal:** 15
  - **Hard:** 10

### Rest restriction
- Rest is blocked if fatigue is below **1%**
- Message shown: **“You are not tired.”**

---

## Wages
Wages can be enabled or disabled in the in-game settings.

### How wages work
- Hours worked are tracked during gameplay
- Wages are paid when the **in-game month changes**
- Payment is based on the hours worked in the previous month

### Default wage rates
Editable in: `scripts/hf/HF_Wages.lua`

- **Easy:** £30/hour
- **Normal:** £25/hour
- **Hard:** £20/hour

---

## Settings
The mod includes native settings toggles for:
- **Enable Fatigue**
- **Enable Hunger**
- **Enable Thirst**
- **Enable Wages**
- **Vehicle speed limiter**

Notes:
- If **Fatigue** is disabled, fatigue is forced to 0 and fatigue penalties do not apply
- If **Hunger** is disabled, hunger is forced to 0
- If **Thirst** is disabled, thirst actions are blocked and thirst is hidden from the HUD

---

## Notes
- Cooldowns use **absolute in-game time**, so they remain consistent across day changes
- Stat progression is designed to continue behaving sensibly even if time speed is paused
- The mod is intended to add light realism without turning the game into a full survival sim
