Skip to content

README.md

Latest commit

 

History

History
227 lines (162 loc) · 16.8 KB

README.md

File metadata and controls

227 lines (162 loc) · 16.8 KB

CyberLevels

A leveling system plugin for Spigot and Paper (Folia-supported). Store player levels and experience, reward players for activities like breaking blocks, fishing, and more. Show progress via chat, action bar, PlaceholderAPI, and more.

Supported versions

  • Minecraft: 1.8 up to latest version (see resource page for the latest tested builds).
  • Native / primary: 1.16+ workflow; older versions may use bundled libraries as needed.
  • Java: 8+ (newer Java versions supported).

Features

  • SQL storage — MySQL, MariaDB, SQLite, or PostgreSQL (optional; SQLite works out of the box). Suited for multi-server setups when using a shared database.
  • Custom EXP requirements — Per-level formulas and/or a general formula in levels.yml.
  • Rewards — Commands, messages, and sounds when players reach configured levels.
  • Permission multipliers — Grant EXP multipliers with permission nodes.
  • Leaderboard — Top players by level/EXP (optional; configurable max-positions in config.yml).
  • Earn EXP events — Many actions in earn-exp.yml (break blocks, PvP, fishing, etc.), including block state keys for crops (e.g. fully grown wheat).
  • Anti-abuse — Limits farming EXP from placed blocks or repeated actions.
  • PlaceholderAPI — Player stats and leaderboard slots (see below).
  • UUID-based data — Renames do not break progress.
  • Messages — Chat, action bar, titles; hex/gradient support via the messaging stack.
  • Auto-updating configs — New keys can be merged from defaults when updates ship.
  • Spigot update notice — Optional async check against the Spigot resource listing (operators can get in-game notices).

Soft-dependencies: PlaceholderAPI, Vault, CyberWorldReset, RivalHarvesterHoes, RivalPickaxes (hooks load when present).

Installation

  1. Download the latest jar from SpigotMC.
  2. Place it in your server’s plugins folder.
  3. Start the server once to generate config.yml, lang.yml, levels.yml, earn-exp.yml, etc.
  4. Edit configs as needed and run /clv reload (requires permission).

For database setup, follow the mysql (or other SQL) section in config.yml and the wiki.

Commands

Main command: /clv (aliases: cyberlevels, cyberlevel, cyberlvl, levels, level, lvl, lvls).

Command Description
/clv about About the plugin
/clv help Help menu
/clv reload Reload configuration (admin)
/clv top Leaderboard
/clv info [player] Level / EXP progress
/clv addExp <amount> [player] Add EXP
/clv setExp <amount> [player] Set EXP
/clv removeExp <amount> [player] Remove EXP
/clv addLevel <amount> [player] Add levels
/clv setLevel <amount> [player] Set level
/clv removeLevel <amount> [player] Remove levels

Permissions

Players

Permission Purpose
CyberLevels.player.* All player permissions
CyberLevels.player.help Help menu
CyberLevels.player.info Own level / EXP info
CyberLevels.player.about Plugin about
CyberLevels.player.multiplier.<name> EXP multiplier (per configured multiplier)

Admins

Permission Purpose
CyberLevels.admin.* All admin permissions
CyberLevels.admin.help Admin help
CyberLevels.admin.info View others’ info
CyberLevels.admin.reload /clv reload
CyberLevels.admin.exp.* add/set/remove EXP
CyberLevels.admin.exp.add Add EXP
CyberLevels.admin.exp.set Set EXP
CyberLevels.admin.exp.remove Remove EXP
CyberLevels.admin.levels.* add/set/remove level
CyberLevels.admin.levels.add Add level
CyberLevels.admin.levels.set Set level
CyberLevels.admin.levels.remove Remove level

PlaceholderAPI

Prefix: %clv_ … %

Leaderboard

Use leaderboard_<type>_<position> where:

  • type: name, displayname, level, or exp
  • position: 1 … up to your configured leaderboard size (config.leaderboard.max-positions)

Examples:

  • %clv_leaderboard_name_1% — name at rank 1
  • %clv_leaderboard_level_3% — level at rank 3

If the leaderboard is disabled or the position is out of range, the expansion returns a short hint string (see config).

Player (viewer must be online for these)

Placeholder Description
%clv_player_level% Current level
%clv_player_level_next% / %clv_player_next_level% Next level (capped at max)
%clv_player_exp% / %clv_player_experience% Current EXP
%clv_player_exp_required% / %clv_player_experience_required% EXP required for next level
%clv_player_exp_remaining% / %clv_player_experience_remaining% EXP until level up
%clv_player_exp_progress_bar% / %clv_player_experience_progress_bar% Progress bar
%clv_player_exp_percent% / %clv_player_experience_percent% Progress percent

Global (no online player restriction in implementation)

Placeholder Description
%clv_level_maximum% Max level
%clv_level_minimum% Min / start level
%clv_exp_minimum% / %clv_experience_minimum% Starting EXP
%clv_experience_minimum% Same as start EXP

API (for plugin developers)

CyberLevels exposes a small Bukkit event you can listen to from another plugin.

Dependency

  • Add CyberLevels as a compileOnly (or provided) dependency if you build against its API classes, and list it under softdepend (or depend) in your plugin.yml so your plugin loads after CyberLevels at runtime.

ExpChangeEvent
Class com.bitaspire.cyberlevels.event.ExpChangeEvent
Fires when A player is about to gain CyberLevels EXP (positive amount), after permission multipliers are applied. Only when the user is online. Does not fire for EXP removal or for setExp flows that bypass the same path.
Threading The event is created with async = true when the calling thread is not the server main thread (see Event constructor). Handle both sync and async listeners as usual.

Methods

Method Description
getUser() LevelUser<?> receiving the EXP
getOldExp() / getNewExp() EXP before and after this gain preview
getOldLevel() / getNewLevel() Level before and after this gain preview
getExpAmount() / setExpAmount(double) EXP being added; you may change the amount before it is applied

Example

plugin.yml (ensure CyberLevels loads first):

name: MyPlugin
main: com.example.myplugin.MyPlugin
version: 1.0
softdepend: [CyberLevels]

Register a Listener in your plugin’s onEnable:

import com.bitaspire.cyberlevels.event.ExpChangeEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        if (getServer().getPluginManager().getPlugin("CyberLevels") == null) {
            getLogger().warning("CyberLevels not found; ExpChangeEvent will never fire.");
            return;
        }
        getServer().getPluginManager().registerEvents(new XpBoostListener(), this);
    }

    private static final class XpBoostListener implements Listener {

        @EventHandler(ignoreCancelled = false)
        public void onCyberLevelsExpChange(ExpChangeEvent event) {
            // Example: add 10% to incoming EXP (must stay non-negative and reasonable)
            double boosted = event.getExpAmount() * 1.1;
            event.setExpAmount(boosted);

            // event.getUser(), getOldExp(), getNewExp(), getOldLevel() and getNewLevel() are also available
        }
    }
}

Support & contributing

Resource terms (summary)

Per the Spigot listing: do not redistribute or sell the resource as your own, do not decompile to claim ownership, and follow any updated terms on the resource page.

Authors

Kihsomray, CroaBeast

Contributors

Klema_LP

© BitAspire.com | Product of ZeroToil LLC