Happy Guy

# 🎭 HAPPY GUY — COMPLETE FEATURE OVERVIEW (A to Z)

---

## 📋 OVERVIEW

**Happy Guy** is an immortal, intelligent, emotional, and protective custom entity for Minecraft Forge 1.21.1. Inspired by the original "Happy Guy" creepypasta/mythos, rebuilt from the ground up with modern modding standards.

> **Mod ID:** `happy_guy`  
> **Entity ID:** `happy_guy:happy_guy`  
> **Version:** 2.4.3-NeutralColors  

---

## 🧬 CORE STATS

| Attribute | Value |
|-----------|-------|
| **Health** | 160 HP (80 hearts) — **Never decreases** |
| **Attack Damage** | 14 (7 hearts) |
| **Speed** | 0.45 base → **2.45 max** (full rage) |
| **Follow Range** | 75 blocks (stalk) / Infinite (chase) |
| **Knockback Resistance** | 1.0 (Complete) |
| **Armor** | 12 |
| **XP Drop** | 0 (Cannot be killed) |
| **Category** | MONSTER |
| **Hitbox** | 1.15 × 3.25 blocks |

---

## 🎭 THREE-PHASE BEHAVIOR CYCLE

### **PHASE 1: CALM STALKER (Default)**
- Silently follows nearest player within 75-block radius
- At 18 blocks: "stalk around" — circles the player
- At 8 blocks (2.5 in water): Stops, locks gaze on player
- **Never attacks**, only watches
- **If player wears Happy Guy Head** → **Completely stops, breaks pursuit**

### **PHASE 2: RAGE TRANSFORMATION (Tantrum + Scream = 20 seconds)**
Triggers: Player hits him, command, or mob hits player

| Stage | Duration | Behavior |
|-------|----------|----------|
| **Tantrum** | 10 sec (200 ticks) | Stomps, hits own head, body slams, guttural sounds |
| **Scream** | 10 sec (200 ticks) | Continuous scream, head flails wildly, body trembles |
| **Chase Ready** | After 20 sec | **Full-speed pursuit begins** |

**Audio:** `tantrum` every 2 sec, `scream` every 2.4 sec (4-layer overlap)

### **PHASE 3: PURSUIT (Rage Chase)**
- **Speed ramp:** 3 minutes (3600 ticks) from 1.0× → 2.45×
- **Smart pathfinding:** Breaks walls, swims lava/water, dimensional travel
- **Long-distance:** 2048+ blocks uses "leapfrog" teleport with chunk tickets
- **Cross-dimension:** Opens portal if player changes dimension, continues hunt
- **Attack:** 3.15 block reach, 20-tick cooldown, knockback + damage

---

## 🛡️ TRUE IMMORTALITY SYSTEM

**Blocks ALL damage sources:**
- `/kill`, void damage, magic bypass, modded one-shots, command blocks, creative mode extremes
- `hurt()` → only provokes, returns `false` (no damage taken)
- `die()` → instantly restores to full health
- `remove(KILLED/DISCARDED)` → refuses deletion, restores instead

**Only bypass:** `/happyguy kill` command (forceKill) → clears NBT → `super.remove(KILLED)`

---

## 🧠 ADVANCED AI & PATHFINDING

### **Navigation**
- Floats on water/lava (`setCanFloat(true)`)
- Water/Lava/Border path cost = 0 (fluids are **paths**, not barriers)
- Smart waypoint system (96+ blocks without loading chunks)
- Obstacle replanning: tries alternate route → jumps → last resort breaks blocks

### **Block Breaking**
- Only breaks **ray-traced** blocks directly between him and target
- Clears 4-block high column
- Breaks bedrock (setBlock AIR), normal blocks drop items

### **Water Escape Mode**
- If stuck in water while player is dry for 80 ticks (4 sec) → activates escape
- Finds nearest dry land within 24 blocks, combines pathfinder + vector steering

---

## 🎭 ANIMATION SYSTEM — NATIVE JSON

**Files:**
- `model/happy_guy.model.json` — 15 bones (root, body, head, arms, hands, legs, ears, fingers)
- `animations/happy_guy.motion.json` — 7 animation clips

| Clip | Loop | Duration | Usage |
|------|------|----------|-------|
| `idle` | ✓ | 2.2s | Standing still |
| `walk` | ✓ | 0.62s | Slow movement |
| `run` | ✓ | 0.42s | Rage chase |
| `angry` | ✓ | 0.72s | Angry idle |
| `attack` | ✗ | 0.62s | Attack (client event 61) |
| `tantrum` | ✓ | 2.35s | Transformation phase 1 |
| `scream` | ✓ | 2.4s | Transformation phase 2 |

**Procedural Secondary Motion (Code-driven):**
- **Breathing:** Sin-wave body bob, slight tilt
- **Ear wiggle:** Idle/walk — ears twitch on Z-axis
- **Head tracking:** Smooth interpolation (yaw ×0.82, pitch ×0.55) — no snapping
- **Walk/Run:** Contra-phase limbs, body bounce, head bob
- **Tantrum:** Chaos mode — random limb flailing at 18× speed
- **Scream:** High-frequency — head shakes 5.5° pitch, 3° yaw, 2.2° roll
- **Angry idle:** Tense posture, finger tremors, arm tension

**Blend System:** 0.18s smoothstep transitions between all clips (no popping)

---

## 🎨 VISUAL TRANSFORMATION — 9-STAGE FACE

| Stage | Rage Ticks | Texture |
|-------|------------|---------|
| 0 | 0 | `happy_guy.png` (Normal, happy) |
| 1–7 | 1–175 | `transform_1.png` through `transform_7.png` |
| 8 | 176–200 | `transform_8.png` |
| **9** | **200+** | **`happy_guy_angry.png` (Full rage)** |

> **Red glitch fix:** Renderer uses `LivingEntityRenderer.getOverlayCoords()` + forced white vertex color.

---

## 🔊 COMPLETE SOUND DESIGN

| Event | Sound ID | Notes |
|-------|----------|-------|
| Ambient | `happy_guy_ambient` | Every 800 ticks |
| Transform | `happy_guy_transform` | 1.6× vol, 0.82 pitch |
| Tantrum | `happy_guy_tantrum` | 1.15× vol, 0.76–0.98 pitch |
| Scream | `happy_guy_scream` | 2.05× vol, 0.84–0.96 pitch (4-layer overlap) |
| Attack | `happy_guy_attack` | 1.0× vol, 0.88–0.96 pitch |
| Hurt/Provoke | `happy_guy_hurt` | — |
| Snarl (Protective) | `happy_guy_snarl` | 1.2× vol, 0.9–1.0 pitch |
| Reconstitute | `happy_guy_reconstitute` | 1.4× vol, 0.82 pitch |
| Step | `happy_guy_step` | Angry: 0.9v/0.68p, Calm: 0.48v/1.02p |

**Full subtitle support:** Both `en_us.json` and `tr_tr.json` complete.

---

## 🧢 HAPPY GUY HEAD (ITEM)

| Property | Detail |
|----------|--------|
| **Type** | Helmet (ArmorItem.Type.HELMET) |
| **Material** | Netherite (0 durability — unbreakable) |
| **Rarity** | RARE (red tooltip) |
| **Fireproof** | Yes |
| **Enchantable** | No (table or anvil) |
| **Max Stack** | 1 |
| **Armor Texture** | `happy_guy:textures/models/armor/happy_guy_head_layer_0.png` |
| **Item Model** | `assets/happy_guy/models/item/happy_guy_head.json` |

### **Effect**
- **Equipped:** Happy Guy **stops following** that player entirely
- **Unequipped:** Happy Guy **resumes pursuit** immediately
- Works via player persistent data (`HappyGuyHeadWorn` boolean)

### **Loot Table**
- **All vanilla chests** (`minecraft:chests/*`)
- **0.5% chance** (`random_chance: 0.005`)
- Injected via global loot modifier (no worldgen conflicts)

---

## ⚔️ PROTECTIVE MODE (NEW FEATURE)

**Trigger:** Player has `hurtTime > 0` (recently hit) AND a nearby mob has `getTarget() == player`

| Parameter | Value |
|-----------|-------|
| **Speed** | `MOVEMENT_SPEED × 3.5` (Enderman-tier ≈ 1.575 blocks/tick) |
| **Duration** | 600 ticks (30 seconds) |
| **Target** | Nearest threatening mob |
| **Behavior** | Hunts **only that mob**, does **NOT** become angry |
| **Particles** | `ENCHANTED_HIT` every 5 ticks |
| **Sound** | `happy_guy_snarl` once at start |
| **End Condition** | Mob dies or 30 seconds expire → Returns to normal stalking |

**Persistence:** `protectiveTargetUuid` + `protectiveCooldown` saved to NBT, resolved on world reload.

---

## 🌍 CHUNK TICKET MANAGEMENT

- **Stalk mode:** 1×1 chunk (self only)
- **Chase/Distant:** 3×3 chunk moving square
- **Cross-dimension:** Old tickets released, new ones acquired
- **Watchdog:** Every 20 ticks ensures single immortal instance per world

---

## 💾 FULL NBT PERSISTENCE

Saves and restores:
- Anger state, rage ticks, target UUID, pursuit speed
- Distant pursuit ticks, player hunt flag, relocation cooldown
- **Protective cooldown, protective target UUID**
- Chunk ticket positions (up to 9 chunks)

---

## 🎮 COMMANDS (`/happyguy` — Op Level 2)

| Command | Description |
|---------|-------------|
| `/happyguy spawn` | Spawns at command user's position |
| `/happyguy rage <entity>` | Provokes Happy Guy at target entity |
| `/happyguy kill` | **Force-kills ALL Happy Guys** (bypasses immortality) |

**Examples:**
```
/happyguy rage @p
/happyguy rage @e[type=iron_golem]
/execute as @e[type=happy_guy,limit=1] run happyguy rage @e[type=zombie,limit=1,sort=nearest]
```

---

## 📦 INSTALLATION & REQUIREMENTS

### **Requirements**
- Minecraft 1.21.1
- Forge 52.1.20+
- Java 21

### **Client/Server**
- **Required on both sides** (custom renderer, animations, particles, sounds)

---

## 🎨 TEXTURES YOU NEED TO PROVIDE

| File | Size | Purpose |
|------|------|---------|
| `happy_guy.png` | 128×128 | Normal face |
| `happy_guy_angry.png` | 128×128 | Full rage face |
| `happy_guy_transform_1.png` – `transform_7.png` | 128×128 | 7 transition frames |
| `happy_guy_head_layer_0.png` | 64×32 | **Armor texture (helmet layer)** |
| `happy_guy_head.png` | 16×16 | **Inventory icon** |

**Paths:**
```
assets/happy_guy/textures/entity/happy_guy*.png
assets/happy_guy/textures/models/armor/happy_guy_head_layer_0.png
assets/happy_guy/textures/item/happy_guy_head.png
```

---

## ⚙️ CONFIGURABLE FUTURE (PLANNED)

- Health, damage, speed multipliers
- Loot chance, stalk radius, rage duration
- Natural spawn conditions/biomes
- Boss bar toggle
- Advancement integration

---

## ✅ CURRENT STATUS

- ✅ **Truly unkillable** (tested against /kill, void, modded damage)
- ✅ **Smart pursuit** (pathfinding + block break + dimension hop)
- ✅ **Emotional depth** (3-phase transformation, 9-frame face, 7 animations)
- ✅ **Protective guardian** (Enderman-speed retaliation when mobs hurt player)
- ✅ **Player control** (Head item toggles following, commands for admin)
- ✅ **Collectible** (Chest loot, rare item)
- ✅ **Visually stable** (No red glitch, smooth blending)
- ✅ **Fully audible** (7 sounds, layered scream, subtitles)
- ✅ **Compiles & builds** — Ready to play

---

## 📝 NOTES FOR CURSEFORGE PAGE

> **⚠️ IMPORTANT NOTES FOR USERS:**
> 
> 1. **This mob cannot be killed by normal means.** The `/happyguy kill` command is the only way to remove it. This is intentional design.
> 
> 2. **The Happy Guy Head item uses a placeholder texture.** You must add your own `happy_guy_head_layer_0.png` (64×32 armor texture) and `happy_guy_head.png` (16×16 item texture) to the resource pack, or the helmet will show as purple/black missing texture.
> 
> 3. **All 9 entity textures (normal, angry, 7 transforms) must be provided** in `assets/happy_guy/textures/entity/` or the visual transformation will show missing textures.
> 
> 4. **Requires Forge 52.1.20+ on both client and server.** Custom renderer, animations, and particles need client-side mod.
> 
> 5. **Loot injection uses global loot modifiers** — compatible with other mods that modify chest loot, no worldgen conflicts.
> 
> 6. **Single instance per world** — The watchdog ensures only one Happy Guy exists per save. If you spawn another, it manages the existing one.
> 
> 7. **Cross-dimension pursuit works** — If the target player goes to the Nether/End, Happy Guy will follow through a generated portal.
> 
> 8. **No natural spawning by default** — Use `/happyguy spawn` or creative inventory spawn egg. Natural spawner exists but is disabled pending config.

---

## 🏷️ TAGS FOR CURSEFORGE

`mob` `boss` `immortal` `ai` `chase` `horror` `creepypasta` `custom-entity` `forge` `1.21.1` `protection` `collectible` `commands` `animation` `sound` `particles`