Spawn API usage

🚀 Spawn Managers – fr.fuzeblocks.homeplugin.spawn.*

HomePlugin centralizes spawn operations behind a single facade: SpawnManager. It delegates to the active storage backend (YAML or SQL) so your code can remain storage‑agnostic.

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

Related Javadoc:

• SpawnManager
• SpawnYMLManager
• SpawnSQLManager
• HomePlugin.getSpawnManager()

---

📦 Supported Backends

Backend	Manager Class	Package	Typical Use
YAML (file)	SpawnYMLManager	fr.fuzeblocks.homeplugin.spawn.yml	Simplicity / single‑server
MySQL	SpawnSQLManager	fr.fuzeblocks.homeplugin.spawn.sql	Networks / multi‑instance

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

---

🔗 Unified Spawn API (via SpawnManager)

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

• boolean setSpawn(Location location)
  Create or replace the spawn for the Location’s world.

• Location getSpawn(World world)
  Retrieve the spawn location for a given world, or null if none is defined.

• boolean hasSpawn(World world)
  Check whether a spawn exists for the world.

• boolean removeSpawn(World world)
  Delete the stored spawn for the world.

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

---

✅ Usage (Facade, storage‑agnostic)

import fr.fuzeblocks.homeplugin.HomePlugin;
import fr.fuzeblocks.homeplugin.spawn.SpawnManager;
import org.bukkit.Location;
import org.bukkit.World;
import org.bukkit.entity.Player;

SpawnManager spawns = HomePlugin.getSpawnManager(); // or SpawnManager.getInstance()

// Set the spawn for a world
Location hub = new Location(world, 0.5, 64, 0.5, 180f, 0f);
boolean set = spawns.setSpawn(hub);

// Query and teleport
World target = player.getWorld();
if (spawns.hasSpawn(target)) {
    Location spawnLoc = spawns.getSpawn(target);
    if (spawnLoc != null) {
        player.teleport(spawnLoc);
    }
}

// Remove
spawns.removeSpawn(target);

---

🧰 Concrete Managers (advanced)

• YAML

  • Package: fr.fuzeblocks.homeplugin.spawn.yml
  • Class: SpawnYMLManager
  • Constructor:

    public SpawnYMLManager(File file)

  • Stores to a local YAML via YamlConfiguration.
  • Javadoc: SpawnYMLManager

• MySQL

  • Package: fr.fuzeblocks.homeplugin.spawn.sql
  • Class: SpawnSQLManager
  • Persists to a SQL database; suited for multi‑server setups.
  • Obtain via HomePlugin.getSpawnSQLManager().
  • Javadoc: SpawnSQLManager

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

---

🧩 Related Components

• TaskManager.spawnTask(Player) — Utilities for delayed teleport flows.
• Events — Hook into lifecycle (e.g., spawn created/teleport). See Events doc.
• CacheManager — May cache spawn data indirectly through the plugin’s cache layer.

---

🔁 Migration Notes (from older direct-manager usage)

• Prefer HomePlugin.getSpawnManager() or SpawnManager.getInstance() to remain backend‑agnostic.
• The facade mirrors the backend methods:
  • setSpawn(...), getSpawn(...), hasSpawn(...), removeSpawn(...), isStatus(...)
• World scoping is unchanged (one spawn per world).
• isStatus(...) remains implementation‑specific; consult your status/limits policy before gating actions.

---

🧪 Example: Safe Teleport Wrapper

public void teleportToSpawn(Player player, World world) {
    var spawns = HomePlugin.getSpawnManager();
    if (spawns.hasSpawn(world)) {
        Location loc = spawns.getSpawn(world);
        if (loc != null) {
            player.teleport(loc);
            player.sendMessage("Teleported to world spawn.");
            return;
        }
    }
    player.sendMessage("No spawn set for this world.");
}

---

Need migration helpers or event hooks around spawn changes? Ask and we’ll include a dedicated section.