API

RareSpawnsAPI

Docs: https://valorless.github.io/RareSpawns/valorless/rarespawns/api/RareSpawnsAPI.html
Import valorless.rarespawns.api.RareSpawnsAPI.

A minimal Java API for interacting with RareSpawns content. It exposes static helpers to detect rare entities and items, resolve IDs, construct items by ID (optionally randomized), and list available rare/entity/ability identifiers. It also provides access to the active JavaPlugin instance.

Table of Contents

• Getting started
  • Maven
  • Gradle
• API surface
• Usage examples
• Notes and best practices
• EntityUtils
  • Methods
  • Usage examples
  • Best practices
• SpawnCause
• Events
  • RareSpawnEvent
  • RareDeathEvent
  • RareUpdateEvent
• Extra Information

Getting started

Maven

<repository>
	<id>jitpack.io</id>
	<url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>com.github.Valorless</groupId>
    <artifactId>RareSpawnsAPI</artifactId>
    <version>BetaAPI</version>
</dependency>

Gradle

dependencyResolutionManagement {
	repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
	repositories {
		mavenCentral()
		maven { url 'https://jitpack.io' }
	}
}

dependencies {
	implementation 'com.github.Valorless:RareSpawnsAPI:BetaAPI'
}

• Add RareSpawns as a depend or softdepend in your plugin.yml so it loads before your plugin.
• Import valorless.rarespawns.api.RareSpawnsAPI.

API surface

• Detection:
  • isRare(Entity) -> boolean
  • isRareItem(ItemStack) -> boolean
• ID resolution:
  • getRareID(Entity) -> String | null
  • getRareID(ItemStack) -> String | null
• Items:
  • getItem(String id, boolean randomize) -> ItemStack | null
  • getItemData(String id) -> ItemData | null
  • getItemIds() -> List<String>
• Rares:
  • getRare(String id) -> EntityData | null
  • getRareIds() -> List<String>
• Abilities:
  • getAbilityIds() -> List<String>
• Spawning:
  • spawnRare(String id, Location location) -> LivingEntity
• Plugin access:
  • getInstance() -> JavaPlugin

Return values may be null if an ID does not exist or the target is not rare.

Usage examples

Basic detection and ID usage:

// Check if an entity is rare and get its ID
if (RareSpawnsAPI.isRare(entity)) {
    String rareId = RareSpawnsAPI.getRareID(entity);
    // Use rareId for logging, rewards, or integration
}

Detecting rare items:

// Validate if a drop or inventory item is a RareSpawns item
boolean rareItem = RareSpawnsAPI.isRareItem(itemStack);
String itemRareId = RareSpawnsAPI.getRareID(itemStack); // may be null if not rare

Building items by ID:

// Build an item by ID; randomize applies any configured random properties
ItemStack randomized = RareSpawnsAPI.getItem("my_item_id", true);

// Build the fixed definition (no randomization)
ItemStack fixed = RareSpawnsAPI.getItem("my_item_id", false);

// Always null-check when looking up by ID
if (fixed != null) {
    player.getInventory().addItem(fixed);
}

Inspect item data without building an ItemStack:

ItemData data = RareSpawnsAPI.getItemData("my_item_id");
if (data != null) {
    // Read definition-time properties (flags, lore template, rarity, etc.)
}

Listing available IDs (for GUIs, commands, or autocompletion):

List<String> itemIds = RareSpawnsAPI.getItemIds();
List<String> rareIds = RareSpawnsAPI.getRareIds();
List<String> abilityIds = RareSpawnsAPI.getAbilityIds();

Fetching rare entity data:

// Retrieve data model for a rare entity definition
EntityData data = RareSpawnsAPI.getRare("zombie_overlord");
if (data != null) {
    // Read configured properties from EntityData
}

See EntityData in the docs for more information.

Spawning a rare via API (fires RareSpawnEvent with cause = EXTERNAL):

LivingEntity spawned = RareSpawnsAPI.spawnRare("zombie_overlord", player.getLocation());

Accessing the plugin instance:

// Obtain the active JavaPlugin instance
JavaPlugin plugin = RareSpawnsAPI.getInstance();

Notes and best practices

• Use main server thread for Bukkit API interactions.
• Always null-check results from lookups by ID.
• Randomized items depend on content configuration; use randomize = false for deterministic results.
• Prefer softdepend if your plugin can run without RareSpawns, and gate calls behind presence checks.

EntityUtils

Docs: https://valorless.github.io/RareSpawns/valorless/rarespawns/api/EntityUtils.html
Import valorless.rarespawns.api.EntityUtils.

A small utility class for common entity-related helpers used by RareSpawns and integrations. It provides methods to find nearby players, compute health percentage, check open-sky exposure, get the geometric center of an entity's bounding box, and generate safe circular spawn locations around an origin.

Notes:

• Call from the main server thread when interacting with Bukkit entities/worlds.
• Requires a Bukkit/Spigot/Paper version that supports Entity#getBoundingBox() for center calculations.

Methods

• List<Player> getPlayersInRadius(LivingEntity entity, double radius)

  • Returns a list of players in the same world whose distance to entity is <= radius.
  • Iterates over World#getPlayers() and checks Euclidean distance from entity.getLocation().

• double getHealthPercentage(LivingEntity entity)

  • Returns the current health as a percentage from 0 to 100.
  • Uses the MAX_HEALTH attribute, falling back to GENERIC_MAX_HEALTH for older server versions.

• boolean isExposedToSunlight(Entity entity)

  • Returns true if the entity is at or above the highest block Y at its X/Z (i.e., open to sky).
  • Does not consider time of day, weather, or skylight level—only geometric openness.

• Location getEntityCenter(Entity entity)

  • Returns the center point of the entity's axis-aligned bounding box as a Location.
  • Useful for spawning particles, projectiles, or positioning effects at the entity center.

• List<Location> generateSafeCircularSpawnLocations(Location location, int amount, double radius)

  • Generates amount spawn points evenly spaced on a circle of radius radius around location.
  • Each candidate point is validated with isLocationSafe; unsafe points fall back to the origin location.

• boolean isLocationSafe(Location location)

  • Returns true if the block at location is not solid (air or passable).
  • Note: Checks a single block at the exact location; if your entities require two-block clearance, validate feet and head blocks.

• String formatLocation(Location loc)

  • Returns a human-readable string like world (100.00, 64.00, 200.00).
  • Coordinates are rounded to two decimals.

• String formatLocation(Location loc, String format)

  • Formats a location using placeholders in format:
    • %w world name, %x X, %y Y, %z Z
  • Example: "%w - %x %y %z" → world - 100.0 64.0 200.0

• double getDamage(Mob mob)

  • Reads the attack damage from the mob's main-hand item attribute modifiers.
  • Falls back to 3.0 if no applicable modifier exists.

• double getAttackSpeed(Mob mob)

  • Reads the attack speed from the mob's main-hand item attribute modifiers.
  • Falls back to 1.0 if no applicable modifier exists.

Usage examples

Find players near a mob and notify them:

List<Player> nearby = EntityUtils.getPlayersInRadius(mob, 16.0);
for (Player p : nearby) {
    p.sendMessage("You feel a strange presence nearby...");
}

Show a health percentage (0–100) for a boss bar:

double hpPct = EntityUtils.getHealthPercentage(boss);
bossBar.setProgress(Math.max(0.0, Math.min(1.0, hpPct / 100.0)));

Apply an effect if the entity is in open sky:

if (EntityUtils.isExposedToSunlight(target)) {
    // e.g., custom burn logic, debuffs, or vulnerability toggles
}

Spawn particles at the precise center of an entity:

Location center = EntityUtils.getEntityCenter(target);
target.getWorld().spawnParticle(Particle.CRIT_MAGIC, center, 10, 0, 0, 0, 0.0);

Generate safe circular spawn points around an origin (e.g., minions around a boss):

List<Location> points = EntityUtils.generateSafeCircularSpawnLocations(boss.getLocation(), 8, 6.0);
for (Location loc : points) {
    // If a point was unsafe, it will be the origin; you may want to filter duplicates.
    boss.getWorld().spawnEntity(loc, EntityType.ZOMBIE);
}

Format a location using the default template:

String s = EntityUtils.formatLocation(player.getLocation());
// e.g., "world (123.46, 64.00, -45.12)"

Format a location with a custom template:

String s = EntityUtils.formatLocation(player.getLocation(), "%w @ %x,%y,%z");
// e.g., "world @ 123.4567,64.0,-45.123"

Read damage/speed from a mob's weapon attributes:

double dmg = EntityUtils.getDamage(mob);
double spd = EntityUtils.getAttackSpeed(mob);

Best practices

• Keep radius checks modest or rate-limit calls for large servers.
• Always validate entities are valid and not dead before acting on them.
• Remember that open-sky exposure is not a full “sunlight burns” check; add time/weather rules if needed.
• For spawning, consider headroom: isLocationSafe checks only one block. Validate both feet and head blocks if your entities are two blocks tall.
• Ensure Location and its World are non-null before calling formatLocation methods to avoid NPEs.

SpawnCause

Docs: https://valorless.github.io/RareSpawns/valorless/rarespawns/api/enums/SpawnCause.html
Import valorless.rarespawns.api.enums.SpawnCause.

Indicates where a rare spawn originated from.

• NULL — Unknown or unspecified.
• INTERNAL — Spawned by RareSpawns internally (natural rules, schedules, internal commands).
• EXTERNAL — Spawned via the public API by another plugin.

Events

All events are synchronous Bukkit events. Register listeners as usual with the Bukkit plugin manager.

RareSpawnEvent

Docs: https://valorless.github.io/RareSpawns/valorless/rarespawns/api/events/RareSpawnEvent.html
Import valorless.rarespawns.api.events.RareSpawnEvent.

Fired when a rare entity spawns. Carries:

• String getId() — Rare definition id.
• LivingEntity getRareEntity() — Spawned entity.
• EntityData getEntityData() — Backing data.
• Location getLocation() — Spawn location.
• SpawnCause getCause() — Origin of spawn (INTERNAL/EXTERNAL/NULL).

Example listener:

@EventHandler
public void onRareSpawn(RareSpawnEvent e) {
    if (e.getCause() == SpawnCause.EXTERNAL) {
        getLogger().info("External rare spawn: " + e.getId());
    }
}

RareDeathEvent

Docs: https://valorless.github.io/RareSpawns/valorless/rarespawns/api/events/RareDeathEvent.html
Import valorless.rarespawns.api.events.RareDeathEvent.

Fired when a rare dies. Carries:

• String getId() — Rare definition id.
• EntityData getEntityData() — Backing data.
• Location getLocation() — Death location.
• Player getKiller() — May be null.
• List<ItemStack> getDrops() — Drops attributed to the death.
• boolean isByCommand() — True if killed via command/admin action.

RareUpdateEvent

Docs: https://valorless.github.io/RareSpawns/valorless/rarespawns/api/events/RareUpdateEvent.html
Import valorless.rarespawns.api.events.RareUpdateEvent.

Fired when a rare is first tracked or refreshed due to chunk/player events. Carries:

• String getId()
• LivingEntity getRareEntity()
• EntityData getEntityData()
• Location getLocation()
• boolean isNew() — True if this is the initial registration.

Extra Information

A lot of the functions and variables in RareSpawns is "public", so you can use pretty much anything in the plugin.
Do note that anything not in the RareSpawnsAPI, may get changed or renamed at any given time.

The source code isn't public yet, but feel free to play around with anything you can get your fingers on.