[HEADING=1]ItemMagnet Documentation[/HEADING]
Version: 1.6.6 · Paper: 1.21.1+ · Java: 21+
Product page · Full docs on GitHub
[HEADING=2]Installation[/HEADING]

1. Download ItemMagnet-1.6.6.jar
2. Place the JAR in your server's
   Code (Text):

   plugins/
   folder
3. Restart the server (Paper 1.21.1 or newer, Java 21+)
4. On first run, ItemMagnet creates
   Code (Text):

   plugins/ItemMagnet/config.yml
   and
   Code (Text):

   messages.yml
5. Give yourself a magnet:
   Code (Text):

   /itemmagnet give YourName fragment 500
6. Tune settings via
   Code (Text):

   /itemmagnet config
   or edit
   Code (Text):

   config.yml
   , then
   Code (Text):

   /itemmagnet reload

[HEADING=2]Quick start for players[/HEADING]

• Hold a magnet in your main hand (unless hold-mode is changed in config)
• Drop items nearby — they pull toward you with visible motion (line-of-sight physics)
• Put redstone dust or a block in either hand; sneak + right-click to transfer fuel
• Redstone blocks add extra charge and a temporary radius boost (power surge)
• Use
  Code (Text):

  /itemmagnet filter
  to set personal item blacklist rules

[HEADING=2]Commands[/HEADING]
Base command: — aliases ,

Command	Permission	Description
/itemmagnet	—	Show help (filtered by permission)
/itemmagnet reload	itemmagnet.reload	Hot-reload config and messages
/itemmagnet config	itemmagnet.config	Open in-game config editor
/itemmagnet filter	itemmagnet.filter	Personal item filter GUI
/itemmagnet filter clear	itemmagnet.filter	Clear personal filter rules
/itemmagnet give <player> <tier|all> [charge]	itemmagnet.give	Give a resonator
/itemmagnet unlock <player> <tier|all>	itemmagnet.unlock	Unlock a tier recipe
/itemmagnet debug	itemmagnet.debug	Stats for your active magnet
/itemmagnet version	itemmagnet.admin	Version, hook status, update info
/itemmagnet import ...	varies	Bulk merge blacklist/filter/preset
/itemmagnet startup-message	itemmagnet.admin	Toggle console thank-you message

[HEADING=2]Key permissions[/HEADING]

Node	Default	Purpose
itemmagnet.use	true	Use magnets
itemmagnet.filter	true	Personal filter GUI, clear, import
itemmagnet.use.<tier>	true	Per-tier use (fragment, survey, anchor)
itemmagnet.wilderness	op	Use in Lands/Towny wilderness
itemmagnet.admin	op	Reload, give, unlock, config, version
itemmagnet.updates	op	In-game update notifications
itemmagnet.bypass.lands	false	Skip Lands checks
itemmagnet.bypass.regions	false	Skip WorldGuard region lists

Granular nodes control access to individual config GUI sections and fields.
[HEADING=2]Configuration overview[/HEADING]
[HEADING=3]settings[/HEADING]
Core magnet behaviour: scan interval, pull step size, hold mode, vertical reach, pickup distance, item blacklist/tags, XP pull, sounds.
[HEADING=3]tiers[/HEADING]
Define Fragment, Survey, Anchor (or custom tiers): material, display name, lore, radius, drain, recipes, unlock gates, tier filters.
[HEADING=3]fuel[/HEADING]
Redstone dust and block charge values, boost duration, radius bonus per boost level.
[HEADING=3]integrations[/HEADING]
Optional hooks for Lands, WorldGuard, Towny, GriefPrevention, Residence, PlotSquared, SuperiorSkyblock2, CMI, Quests. Each integration is independently enabled.
[HEADING=3]player-filter[/HEADING]
Default preset for new players; storage backend , , or .
[HEADING=3]metrics[/HEADING]

• Code (Text):

  update-check
  —
  Code (Text):

  ON_STARTUP
  ,
  Code (Text):

  ALWAYS
  , or
  Code (Text):

  DISABLED
• Code (Text):

  update-download-url
  — link shown in update notifications (default GitHub releases)
• bStats plugin ID and block-reason charts

[HEADING=3]preset[/HEADING]
Merge a built-in server preset on load: , , , , , .
[HEADING=2]Integrations[/HEADING]
All integrations are optional soft dependencies. ItemMagnet runs standalone on Paper with no extra plugins required.

• Lands — wilderness, owner, member, and flag-based modes
• WorldGuard — region whitelist/blacklist and item-pickup flag
• Towny — town plot protection
• GriefPrevention — claim respect
• Residence — residence claim and itempickup flags
• PlotSquared — plot membership checks
• SuperiorSkyblock2 — island permission hook
• CMI — stat/rank unlock gates
• LuckPerms — LP_GROUP unlock type
• mcMMO — skill level unlock gates
• Quests — quest-complete tier unlocks
• PlaceholderAPI — charge, radius, tier, boost, filter placeholders

[HEADING=2]FAQ[/HEADING]
[HEADING=3]Does the magnet pull items through walls?[/HEADING]
No. ItemMagnet uses stepped movement with line-of-sight checks. Items stop when a solid block blocks the path.
[HEADING=3]Does it work without Lands or WorldGuard?[/HEADING]
Yes. Both are optional. With integrations disabled, only permission checks apply.
[HEADING=3]How do I fuel the magnet?[/HEADING]

1. Shift + right-click with redstone dust or block in either hand
2. Auto-absorb — drop redstone nearby while holding a charged magnet

[HEADING=3]How do I disable update notifications?[/HEADING]
Set in config, or remove from staff.
[HEADING=2]Privacy & external services[/HEADING]
[HEADING=3]bStats (optional telemetry)[/HEADING]
When is true, ItemMagnet sends anonymous aggregate statistics to bStats. No player names, UUIDs, locations, or chat are transmitted. Disable with or in .
[HEADING=3]Update checker (optional)[/HEADING]
When enabled, ItemMagnet makes a read-only HTTPS request to the GitHub Releases API (async, 5s timeout) to compare version tags only. Console and in-game notifications require . Disable with .
[HEADING=3]Security practices[/HEADING]

• Permission-gated admin commands and granular
  Code (Text):

  itemmagnet.config.*
  GUI access
• Protection hooks for Lands, WorldGuard, Towny, and others; bypass permissions default to false
• Line-of-sight pull physics — items do not teleport through walls
• Config audit log at
  Code (Text):

  plugins/ItemMagnet/config-audit.log
• SQLite/MySQL filter storage uses parameterized SQL queries
• All integrations are optional soft dependencies

[HEADING=2]Support[/HEADING]

• Report a bug on GitHub
• ItemMagnet product page

Include your Paper version, Java version, ItemMagnet version, and steps to reproduce when reporting issues.
MIT License.