DeadFall

DeadFall is a zombie-apocalypse overhaul plugin for Paper Minecraft servers. It adds survivor mechanics (bleeding, infection, hydration), a full custom gun and ammo system with an in-game editor, and a resource pack that ships the custom weapon models to players automatically.

---

What's in it

Survivor status

Players track bleed, infection, and hydration, all shown live on a sidebar. Bleeding comes in tiers and can be treated with the right items. Hydration drains over time and needs drinks to top back up.

Infection is tracked and shown on the sidebar too, but that's all it does right now — nothing actually raises or lowers it yet, there's no infection mechanic behind it. It's wired up and ready for when that gets built.

Guns and ammo

Seven gun types — pistol, SMG, rifle, LMG, shotgun, sniper, launcher — each with its own damage, range, recoil, and fire-rate ranges. Snipers and launchers fire real physical projectiles that travel and drop with gravity; every other gun type is instant-hit. Guns support camo skins, tracer colors, and aim-down-sights zoom.

Attachment slots exist on every gun (optic, muzzle, grip, stock, magazine, rail) and are editable per gun, but there's no actual attachment system behind them yet — no attachment items, no stat changes. Right now they're just reserved schema so a real attachment system can slot in later without reshaping guns.yml again.

Every gun and ammo type is defined in guns.yml and ammo.yml, and both can be created, edited, and deleted entirely in-game through /deadfall — no server restart or file editing needed.

Bedrock support

Works with Geyser/Floodgate so Bedrock players get the same guns and status effects as Java players, with a few quirks handled behind the scenes (trigger timing, packet-level fixes) so Bedrock doesn't behave worse than Java.

Resource pack delivery

DeadFall can host its own resource pack and hand it to players automatically on join, so nobody has to install anything by hand.

---

Requirements

• A Paper server (or a fork of Paper) matching the API version in paper-plugin.yml.
• The bundled DeadFall datapack has to be enabled on the server. If it isn't, the plugin logs a warning on startup and doesn't enable.
• PacketEvents — required. Guns depend on it for ADS zoom and for suppressing the vanilla bow-shoot sound on Bedrock. Paper won't enable DeadFall at all if it's missing.
• Floodgate — optional, only needed if you want Bedrock players supported.

---

Installation

1. Drop the built plugin jar into your server's plugins folder.
2. Make sure the bundled datapack is enabled (see Requirements above).
3. Start the server once. This generates config.yml, guns.yml, and ammo.yml in the plugin's data folder if they don't already exist.
4. Edit config.yml to taste (see Configuration below), then restart if you changed anything that's only read on startup.

---

Commands

Guns

Command	What it does
/deadfall guns	Opens the gun catalog: browse by rarity, then edit or give any gun straight from the list. Editing (creating, tweaking stats, deleting) all happens through this same screen — there's no separate editor command to remember.
/deadfall guns give <player> <gun id>	Give a specific gun straight to a player. This is also what the catalog's own Give button uses under the hood.

Ammo

Command	What it does
/deadfall ammo	Opens the ammo catalog: browse by category, then edit or give any ammo type straight from the list. Same as guns — no separate editor command.
/deadfall ammo give <player> <ammo id> [amount]	Give a specific ammo type straight to a player.

General

Command	What it does
/deadfall reload	Reloads guns.yml and ammo.yml from disk without restarting the server.
/deadfallstatus <get|set|add> <player> [bleed|infection|hydration] [value]	Admin/testing command for checking or nudging a player's survivor status directly.

Full details on every editor field, its valid range, and every dropdown option are in gun-ammo-reference.txt.

---

Configuration (config.yml)

Catalog

• catalog.overwrite-on-startup — If turned on, guns.yml and ammo.yml get overwritten with the plugin's bundled copies every time the server starts, wiping out any local edits. Useful for pushing an updated catalog out to a server; turn it back off afterward so hand-edited catalogs don't get stomped on the next restart. Off by default.

Resource pack

• resourcepack.enabled — Turns the built-in resource pack hosting on or off.
• resourcepack.port — Port the resource pack gets served from.
• resourcepack.public-url — The address players actually fetch the pack from. Leave blank to auto-build one from the server's bound IP (only works for players on the same machine as the server). For a real deployment behind NAT/port-forwarding, set this to the server's real public address and make sure the port above is open.
• resourcepack.required — Whether players are forced to accept the resource pack to play.
• resourcepack.prompt — The message shown to players when the resource pack is offered.

Bedrock

• bedrock.auto-fire-release-threshold-millis — How long the plugin waits for another input event from a Bedrock player before deciding they let go of the trigger on a full-auto gun. Raise this if full-auto guns cut off early for Bedrock players; lower it if releasing the trigger feels laggy for them. Doesn't affect Java players.
• bedrock.debug-log-trigger-timing — Diagnostic switch; logs raw Bedrock trigger timing to console when turned on. Meant for tuning the setting above, not for normal use.

---

Project layout

src/main/java/...          Plugin source code.
src/main/resources/        config.yml, guns.yml, ammo.yml defaults,
                            plus the bundled datapack and resource pack.
gun-ammo-reference.txt     Full reference for every gun/ammo editor field,
                            its valid range, and every dropdown option.

---

Tools & development notes

Claude (Anthropic's AI assistant) was used throughout this project as a research and organization helper, specifically for:

• Research into niche systems — finding the obscure plugins, APIs, and packet-level behaviors this project leans on, and tracking down workarounds for the limitations of default systems (for example, the Bedrock trigger-timing and bow-sound quirks).
• Organization and structure — compartmentalizing the moving parts of the project and keeping the overall architecture legible.
• Explaining the codebase — clarifying what a given piece of code does, why it works, and how the pieces fit together.

Design decisions, implementation, and testing are my own; Claude was a research and organizational aid, not the author of the project.