Malnutrition Matters

### 1.0.2
- Added death grace period: on death all active disease tiers are rolled back one step and tier escalation is suspended for half an in-game day. Addresses compounding punishment from dangerous situations such as temporal storms.

### 1.0.1
- Increased Dairy category day floor from Day 42 to Day 90, reflecting the realistic time investment required to establish a milkable animal in survival gameplay.
- Increased tier escalation grace periods to reduce early-game harshness (Healthy→Tier 1: 2→3 days, Tier 1→Tier 2: 1.5→2.25 days, Tier 2→Tier 3: 1→1.5 days). Subject to further tuning based on playtesting.
- Added per-player first-seen grace period of 7 in-game days. Players on existing long-term worlds will no longer be immediately punished when the mod is added mid-playthrough.

# Malnutrition Matters
### A Vintage Story Mod by SeaWolf
**Version:** 1.0.0 | **Game Version:** 1.22.3

---

## Overview

Malnutrition Matters adds a realistic nutritional deficiency and disease system to Vintage Story. The base game rewards balanced nutrition with a health bonus, but does not penalize neglect. This mod changes that — ignore your diet long enough and your body will show it.

Deficiency diseases are named after their real-world counterparts, grounded in adult pathology. The system is designed to add urgency and depth to the nutrition mechanic without being immediately punishing to new players.

---

## How It Works

### Nutrition Categories
The mod tracks four nutritional categories mapped from the game's five food groups:

| Mod Category | Game Foods |
|---|---|
| Fruit & Veg | Fruit + Vegetable (higher of the two is used) |
| Protein | Protein |
| Grain | Grain |
| Dairy | Dairy |

### Deficiency Threshold
A category is considered deficient when its nutrition value falls below **25% of maximum saturation**.

### Grace Periods
New players are protected from immediate punishment. Each category has a **day floor** — a hard deadline before which no deficiency penalties apply — and a **first consumption** trigger that starts the clock early for players who find food ahead of schedule.

| Category | Day Floor | Notes |
|---|---|---|
| Fruit & Veg | Day 3 | Berries and fruit available from day 1 |
| Protein | Day 7 | Hunting takes time to establish |
| Grain | Day 21 | First wild crop or farming cycle |
| Dairy | Day 42 | Finding, taming, and milking animals takes weeks |

**Hybrid grace logic:** A category goes live when either:
- The day floor is reached (hard deadline), OR
- The player has consumed that category at least once (early trigger)

A player who finds dairy on day 10 starts their dairy clock immediately. A player who hasn't found dairy by day 42 starts their clock then regardless.

---

## Disease System

### Solo Disease Tracks

Each category has three tiers of escalating disease, named after real adult malnutrition conditions.

**Fruit & Veg — Vitamin C deficiency**
| Tier | Disease | Effects |
|---|---|---|
| 1 | Hypovitaminosis | Reduced healing rate (-20%) |
| 2 | Scurvy | Reduced healing rate (-45%), minor max HP loss |
| 3 | Scorbutic Crisis | Severe healing suppression (-80%), major HP loss, periodic damage ticks |

**Protein deficiency**
| Tier | Disease | Effects |
|---|---|---|
| 1 | Hypoproteinemia | Reduced mining/action speed (-20%) |
| 2 | Kwashiorkor | Reduced action speed (-35%), minor max HP loss |
| 3 | Cachexia | Major action speed loss (-55%), significant HP loss, periodic damage ticks |

**Grain — B3/energy deficiency**
| Tier | Disease | Effects |
|---|---|---|
| 1 | Fatigue Syndrome | Accelerated hunger drain (+20%) |
| 2 | Pellagra | Accelerated hunger drain (+40%), reduced movement speed (-15%) |
| 3 | Pellagra Gravis | Major hunger drain (+65%), movement penalty (-30%), periodic damage ticks |

**Dairy — Calcium deficiency**
| Tier | Disease | Effects |
|---|---|---|
| 1 | Hypocalcemia | Minor movement reduction (-10%) |
| 2 | Osteomalacia | Movement penalty (-20%), increased fall damage (+30%) |
| 3 | Osteoporosis | Significant movement penalty (-35%), severe fall damage multiplier (+75%) |

---

### Combinational Diseases

When multiple categories are deficient simultaneously, additional diseases can trigger on top of solo track effects.

| Trigger | Disease | Effects |
|---|---|---|
| Fruit+Veg AND Grain deficient | Beriberi (dry) | Movement penalty (-20%), mining speed reduction (-25%) |
| Protein AND Dairy deficient | Marasmus | Max HP gutted (-8), severe action speed loss (-40%) |
| Fruit+Veg AND Dairy deficient | Xerophthalmia | Movement/perception penalty (-15%) |
| ALL categories deficient | Starvation Syndrome | Stacks on all active debuffs: HP loss (-10), movement (-30%), action speed (-50%), hunger drain (+80%), periodic damage ticks |

Starvation Syndrome is intentionally severe — it stacks on top of every active solo and combinational debuff simultaneously.

---

### Tier Escalation

A category must be deficient for a sustained period before the disease worsens. The grace window shrinks as severity increases, representing the body's resilience wearing down.

| Transition | Time Deficient Required |
|---|---|
| Healthy → Tier 1 | 2 in-game days |
| Tier 1 → Tier 2 | 1.5 in-game days |
| Tier 2 → Tier 3 | 1 in-game day |

---

### Recovery

Recovery occurs when a category's nutrition value rises above the deficiency threshold. Tiers step back down one at a time — there is no instant cure. The player will receive chat notifications as each tier improves.

---

## Balance Reward

Maintaining all four categories above the deficiency threshold is rewarded with a scaling reduction to hunger drain rate. The bonus scales up over 3 in-game days of sustained balance, reaching a maximum of **30% reduced hunger drain**. The bonus resets immediately if any category becomes deficient.

---

## Notifications

The mod communicates disease state through chat notifications. Players will be informed when:
- A new disease tier begins
- A condition worsens to the next tier
- A condition begins to ease
- Full recovery is achieved
- A combinational disease triggers or subsides

---

## Technical Notes

### Architecture
The mod is server-side authoritative. All nutrition tracking, tier management, and debuff application occurs on the server. No client-side components are required for core functionality.

### Save Data
Player nutrition state (tier, grace period timers, balance timer) is saved to the world save file on player disconnect and on world save. State is loaded on player join. Each player's state is keyed to their unique player UID and is world-specific.

### Stat Modifiers
Debuffs are applied via `EntityStats.Set` with unique modifier codes per disease track. All modifiers are cleanly removed when a disease tier drops or a player recovers, preventing stacking or ghost effects.

### Nutrition Reading
Nutrition values are read from the entity's `WatchedAttributes` hunger tree each server tick using the following keys:
- `fruitLevel`
- `vegetableLevel`
- `grainLevel`
- `proteinLevel`
- `dairyLevel`

The mod uses the higher of `fruitLevel` and `vegetableLevel` for the combined Fruit & Veg category.

### Performance
The mod registers a single server tick listener firing every 1 second. Time delta is calculated from the game calendar rather than wall clock time, ensuring correct behavior at any time speed multiplier.

### Debug Commands
Two debug commands are available to players with chat privilege:

- `/mmstatus` — displays current nutrition values, tier state, grace period status, and balance timer
- `/mmreset` — resets all mod state for the calling player and clears all active debuffs (intended for testing)

---

## Compatibility

- **Vintage Story:** 1.22.3
- **Dependencies:** game, survival
- **Known conflicts:** None at time of release. Mods that significantly alter the hunger system or `EntityBehaviorHunger` may cause unexpected behavior.

---

## Planned Features

- Small unobtrusive HUD icon above the hunger bar showing active disease state
- Balance tuning based on playtesting feedback

---

## Credits

**Design & Development:** SeaWolf

*Malnutrition Matters was built with the goal of making Vintage Story's nutrition system feel meaningful — not punishing for the sake of punishment, but grounded in the real consequences of dietary neglect.*