Documentation Guide (Full)

Quick Start (5 minutes)

1. Install: Drop the jar into
   Code (Text):

   /plugins
   and restart the server.
2. Open the Admin GUI: Run
   Code (Text):

   /deadbody gui
   (requires admin permission).
3. Pick your visual mode:
   
   • ARMOR_STAND – classic and most “vanilla-friendly”
     
   • ITEM_DISPLAY – best for custom-modeled corpse bodies (resource pack)
     
   • PLAYER_MODEL – “real” player bodies (recommended with LibsDisguises)
     
4. Set loot rules: In GUI → Interaction/Cleanup, confirm loot access is configured the way you want.
5. Optional:
   
   • Install LibsDisguises for player-model corpses + mob-model corpses.
     
   • Enable Mob Corpses in GUI if you want lootable mob bodies.
     
   • Enable MythicMobs filtering if you use Mythic NPCs that reuse vanilla entity types.
     
   • Enable CombatBodies if you want /logout + combat logging handling.
     

Requirements
Required

• Paper 1.21.4+
• Java 21

Optional soft dependencies (plugin works without these; features gracefully fall back)

• LibsDisguises (Premium recommended): Player model corpses and mob model corpses
• ProtocolLib: Optional/experimental packet player-model path (not required for the primary LD path)
• MythicMobs: Mob corpse filtering and custom mob overrides
• WorldGuard: Optional compatibility for region-cancelled interactions
• Citizens: Declared soft dependency

Files & Folders
Dead Body stores everything in:
Generated files:

• dead-body.yml (main configuration)
• combat-bodies.yml (CombatBodies module configuration)
• dead-body.db.yml (persistence DB file; only appears if persistence is enabled and data exists)

Important: Many server owners delete the plugin folder to regenerate defaults. Dead Body regenerates defaults from source code

Core Concepts
Corpse container
- On death, items are captured, filtered, and inserted into a lootable corpse inventory UI.
- Vanilla drops are removed from the ground.

Corpse “anchor” (design invariant)
- A root entity (typically an ArmorStand) is used as the stable “truth entity” for:
- placement / grounding
- tracking / indexing
- despawn scheduling
- PersistentDataContainer (PDC) keys
- Even when visuals are ITEM_DISPLAY or PLAYER_MODEL, the anchor is still used behind the scenes.

Interaction model
- Corpses can be opened by interacting with the corpse entity and/or a dedicated Interaction hitbox bound to the corpse.

Commands
Primary commands:

• /deadbody – main command
• /body – alias for /deadbody
• /logout – CombatBodies safe logout
• /combatbodies – CombatBodies admin

Current /deadbody subcommands:

• /deadbody help – shows help
• /deadbody gui – opens in-game Admin GUI
• /deadbody display – opens display editing tools (ItemDisplay studio / display utilities)
• /deadbody itempose <create|edit|save|cancel|list> – ItemDisplay Pose Studio profiles
• /deadbody pose <create|edit|save|cancel|list|delete> – ArmorStand Pose Studio poses
• /deadbody reload – reload config
• /deadbody list – list active corpses
• /deadbody clearnear [radius] – clear corpses near you
• /deadbody kill <player> – debug: force-create a corpse from a player (useful for testing)

Permissions (Exact Node List)
Declare these in your permissions plugin (LuckPerms recommended). Defaults are set in plugin.yml.

Core Dead Body command access

• deadbody.command (default: op) – allows /deadbody and /body

Admin (full access)

• deadbody.admin (default: op) – full Dead Body admin access
• Includes children:
  
  • deadbody.command
    
  • deadbody.gui
    
  • deadbody.display
    
  • deadbody.itempose
    
  • deadbody.pose
    
  • deadbody.reload
    
  • deadbody.list
    
  • deadbody.clearnear
    
  • deadbody.kill
    
  • deadbody.loot.bypass
    

Granular admin nodes (all default: op)

• deadbody.gui
• deadbody.display
• deadbody.itempose
• deadbody.pose
• deadbody.reload
• deadbody.list
• deadbody.clearnear
• deadbody.kill

Loot permissions

• deadbody.loot (default: true)
  
  • deadbody.loot.player (default: true)
    
  • deadbody.loot.mob (default: true)
    
• deadbody.loot.bypass (default: op) – bypass loot checks when admin bypass is enabled in config

CombatBodies

• combatbodies.logout (default: true) – allows /logout
• combatbodies.admin (default: op)

Loot Access Model (How looting is controlled)
Loot access is enforced in the corpse interaction flow and is configurable.

Config path
in Default keys:
Behavior with defaults
- Looting is open to normal players (public-server friendly).
- The nodes only become required if you turn on the corresponding “require-permission” toggles.
- bypasses loot checks when admin-bypass-enabled is true.
- owner-always-allowed applies to player corpses (the owner can always loot their own body).

Where to change it in GUI
- /deadbody gui → Interaction / Cleanup page → Loot access controls.

WorldGuard Notes (common issue)
Problem: Players have deadbody.loot but still cannot loot corpses inside a protected region.

Cause:
Some WorldGuard regions using cancel entity right-click events.

Solutions:

• Prefer region flags like
  Code (Text):

  block-break: deny
  and
  Code (Text):

  block-place: deny
  instead of using
  Code (Text):

  build: deny
  as your “loot gate”.
• Use these compatibility toggles in
  Code (Text):

  dead-body.yml
  :
  
  • Code (Text):

    interaction.worldguard.allow-open-on-cancelled-interact
  • Code (Text):

    interaction.worldguard.require-plugin-present

Admin GUI Guide
Open the GUI:
Major categories (names may vary slightly by build, but these are the core areas):

• Core / Worlds – enable worlds, safety toggles
• Visuals – choose visual mode (ArmorStand / ItemDisplay / Player Model), nameplates, render style
• Interaction & Cleanup – loot rules, delays, empty-despawn behavior, startup cleanup
• Poses – pose list + death-cause mapping + Pose Studio entry points
• Mob Corpses – enable mob bodies, renderer selection, interaction hitbox sizing, MythicMobs filters
• Combat Logging – CombatBodies module toggles, /logout rules
• Despawn / Effects – lifetime, animated despawn, particles/sounds

Player Corpse Flow (What happens on death)

1. Capture drops
   
   • Dead Body captures death drops.
     
   • Applies filters.
     
   • Clears vanilla drops from the ground.
     
   • Inserts items into the corpse container UI.
     
2. Spawn corpse anchor
   
   • A root ArmorStand is spawned to store PDC keys and act as the stable “truth” entity for placement/despawn.
     
3. Spawn visuals
   
   • ARMOR_STAND: anchor is also the visible body.
     
   • ITEM_DISPLAY: anchor is invisible; visuals are display entities + interaction hitbox.
     
   • PLAYER_MODEL: anchor is invisible; visuals are rendered through LibsDisguises.
     
4. Interaction + looting
   
   • Players right-click the corpse (or its interaction hitbox) to open the container.
     
   • Loot permissions can be open-to-all or permission-gated.
     
5. Despawn
   
   • Corpses despawn on timer and/or when empty (optional), and can run despawn animations.
     

Placement / Grounding
Dead Body supports multiple placement behaviors (names may vary slightly by build):

• SNAP_TO_SURFACE – places corpse at nearest surface immediately
• FALL_TO_GROUND – spawns above, falls, then snaps into pose when grounded
• ABSOLUTE – places exactly at death location coordinates

Water behavior
- If enabled: corpses can sink and settle on the bottom.
- Shallow water should avoid harsh multi-block teleports (use sink/settle behavior).

Visual Modes

1) ARMOR_STAND (classic)
Best for vanilla-friendly setups.

• ArmorStand Euler poses (limb/head/body)
• Equipment display rules (visual-only clones; loot stays in container)
• Reliable interaction + minimal dependencies

2) ITEM_DISPLAY (resource-pack friendly)
View attachment 946745
Best for custom modeled corpse bodies.

• ItemDisplay transform editing (translation/rotation/scale)
• Fixed or random rotations
• Single model item or multiple profiles for random selection

Typical workflow

1. Set
   Code (Text):

   visuals.mode: ITEM_DISPLAY
2. Choose base item (material + custom model data)
3. Use ItemDisplay Pose Studio to tune transforms
4. Save profile
5. Add profile to random list and/or map to death causes

3) PLAYER_MODEL (LibsDisguises)
Most immersive player corpses.

• Full “real player body” on the ground
• Armor + held items visible
• Multiple pose states (sleeping, swimming, fall_flying, sitting, riding, riptide/spin)

Notes
- LibsDisguises is the recommended path for stability.
- Some poses should lock pitch/yaw to prevent clipping (fall_flying is a good example).
- Some poses use pose-specific Y offsets to avoid clipping.

Poses (How pose selection works)
A pose is a named preset that can define:

• a visual mode override (optional)
• pose-specific offsets
• ArmorStand limb eulers (ArmorStand mode)
• PlayerModel pose state (PlayerModel mode)
• ItemDisplay profile name / transform (ItemDisplay mode)

Pose selection:

• Fixed – always use a chosen pose
• Random – choose from a list
• Mapped – choose based on death cause or mob type

Death-cause mapping examples:

• Fall damage → “face down” / fall_flying
• Drowning → “swimming”
• Explosion → “thrown” / ragdoll style

Edit in GUI: Death Poses section.

Pose Studio (ArmorStand)
Create/edit ArmorStand corpse poses in-game.

Workflow

1. Code (Text):

   /deadbody pose create <name>
2. Use hotbar tools to select limbs, rotate, adjust step sizes, adjust pose Y offset.
3. Code (Text):

   /deadbody pose save
4. Code (Text):

   /deadbody pose cancel
   (discard)

Studio guarantees

• Your inventory is restored on exit.
• The studio prevents equipping the stand with editor tools.

ItemDisplay Pose Studio (Profiles)
Used for custom modeled ItemDisplay corpses.

Recommended workflow

1. Switch to ITEM_DISPLAY mode
2. Open the studio from Admin GUI or command:
   
   • Code (Text):

     /deadbody itempose create <profile>
   • Code (Text):

     /deadbody itempose edit <profile>
3. Set an item model:
   
   • Pick from inventory (creative-friendly)
     
   • Or set by chat input:
     Code (Text):

     MATERIAL cmd=<customModelData>
4. Use hotbar tools:
   
   • Translation (x/y/z)
     
   • Rotation (yaw/pitch/roll)
     
   • Scale (x/y/z)
     
5. Save and add profile to random list / mappings

Nameplates
Nameplates are optional and can be applied globally across corpse types.

Styles:

• FLAT – clean one-sided “panel” look
• BILLBOARD – rotates to face viewer, readable from all angles

Common settings:

• Enable/disable
• Y offset
• Text format (MiniMessage)
• Optional timer (time remaining before despawn)

Despawn System & Animated Effects
Corpses can despawn via:

• Fixed lifetime timer
• Despawn when emptied (optional)
• Admin cleanup commands

Animated despawn effects (depending on build configuration):

• Sink into ground
• Scale down
• Rotate/spin
• Jitter/shake
• Pop vanish

Selection rules:

• Global animation
• Random selection from a list
• Per-pose override

Filters (What goes into the corpse container)
Filtering controls what items are stored in the corpse container.

Typical filters:

• Material whitelist/blacklist
• Lore contains / not contains
• PDC key contains / not contains

Common use cases:

• Exclude “soulbound” items from corpses
• Exclude server currency items
• Exclude quest items / special tokens

CombatBodies Module (Combat logging)
When enabled:

• Players can be tagged in combat.
• Attempting to log out in combat can be blocked or handled via safe logout rules.
• If a proxy dies, a corpse can spawn for the offline player (no dupes).

Commands:

• Code (Text):

  /logout
• Code (Text):

  /combatbodies

Permissions:

• combatbodies.logout
• combatbodies.admin

Mob Corpses
When enabled:
- Dead mobs can spawn lootable corpses using their drops.

Renderers:

• LibsDisguises mob model (preferred): corpse resembles the mob lying on the ground
• Fallback: ArmorStand-based placeholder (if disguise is not available)

Quality features supported:

• Baby mobs render as baby
• Villagers preserve profession/type/level
• Large mobs have large interaction hitboxes (easier to click)

MythicMobs Integration (Optional)
Use MythicMobs filtering to prevent duplicate corpses for custom mobs that reuse vanilla entity types (zombie NPCs, etc.).

Concepts:

• Enabled toggle
• Filter mode: WHITELIST or BLACKLIST
• Mythic internal name list (normalized matching recommended)

Recommended setups:

• BLACKLIST NPC mobs (prevents your NPC plugin from spawning one corpse while Dead Body spawns another).
• WHITELIST only bosses/important mobs.

Troubleshooting / FAQ

Players can’t loot corpses (only OP can)

• Grant
  Code (Text):

  deadbody.loot
  to your default player group.
• Check loot access toggles under
  Code (Text):

  interaction.loot-access.*
  (GUI: Interaction/Cleanup).
• If using WorldGuard, see the WorldGuard section above.

Player model mode does not render

• Install and enable LibsDisguises.
• Confirm PLAYER_MODEL mode is selected.

Mob corpses vanish at short range

• If players/armorstands render at long range but mob corpses don’t: this is typically an anchor configuration issue.
• Confirm mob corpse anchor is not being forced into marker/short-track mode.
• If still present, review Paper entity tracking range settings.

Corpse clips into ground

• Increase pose Y offset slightly.
• Use FALL_TO_GROUND or SNAP_TO_SURFACE appropriate for carpets/slabs/partial blocks.