---

📖 Table of Contents

• ✨ Features
• 📦 Requirements
• 🚀 Installation
• ⌨️ Commands & Permissions
• 🔧 Configuration
• 🔫 CombatGunSSS Integration
• 🧩 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 b), gunshots (30 b), and explosions (50 b) 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 (7 b) < standing (40 b) < sprinting (60 b)
• 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 and spreads via zombie hits. It decays naturally (~1 point/30 s 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
• 3 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

🩹 Survival Items

Five core survival items craftable at vanilla crafting tables:

Item	Effect	Notes
Bandage	Stops bleeding	Paper ×2 + String
Antivirus	Cures infection (resets to 0 points)	Golden Apple + Potion + Fermented Spider Eye
Adrenaline	Speed III + Strength I for 10 s (60 s cooldown)	Sugar + Glowstone Dust + Spider Eye
Zombie Camo	Zombies ignore you for 60 s	8× Rotten Flesh + Slime Ball
Radio	Shows location & ETA of next Supply Drop	9× Compass · 5 min cooldown

🔫 Want guns and advanced weapons? See CombatGunSSS Integration below.

🌕 Blood Moon

• Activates once per eligible night with a configurable probability (default 5 %)
• 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	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.

🏚️ World Structures

Discover abandoned structures scattered across the world, each with unique loot and dangers:

Structure	Spawn Chance	Description
Military Checkpoint	0.3 %	Abandoned roadblock with barriers and watchtower
Crashed Supply Plane	0.2 %	Emergency landing site with scattered cargo
Abandoned Hospital	0.15 %	Medical facility with beds and equipment
Survivor Camp	0.4 %	Makeshift camp with tents and campfire
Abandoned Outpost	0.5 %	Small fenced compound

Structures will not spawn in ocean or river biomes (fixed in v4.3.1).

---

📦 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(), etc.).

---

🚀 Installation

1. Download ZombieApocalypseSSS-4.3.1.jar from Modrinth
2. Drop the jar into your server's plugins/ folder
3. Start the server — configs are auto-generated in plugins/ZombieApocalypseSSS/
4. Customize the configs (see Configuration)
5. Apply changes live with /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 (sets infection to 50 points)	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 (infection pts, sanity, bleeding)	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

bandage · antivirus · adrenaline · zombie-camo · radio · campfire_tier1 · campfire_tier2 · campfire_tier3

🔫 Want guns? Install CombatGunSSS!

🔐 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, structure spawn chances
zombies.yml	Zombie types, stats, AI, moans, mutation, evolution, bleeding
items.yml	Custom item CustomModelData and lore
events.yml	🌕 Blood Moon, 📦 Supply Drop, loot table
mechanics.yml	Campfire, infection decay, sanity, horror, corpse settings
turrets.yml	Turret range, damage, ammo, fire rate
sun-effect.yml	Sun behaviour on custom zombies
spawn-control.yml	Spawn rate, world filters
language/messages_en.yml	English messages (including blood-moon-start, blood-moon-end)
language/messages_vi.yml	Vietnamese messages

🌟 Key Config Snippets

events.yml — Blood Moon & Supply Drop:

blood-moon:
  enabled: true
  chance: 0.05        # 5% — rolled ONCE per eligible night (fixed in v4.3.1)
  cycle-days: 7       # eligible every 7 days

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

zombies.yml — Zombie settings (all zombie config now in this file):

zombies:
  health-multi: 1.5
  ai:
    sneak-detection-range: 7.0
    hive-mind-radius: 15.0
moans:
  enabled: true
  interval-ticks: 200
mutation:
  enabled: true
  interval-ticks: 2400
zombie-breaking:
  enabled: true
  chance: 0.3
bleeding:                    # NEW in v4.3.1
  chance: 30.0               # % per zombie hit
  armor-reduction: 0.04      # % reduction per armor point

mechanics.yml — Infection decay:

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

---

🔫 CombatGunSSS Integration

🎯 Want guns, ammo, and advanced weaponry? Install CombatGunSSS!

ZombieApocalypseSSS handles core survival. For firearms pair it with CombatGunSSS:

• 30+ guns — Pistols, SMGs, ARs, Snipers, Shotguns
• Ballistics engine — Raycast, penetration, ricochet
• Ammo system — Craftable ammo types
• Full integration — Works with ZombieApocalypseSSS infection and zombie systems

plugins/
├── ZombieApocalypseSSS-4.3.1.jar
└── CombatGunSSS-x.x.jar          ← optional, for guns

---

🧩 Developer API

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

softdepend: [ZombieApocalypseSSS]

Quick Reference

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

@EventHandler
public void onBloodMoonStart(BloodMoonStartEvent e)  { World w = e.getWorld(); }

@EventHandler
public void onSupplyDrop(SupplyDropEvent e)           { e.setCancelled(true); }

@EventHandler
public void onZombieInfect(ZombieInfectEvent e)      { /* e.getPlayer() */ }

@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 Paper 1.21+ (not Spigot)

📦 Supply Drop has wrong / no loot

• Loot table must be in events.yml under supply-drop.loot
• Run /zapoc reload after editing
• Check console for [SupplyDrop] Invalid material: warnings

🌕 Blood Moon never / always triggers

• blood-moon.chance and blood-moon.enabled are in events.yml (not config.yml)
• 0.05 = 5 % chance per eligible night; rolled once per night (fixed v4.3.1)
• Test manually: /zapoc bloodmoon start

💉 Antivirus / Bandage not working

Fixed in v4.3.1. Both items had internal type mismatches that prevented them from detecting player status. Update to v4.3.1.

🧟‍♂️ Zombie Camo has no effect

Fixed in v4.3.1. The camo item was writing to a different PDC key than what the AI system read. Update to v4.3.1.

🏗️ Structures spawning in the ocean

Fixed in v4.3.1. Structures now skip ocean and river biomes. Update to v4.3.1.

🔄 /zapoc reload duplicating structure spawns

Fixed in v4.3.1. The old StructureManager listener is now properly unregistered before reload.

🏰 Turrets disappear after restart

Fixed in v4.1. Ensure turrets_data.yml is being created in the plugin folder.

🔫 Where are the guns?

As of v4.2, guns are in a separate plugin.

1. Download CombatGunSSS from modrinth.com/plugin/combatgunsss
2. Drop it into plugins/ alongside ZombieApocalypseSSS
3. Restart — plugins auto-integrate

---

📄 Credits