Skip to content
This repository was archived by the owner on Mar 31, 2026. It is now read-only.

Developer Documentation

Jump to bottom
DarkLash edited this page Jan 20, 2026 · 8 revisions

API Version: 1.0.0
Compatibility: Spigot / Paper / Folia
Status: Stable

RegenSystem provides a public, stable, and event-driven API allowing external plugins to interact safely with regenerable zones, flags, and regeneration logic without touching internal implementation details.

Table of Contents

  1. Introduction
  2. API Stability & Versioning
  3. Installation & Dependency (JitPack)
  4. Getting Started
  5. RegenSystemAPI
  6. ZoneRegistry
  7. RegenZone
  8. ZoneFlag
  9. RegenResult
  10. Events
  11. API Rules & Restrictions
  12. Internal & Experimental APIs

1. Introduction

The RegenSystem API allows plugin developers to:

  • Access all registered regeneration zones
  • Query zones by name, location, flags, or distance
  • Trigger regenerations manually
  • Modify zone flags at runtime
  • Listen to zone lifecycle events
  • Integrate RegenSystem with custom game modes, GUIs, or mechanics

This API is safe, stable, and designed for production servers.

2. API Stability & Versioning

RegenSystem follows semantic versioning: MAJOR.MINOR.PATCH

Version fields

RegenSystemAPI.API_VERSION
RegenSystemAPI.API_MAJOR
RegenSystemAPI.API_MINOR
RegenSystemAPI.API_PATCH

Compatibility rules

Change type Compatibility
PATCH Bug fixes (non-breaking)
MINOR New features (non-breaking)
MAJOR Breaking changes

3. Installation & Dependency (JitPack)

Add JitPack repository

Gradle (Kotlin DSL)

repositories {
    maven("https://jitpack.io")
}

Gradle (Groovy)

repositories {
    maven { url 'https://jitpack.io' }
}

Maven

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

Add RegenSystem API dependency

Gradle

dependencies {
    compileOnly("com.github.DarkLashDev:RegenSystem:v2.0.2")
}

Maven

<dependency>
  <groupId>com.github.DarkLashDev</groupId>
  <artifactId>RegenSystem</artifactId>
  <version>v2.0.2</version>
  <scope>provided</scope>
</dependency>

plugin.yml

depend:
  - RegenSystem

4. Getting Started

Before using the API, always check availability:

if (!RegenSystemAPI.isInitialized()) {
    throw new IllegalStateException("RegenSystem API not available");
}

ZoneRegistry zones = RegenSystemAPI.getZones();

5. RegenSystemAPI

Central static access point of the API.

ZoneRegistry registry = RegenSystemAPI.getZones();

Responsibilities

  • Expose the public API
  • Handle API versioning
  • Protect internal initialization logic
    ⚠️ init(...) is internal and must never be called by addons.

6. ZoneRegistry

Provides access to all registered zones.

Methods

Method Description
getZone(String) Get a zone by name
getZones() Get all zones
getZoneNames() Get all zone names
isRegistered(String) Check if a zone exists
getTimeLeft(String) Remaining time before regen
getZonesContaining(Location) Zones containing a location
getZonesByFlag(ZoneFlag) Zones with a flag
getZonesNear(Location, int) Zones near a location

Example:

Optional<RegenZone> zone = RegenSystemAPI.getZones().getZone("mine");

// Another way

RegenZone zone = RegenSystemAPI.getZones().getZone("mine").orElse(null);

7. RegenZone

Represents a regenerable cuboid area.

Core methods

Method Description
getName() Zone name
getCorner1() First corner
getCorner2() Second corner
getCenter() Center location
isEnabled() Zone enabled state
getBlockCount() Stored blocks count

Logic

Method Description
contains(Location) Check if location is inside
regenerate() Trigger regeneration
countPlayersInside() Count players in zone 
RegenResult result = zone.regenerate();

Flags

boolean pvp = zone.hasFlag(ZoneFlag.PVP);
zone.setFlag(ZoneFlag.PVP, false);

Map<ZoneFlag, Boolean> flags = zone.getFlags();

Visuals

zone.highlight(
    Particle.VILLAGER_HAPPY,
    Duration.ofSeconds(5)
);

8. ZoneFlag

Controls zone behavior.

Available flags:

  • PVP
  • EXPLOSION
  • BLOCK_BREAK
  • BLOCK_PLACE
  • ITEM_DROP
  • ITEM_PICKUP
  • MOB_SPAWN
  • MOB_DAMAGE

Parsing from user input:

ZoneFlag flag = ZoneFlag.fromString("bb");

9. RegenResult

Represents the result of a regeneration.

Result Meaning
SUCCESS Regeneration completed
SKIP Nothing to regenerate
STOP Cancelled or disabled
ERROR Internal error 
if (result.isSuccess()) {
    // regeneration successful
}

10. Events

All events are standard Bukkit events.

ZoneCreateEvent (Cancellable)

@EventHandler
public void onCreate(ZoneCreateEvent e) {
    e.setCancelled(true);
}

ZoneDeleteEvent (Cancellable)

Called before a zone is deleted.

ZoneReloadEvent (Cancellable)

Called before a zone is reloaded.

ZonePreRegenEvent (Cancellable)

@EventHandler
public void onPreRegen(ZonePreRegenEvent e) {
    if (e.getZone().countPlayersInside() > 0) {
        e.setCancelled(true);
    }
}

ZonePostRegenEvent (Not cancellable)

Called after regeneration.

ZoneFlagChangeEvent (Cancellable)

@EventHandler
public void onFlagChange(ZoneFlagChangeEvent e) {
    if (e.getFlag() == ZoneFlag.PVP) {
        e.setCancelled(true);
    }
}

11. API Rules & Restrictions

✅ Allowed

  • Read zone data
  • Modify flags
  • Trigger regeneration
  • Listen to events ❌ Forbidden
  • Casting API objects to internal classes
  • Using fr.darklash.regensystem.core.*
  • Reflection on RegenSystem internals
  • Calling internal methods
    Violating these rules voids compatibility guarantees.

12. Internal & Experimental APIs

Internal API

Methods annotated with:

@ApiStatus.Internal

➡️ Must never be used by addons.

Experimental API

Future experimental features will be located in:
fr.darklash.regensystem.api.experimental

⚠️ Experimental APIs:

  • May change at any time
  • Are not guaranteed stable
  • Can be removed without notice

Clone this wiki locally