---

📖 Table of Contents

• ✨ Features
• 📦 Requirements
• 🚀 Installation
• ⌨️ Commands & Permissions
• 🔧 Configuration
• 🧩 Developer API
• 🔍 Troubleshooting
• 📄 Credits

---

✨ Features

🧠 Advanced Zombie AI

• 20+ zombie types fully configurable in zombies.yml — Normal, Fast, Tank, Miner, Screamer, Spitter, Charger, Assassin, Explosive, Frozen, Blind, Poison, Crawler, Stalker, Boss, and more
• Hive Mind — when one zombie detects a player, all zombies within 15 blocks immediately aggro
• Noise Propagation — block breaks (20 blocks), bow shots (30 blocks), and explosions (50 blocks) attract nearby zombies
• Feign Death — certain zombies play dead and spring back to life after 3–5 seconds
• Scent Detection — detection range scales with player movement: sneaking (7b) < standing (40b) < sprinting (60b)
• Breaker AI — Miner zombies actively destroy doors and dig through stone/cobblestone

🧬 Infection System

Five escalating infection levels tracked by infection points (0–100):

Level	Points	Effect
1	20+	🫧 Occasional blindness flash
2	40+	👂 Eerie whispers and sculk sounds
3	60+	🏪 Villagers refuse to trade with you
4	80+	🧟 Zombies ignore you (you smell like one of them)
5	100	💢 Strength II + Nausea + random swings

Infection increases passively over time and spreads via zombie hits. It now decays naturally (~1 point per 30s when HP > 50%, 3× faster in safe zones).

🔥 Campfire Safe Zones

• Place a Campfire of Hope to create a radius safe zone — zombies cannot enter
• 5 upgrade tiers — each crafted using the previous tier as an ingredient
• Zombies actively attack campfires to destroy your sanctuary
• Standing inside a safe zone restores sanity and accelerates infection recovery

🔫 Gun System & Ballistics Engine

Five gun types: Pistol, SMG, AK-47, Sniper Rifle, Shotgun

The ballistics engine simulates real projectile physics:

• 🎯 Raycast-based hit detection
• 🪨 Penetration — bullets pierce soft blocks with damage × 0.7
• 🔄 Ricochet — bullets bounce off hard surfaces: R = D - 2(D·N)N, damage × 0.4 (max 3 bounces)
• 🎚️ Accuracy model — improves when aiming (Slowness) and crouching
• 🔃 Animated reload bar via ActionBar
• ⚙️ Ammo & crafting restricted to Engineering Table only

🌕 Blood Moon

• Activates on eligible cycle nights with a configurable probability
• Dramatically increases spawn rates and zombie strength
• Fires cancellable BloodMoonStartEvent / BloodMoonEndEvent for API consumers

📦 Supply Drop

• Drops a loot chest near a random online player at configurable intervals
• Fully configurable loot table in events.yml with per-item chances and amount ranges
• Lightning strike visual effect on landing
• Optional coordinate broadcast

🏰 Sentry Turrets

• Placeable auto-firing turrets that target nearby zombies
• 🔋 Persists across restarts (saved to turrets_data.yml)
• Configurable range, damage, and fire rate

😱 Psychological Horror & Sanity

Sanity (0–100) displayed as a color-coded BossBar (🟢 → 🟡 → 🔴 → 🟣):

Sanity	Trigger	Effect
< 50	👂 Whispers from the dark
< 40	👣 Phantom footsteps
< 30	👻 Hallucination zombies (visible only to you)

Sanity drains near zombies and in darkness; recovers in light, near other players, and inside safe zones.

⚙️ Other Mechanics

• 🩸 Bleeding — zombie hits can cause bleeding; armor reduces chance
• ☠️ Corpse Reanimation — on death, a zombie spawns wearing your gear (configurable)
• 🔨 Engineering Table — restricts gun/ammo/trap crafting to a designated block
• 📈 Difficulty Scaling — spawn rate, HP, and speed scale with server active days
• 🧬 Tier Evolution — PRIMAL → ADAPTED → MUTATED → ABERRANT based on Threat Level
• 🏚️ Abandoned Outpost — structures that can spawn randomly in newly generated chunks
• 📚 Survival Guide Book — in-game /zapoc book documents all mechanics for new players

---

📦 Requirements

Component	Version
☕ Java	21 or higher
📄 Paper (or fork)	1.21 or higher
🌍 WorldGuard	7.0+ (optional)
🔌 ProtocolLib	5.x (optional)

⚠️ Spigot is not supported. This plugin uses Paper-exclusive APIs (getPathfinder(), hideEntity(), spawnParticle() variants).

---

🚀 Installation

1. Download ZombieApocalypseSSS-4.1.jar from Modrinth
2. Drop the jar into your server's plugins/ folder
3. Start the server — the plugin auto-generates plugins/ZombieApocalypseSSS/ with all default configs
4. Customize the configs to your liking (see Configuration)
5. Apply changes without restarting using /zapoc reload

---

⌨️ Commands & Permissions

All admin commands use /zapoc (aliases: /za, /zombieapoc)

Command	Description	Permission
/zapoc reload	Reload all configs & data	zapoc.admin
/zapoc give <item> [player]	Give a custom item	zapoc.admin
/zapoc summon <type>	Spawn a zombie type at your location	zapoc.admin
/zapoc infect <player>	Infect a player	zapoc.admin
/zapoc cure <player>	Cure a player's infection	zapoc.admin
/zapoc panic	Spawn a zombie horde around you	zapoc.admin
/zapoc bloodmoon <start|stop>	Force Blood Moon on/off	zapoc.admin
/zapoc supplydrop	Force a supply drop	zapoc.admin
/zapoc structure <type>	Spawn a world structure	zapoc.admin
/zapoc stats [player]	View survival statistics	zapoc.admin
/zapoc butchery	Kill all tracked custom zombies	zapoc.admin
/zapoc book	Give the Survival Guide book	zapoc.admin
/zapoc debug item	Inspect held item PDC data	zapoc.admin

🎁 Giveable Items

antivirus · bandage · medkit · adrenaline · molotov · grenade · flashbang landmine · radio · camo · goggles · pistol · smg · ak47 · sniper shotgun · ammo · baseball_bat · reinforced_bat · spiked_bat · fire_axe modern_axe · tactical_axe · katana · chainsaw

🔐 Permissions

Permission	Default	Description
zapoc.admin	OP	Full access to all /zapoc commands
zapoc.use	Everyone	Can use custom items and interact with campfires/turrets
zapoc.immune	Nobody	Immune to infection and bleeding

---

🔧 Configuration

The plugin uses 9 separate config files inside plugins/ZombieApocalypseSSS/:

📁 File	Contents
config.yml	Language, enabled worlds, update checker
zombies.yml	Zombie types, stats, AI settings
items.yml	Custom items, CustomModelData, lore
events.yml	🌕 Blood Moon, 📦 Supply Drop, loot table
mechanics.yml	Campfire, infection, sanity, corpse settings
turrets.yml	Turret range, damage, ammo, fire rate
sun-effect.yml	Sun behavior on custom zombies
spawn-control.yml	Spawn rate, world filters
language/messages_en.yml	English messages
language/messages_vi.yml	Vietnamese messages

🌟 Key Config Snippets

events.yml — Blood Moon & Supply Drop:

blood-moon:
  enabled: true
  chance: 0.05        # 5% chance per eligible night
  cycle-days: 7       # eligible every 7 days

supply-drop:
  enabled: true
  interval: 18000     # ticks (18000 = 15 minutes)
  announce-location: false
  loot:
    items:
      antivirus: { type: custom, key: antivirus, chance: 30, amount: 1 }
      golden_apple: { type: material, material: GOLDEN_APPLE, chance: 40, amount: 1-2 }
      iron_ingot: { type: material, material: IRON_INGOT, chance: 60, amount: 3-8 }

mechanics.yml — Corpse & Infection Decay:

corpse-reanimation:
  enabled: true       # set false to disable zombie corpse on player death

infection:
  natural-decay:
    enabled: true
    chance-per-second: 0.033   # ~1 point / 30s; 3× faster in Campfire zones

---

🧩 Developer API

Add ZombieApocalypseSSS as a soft-depend in your plugin.yml:

softdepend: [ZombieApocalypseSSS]

Quick Reference

import vn.duong2012g.zombieapoc.api.ZombieApocAPI;

ZombieApocAPI api = ZombieApocAPI.getInstance();

// ── Infection ─────────────────────────────────────────────────
boolean infected  = api.isInfected(player);          // true if points > 0
int     level     = api.getInfectionLevel(player);   // 0 – 5
int     points    = api.getInfectionPoints(player);  // 0 – 100
api.setInfectionPoints(player, 50);
api.curePlayer(player);                              // resets to 0

// ── World State ───────────────────────────────────────────────
boolean bloodMoon = api.isBloodMoon(world);
double  threat    = api.getThreatLevel();

// ── Zombie Info ───────────────────────────────────────────────
ZombieTier tier = api.getZombieTier(zombie);         // PRIMAL / ADAPTED / MUTATED / ABERRANT
boolean    safe = api.isInSafeZone(location);

// ── Spawning ──────────────────────────────────────────────────
Zombie z = api.spawnZombie(world, location, "tank");

🎯 Custom Events

// All events are cancellable
@EventHandler
public void onBloodMoonStart(BloodMoonStartEvent e) {
    World w = e.getWorld();
}

@EventHandler
public void onSupplyDrop(SupplyDropEvent e) {
    Location loc = e.getLocation();
    e.setCancelled(true); // prevent the drop
}

@EventHandler
public void onZombieInfect(ZombieInfectEvent e) {
    Player player = e.getPlayer();
    if (hasImmunityArmor(player)) e.setCancelled(true);
}

@EventHandler
public void onBloodMoonEnd(BloodMoonEndEvent e) { }

---

🔍 Troubleshooting

🧟 Zombies aren't spawning

• Check spawn-control.yml → enabled: true
• Check config.yml → worlds.enabled includes your world name
• Verify the server is on Paper 1.21+ (not Spigot)

📦 Supply Drop has wrong / no loot

• Make sure supply-drop.loot is defined in events.yml, not config.yml
• Run /zapoc reload after editing the file
• Check console for [SupplyDrop] Invalid material: warnings

🌕 Blood Moon never triggers / always triggers

• blood-moon.chance (0.0–1.0) and blood-moon.enabled must be in events.yml
• 0.05 = 5% chance per eligible night; 1.0 = always; 0.0 = never
• Use /zapoc bloodmoon start to test manually

🏰 Turrets disappear after restart

Fixed in v4.1. Ensure you're running the latest version. Check that turrets_data.yml is being created in the plugin folder.

🔫 Reload lock after relog

Fixed in v4.1. Gun cooldowns are now stored in-memory and reset on disconnect.

💉 Infection won't go away

• Craft or find an Antivirus (available in Supply Drops or /zapoc give antivirus)
• Or enable infection.natural-decay in mechanics.yml (default: on since v4.1)
• Admins can use /zapoc cure <player>

---

📄 Credits