Skip to content

README.md

Latest commit

 

History

History
245 lines (178 loc) · 9.91 KB

README.md

File metadata and controls

245 lines (178 loc) · 9.91 KB

CyberLevels

A leveling system plugin for Spigot and Paper with Folia support. Store player levels and experience, reward activity across your server, sync progress through SQL storage, and show progression through chat, action bar, PlaceholderAPI, leaderboards, and more.

🧩 Supported versions

  • Minecraft: 1.8+ (check the resource page for the latest tested builds).
  • Native / primary: 1.16+ workflow, with legacy dependency loading for older servers when needed.
  • Java: 8+ (newer Java versions supported).
  • Platforms: Spigot, Paper, and Folia-supported server setups.

✨ Features

  • 💾 Flexible storage - Flat-file storage, MySQL, MariaDB, SQLite, PostgreSQL, and H2. SQLite works out of the box when SQL storage is enabled with the default type.
  • 🔁 Shared database syncing - Useful for multi-server networks that share the same database table.
  • 🧮 Custom EXP requirements - Use a general formula or per-level formulas in levels.yml.
  • 🔢 Large-number mode - Optional BigDecimal calculations for servers that use very large EXP values.
  • 🎁 Level rewards - Run player or console commands, send chat/action bar/title/global messages, play sounds, and control duplicate reward claims.
  • ⚡ Earn EXP events - Configure EXP from timed rewards, deaths, damage, kills, placing, breaking, consuming, moving, crafting, brewing, enchanting, fishing, breeding, chat, and vanilla EXP gains.
  • 🧱 Block-state keys - Reward precise block states for crops and other blocks where server versions expose that data.
  • 🛡️ Anti-abuse controls - Natural-block checks, silk-touch behavior, crop maturity checks, cooldowns, limiters, timers, and world filters.
  • 📈 Leaderboard - Configurable /clv top rankings with PlaceholderAPI leaderboard slots.
  • 🚀 Multipliers - Permission-based EXP multipliers, plus external booster support when AxBoosters is installed.
  • 🔌 Plugin hooks - PlaceholderAPI, RivalHarvesterHoes, RivalPickaxes, AxBoosters, AxHoes, and AxPickaxes hooks load when present.
  • 🧰 Auto-updating configs - New config.yml, lang.yml, and earn-exp.yml keys can be merged from defaults on update.
  • 🔔 Spigot update notice - Optional async startup check with operator chat notifications.

Soft-dependencies declared by the plugin: PlaceholderAPI, Vault, CyberWorldReset, RivalHarvesterHoes, RivalPickaxes, AxBoosters, AxHoes, AxPickaxes.

📦 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, rewards.yml, and anti-abuse.yml.
  4. Edit configs as needed and run /clv reload with admin permission.

For database setup, use the config.mysql section in config.yml. Set enabled: false for flat-file storage, or keep it enabled and choose one of MYSQL, MARIADB, SQLITE, POSTGRES, POSTGRESQL, or H2.

Full documentation: CyberLevels Wiki

🕹️ Commands

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

Command Description
/clv Show your level / EXP progress
/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
/clv purge <player> Remove a player from CyberLevels data (admin)

🔐 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.top View leaderboard
CyberLevels.player.multiplier.<amount> EXP multiplier, for example CyberLevels.player.multiplier.2
cyberlevels.suppress.levelup.player Suppress personal level-up reward messages
cyberlevels.suppress.levelup.global Suppress global level-up reward messages
cyberlevels.suppress.levelup.* Suppress all level-up reward messages

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.purge /clv purge <player>
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
  • %clv_leaderboard_exp_5% - EXP at rank 5

If the leaderboard is disabled, loading, or the position is out of range, the expansion returns the configured fallback text.

👤 Player

The player placeholders require an online player context.

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

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

🧬 API (for plugin developers)

CyberLevels exposes a Bukkit event for plugins that want to inspect or adjust incoming EXP.

📚 Dependency

  • Add CyberLevels as a compileOnly or provided dependency if you build against its API classes.
  • Add CyberLevels under softdepend or depend in your plugin.yml so your plugin loads after CyberLevels at runtime.
  • New integrations should use com.bitaspire.cyberlevels.event.ExpChangeEvent.
  • The legacy net.zerotoil.dev.cyberlevels.api.events.XPChangeEvent is still present for compatibility, but it is deprecated.

ExpChangeEvent
Class com.bitaspire.cyberlevels.event.ExpChangeEvent
Fires when A player is about to gain CyberLevels EXP after permission and booster multipliers are applied. Only positive EXP gains from online users fire this event.
Can modify setExpAmount(double) or setAmount(double) can change the EXP amount before CyberLevels applies it.
Threading The event is async when the calling thread is not the server main thread. Handle both sync and async listeners as usual.

Methods

Method Description
getUser() LevelUser<?> receiving the EXP
getPlayer() Online Bukkit player 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
getAmount() / setAmount(double) Legacy-style aliases for the EXP amount
getOldXP() / getNewXP() Legacy-style aliases for EXP values

Example

plugin.yml:

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) {
            double boosted = event.getExpAmount() * 1.1;
            event.setExpAmount(boosted);
        }
    }
}

🤝 Support & contributing

  • Bugs / questions: primarily use our Discord server. We do not check GitHub issues that often, and Spigot reviews should not be used as support tickets.
  • Donations: PayPal: zerotoildev

📜 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