Level#
Level lets your players compete to have the top island! Place blocks and increase the island level!
Created and maintained by tastybento.
Useful links
Installation#
- Place the level addon jar in the addons folder of the BentoBox plugin
- Restart the server
- The addon will create a data folder and inside the folder will be a config.yml
- Edit the config.yml how you want. The config specifies how much blocks are worth (see below)
- Restart the server if you make a change
Configuration#
Level addon has 3 general configuration things:
- config.yml file contains default addon configuration files.
- blockconfig.yml file contains value for each block.
- /panels/ contains files that manages player GUI's
config.yml#
Config file contains main functions for the addon.
The latest config.yml can be found here.
This section defines a number of overall settings for the add-on.
disabled-game-modes
Allows to specify in which GameModeAddons Level addon should not operate.
Level will NOT hook into these game mode addons.
Default: []
log-report-to-console
Allows to see a level report if command is executed from console.
Default: true
concurrent-island-calcs
Allows to specify how many island level calculations can be happening at once.
If your CPU can handle it, you can run parallel island calcs if there are more than one in the queue.
Default: 1
calculation-timeout
Allows to specify the amount of minutes when level calculation should be stopped.
Generally, calculation should only take a few seconds, so if this ever triggers then something is not right.
Default: 5
zero-new-island-levels
Allows to specify if starting blocks should be included in island level.
If true, Level will calculate the starter island's level and remove it from any future level calculations. Player level may go into negative values if all starting blocks are removed.
If this is false, the player's starter island blocks will count towards their level.
Default: true
login
Allows to set that island level is calculated on player login.
This silently calculates the player's island level when they login.
Default: false
nether
Allows to include nether island in level calculation.
Warning: Enabling this mid-game will give players with an island a jump island level. New islands will be correctly zeroed.
Default: false
end
Allows to include the end island in level calculation.
Warning: Enabling this mid-game will give players with an island a jump island level. New islands will be correctly zeroed.
Default: false
include-chests
Allows to include chest content in level calculation.
Warning: level calculation will be longer and server performance may be affected.
Default: false
underwater
Allows to specify underwater block multiplier.
If blocks are below sea-level, they can have a higher value. e.g. 2x. Promotes under-water development if there is a sea. Value can be fractional.
Default: 1.0
levelcost
Allows to specify value of one island level.
Default: 100
Minimum: 1
level-calc
Allows to specify the formula for level calculation.
- blocks - the sum total of all block values, less any death penalty
- level_cost - in a linear equation, the value of one level
This formula can include +,=,*,/,sqrt,^,sin,cos,tan,log (natural log). Result will always be rounded to a long integer.
For example, an alternative non-linear option could be: 3 * sqrt(blocks / level_cost)
Default: blocks / level_cost
levelwait
Allows to specify cool down between level requests in seconds.
Default: 60
deathpenalty
Allows to specify the death penalty.
How many block values a player will lose per death. Default value of 100 means that for every death, the player will lose 1 level (if levelcost is 100).
Set to zero to not use this feature.
Default: 100
sumteamdeaths
Allows to sum all team members for the death penalty.
If false, only the leader's deaths counts.
Default: false
shorthand
Allows to show shorter island level numbers.
Shows large level values rounded down, e.g., 10,345 -> 10k
Default: false
blockconfig.yml#
Block config file contains values for blocks.
The latest blockconfig.yml can be found here.
This section defines values for blocks and limits for them.
Tip
Values in this file supports only integers -> full numbers.
Tip
The correct material names can be found in Spigot material page.
Note: this is latest spigot material list: MATERIALS
limits
This section lists the limits for any particular block. Blocks over this amount are not counted. This limit applies to all game modes and is not world-specific.
Format: MATERIAL: NUMBER
blocks
This section lists the value of a block in all game modes (worlds). To specific world-specific values, use the next section. Any blocks not listed will have a value of 0. AIR is always zero.
Format: MATERIAL: NUMBER
worlds
List any blocks that have a different value in a specific world. If a block is not listed, the default value will be used from the blocks section. Prefix with world name. The values will apply to the associated nether and the end if they exist.
Example:
worlds:
AcidIsland_world:
SAND: 0
SANDSTONE: 0
ICE: 0
In this example, AcidIsland will use the same values as BSkyBlock for all blocks except for sand, sandstone and ice.
Customizable GUI's#
BentoBox 1.17 API introduced a function that allows to implement customizable GUI's. We tried to be as simple as possible for customization, however, some features requires explanation. You can find more information how BentoBox custom GUI's works here: Custom GUI's
How can I customize GUI's
To customize Level Addon GUI's you need to have version 2.10.0. This is a first version that has implemented them. Addon will create a new directory under /plugins/bentobox/addons/level
with a name panels
Currently you can customize 3 GUI's:
- Top panel:
top_panel
- allows to see top 10 islands. - The detail block panel:
detail_panel
- allows to view detailed list block values in game. - The block value panel:
value_panel
- allows to view each block value in game.
Each GUI contains functions that is supported only by itself.
What does PREVIOUS
|NEXT
button type?
This button is available in detail_panel and value_panel. The PREVIOUS and NEXT button types allows creating automatic paging, when you have more blocks than spaces in GUI. These types have extra parameters under data:
indexing
- indicates if button will show page number.
Example:
icon: TIPPED_ARROW:INSTANT_HEAL::::1
title: level.gui.buttons.previous.name
description: level.gui.buttons.previous.description
data:
type: PREVIOUS
indexing: true
action:
left:
tooltip: level.gui.tips.click-to-previous
What does TOP
button type?
This button is available in top_panel. It shows island at the top X by island level.
The icon
by default will be PLAYER_HEAD
with a proper player skin. Enabling it will replace it with specified material.
index
in the data field allows to specify which place of Top 10 should be showed in current spot.
Top panel has 2 implemented actions which funstion requires extra addon:
warp
- requires Warps addon. Will be shown only if warp sign exists on players island.visit
- requires Visit addon. Will be shown only if visiting is allowed on players island.
Fallback allows to change background icon, when there are no player in top spot.
Example:
#icon: PLAYER_HEAD
title: level.gui.buttons.island.name
description: level.gui.buttons.island.description
data:
type: TOP
index: 1
actions:
warp:
click-type: LEFT
tooltip: level.gui.tips.click-to-warp
visit:
click-type: RIGHT
tooltip: level.gui.tips.right-click-to-visit
fallback:
icon: LIME_STAINED_GLASS_PANE
title: level.gui.buttons.island.empty
What does VIEW
button type?
This button is available in top_panel. It shows viewer island level.
The icon
by default will be PLAYER_HEAD
with a proper player skin. Enabling it will replace it with specified material.
The action view
allows to see detailed menu of players island.
Example:
#icon: PLAYER_HEAD
title: level.gui.buttons.island.name
description: level.gui.buttons.island.description
data:
type: VIEW
actions:
view:
click-type: unknown
tooltip: level.gui.tips.click-to-view
What does BLOCK
button type?
This button is available in detail_panel and value_panel. This button shows given material as icon.
Example:
#icon: STONE
title: level.gui.buttons.value.name
description: level.gui.buttons.value.description
data:
type: BLOCK
Commands#
Tip
[player_command]
and [admin_command]
are commands that differ depending on the gamemode you are running. The Gamemodes' config.yml
file contains options that allows you to modify these values. As an example, on BSkyBlock, the default [player_command]
is island
, and the default [admin_command]
is bsbadmin
.
/[player_command] top
: access to the top panel. Requires[gamemode].island.top
permission./[player_command] level
: triggers level calculation for player. Requires[gamemode].island.level
permission./[player_command] value [material]
: allows to check block value. Requires[gamemode].island.value
permission.
/[admin_command] level <player>
: triggers level calculation for player. Requires[gamemode].admin.level
permission./[admin_command] levelstatus
: shows how many islands are in the queue. Requires[gamemode].admin.levelstatus
permission./[admin_command] sethandicap <player> <number>
: allows to set initial number of island level. Requires[gamemode].admin.level.sethandicap
permission./[admin_command] top
: shows the top 10 islands in chat. Requires[gamemode].admin.top
permission./[admin_command] top remove <player>
: allows to remove player from the top. Requires[gamemode].admin.top.remove
permission.
Permissions#
Tip
[gamemode]
is a prefix that differs depending on the gamemode you are running. The prefix is the lowercased name of the gamemode, i.e. if you are using BSkyBlock, the prefix is bskyblock
. Similarly, if you are using AcidIsland, the prefix is acidisland
.
[gamemode].intopten
- (default:true
) - Lets the player be in top 10 panel.[gamemode].island.level
- (default:true
) - Allows player to use the/[player_command] level
command.[gamemode].island.top
- (default:true
) - Allows player to use the/[player_command] top
command.[gamemode].island.value
- (default:true
) - Allows player to use the/[player_command] value
command.[gamemode].island.level.details.blocks
- (default:true
) - Allows player to see detailed list of blocks for island.[gamemode].island.level.details.spawners
- (default:false
) - Allows player to see detailed list of spawners for island.[gamemode].island.level.details.underwater
- (default:false
) - Allows player to see detailed list of underwater blocks for island.[gamemode].island.level.details.above-sea-level
- (default:false
) - Allows player to see detailed list of above the sea level blocks for island.
[gamemode].admin.level
- (default:op
) - Let the player use the/[admin_command] level <player>
command.[gamemode].admin.levelstatus
- (default:op
) - Let the player use the/[admin_command] levelstatus
command.[gamemode].admin.level.sethandicap
- (default:op
) - Let the player use the/[admin_command] sethandicap <player> <number>
command.[gamemode].admin.top
- (default:op
) - Allows the access to/[admin_command] top
command.[gamemode].admin.top.remove
- (default:op
) - Allows the access to/[admin_command] top remove <player>
command.
Something is missing?
You can find the comprehensive list of permissions in the addon.yml file of this addon.
If something is indeed missing from the list below, please let us know!
Placeholders#
Tip
[gamemode]
is a prefix that differs depending on the gamemode you are running.
The prefix is the lowercased name of the gamemode, i.e. if you are using BSkyBlock, the prefix is bskyblock
.
Properly translated placeholders for each gamemode can be found:
Please read the main Placeholders page.
Placeholder | Description | Level version |
---|---|---|
%Level_[gamemode]_island_level% | Island level of the player's island | 1.9.0 |
%Level_[gamemode]_visited_island_level% | Island level of the island the player is standing on | 1.9.0 |
%Level_[gamemode]top_value#rank#% | Island level of the #rank# -th island in the Top 10 | 1.9.0 |
%Level_[gamemode]top_name#rank#% | Island owner's name of the #rank# -th island in the Top 10 | 1.9.0 |
%Level_[gamemode]_points_to_next_level% | Points to the next level for player | 2.3.3 |
%Level_[gamemode]_rank_value% | Displays island rank value | 2.7.2 |
%Level_[gamemode]_island_level_raw% | Unformatted island level | 2.8.1 |
%Level_[gamemode]_island_total_points% | Total number of points counted before applying level formula | 2.10.0 |
%Level_[gamemode]_island_level_max% | Maximum level this island has ever been. Current level maybe lower. | 2.10.0 |
FAQ#
Can you add a feature X?
Please add it to the list here.
How to make that level-cost
increases after each level?
You cannot do it directly because BentoBox level calculation happens at once, and not iterative for each level.
However, this can be done using the level-calc
formula, if you know what formula you need. If we use your example of making each level 50% harder to reach than the previous level, then the approximate formula for that is:
level-calc: 2.4661 * log(blocks) - (2.4661 * log(level_cost) - 1)
where level_cost
is the cost in blocks to get to level 1. e.g., if level 1 costs 100 blocks, the level 2 costs 150 blocks, level 3 costs 225, etc.
Here's the graph:
Note that that particular formula does start to asymptote around level 25, i.e., it becomes really hard to get to level 26 or 27 because so many blocks are required, so having that particular rule might not be that good an approach because eventually almost everyone will end up with the same level.
Anyway, although I understand what you're asking, the level-calc
formula should actually be able to provide what you want so long as it supports the right formula. Having the next-levelcost
is problematic from a programming standpoint because the level calculations would have to be done iteratively instead of by just applying a single formula to the blocks counted. I can't quite work out how to do that right now but I do know that the current method of having a formula for how you want levels increased does work for sure.
How can I work out a formula for levels?
The best way is to start with a formula and plot it to see if it makes sense, e.g., by using something like Excel. If you want to work out what formula you need from say a table of values, then Excel (or maybe some other spreadsheet) can do that too: make a graph of levels and how many blocks for each level and then plot a graph of the table (X Y Plot). Right click the graph to add a trend line, select the approximation, e.g., linear, log, exponential, etc. that best fits, and then select "Display equation on chart" to display the formula and substitute blocks
for x
. Here's some screenshots of what I did you find out the equation for increasing by 50% each time with a starting cost of 100 blocks.
So, for that, it would be:
level-calc: 2.4661 * log(blocks) - 10.357
I hope that helps.
Translations#
We need your help!
A vast majority of strings in BentoBox and its addons can be translated into virtually any language. However, most of the translations that are provided with BentoBox or said addons are made by the community, on which we heavily rely. We cannot review all the content of these translations nor guarantee its quality, hence why we highly appreciate any contributions.
- If your language is not available for this addon or if you would like to improve the existing translation, please read the translation guidelines and start translating!
- If your language is not listed below, please contact us on Discord and we will setup everything so that you can start translating!
Available | Language | Language code | Progress |
---|---|---|---|
✅ | English (United States) | en-US | 100% (Default) |
✅ | Chinese (China) | zh-CN | |
❌ | Chinese (Hong Kong) | zh-HK | |
❌ | Chinese (Taiwan) | zh-TW | |
❌ | Croatian | hr | |
✅ | Czech | cs | |
✅ | French | fr | |
✅ | German | de | |
✅ | Hungarian | hu | |
✅ | Indonesian | id | |
❌ | Italian | it | |
❌ | Japanese | ja | |
❌ | Korean | ko | |
✅ | Latvian | lv | |
✅ | Polish | pl | |
❌ | Portuguese | pt | |
✅ | Romanian | ro | |
❌ | Russian | ru | |
✅ | Spanish | es | |
✅ | Turkish | tr | |
❌ | Vietnamese | vi |
API#
Since Level 2.7.2 and BentoBox 1.17 other plugins can access to the Level addon data directly. However, addon requests are still a good solution for a plugins that do not want to use too many dependencies.
Maven Dependency#
Level provides an API for other plugins. This covers Level 2.8.1 and onwards.
Note
Add the Level dependency to your Maven POM.xml:
<repositories>
<repository>
<id>codemc-repo</id>
<url>https://repo.codemc.io/repository/maven-public/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>world.bentobox</groupId>
<artifactId>level</artifactId>
<version>2.8.1</version>
<scope>provided</scope>
</dependency>
</dependencies>
Use the latest Level version.
Then you can obtain the level for a player by asking Level once you have the world that the island is in and confirming that the player is the owner of an island in that world.
The JavaDocs for Level can be found here.
Events#
Description
Event that is triggered when player level is calculated.
Link to the class: IslandLevelCalculatedEvent
Variables
Island island
- the island object.UUID targetPlayer
- id of the player who calculated level.Results results
- the calculated island results.
Code example
@EventHandler(priority = EventPriority.MONITOR)
public void onLevelCalculated(IslandLevelCalculatedEvent event) {
UUID user = event.getTargetPlayer();
Island island = event.getIsland();
Results results = event.getResults();
// death handicap from results.
int deathHandicap = event.getDeathHandicap();
// the island initial level from results.
long initialLevel = event.getInitialLevel();
// the island level from results.
long level = event.getLevel();
// this will overwrite island level to 100.
event.setLevel(100);
// number of points required to next level
long pointsToNextLevel = event.getPointsToNextLevel();
// the report text from results.
List<String> report = event.getReport();
}
Description
Event that is triggered before player level is calculated.
Link to the class: IslandPreLevelEvent
Variables
Island island
- the island object.UUID targetPlayer
- id of the player who calculated level.
Code example
@EventHandler(priority = EventPriority.LOW)
public void beforeLevelCalculated(IslandPreLevelEvent event) {
UUID user = event.getTargetPlayer();
Island island = event.getIsland();
}
Addon Request Handlers#
Till BentoBox 1.17 we had an issue with accessing data outside BentoBox environment doe to the class loader we used to load addons. This meant that data was accessible only from other addons. But BentoBox implemented PlAddon functionality, which means that request handlers are not necessary anymore.
More information about addon request handlers can be found here
Description
Returns the level of this player's island in the given world.
Input
world-name
: String - the name of the world.player
: UUID - the UUID of the player.
Output
The player's island level or 0L
if the input was invalid or if this player does not have an island in this world.
Failure
This handler will return 0L
if the world-name
has not been provided or if the world-name
does not exist or is not a gamemode world.
Code example
/**
* Returns the level of this player's island in the given world.
* @param playerUUID UUID of the player, not null.
* @param worldName Name of the world (Overworld) the island is in, not null.
* @return the player's island level or {@code 0L} if the input was invalid or
* if this player does not have an island in this world.
*/
public long getIslandLevel(UUID playerUUID, String worldName) {
return (Long) new AddonRequestBuilder()
.addon("Level")
.label("island-level")
.addMetaData("world-name", worldName)
.addMetaData("player", playerUUID)
.request();
}
Description
Returns the players whose island they own is in the Top 10 mapped to the level of their island.
Input
world-name
: String - the name of the world.
Output
Map<UUID, Long>
containing the UUIDs of the island owners whose island is in the Top 10, mapped to the level of their island.
Failure
This handler will return empty map if the world-name
has not been provided or if the world-name
does not exist or is not a gamemode world.
Code example
/**
* Returns the players whose island they own is in the Top 10 mapped to the level of their island.
* @param worldName Name of the world (Overworld) the island is in, not null.
* @return a Map containing the UUIDs of the island owners whose island is in the Top 10, mapped to the level of their island,
* or an empty map if the specified world doesn't exist or doesn't contain islands.
*/
public Map<UUID, Long> getTopTen(String worldName) {
return (Map<UUID, Long>) new AddonRequestBuilder()
.addon("Level")
.label("top-ten-level")
.addMetaData("world-name", worldName)
.request();
}