ValorlessUtils is a library of various utilities, created to make the creation of my other addons easier.
My primary programing language is C#, so the functions will resemble those.
"T" refers to type, such as Integer or Double.
| Type | Parameters | Description |
|---|---|---|
Vector2 |
T x, T y |
A generic class representing a 2D vector with components of a number type. |
Vector3 |
T x, T y, T z |
A generic class representing a 3D vector with components of a number type. |
Both Vector2 & Vector3 have the following functions:
(Using Vector3 as example)
| Function | Parameters | Returns | Description |
|---|---|---|---|
Set() |
Vector component, T value |
Sets the value of a specific component in the vector. | |
Set() |
T x, T y, T z |
Sets the values of all components in the vector. | |
Equals() |
Vector3<T> other |
Boolean | Checks if the current Vector3 instance is equal to another Vector3 instance. |
Various utilities.
| Function | Parameters | Returns | Description |
|---|---|---|---|
IsStringNullOrEmpty() |
String string |
Boolean | Checks if a given string is null or empty. |
Percent() |
Number current, Number max |
Double/Float | Calculates the percentage of a given value relative to a maximum value. |
Chance() |
Double percent |
Boolean | Determines if an event occurs based on a given percentage chance. |
RandomRange() |
Integer min, Integer max |
Integer | Generates a random integer within the specified range (inclusive). |
RandomRange() |
Double min, Double max |
Double | Generates a random double within the specified range (inclusive). |
Clamp() |
T value, T min, T max |
Comparable | Clamps a value between a minimum and maximum value. |
Clamp01() |
Number value |
Integer/Double/Long/Float | Clamps a Number value between 0 and 1. |
Bool.FromValue() |
Integer value |
Boolean | Converts an Integer value to a Boolean. |
Bool.ToValue() |
Boolean bool |
Integer | Converts a Boolean value to an Integer. |
Easy console logging.
| Function | Parameters | Description |
|---|---|---|
Info() |
JavaPlugin caller, String msg |
Logs desired message in the console as the type INFO. |
Warning() |
JavaPlugin caller, String msg |
Logs desired message in the console as the type WARNING. |
Error() |
JavaPlugin caller, String msg |
Logs desired message in the console as the type SEVERE. |
Debug() |
JavaPlugin caller, String msg |
Logs desired message in the console as the custom type DEBUG. This checks for the boolean variable 'debug' in the caller's config.yml. |
Easy NBT tagging.
| Function | Parameters | Description | Returns |
|---|---|---|---|
Set<type>() |
ItemStack item, String key, <type> value |
Sets a custom tag onto chosen ItemStack. Run after setting or before getting ItemMeta. |
|
Get<type>() |
ItemStack item, String key |
Gets the value of a chosen tag in the chosen container. | <type> |
Has() |
ItemStack item, String key |
Checks if the ItemStack has the tag. | Boolean |
Supported types: String, Integer, Integer[], Float, Double, UUID, Bool
Easy usage of Config.yml.
Instatiating new config.
import valorless.valorlessutils.config.Config;
public final Config config = new Config(JavaPlugin, "FileName.Extension");| Function | Parameters | Description | Returns |
|---|---|---|---|
Reload() |
Reloads file. | ||
HasKey() |
String key |
Checks file if the key exists. | Boolean |
SaveConfig() |
Saves file. | ||
Get() |
String key |
Returns value found on key. | Object |
GetString() |
String key |
Returns value found on key. | String |
GetBool() |
String key |
Returns value found on key. | Boolean |
GetInt() |
String key |
Returns value found on key. | Integer |
GetFloat() |
String key |
Returns value found on key. | Double |
GetStringList() |
String key |
Returns value found on key. | List<String> |
GetIntList() |
String key |
Returns value found on key. | List<Integer> |
GetDoubleList() |
String key |
Returns value found on key. | List<Double> |
GetList() |
String key |
Returns value found on key. | List<?> |
Set() |
String key, Object value |
Set value of key. | |
AddValidationEntry() |
String key, Object defaultValue |
Add config.yml key you want to validate exists or not. Primarily used for when updating a plugin, and existing config.yml do not add new keys. |
|
Validate() |
Validate config.yml using the entries defined using AddValidationEntry(). Primarily used for when updating a plugin, and existing config.yml do not add new keys. |
Easy usage of item/block translations.
(Uses translation keys: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Translatable.html#getTranslationKey())
Languages Supported: English, Danish, German, Spanish, French, Turkish, Dutch, Japanese, Korean, Chinese (Simplified), Russian, Polish
(Additonal languages can be requested, but they must be on this list: https://minecraft.wiki/w/Language#Languages)
Instatiating new translator.
import valorless.valorlessutils.translate.Translator;
public final Translator translator = new Translator("en-us");| Function | Parameters | Description | Returns |
|---|---|---|---|
Translate() |
String translationKey |
Translate item/block name. (Example) | String |
GetLanguageKey() |
Returns current language. (i.e. "en-us") | String | |
SetLanguage() |
String key |
Change langauge of the translator. | |
GetLanguageFileContent() |
String key |
Returns all content of the current language file. | String |
| Function | Parameters | Description | Returns |
|---|---|---|---|
Play() |
String string, Float volume, Float pitch, Player player |
Play a sound at the location of the player with the given volume and pitch. |
| Function | Parameters | Returns | Description |
|---|---|---|---|
Encode() |
String message, int shift |
String | Encodes a message using the Caesar Cipher algorithm with a specified shift. |
Decode() |
String encodedMessage, int shift |
String | Decodes an encoded message using the Caesar Cipher algorithm with a specified shift. |
Create custom vanilla-like crafting recipes easily.
Each recipe will check if the player has the permission to craft it.
Instatiating new CraftRecipe.
import valorless.valorlessutils.crafting.CraftRecipe;
import valorless.valorlessutils.crafting.Ingredient;
ItemStack result = new ItemStack(Material.GRASS_BLOCK);
List<String> shape = new ArrayList<String>();
shape.add("XXX");
shape.add("XDX");
shape.add("XXX");
List<Ingredient> ingredients = new ArrayList<Ingredient>();
ingredients.add(new Ingredient("D", Material.DIRT));
CraftRecipe recipe = new CraftRecipe(
PLUGIN,
"TestRecipe1",
RecipeType.Shaped,
ingredients,
result,
shape
);
recipe.SetPermission("Test.Permission");
recipe.Add();| Function | Parameters | Description | Returns |
|---|---|---|---|
Add() |
Adds the crafting recipe to the server. | ||
Remove() |
Removes the crafting recipe from the server. | ||
SetShape() |
List<String> shape |
Sets the shape of the recipe (for shaped recipes) | |
GetShape() |
Gets the shape of the recipe. | List<String> | |
SetIngredients() |
List<Ingredient> ingredients |
Sets the ingredients required for the recipe. | |
GetIngredients() |
Gets the list of ingredients required for the recipe. | List<Ingredient> | |
SetType() |
RecipeType type |
Sets the type of the crafting recipe. | |
GetType() |
Gets the type of the crafting recipe. | RecipeType | |
SetPermission() |
String permission |
Sets the permission required to craft the recipe. If the permission is set to null, anyone can craft the item. |
|
SetPermission() |
Permission permission |
Sets the permission required to craft the recipe. If the permission is set to null, anyone can craft the item. |
|
GetPermission() |
Gets the permission required to craft the recipe. | Permission | |
SetResult() |
ItemStack result |
Sets the result of the crafting recipe. | |
GetResult() |
Gets the result of the crafting recipe. | ||
toString() |
Returns a string representation of this CraftRecipe object. |
As I've just recently started making plugins, I'm going to asume you're using Eclipse & Maven, as that's what I am.
The way I'm about to show if the say I've found out how to do this.
There are other ways, and if you know those, feel free to do it that way.
Add ValorlessUtils.jar to any folder in your project.
(I decided to make a new folder called 'dependencies', and placed it there.)
Using Maven you have to define your dependencies manually.
So we're gonna add these a plugin and a dependency it into our file 'pom.xml'.
Plugin:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-install-plugin</artifactId>
<version>2.5.2</version>
<executions>
<execution>
<id>install-external</id>
<phase>clean</phase>
<configuration>
<file>${basedir}/dependencies/ValorlessUtils-1.0.0.69-SNAPSHOT.jar</file> <!-- Location of the ValorlessUtils.jar file. -->
<repositoryLayout>default</repositoryLayout>
<groupId>valorless.valorlessutils</groupId>
<artifactId>ValorlessUtils</artifactId>
<version>1.0.0.69-SNAPSHOT</version> <!-- Or which ever version you choose to use. -->
<packaging>jar</packaging>
<generatePom>true</generatePom>
</configuration>
<goals>
<goal>install-file</goal>
</goals>
</execution>
</executions>
</plugin>
Dependency:
<dependencies>
<dependency>
<groupId>valorless.valorlessutils</groupId>
<artifactId>ValorlessUtils</artifactId>
<version>1.0.0.69-SNAPSHOT</version> <!-- Or which ever version you choose to use. -->
</dependency>
</dependencies>Your pom.xml file should look something like this now:
pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>valorless.valorlessutils</groupId>
<artifactId>ValorlessUtils</artifactId>
<version>1.0.0</version>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-install-plugin</artifactId>
<version>2.5.2</version>
<executions>
<execution>
<id>install-external</id>
<phase>clean</phase>
<configuration>
<file>${basedir}/dependencies/ValorlessUtils-1.0.0.69-SNAPSHOT.jar</file> <!-- Location of the ValorlessUtils.jar file. -->
<repositoryLayout>default</repositoryLayout>
<groupId>valorless.valorlessutils</groupId>
<artifactId>ValorlessUtils</artifactId>
<version>1.0.0.69-SNAPSHOT</version> <!-- Or which ever version you choose to use. -->
<packaging>jar</packaging>
<generatePom>true</generatePom>
</configuration>
<goals>
<goal>install-file</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>spigot-repo</id>
<url>https://hub.spigotmc.org/nexus/content/repositories/public/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>org.spigotmc</groupId>
<artifactId>spigot-api</artifactId>
<version>1.18.2-R0.1-SNAPSHOT</version><!--change this value depending on the version or use LATEST-->
<type>jar</type>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>valorless.valorlessutils</groupId>
<artifactId>ValorlessUtils</artifactId>
<version>1.0.0.69-SNAPSHOT</version>
</dependency>
</dependencies>
</project>
Once this is added, save the file and run Maven Clean on your project to install the jar.
Inside plugin.yml we have to add depend: [ValorlessUtils] for the plugin to require it. or change 'depend' to 'soft-depend' if it's only optional.
In this case we'll be going with 'depend'.
Your plugin.yml file should look something like this now:
plugin.yml
name: HavenBags
main: valorless.havenbags.Main
version: version-number
author: Valorless
api-version: 1.18
website: https://www.spigotmc.org/resources/110420/
description: Create shulker-like bags of varying sizes bound to a player, or accessible by anyone.
depend: [ValorlessUtils]
softdepend: [ChestSort]
commands:
havenbags:
description: Main command.
usage:
aliases: [bags, bag]
permissions:
havenbags.*:
description: Gives access to all HavenBags commands.
children:
havenbags.reload: true
havenbags.use: true
havenbags.rename: true
havenbags.create: true
havenbags.give: true
havenbags.restore: true
havenbags.bypass: true
havenbags.preview: true
havenbags.reload:
description: Allows you to reload the configuration.
default: op
havenbags.use:
description: Allows you to use bags.
default: op
havenbags.rename:
description: Allows you to rename bags. Without havenbags.bypass, you can only rename your own bags.
default: op
havenbags.create:
description: Allows you to create bags.
default: op
havenbags.give:
description: Allows you to give bags.
default: op
havenbags.restore:
description: Allows you to restore bags.
default: op
havenbags.bypass:
description: Allows you to bypass ownership locks.
default: op
havenbags.preview:
description: Allows you to bypass preview bags.
default: opNow we have to add the jar file into Java Build Path, so Eclipse can find the packages.
Head into the properties of your project. (Right click your project, or go to 'Project > Properties' )
In there we head to 'Java Build Path > Libraries', and press the button saying 'Add External Jar'.
Locate ValorlessUtils.jar and select it.
Once done, it should look something like this:
Apply and Close.
With this, ValorlessUtils should now have been added to your project's dependencies, and you can proceed to use it.
I went about it slightly differently in step 4, as I chose 'Add External Class Folder' instead, where all the code from ValorlessUtils is anyway.