Home API usage

🏠 Home Managers – fr.fuzeblocks.homeplugin.home.*

HomePlugin now centralizes home operations behind a single facade: HomeManager. It delegates to the active storage backend (YAML or SQL) so your code can stay storage‑agnostic.

• Preferred entry points:
  • HomePlugin.getHomeManager() — plugin-level accessor
  • HomeManager.getInstance() — static singleton
• Backends are selected by plugin configuration. You can still interact with concrete managers when you need backend-specific control.

Related Javadoc:

• HomeManager
• HomeYMLManager
• HomeSQLManager
• HomePlugin.getHomeManager()

---

📦 Supported Backends

Backend	Manager Class	Package	Typical Use
YAML (local file)	HomeYMLManager	fr.fuzeblocks.homeplugin.home.yml	Simple / single‑server
MySQL (database)	HomeSQLManager	fr.fuzeblocks.homeplugin.home.sql	Networks / multi‑instance

Tip: Use the facade (HomeManager) for most integrations. Reach for concrete managers only if you must control files, connections, or migrations.

---

🔗 Unified Home API (via HomeManager)

Each method forwards to the active backend (YAML or SQL) with identical behavior.

• boolean addHome(Player player, String name)
  Create a home at the player’s current location. Returns false if the name already exists.

• boolean setHome(Player player, String name, Location location)
  Create or overwrite a home at an explicit location.

• boolean renameHome(Player player, String oldHomeName, String newHomeName)
  Rename an existing home.

• boolean relocateHome(Player player, String homeName, Location newLocation)
  Move an existing home to a new location.

• List<Location> getHomesLocation(Player player)
  All home locations for the player.

• int getHomeNumber(Player player)
  Count of a player’s homes.

• List<String> getHomesName(Player player)
  All home names for the player.

• Location getHomeLocation(Player player, String homeName)
  Location for a specific home, or null if missing.

• boolean deleteHome(Player player, String homeName)
  Remove the named home.

• boolean exist(Player player, String homeName)
  Check if the named home exists.

• boolean isStatus(Player player)
  Status flag (plugin‑specific; see Status/limits logic).

• CacheManager getCacheManager()
  Access the cache layer used by the active backend.

---

✅ Usage (Facade, storage‑agnostic)

import fr.fuzeblocks.homeplugin.HomePlugin;
import fr.fuzeblocks.homeplugin.home.HomeManager;
import org.bukkit.Location;
import org.bukkit.entity.Player;

HomeManager homes = HomePlugin.getHomeManager(); // or HomeManager.getInstance()

// Create at player's current location
boolean created = homes.addHome(player, "spawn");

// Create at an explicit location
Location base = new Location(world, 100.5, 64, -32.5, 90f, 0f);
boolean set = homes.setHome(player, "base", base);

// Rename and relocate
homes.renameHome(player, "base", "main");
homes.relocateHome(player, "main", base.add(10, 0, 0));

// Query
int count = homes.getHomeNumber(player);
boolean exists = homes.exist(player, "main");
Location where = homes.getHomeLocation(player, "main");
for (String name : homes.getHomesName(player)) {
    // ...
}

// Delete
homes.deleteHome(player, "spawn");

---

🧰 Concrete Managers (advanced)

• YAML

  • Class: HomeYMLManager
  • Constructor: HomeYMLManager(File file)
  • Stores to a local YAML via YamlConfiguration.
  • Javadoc: HomeYMLManager

• MySQL

  • Class: HomeSQLManager
  • Constructor: HomeSQLManager()
  • Persists to a SQL database; suited for multi‑server setups.
  • Javadoc: HomeSQLManager

Use HomePlugin.getHomeManager() unless you specifically need to operate the YAML file directly or manage SQL concerns.

---

🧩 Related Components

• HomePermissionManager — Check limits/entitlements before creation.
• CacheManager — In‑memory / Redis sync layer used by managers.
• Events — Hook into lifecycle (e.g., created/teleport). See Events doc.
• TaskManager.homeTask(...) — Integrates with delayed teleports.

---

🔁 Migration Notes (from older direct-manager usage)

• Prefer HomePlugin.getHomeManager() or HomeManager.getInstance() to remain backend‑agnostic.
• New/expanded API in the facade:
  • setHome(...) for explicit coordinates
  • renameHome(...)
  • relocateHome(...)
• addHome(...) continues to create at the player’s current location, preserving previous behavior.
• isStatus(...) remains implementation‑specific; consult your status/limits policy before gating actions.

---

Need YAML→MySQL migration helpers or examples using CacheManager and events? Ask and we’ll include a dedicated section.