Tutorials

Everything to get PaperMC Despawned Items running on your server and into your players' hands.

Install

Grab papermc-despawned-items-<version>.jar from the Download page.
Drop it into your server's plugins/ folder.
Start the server (Paper 1.21.11+, Java 21+; also loads on 26.x). The plugin creates plugins/papermc-despawned-items/config.yml on first run.

For SQLite or MySQL storage, Paper downloads the JDBC driver and HikariCP automatically on first start (declared as plugin libraries:) — no extra jars to install.

First steps in game

Look at a chest (or furnace, barrel, item frame, …) and run /despi add this — that block is now part of your despawn network. Items that would despawn near it get relocated into it instead. Players do this themselves, up to their limit; /recycle feeds the item in your hand straight into the network for a small reward.

Commands & permissions

Command	Permission	Purpose
`/despi add this [player]`	`despi.use` (self) · `despi.elevated` (for others)	register the block you're looking at, subject to your limit
`/despi remove …` · `/despi clear …` · `/despi exists …` · `/despi locations …`	`despi.use` (self) · `despi.elevated` (others)	manage locations
`/despi purge …`	`despi.use` (own) · `despi.elevated` (others/everyone)	bulk-remove materials from despawn storage
`/despi despawn …` · `/despi effects …` · `/despi reload do` · `/despi save do`	`despi.elevated`	admin / testing
`/recycle`	`recycle.use`	despawn the item in your hand for a reward

despi.use and recycle.use default to everyone; despi.elevated and despi.limit.bypass default to ops. Grant a group despi.limit.50 for a 50-location cap (LuckPerms-friendly).

Configuration

plugins/papermc-despawned-items/config.yml sections:

sound / particles — the landing effect (keys, not enums; colored DUST supported).
limits — default cap and unlimited toggle (permissions override per group).
performance — max-per-tick, max-concurrent, max-queue, drop-when-full.
storage — type: yaml | sqlite | mysql, plus MySQL connection + pool settings. Switching backends migrates existing data.

/despi reload do re-reads the file live.

Build from source

./gradlew build            # runs the test suite → build/libs/papermc-despawned-items-<version>.jar
./gradlew assembleDocsSite  # builds this docs site → build/docs-site

JDK 21 is provisioned automatically (foojay resolver); the Gradle wrapper is committed. The build runs a JUnit 5 + MockBukkit suite (unit, property/fuzz, database, performance, mocked-server integration).