MagnetHomes 🧲

A vanilla-friendly, hardcore approach to player homes. Bind your teleportation point to a physical Lodestone and a specific Compass. If the block is destroyed, your home is lost forever.

---

✨ Features

• 🔗 Physical Binding: Teleportation requires a real Lodestone in the world.
• 🧭 Physical Keys: You cannot teleport without holding the specific Compass linked to that home.
• 🔒 Secure Data: Uses PersistentDataContainer (PDC) to store home data directly on the item. Renaming a random compass won't work.
• 💥 Risk & Reward: If the Lodestone is broken (by players, TNT, or Creepers), the home is deleted instantly and the compass becomes useless.
• ⚡ Optimized: Uses caching to handle block break events efficiently ($O(1)$ complexity).
• ⏳ Warmup System: Configurable warmup time with movement cancellation.

---

📖 How to Use

Step 1: Prepare the Anchor

1. Craft a Lodestone and place it down.
2. Craft a Compass and right-click the Lodestone to bind it (vanilla mechanic).

Step 2: Create the Home

Stand near the Lodestone (within 3 blocks by default) while holding the bound compass and run:

/sethome <name>

The compass will be enchanted, renamed, and imprinted with the home data.

Step 3: Teleport

To return home, hold the specific compass and run:

/home <name>

There is a warmup period. Moving during this time cancels the teleport.

⚠️ Important Mechanics

Protect your Lodestone! The plugin listens for block breaks and explosions. If the Lodestone is destroyed:

1. The home is deleted from the database immediately.
2. The compass "key" stops working.
3. The owner receives a notification (if online).

---

🛠 Commands & Permissions

Command	Description	Permission
/sethome <name>	Binds the held Compass to the nearby Lodestone.	magnethomes.use (default: true)
/home <name>	Teleports to the home (requires holding the key).	magnethomes.use (default: true)
/magnetreload	Reloads the configuration file.	magnethomes.admin

---

⚙️ Configuration

The config.yml allows you to change settings and messages. The database is stored in homes.yml.

settings (config.yml)

settings:
  warmup_seconds: 5    # Time to wait before teleporting
  max_distance: 3      # Max distance from Lodestone allowed when using /sethome

Data Storage Example (homes.yml)

Do not edit this manually unless you know what you are doing.

homes:
  <PlayerUUID>:
    home_name:
      world: world
      x: 100.5
      y: 64.0
      z: -200.5
      yaw: 90.0
      pitch: 0.0
      # The physical location of the Lodestone block
      lodestone_loc: "world;100;64;-200"

---

📥 Installation

1. Ensure you are running Paper 1.20 or higher.
2. Download the latest release .jar.
3. Drop the file into your server's /plugins folder.
4. Restart the server.