CuboidService

🗂️ CuboidService

Centralized management system for all cuboids in your plugin.

---

Overview

The CuboidService provides global cuboid management:

• Auto-Registration — Cuboids register automatically on creation
• Global Access — Query all cuboids from anywhere
• UUID Tracking — Track cuboids by player/owner
• Lifecycle Management — Register, unregister, clear operations

---

Table of Contents

• Getting Started
• Registration
• Querying Cuboids
• Lifecycle Management
• Complete Examples
• Best Practices

---

Auto-Registration

// Cuboids are automatically registered on creation
Cuboid cuboid = new Cuboid(loc1, loc2);
// ✅ Automatically registered in CuboidService

---

Registration

Manual Registration

By default the autRegister is true.

cuboidService.autoRegister(false);

Cuboid cuboid = new Cuboid(loc1, loc2);

// Manually register (optional, done automatically)
cuboidService.register(cuboid);

Unregister Cuboid

// Remove from service
cuboidService.unregister(cuboid);

Clear All

// Remove all registered cuboids
cuboidService.clear();

---

Querying Cuboids

Get All Cuboids

Set<Cuboid> allCuboids = cuboidService.getCuboids();

getLogger().info("Total cuboids: " + allCuboids.size());

for (Cuboid cuboid : allCuboids) {
  Location center = cuboid.getCenter();
  getLogger().info("Cuboid at: " + center);
}

Get Cuboids by UUID

UUID playerId = player.getUniqueId();
Set<Cuboid> playerCuboids = cuboidService.getCuboidsOf(playerId);

player.sendMessage(
  Component.text("You have " + playerCuboids.size() + " cuboids", 
    NamedTextColor.GREEN)
);

Find Cuboid at Location

public Cuboid findCuboidAt(Location location) {
  for (Cuboid cuboid : cuboidService.getCuboids()) {
    if (cuboid.isLocationIn(location)) {
      return cuboid;
    }
  }
  return null;
}

// Usage
Cuboid found = findCuboidAt(player.getLocation());
if (found != null) {
  player.sendMessage(
    Component.text("You are in a cuboid!", NamedTextColor.GREEN)
  );
}

---

Lifecycle Management

Plugin Enable

public class MyCuboidPlugin extends DreamPlugin {

  private CuboidService cuboidService;

  private final List<Cuboid> regions = new ArrayList<>();

  @Override
  public void onDreamEnable() {
    // Create cuboids
    regions.add(new Cuboid(loc1, loc2));  // Auto-registered
    regions.add(new Cuboid(loc3, loc4));  // Auto-registered

    getLogger().info("Loaded " + regions.size() + " regions");
  }
}

Plugin Disable

@Override
public void onDreamDisable() {
  // Unregister all plugin cuboids
  for (Cuboid cuboid : regions) {
    cuboidService.unregister(cuboid);
  }

  regions.clear();

  getLogger().info("Unregistered all cuboids");
}

---

Complete Examples

Region Manager

public class RegionManager {

  private CuboidService cuboidService = DreamAPI.getAPI().getService(CuboidService.class);

  private final Map<String, Cuboid> regions = new HashMap<>();

  public void createRegion(String name, Location corner1, Location corner2) {
    Cuboid region = new Cuboid(corner1, corner2);
    regions.put(name, region);

    getLogger().info("Created region: " + name);
  }

  public Cuboid getRegion(String name) {
    return regions.get(name);
  }

  public void deleteRegion(String name) {
    Cuboid region = regions.remove(name);

    if (region != null) {
      cuboidService.unregister(region);
      getLogger().info("Deleted region: " + name);
    }
  }

  public Set<String> getRegionsAt(Location location) {
    Set<String> found = new HashSet<>();

    for (Map.Entry<String, Cuboid> entry : regions.entrySet()) {
      if (entry.getValue().isLocationIn(location)) {
        found.add(entry.getKey());
      }
    }

    return found;
  }

  public void listAllRegions(Player player) {
    player.sendMessage(
      Component.text("=== Regions ===", NamedTextColor.GOLD)
    );

    for (String name : regions.keySet()) {
      player.sendMessage(
        Component.text("- " + name, NamedTextColor.GRAY)
      );
    }
  }
}

Player Claims System

public class ClaimSystem {

  private CuboidService cuboidService = DreamAPI.getAPI().getService(CuboidService.class);

  private final Map<UUID, Set<Cuboid>> claims = new HashMap<>();

  public void createClaim(Player player, Location corner1, Location corner2) {
    UUID playerId = player.getUniqueId();

    // Check limit
    Set<Cuboid> playerClaims = claims.get(playerId);
    if (playerClaims != null && playerClaims.size() >= 3) {
      player.sendMessage(
        Component.text("You have reached the claim limit!", NamedTextColor.RED)
      );
      return;
    }

    // Check overlap
    Cuboid newClaim = new Cuboid(corner1, corner2);
    if (isOverlapping(newClaim)) {
      player.sendMessage(
        Component.text("This area overlaps with another claim!", NamedTextColor.RED)
      );
      cuboidService.unregister(newClaim);
      return;
    }

    // Create claim
    claims.computeIfAbsent(playerId, k -> new HashSet<>()).add(newClaim);

    player.sendMessage(
      Component.text("Claim created!", NamedTextColor.GREEN)
    );
  }

  private boolean isOverlapping(Cuboid newClaim) {
    Location center = newClaim.getCenter();

    for (Cuboid existing : cuboidService.getCuboids()) {
      if (existing.isLocationIn(center)) {
        return true;
      }
    }

    return false;
  }

  public void removeClaim(Player player, Location location) {
    UUID playerId = player.getUniqueId();
    Set<Cuboid> playerClaims = claims.get(playerId);

    if (playerClaims == null) return;

    for (Cuboid claim : playerClaims) {
      if (claim.isLocationIn(location)) {
        playerClaims.remove(claim);
        cuboidService.unregister(claim);

        player.sendMessage(
          Component.text("Claim removed!", NamedTextColor.GREEN)
        );
        return;
      }
    }
  }

  public void listClaims(Player player) {
    UUID playerId = player.getUniqueId();
    Set<Cuboid> playerClaims = claims.get(playerId);

    if (playerClaims == null || playerClaims.isEmpty()) {
      player.sendMessage(
        Component.text("You have no claims", NamedTextColor.GRAY)
      );
      return;
    }

    player.sendMessage(
      Component.text("Your claims (" + playerClaims.size() + ")", NamedTextColor.GOLD)
    );

    int i = 1;
    for (Cuboid claim : playerClaims) {
      Location center = claim.getCenter();
      player.sendMessage(
        Component.text(i + ". " + center.getBlockX() + ", " + 
          center.getBlockY() + ", " + center.getBlockZ(), 
          NamedTextColor.GRAY)
      );
      i++;
    }
  }
}

Protection System

public class ProtectionSystem implements Listener {

  private CuboidService cuboidService = DreamAPI.getAPI().getService(CuboidService.class);

  private final Map<Cuboid, UUID> owners = new HashMap<>();

  public void createProtectedZone(Player owner, Location corner1, Location corner2) {
    Cuboid zone = new Cuboid(corner1, corner2);
    owners.put(zone, owner.getUniqueId());

    owner.sendMessage(
      Component.text("Protected zone created!", NamedTextColor.GREEN)
    );
  }

  @EventHandler
  public void onBlockBreak(BlockBreakEvent event) {
    Player player = event.getPlayer();
    Block block = event.getBlock();

    for (Map.Entry<Cuboid, UUID> entry : owners.entrySet()) {
      Cuboid zone = entry.getKey();

      if (zone.isLocationIn(block.getLocation())) {
        UUID ownerId = entry.getValue();

        if (!player.getUniqueId().equals(ownerId)) {
          event.setCancelled(true);
          player.sendMessage(
            Component.text("This area is protected!", NamedTextColor.RED)
          );
        }
        return;
      }
    }
  }

  @EventHandler
  public void onBlockPlace(BlockPlaceEvent event) {
    Player player = event.getPlayer();
    Block block = event.getBlock();

    for (Map.Entry<Cuboid, UUID> entry : owners.entrySet()) {
      Cuboid zone = entry.getKey();

      if (zone.isLocationIn(block.getLocation())) {
        UUID ownerId = entry.getValue();

        if (!player.getUniqueId().equals(ownerId)) {
          event.setCancelled(true);
          player.sendMessage(
            Component.text("This area is protected!", NamedTextColor.RED)
          );
        }
        return;
      }
    }
  }
}

Statistics Tracker

public class CuboidStats {

  @Inject
  private CuboidService cuboidService;

  public void showStats(Player player) {
    Set<Cuboid> allCuboids = cuboidService.getCuboids();

    int total = allCuboids.size();
    int totalBlocks = 0;
    int totalEntities = 0;

    for (Cuboid cuboid : allCuboids) {
      totalBlocks += cuboid.getBlocks().size();
      totalEntities += cuboid.getEntities().size();
    }

    player.sendMessage(
      Component.text("=== Cuboid Statistics ===", NamedTextColor.GOLD)
    );
    player.sendMessage(
      Component.text("Total cuboids: " + total, NamedTextColor.GREEN)
    );
    player.sendMessage(
      Component.text("Total blocks: " + totalBlocks, NamedTextColor.AQUA)
    );
    player.sendMessage(
      Component.text("Total entities: " + totalEntities, NamedTextColor.YELLOW)
    );
  }

  public void findLargestCuboid(Player player) {
    Set<Cuboid> allCuboids = cuboidService.getCuboids();

    Cuboid largest = null;
    int maxBlocks = 0;

    for (Cuboid cuboid : allCuboids) {
      int blocks = cuboid.getBlocks().size();
      if (blocks > maxBlocks) {
        maxBlocks = blocks;
        largest = cuboid;
      }
    }

    if (largest != null) {
      Location center = largest.getCenter();
      player.sendMessage(
        Component.text("Largest cuboid: " + maxBlocks + " blocks", 
          NamedTextColor.GOLD)
      );
      player.sendMessage(
        Component.text("Location: " + center.getBlockX() + ", " + 
          center.getBlockY() + ", " + center.getBlockZ(), 
          NamedTextColor.GRAY)
      );
    }
  }
}

Cleanup System

public class CuboidCleanup {

  @Inject
  private CuboidService cuboidService;

  public void cleanupEmptyCuboids() {
    Set<Cuboid> allCuboids = cuboidService.getCuboids();
    int removed = 0;

    for (Cuboid cuboid : new ArrayList<>(allCuboids)) {
      if (isEmpty(cuboid)) {
        cuboidService.unregister(cuboid);
        removed++;
      }
    }

    getLogger().info("Removed " + removed + " empty cuboids");
  }

  private boolean isEmpty(Cuboid cuboid) {
    for (Block block : cuboid.getBlocks()) {
      if (block.getType() != Material.AIR) {
        return false;
      }
    }
    return true;
  }

  public void cleanupWorld(World world) {
    Set<Cuboid> allCuboids = cuboidService.getCuboids();
    int removed = 0;

    for (Cuboid cuboid : new ArrayList<>(allCuboids)) {
      if (cuboid.getLocA().getWorld().equals(world)) {
        cuboidService.unregister(cuboid);
        removed++;
      }
    }

    getLogger().info("Removed " + removed + " cuboids from " + world.getName());
  }
}

---

Best Practices

✅ Do's

• Let auto-register — Cuboids register automatically
• Track ownership — Use UUID maps for player cuboids
• Clean up — Unregister on plugin disable
• Validate queries — Check for empty results
• Use events — React to cuboid interactions
• Cache results — Don't query repeatedly

❌ Don'ts

• Don't manual register — Auto-registration handles it
• Don't forget cleanup — Unregister unused cuboids
• Don't iterate excessively — Cache query results
• Don't ignore null — Check for null results
• Don't leak memory — Clear maps on disable
• Don't skip validation — Always validate inputs

---

API Reference

CuboidService Methods

Method	Description
register(cuboid)	Register cuboid (auto-called on creation)
unregister(cuboid)	Unregister cuboid
clear()	Remove all cuboids
getCuboids()	Get all registered cuboids
getCuboidsOf(uuid)	Get cuboids by UUID

---

Next Steps

• 📦 Cuboid — Learn about Cuboid types
• 🎯 Event — Listen to block/entity events
• 💾 Configuration — Save cuboids to config