A flexible command framework which removes lots of boilerplate code used in commands

<h2>Getting Started</h2>
Welcome to the <code>command-flow</code> documentation
CommandFlow is a flexible command framework which removes lots of
boilerplate code used in commands
The command framework is divided into two parts. One is the actual
command framework and the other one is the API to allow creation of
a complete command tree based on annotations
<h3>Components of the Command Framework</h3>
There are some basic components that you should at least be aware of to use CommandFlow
<ul>
<li>
Command: This is the most fundamental component, the Command. It contains all the information related to a command, included but not limited to name, aliases, permission, parts, etc.
Those are created using the <code>Command.builder(String)</code> method, which returns an <code>Command.Builder</code> instance where you can set all the information of the command.
</li>
<li>
CommandPart: This is the second most fundamental component, it can be understood as every argument of a Command, including things like subcommands, flags, non positional arguments, etc. It can use arguments from the argument list, or provide them using any other means also they can forward the parsing to another part and just act as a modifier. Most of the default parts can be found at the class <code>Parts</code>
</li>
<li>
CommandContext: This is a mutable object which contains the context for the called command including but not limited to the values for every part parsed, the raw arguments list and the raw arguments for every part, the labels and the Command execution path(which path of subcommands was taken).
</li>
</ul>
<h3>Known bugs or misbehaviours</h3>
The next list are the known bugs that must be resolved at some point:
<ul>
<li>No known bugs at the moment.</li>
</ul>

Getting Started

<h2>Installation</h2>
You can add <code>command-flow</code> to your project using <a href="https://gradle.org/">Gradle</a>,
<a href="https://maven.apache.org/">Maven</a> or manually downloading the JAR files
<h3>Gradle</h3>
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
<pre><code class="hljs language-kotlin">dependencies {
 implementation("me.fixeddev:commandflow-universal:0.5.3")
}
</code></pre>
<h3>Maven</h3>
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>me.fixeddev&#x3C;/groupId>
 &#x3C;artifactId>commandflow-universal&#x3C;/artifactId>
 &#x3C;version>0.5.3&#x3C;/version>
&#x3C;/dependency>
</code></pre>

Installation

command-flow

Collection of small Java libraries containing boilerplate code for our applications and other libraries

<h1>Error</h1>
Library for multiple-error handling and complete error reports
<h2>Examples</h2>
We usually just throw an exception if something is wrong
<pre><code class="hljs language-java">for (Listener listener : getListenersForEvent(event)) {
 try {
 listener.listen(event);
 } catch (Exception e) {
 throw new EventException("Cannot pass event " + event.getName(), e); 
 }
}
</code></pre>
This only reports the first error found, bad if we want to fix all the
errors without having to compile, test, find errors, fix and so on with
all the errors, because it will be reported one at a time
But with this library:
<pre><code class="hljs language-java">// the main message of the errors
ErrorDetails errors = new ErrorDetails("Cannot pass event " + event.getName());
for (Listener listener : getListenersForEvent(event)) {
 try {
 listener.listen(event);
 } catch (Exception e) {
 // error is added, not thrown
 errors.add(e);
 }
}
// then, throw all exceptions once
throw errors.toException(EventException::new);
</code></pre>
This reports all errors, not only the first. It also prints a pretty message
with all the stack traces in this format:
<pre><code class="hljs language-cs">Exception in thread &#x3C;thread> &#x3C;package>.EventException: Cannot pass event &#x3C;eventName>
1) java.lang.NullPointerException: null
 at sample.stack.Trace.make(Trace.java:25)
 at sample.stack.Trace.make(Trace.java:34)
 at sample.stack.Trace.create(Trace.java:50)
 at sample.listener.Listener.listen(Listener.java:32)

2) java.lang.IllegalStateException: The library is so cool
 at sample.stack.Trace.make(Trace.java:25)
 at sample.stack.Trace.make(Trace.java:34)
 at sample.stack.Trace.create(Trace.java:50)
 at sample.listener.Listener.listen(Listener.java:32)
</code></pre>
All stack-traces enumerated and formatted
<h2>Dependency</h2>
You can download the JAR in the repository releases, or add the dependency to
Gradle build-script or your Maven project object model
Repository:
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
Dependency:
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>commons-error&#x3C;/artifactId>
 &#x3C;version>VERSION&#x3C;/version>
&#x3C;/dependency>
</code></pre>

Error

<h1>commons</h1>
<ul>
<li><a href="/docs/commons/reflect">Reflection</a> for easy handling of types and generic types
using <code>TypeReference</code></li>
<li><a href="validation">Validation</a> for creating fail-fast APIs and shorten code</li>
<li><a href="/docs/commons/error">Error</a> for multiple error logging, track all errors, once all
have been collected, warn about all, not just the first one</li>
</ul>

commons

<h1>Reflect Utils</h1>
There're some classes for easy handling of types, generic types, and other things with reflection. This module contains
three principal util classes:
<ul>
<li><code>TypeReference</code> An util class to handle Java types</li>
<li><code>Types</code> A collection of util methods for resolving types and constructing <code>TypeReference</code> objects</li>
<li><code>CompositeTypeReflector</code> To resolve type variables</li>
</ul>
<h2>Usage</h2>
The main use of <code>TypeReference</code> is to easily manipulate (compare, store, etc)
Java types, just like a Java <code>Class</code> type but supporting parameterized types,
wildcard types and more
<pre><code class="hljs language-java">// Here we create a type reference that holds a List&#x3C;String> generic type
TypeReference&#x3C;List&#x3C;String>> listType = new TypeReference&#x3C;List&#x3C;String>>() {};

// Now we check all the method return types and parameters (fully-specified)
for (Method method : List.class.getDeclaredMethods()) {
 List&#x3C;TypeReference&#x3C;?>> parameterTypes = listType.getParameters(method);
 TypeReference&#x3C;?> returnType = listType.getReturnType(method);
}
</code></pre>
A type is <code>fully-specified</code> when it doesn't require a context or a
<code>GenericDeclaration</code> to be completed. For example:
<pre><code class="hljs language-java">public class Foo&#x3C;T> { // GenericDeclaration

 private final List&#x3C;T> list; // non-fully-specified type
 private final Set&#x3C;String> set; // fully-specified type!

 // ...
}
</code></pre>
Here, the <code>list</code> cannot be completed if there isn't a GenericDeclaration.
<code>TypeReference</code>, <code>Types</code> and <code>CompositeTypeReflector</code> help you with this
<h2>Dependency</h2>
You can download the JAR in the repository releases, or add the dependency to
Gradle build-script or your Maven project object model
Repository:
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
Dependency:
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>commons-reflect&#x3C;/artifactId>
 &#x3C;version>VERSION&#x3C;/version>
&#x3C;/dependency>
</code></pre>

Reflect Utils

<h1>Validation</h1>
Library for create fail-fast APIs and shorten code
<h2>Examples</h2>
For example, validating normally
<pre><code class="hljs language-java">public void setPages(List&#x3C;String> pages) {
 if (this.pages != null) {
 throw new IllegalStateException("Pages is already defined");
 }
 if (pages == null) {
 throw new NullPointerException("pages cannot be null");
 }
 for (String page : pages) {
 if (page.length() > 500) {
 throw new IllegalArgumentException("a page cannot contain more than 500 characters");
 }
 }
 this.pages = pages;
}
</code></pre>
Using this library:
<pre><code class="hljs language-java">public void setPages(List&#x3C;String> pages) {
 Validate.state(this.pages == null, "Pages is already defined!");
 Validate.notNull(pages, "Pages cannot be null");
 Validate.argument(Filters.all(page -> page.length() &#x3C; 500), "A page cannot contain more than 500 characters");
 this.pages = pages;
}
</code></pre>
<h2>Why fail-fast?</h2>
Fail-fast methodology is very helpful for debugging. Functions that fail quickly
in case of providing invalid input make it easier to search for errors
This library helps you create fail-fast functions without the need to write so
much code. In addition, it helps you easily create messages for errors
For example, in a non-fail-fast method:
<pre><code class="hljs language-java">public String format(String text) {
 if (text == null) {
 return null;
 }
 return /* format the text */;
}
</code></pre>
Then
<pre><code class="hljs language-java">String message = messages.get("message-name"); // nullable, this is the bug
String formattedMessage = format(message); // null message, null formattedMessage
// ...do other things with non-fail-fast-methods...
log(formattedMessage.replace('.', '/')); // NullPointerException!
</code></pre>
In this case, the error was not reported from the beginning, it was reported later. In this case, you would be seeing
the exception's stack-trace, checking on which line it failed, which variable could be null, checking on which line this
variable was created, etc.
With a fail-fast method:
<pre><code class="hljs language-java">public String format(String text) {
 Validate.notNull(text, "text cannot be null");
 return /* format the text */;
}
</code></pre>
Then
<pre><code class="hljs language-java">String message = messages.get("message-name"); // nullable, this is the bug
String formattedMessage = format(message); // in case of null, fails
// ...do other things...
log(formattedMessage.replace('.', '/'));
</code></pre>
The method fails instantly on passing it a null reference, it fails with a
descriptive message about what failed. The error is easily found
<h2>Dependency</h2>
You can download the JAR in the repository releases, or add the dependency to
Gradle build-script or your Maven project object model
Repository:
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
Dependency:
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>commons-validation&#x3C;/artifactId>
 &#x3C;version>VERSION&#x3C;/version>
&#x3C;/dependency>
</code></pre>

Validation

A resource-pack library for Minecraft: Java Edition

<h2>Developer API Introduction</h2>
<h3>Adding central to your project</h3>
The first step to using <code>creative-central</code> is to add it to your project, you can do
this using Gradle (recommended) or Maven
<h4>Gradle</h4>
If you are using Gradle, you have to add our repository and the central dependency
to your build script (<code>build.gradle(.kts)</code>)
<h5>Kotlin DSL:</h5>
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}

dependencies {
 compileOnly("team.unnamed:creative-central-api:0.7.1-SNAPSHOT")
}
</code></pre>
<h5>Groovy DSL:</h5>
<pre><code class="hljs language-groovy">repositories {
 maven {
 url "https://repo.unnamed.team/repository/unnamed-public/"
 }
}

dependencies {
 compileOnly "team.unnamed:creative-central-api:0.7.1-SNAPSHOT"
}
</code></pre>
<h4>Maven</h4>
If you are using Maven, you have to add our repository and the central dependency
to your <code>pom.xml</code>
<pre><code class="hljs language-xml">&#x3C;repositories>
 &#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
 &#x3C;/repository>
&#x3C;/repositories>

&#x3C;dependencies>
 &#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>creative-central-api&#x3C;/artifactId>
 &#x3C;version>0.7.1-SNAPSHOT&#x3C;/version>
 &#x3C;scope>provided&#x3C;/scope>
 &#x3C;/dependency>
&#x3C;/dependencies>
</code></pre>
<h3>Declaring a dependency on central</h3>
If you are developing a plugin that uses <code>creative-central</code>, you should declare a dependency
on it in your plugin's <code>plugin.yml</code>, this will make sure that your plugin will not be loaded
if <code>creative-central</code> is not present
plugin.yml in Bukkit plugins
<pre><code class="hljs language-yaml">name: ...
main: ...
version: ...
...
depend: [creative-central]
</code></pre>
<h3>Getting an instance of the API</h3>
First of all, you need to obtain an instance of <code>CreativeCentral</code>, you can do this by using
your platform's service provider (preferred) or using <code>CreativeCentralProvider#get()</code>, the
static service provider
Using Bukkit's service provider
<pre><code class="hljs language-java">RegisteredServiceProvider&#x3C;CreativeCentral> provider = Bukkit.getServicesManager().getRegistration(CreativeCentral.class);
if (provider != null) {
 CreativeCentral central = provider.getProvider();
 // ...
}
</code></pre>
Using the static service provider
<pre><code class="hljs language-java">CreativeCentral central = CreativeCentralProvider.get();
</code></pre>
Now that we have a <code>CreativeCentral</code> instance, we can get to the next step

Developer API Introduction

<h2>Developer API Usage</h2>
Now that we have a <code>CreativeCentral</code> instance, we can use it to subscribe to
events, fire the resource-pack generate event, etc.
<h3>Adding resources to the server resource-pack</h3>
You can add your own resources to the server resource-pack by subscribing
to the <code>ResourcePackGenerateEvent</code>, which is called when the server is
loading or when the <code>/central reload</code> command is executed.
<pre><code class="hljs language-java">CreativeCentral central = ...;

central.eventBus().listen(plugin, ResourcePackGenerateEvent.class, event -> {
 ResourcePack resourcePack = event.resourcePack();
 
 // now we do the most important part, adding our own resources to
 // the resource-pack, imagine that we want to add a texture, we
 // would do the following:
 
 // here we create the texture for the minecraft note block
 Texture texture = Texture.builder()
 .key(Key.key("minecraft:block/note_block.png"))
 .data(Writable.file(new File("path/to/texture.png"))
 .build();
 
 // here we register the texture
 resourcePack.texture(texture);
});
</code></pre>
For more information, check the <a href="/docs/creative/central/getting-started">creative API</a>

Developer API Usage

<h2>Commands</h2>
<code>creative-central</code> only has the necessary commands to administrate server's resource-pack
and to apply it to players. The commands are:
<h3>Command <code>/central help</code></h3>
Permission: <code>creative-central.command.help</code> (Default for everyone)
Or just <code>/central</code>, sends a list of all commands to the player. Similar
to this page.
<h3>Command <code>/central reload</code></h3>
Permission: <code>creative-central.command.reload</code> (Default for operators)
Reloads the plugin's configuration, regenerates and exports the server
resource-pack, and sends it to all players connected to the server.
<h3>Command <code>/central apply [target]</code></h3>
Permissions:
<ul>
<li><code>creative-central.command.apply</code> (Default for everyone, but won't let them apply the resource-pack for others)</li>
<li><code>creative-central.command.apply.others</code> (Default for operators)</li>
</ul>
Applies the server resource-pack to the given player (Specified in the [target]
argument) or to the player who executed the command if no target is specified.
As the <code>[target]</code> argument, you can use a player's name or <code>@a</code> to apply the resource-pack
to all players connected to the server.

Commands

<h2>Creative Central</h2>
Welcome to the <code>creative-central</code> documentation, creative-central is a plugin
that unifies the server's resource-pack, allowing other plugins to
programmatically add resources to the server's resource-pack
<code>creative-central</code> allows administrators to use multiple plugins that
use resource-packs without generating conflicts
<h3>I don't understand yet...</h3>
Do you know <a href="https://github.com/MilkBowl/Vault">Vault</a>? Vault provides an API to
unify the server's permissions, chat and economy, imagine a plugin that could do
this, but for resource-packs, that's <code>creative-central</code>!
<h3>Features</h3>
<ul>
<li>Add resources from your manually created resource-pack</li>
<li>Automatically generate the server's resource-pack</li>
<li>Automatically upload the resource-pack to a server or host it locally</li>
<li>Automatically send the resource-pack to everyone</li>
<li>Plug &#x26; play!</li>
<li>Say goodbye to bloated resource-packs! With <code>creative-central</code>, you can even have an empty resource-pack!</li>
<li>..and all the benefits from <a href="https://unnamed.team/docs/creative">creative</a></li>
<li>
<ul>
<li>Validate and compress your resource-pack</li>
</ul>
</li>
<li>
<ul>
<li><code>adventure</code> support!</li>
</ul>
</li>
</ul>

Creative Central

Central

<h2>Hello World</h2>
Let's create a simple and empty resource-pack using <code>creative-api</code>
and <code>creative-serializer-minecraft</code>
<pre><code class="hljs language-java">ResourcePack resourcePack = ResourcePack.create();

// Here we specify the resource-pack format (12) and description (Hello world!)
resourcePack.packMeta(12, "Hello world!");

// Then we write the resource-pack to a folder
MinecraftResourcePackWriter.minecraft()
 .writeToDirectory(new File("folder"), resourcePack);
</code></pre>
The code above writes the resource-pack to a folder named 'folder', its content
will be the following:
<pre><code class="hljs language-lua">folder/
 |------- pack.mcmeta
</code></pre>
Where <code>pack.mcmeta</code> file has the following content (but minimized):
<pre><code class="hljs language-json">{
 "pack": {
 "pack_format": 12,
 "description": "Hello world!"
 }
}
</code></pre>

Hello World

Examples

<h2>Fonts</h2>
Minecraft supports adding and modifying fonts. We can do a lot of
customization using this, such as:
<ul>
<li>Adding emojis to the Minecraft chat (And our plugin <a href="https://github.com/unnamed/emojis">µŋemojis</a>
is an example)</li>
<li>Creating custom inventories</li>
<li>And more...!</li>
</ul>
<h3>Font Providers</h3>
Font providers are the base components of a complete font, a font
may complete multiple font providers. Font providers can be: a bitmap
font provider, legacy unicode font provider, true type font provider
<h3>BitMap Font Provider</h3>
This type of font provider requires a bitmap (PNG) texture
(see <a href="/docs/creative/textures">Textures</a>), ascent (vertical offset for
the glyphs) and characters to use for this font
<pre><code class="hljs language-java">Texture texture = ...;

FontProvider provider = FontProvider.bitMap()
 .file(texture.key())
 .ascent(7)
 .characters(
 "abcdef",
 "012345",
 "6789ñá"
 )
 .build();
</code></pre>
TODO: add the other font providers
<h3>Putting all together</h3>
To finally create a <code>Font</code>, we just merge all the font
providers and assign a key
<pre><code class="hljs language-java">Font font = Font.of(
 Key.key("namespace", "my_font"),
 fontProvider1,
 fontProvider2,
 ...
);
</code></pre>
<h3>Using a font</h3>
Using Adventure, you could use:
<pre><code class="hljs language-java">Font font = MyFonts.MY_SPECIAL_FONT;

player.sendMessage(
 text()
 .content("Hello world")
 .font(font.key())
);
</code></pre>

Fonts

<h2>Getting Started</h2>
Welcome to the <code>creative</code> documentation
<code>creative</code> is a resource-pack library for vanilla Minecraft: Java
Edition, it is not dependent on the server implementation (It doesn't
matter if you use Spigot, Paper, Waterfall, BungeeCord, Velocity, etc.)
See this example of the <code>creative</code> API:
<pre><code class="hljs language-java">ResourcePack resourcePack = ResourcePack.create();
 
// Required to have a valid resource pack
resourcePack.packMeta(9, "Description!");

// adding the resource pack icon
resourcePack.icon(Writable.file(new File("my-icon.png")));

// adding a texture
resourcePack.texture(texture);

// adding a non special file
resourcePack.unknownFile("credits.txt", Writable.stringUtf8("Unnamed Team"));

// now we have a resource pack ready to be exported/written
// as a ZIP file or as a file tree (you need the 'creative-serializer-minecraft'
// dependency for this class)
MinecraftResourcePackWriter.minecraft().writeToZipFile(
 new File("my-resource-pack.zip"),
 resourcePack
);
</code></pre>
<h3>Features</h3>
<ul>
<li>Create, verify and serve resource-packs programmatically</li>
<li>Create the most compact resource-packs, everything is reduced if it is possible</li>
<li><code>creative</code> uses &#x26; supports <a href="https://github.com/KyoriPowered/adventure">Kyori's adventure</a></li>
<li>...More things are possible, you just have to discover them</li>
</ul>
See <a href="https://github.com/unnamed/hephaestus-engine">hephaestus-engine</a>, this
is an example of what can be done with creative
If you prefer to learn with examples you can see the <a href="/docs/creative/examples/hello-world">Examples section</a>

<h2>Installation</h2>
You can add <code>creative-api</code> to your project using <a href="https://gradle.org/">Gradle</a>
(recommended), <a href="https://maven.apache.org/">Maven</a> or manually downloading the
JAR files
<h3>Gradle</h3>
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
<pre><code class="hljs language-kotlin">dependencies {
 implementation("team.unnamed:creative-api:0.7.1-SNAPSHOT")
 
 // Serializer for Minecraft format (ZIP / Folder)
 implementation("team.unnamed:creative-serializer-minecraft:0.7.1-SNAPSHOT")
 
 // Resource Pack server
 implementation("team.unnamed:creative-server:0.7.1-SNAPSHOT")
}
</code></pre>
<h3>Maven</h3>
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>creative-api&#x3C;/artifactId>
 &#x3C;version>0.7.1-SNAPSHOT&#x3C;/version>
&#x3C;/dependency>
</code></pre>

<h2>Language</h2>
Using a resource-pack, you can add or modify language translations.
A creative language representation is very simple, it is just a
keyed map of translations, e.g.
<pre><code class="hljs language-java">Language language = Language.of(
 Key.key("minecraft", "en_US"),
 Map.of(
 // translation key // translation
 "gui.yes", "Yes please",
 "gui.no", "No!",
 "gui.proceed", "Do it!"
 )
);
</code></pre>
Then you can add the language using <code>ResourcePack#language(Language)</code>

Language

<h2>Putting it all together</h2>
Now we can build the resource-pack!
<pre><code class="hljs language-java">ResourcePack resourcePack = ResourcePack.create();

// Required to have a valid resource pack
resourcePack.packMeta(9, "Description!");

// adding the resource pack icon
resourcePack.icon(Writable.file(...)); // Use any type of Writable
 
// adding a font
resourcePack.font(font);

// adding a texture
resourcePack.texture(texture);

// adding a non special file
resourcePack.unknownFile("credits.txt", Writable.stringUtf8("Unnamed Team"));

// now we have a resource pack ready to be exported/written
// as a ZIP file or as a file tree (you need the 'creative-serializer-minecraft'
// dependency for this class)
MinecraftResourcePackWriter.minecraft().writeToZipFile(
 new File("my-resource-pack.zip"),
 resourcePack
);
</code></pre>

Putting it all together

<h2>Creative Server</h2>
Welcome to the <code>creative-server</code> documentation, creative-server is a fast,
lightweight and specialized HTTP(s) server for Minecraft: Java Edition
resource-packs
<h3>Features</h3>
The server parses the information that the vanilla Minecraft client sends when
it requests a resource-pack, so we can:
<ul>
<li>Return a different resource-pack depending on the player (this implies:
language, version, client name, etc.)</li>
<li>Ignore or block non-minecraft clients (like browsers)</li>
</ul>

Creative Server

<h2>Download Request</h2>
From our Minecraft server we must ask the player to download our
resource-pack, this is platform-dependent, but it commonly takes
the resource-pack server address and the resource-pack SHA-1 hash
(which can be taken from <code>BuiltResourcePack#hash()</code>)
<pre><code class="hljs language-java">BuiltResourcePack pack = ...;

String hash = pack.hash();

// The resource-pack path, can be empty, but due to a bug
// on the Minecraft client, the hashes are not correctly
// checked, and it will fail to update
String path = hash + ".zip";

// just an example! replace this by your server's
// public address for production
// HTTP is required if you did not configure HTTPS
String url = "http://127.0.0.1:7270/" + path;
</code></pre>
<h3>Paper</h3>
On <a href="https://papermc.io/">Paper</a> we can use the <code>Player#setResourcePack</code>
method:
<pre><code class="hljs language-java">player.setResourcePack(url, hash /*, prompt, force */);
</code></pre>
<h3>Minestom</h3>
On <a href="https://minestom.net/">Minestom</a> we can use the <code>Player#setResourcePack</code>
method:
<pre><code class="hljs language-java">// forced(...) or optional(...)
player.setResourcePack(ResourcePack.forced(url, hash /*, prompt */));
</code></pre>

Download Request

<h2>Handling Requests</h2>
As we said in <a href="/docs/creative/server/start-stop">Start and Stop</a>, when constructing a resource-pack
server, we can set either a <code>handler</code> or a <code>pack</code>, see how this works:
When setting a resource-pack to the server, it creates a default handler that will
always return it no matter the resource-pack request information
We can replace this behavior by specifying a custom resource-pack request handler
<pre><code class="hljs language-java">ResourcePackServer server = ResourcePackServer.builder()
 .address("127.0.0.1", 7270)
 .handler(handler) // &#x3C;-- Here, see below
 // ...
 .build();
</code></pre>
<h3>Handler</h3>
A handler is a <code>ResourcePackRequestHandler</code> implementation, it receives a
parsed <code>ResourcePackRequest</code> which contains the player uuid, username, client
version, and pack format. It also receives an <code>HttpExchange</code> used to set
the response information
Example:
<pre><code class="hljs language-java">BuiltResourcePack pack8 = MinecraftResourcePackWriter.minecraft().build(this::createPack8);
BuiltResorucePack pack9 = MinecraftResourcePackWriter.minecraft().build(this::createPack9);

ResourcePackRequestHandler handler = (request, exchange) -> {
 // available methods:
 // - request.uuid()
 // - request.username()
 // - request.clientVersion()
 // - request.clientVersionId()
 // - request.packFormat()
 
 int expectedPackFormat = request.packFormat();
 BuiltResourcePack pack;
 
 if (expectedPackFormat == 9) {
 pack = pack9;
 } else if (expectedPackFormat == 8) {
 pack = pack8;
 } else {
 // no pack with this format :(
 byte[] response = "No pack for u".getBytes(StandardCharsets.UTF_8);
 exchange.sendResponseHeaders(400, response.length);
 try (OutputStream responseStream = exchange.getResponseBody()) {
 responseStream.write(response);
 }
 return;
 }

 // write our resource pack
 byte[] data = pack.bytes();
 exchange.getResponseHeaders().set("Content-Type", "application/zip");
 exchange.sendResponseHeaders(200, data.length);
 try (OutputStream responseStream = exchange.getResponseBody()) {
 responseStream.write(data);
 }
};
</code></pre>
<h3>Invalid Requests</h3>
Invalid requests are those that do not have the information that the
vanilla Minecraft client sends, we can handle them by overriding the
<code>onInvalidRequest</code> method
In the example above we did not override the <code>onInvalidRequest</code> method,
so the behavior is defaulted (a 'Please use a Minecraft client' message
is shown)
<pre><code class="hljs language-java">ResourcePackRequestHandler handler = new ResourcePackRequestHandler() {
 
 @Override
 public void onRequest(ResourcePackRequest request, HttpExchange exchange) throws IOException {
 // handle valid request
 }
 
 @Override
 public void onInvalidRequest(HttpExchange exchange) throws IOException {
 // handle invalid request
 // we can return resource-packs here too!
 // we just do not have the 'request' information available
 }
 
};
</code></pre>

Handling Requests

<h2>Installation</h2>
You can add <code>creative-server</code> to your project using <a href="https://gradle.org/">Gradle</a>
(recommended), <a href="https://maven.apache.org/">Maven</a> or manually downloading the
JAR files
<h3>Gradle</h3>
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
<pre><code class="hljs language-kotlin">dependencies {
 implementation("team.unnamed:creative-server:0.7.1-SNAPSHOT")
}
</code></pre>
<h3>Maven</h3>
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>creative-server&#x3C;/artifactId>
 &#x3C;version>0.7.1-SNAPSHOT&#x3C;/version>
&#x3C;/dependency>
</code></pre>

<h2>Start and Stop</h2>
Before everything, we must build a resource-pack server, during this
phase we can set some settings like the server address, server port,
handler path, SSL/TLS for HTTPS, etc.
Example:
<pre><code class="hljs language-java">ResourcePackServer server = ResourcePackServer.builder()
 .address("127.0.0.1", 7270) // (required) address and port
 .pack(ResourcePack) // (required) pack to serve
 .secure(...) // (optional) SSL/TLS configuration
 .path("/get/") // (optional) handler path, default = "/"
 .build();
</code></pre>
Note:
<ul>
<li>This will not automatically start the server</li>
<li><code>pack(...)</code> can be replaced by <code>handler(...)</code>, see
<a href="/docs/creative/server/handle-request">Handling Requests</a></li>
</ul>
<h3>Start</h3>
After we built the resource-pack server we can start it, so it starts
listening for requests
Note: This method is not blocking, so it is not necessary to invoke
it in a different thread, the internal HttpServer already starts it in a
background thread, see <a href="https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpServer.html#start--">HttpServer#start</a>
<pre><code class="hljs language-java">server.start(); // NOT BLOCKING!
</code></pre>
<h3>Stop</h3>
We stop the server using the <code>stop(int)</code> method, it asks for an integer value,
which specifies the maximum time in seconds to wait until requests have finished
Note: Waiting for the requests is a blocking operation if the maximum time
is greater than zero
<pre><code class="hljs language-java">server.stop(0); // BLOCKING IF NOT ZERO!
</code></pre>

Start and Stop

Server

<h2>Sounds</h2>
Create a sound using the creative's <code>Sound</code> class
<pre><code class="hljs language-java">// where "key" points to an OGG audio file
Key key = Key.key("namespace", "brrr");

Sound sound = Sound.builder()
 .nameSound(key)
 .volume(2.0f)
 .pitch(2.0f)
 .attenuationDistance(10)
 .build();
</code></pre>
Then assign it to a <code>SoundEvent</code>
<pre><code class="hljs language-java">SoundEvent soundEvent = SoundEvent.builder()
 .key(Key.key("namespace", "my_sound"))
 .sounds(List.of(sound1, sound2, ...))
 .build();
</code></pre>
<h3>Playing a custom sound</h3>
Using adventure, you could use
<pre><code class="hljs language-java">SoundEvent soundEvent = ...;

player.playSound(Sound.sound(soundEvent.key(), Sound.Source.AMBIENT, 1f, 1.1f));
</code></pre>
See <a href="https://docs.adventure.kyori.net/sound.html">their documentation</a>

Sounds

<h2>Textures</h2>
A texture requires: a <code>Key</code> (identifier), and the actual
texture PNG data, which can be passed using the <code>Writable</code> API,
e.g.
<pre><code class="hljs language-java">Texture texture = Texture.builder()
 .key(Key.key("namespace", "my_texture.png"))
 .data(Writable.file(new File("exampleTexture.png")))
 .build();
</code></pre>
A texture is also meta-datable, this means you can add some
specific metadata sections to it, e.g. animating a texture
<pre><code class="hljs language-java">Texture texture = Texture.builder()
 .key(Key.key("namespace", "my_texture.png"))
 .data(Writable.file(new File("exampleTexture.png")))
 .meta(
 Metadata.builder()
 .add(AnimationMeta.builder().height(16).build())
 .build()
 )
 .build();
</code></pre>
Then you can add the texture using <code>ResourcePack#texture(Texture)</code>

Textures

creative

Render, animate and interact with custom entity models in Minecraft: Java Edition servers

<h2>Generating the Resource Pack</h2>
Hephaestus-engine uses <a href="https://github.com/unnamed/creative">creative</a> to
interact with resource pack data, we convert a <code>Model</code> and its bones to
creative's block models
See <a href="https://github.com/unnamed/creative/">creative documentation</a> for
resource-pack hosting/serving
<h3>Writing to a resource pack ZIP</h3>
<pre><code class="hljs language-java">Collection&#x3C;Model> models = ...;

File file = new File("resource-pack.zip");
file.createNewFile();

try (FileTree tree = FileTree.zip(new ZipOutputStream(new FileOutputStream(file)))) {
 ModelWriter.resource("mynamespace").write(tree, models);
 
 // you can write your own assets here!
 // check https://github.com/unnamed/creative
}
</code></pre>
<h3>Writing to a directory</h3>
<pre><code class="hljs language-java">Collection&#x3C;Model> models = ...;

File directory = new File("resource-pack");
directory.mkdirs();

try (FileTree tree = FileTree.directory(directory)) {
 ModelWriter.resource("mynamespace").write(tree, models);
 
 // you can write your own assets here!
 // check https://github.com/unnamed/creative
}
</code></pre>
<h3>Removing unused information</h3>
After we generate the resource pack, some loaded information will be unnecessary,
to solve this, we can use <code>Model#discardResourcePackData()</code>, it removes data
like textures, elements, etc. but makes the model unable to be written to a
resource pack (writer will throw an exception)

Generating the Resource Pack

<h2>Getting Started</h2>
Welcome to the <code>hephaestus-engine</code> documentation.
Hephaestus-engine is a custom model creation, animation and interaction library
for Minecraft: Java Edition, you can use it in multiple platforms like Spigot,
<a href="https://papermc.io/">Paper</a> and <a href="https://minestom.net/">Minestom</a>
Note that hephaestus-engine is a work in progress, we are looking for
contributors.
<h3>Features</h3>
<ul>
<li>Automatic and extensible resource-pack generation using <a href="https://github.com/unnamed/creative">creative</a></li>
<li>Flexible model animation support, lets you handle how to animate the models:
asynchronously in a single thread, asynchronously in multiple threads, etc</li>
<li><a href="https://blockbench.net/">Blockbench</a> model loading (loads the model itself,
its textures and animations)</li>
</ul>
<img src="https://github.com/unnamed/hephaestus-engine/raw/main//.github/redstone-monstrosity.png" alt="Redstone Monstrosity Model">
Yes, this is vanilla Minecraft

<h2>Installation</h2>
You can add hephaestus-engine to your project using <a href="https://gradle.org/">Gradle</a>
(recommended), <a href="https://maven.apache.org/">Maven</a> or manually downloading the
JAR files
<h3>Gradle</h3>
Add our repository
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
Add the necessary dependencies
<pre><code class="hljs language-kotlin">dependencies {
 // Core API, necessary for everything
 implementation("team.unnamed:hephaestus-api:0.1.0-SNAPSHOT")
 
 // Blockbench model reader (optional)
 implementation("team.unnamed:hephaestus-reader-blockbench:0.1.0-SNAPSHOT")
 
 // Bukkit runtime projects (you might want to add :reobf classifier to adapt-v1_18_R2)
 implementation("team.unnamed:hephaestus-runtime-bukkit-api:0.1.0-SNAPSHOT")
 implementation("team.unnamed:hephaestus-runtime-bukkit-adapt-v1_18_R2:0.1.0-SNAPSHOT")
 
 // Minestom runtime
 implementation("team.unnamed:hephaestus-runtime-minestom:0.1.0-SNAPSHOT")
}
</code></pre>
<h3>Maven</h3>
Add our repository
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
Add the necessary dependencies
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>hephaestus-api&#x3C;/artifactId>
 &#x3C;version>0.1.0-SNAPSHOT&#x3C;/version>
&#x3C;/dependency>
</code></pre>

<h2>Model Limitations</h2>
Using the vanilla Minecraft client, we have the following
limitations when creating models:
<ul>
<li>Bone cubes cannot be larger than <code>128x128x128</code> units,
where <code>16</code> units are equal to the size of a Minecraft block</li>
<li>Bone cube rotations can only be <code>-45º</code>, <code>-22.5º</code>, <code>0º</code>,
<code>22.5º</code> or <code>45º</code>, however, this does not apply to bone
rotations</li>
</ul>

Model Limitations

<h2>Model Reading</h2>
To create a <code>Model</code> instance, we provide the concept of <code>ModelReader</code>and
some built-in implementations like the <code>bbmodel</code> reader, which reads models
from the <a href="https://blockbench.net/">Blockbench</a> <code>bbmodel</code> format
Every model reader instance has a <code>ModelDataCursor</code> instance used to assign
a <code>custom_model_data</code> property to every model bones. A single instance of
<code>ModelDataCursor</code> should always be used for a resource pack, thus maintaining
unique <code>custom_model_data</code> properties for each bone
<h3>BBModel Reader</h3>
Create a <code>ModelReader</code> for Blockbench models
<pre><code class="hljs language-java">ModelReader reader = BBModelReader.blockbench();
</code></pre>
Create a <code>ModelReader</code> for Blockbench models, using an assigned <code>ModelDataCursor</code>
<pre><code class="hljs language-java">ModelDataCursor modelDataCursor = new ModelDataCursor(0);
ModelReader reader = BBModelReader.blockbench(modelDataCursor);
</code></pre>
<h3>Examples</h3>
Reading a Blockbench model from a file
<pre><code class="hljs language-java">ModelReader reader = BBModelReader.blockbench(new ModelDataCursor(0));
Model model = reader.read(new File("model.bbmodel"));

// do something with 'model'
</code></pre>

Model Reading

<h2>Model Views</h2>
<code>api</code> defines an interface <code>BaseModelView</code>, which can be used for basic
and platform independent operations such as animations, colors, movements,
animation ticking, etc.
To get a more specialized model view, you can use the platform specific
implementations
<h3>Creating Views</h3>
Creating a model view depends on the platform
<h4>Bukkit</h4>
TODO!
<h4>Minestom</h4>
To use hephaestus-engine in Minestom, you will have to include the Runtime
Minestom subproject <code>hephaestus-runtime-minestom</code>
<pre><code class="hljs language-java">Model model = ...;
ModelEntity view = MinestomModelEngine.minestom().createViewAndTrack(
 model,
 instance, // Instance
 position // Pos
);
</code></pre>
<h3>Coloring</h3>
Model views can be colored with any RGB color, just use <code>BaseModelView#colorize</code>
or <code>BaseBoneView#colorize</code> to colorize a specific bone
Example:
<pre><code class="hljs language-java">public void setRedColor(BaseModelView&#x3C;?> view) {
 view.colorize(255, 0, 0); 
}
</code></pre>
<h3>Animation</h3>
You can animate views by just using <code>AnimationController#queue</code>, stop
animations using <code>AnimationController#clearQueue</code>
Example:
<pre><code class="hljs language-java">public void animate(BaseModelView&#x3C;?> view) {
 // walkAnimation is a ModelAnimation instance that can
 // be obtained from Model#animations()
 view.animationController().queue(walkAnimation);
}
</code></pre>

Model Views

hephaestus-engine

A fast and very lightweight dependency injection library for Java 8+

<h2>Basic Usage</h2>
So now we know what the <code>@Inject</code> does:
<ul>
<li>In a field: declares that the field is a dependency that must be set</li>
<li>In constructors and methods: declares that the parameters are dependencies that must be provided</li>
</ul>
<h3>Declaration</h3>
Using the <code>@Inject</code> annotation we can declare dependencies, e.g.
<pre><code class="hljs language-java">public class ItemDao {
 
 @Inject private Database database;
 @Inject private Configuration configuration;
 
 // ...
 
}
</code></pre>
However, the declaration does nothing, we must process it
<h3>Processing</h3>
When you declare a dependency on some class, like <code>@Inject private Database database</code>,
the dependency is processed when the class is processed, so it is not necessary to manually
process them all.
As we said, the dependencies of an object will be processed together with it, but, we need to
manually process an initial object, the entry point
To do this, we must create an <code>Injector</code> and optionally configure it (we will explain this later)
<pre><code class="hljs language-java">public class Main {
 
 @Inject private Server server;
 
 public void start() {
 server.start();
 }
 
 public static void main(String[] args) {
 Injector injector = Injector.create();
 // here we manually tell the injector to instantiate
 // our Main class that declares a dependency on the
 // Server class, our Injector is smart and will instantiate
 // and set it too
 Main main = injector.getInstance(Main.class);
 main.start();
 
 // We can alternatively do:
 Main main = new Main();
 injector.injectMembers(main);
 main.start();
 // however, the Injector does not know about the Main
 // constructor, and it will not process it so injections
 // there will not work. It will just inject fields and methods
 }
 
}
</code></pre>
In this case, the injector will instantiate both <code>Main</code> and <code>Server</code>
using the default constructor, but what if we need more? what if Server
is an interface? how do we bind the interface to an implementation?
See <a href="/docs/inject/config/injector-configuration">Injector Configuration</a>

Basic Usage

<h2>Dependency Injection</h2>
Dependency injection (<a href="https://en.wikipedia.org/wiki/Dependency_injection">Wikipedia</a>) is an
OOP design pattern where classes declare their dependencies as arguments instead of directly
creating them.
This pattern lets us easily create flexible and testable objects, following the
<a href="https://en.wikipedia.org/wiki/Liskov_substitution_principle">Liskov Substitution Principle</a>
<h3>Without Dependency Injection</h3>
Here is an example where we do not use dependency injection:
<pre><code class="hljs language-java">public class UserDao {
 
 private final Database database = new SQLiteDatabase("/myfile.dat");
 
 // ...
 
}
</code></pre>
In this example, you can't replace the database implementation or file path, which
makes it hard to test and re-use
<h3>With Dependency Injection</h3>
Here is an example where we do use dependency injection:
<pre><code class="hljs language-java">public class UserDao {
 
 private final Database database;
 
 public FileReader(Database database) {
 this.database = database;
 }
 
 // ...
 
}
</code></pre>
In this example, we can set any database implementation, so it is testable
and re-usable
<h3>With unnamed/inject</h3>
Here is an example that uses dependency injection with <code>unnamed/inject</code>
<pre><code class="hljs language-java">import team.unnamed.inject.Inject;

public class UserDao {
 
 @Inject private Database database;
 
}
</code></pre>
In this example, we just declare a dependency using the <code>@Inject</code> annotation
instead of as an argument in a constructor. However, the <code>@Inject</code> annotation is
not magic and this will not work using <code>new UserDao()</code> since the object is
not processed.

Dependency Injection

<h2>Getting Started</h2>
Welcome to the <code>inject</code> documentation
<code>unnamed/inject</code> is a zero-dependency, lightweight and fast runtime dependency
injection library for Java 8+
<h3>Features</h3>
<ul>
<li>Known and easy to use DSL (domain specific language) to configure bindings</li>
<li>Potentially increase your programming productivity, you don't have to worry
about manually injecting dependencies</li>
<li>Out of the box support for features like multibinding and assisted inject</li>
</ul>

<h2>Installation</h2>
You can add <code>inject</code> to your project using <a href="https://gradle.org/">Gradle</a> (recommended),
<a href="https://maven.apache.org/">Maven</a> or manually downloading the JAR files
<h3>Gradle</h3>
Add our repository
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
Add the dependency
<pre><code class="hljs language-kotlin">dependencies {
 implementation("team.unnamed:inject:2.0.0")
}
</code></pre>
<h3>Maven</h3>
Add our repository
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
Add the dependency
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>inject&#x3C;/artifactId>
 &#x3C;version>2.0.0&#x3C;/version>
&#x3C;/dependency>
</code></pre>

inject

Simple, flexible and helpful library to handle messages with internationalization support for Java 8+

<h2>Convenience Methods</h2>
There are many methods for ease the message handling in the <code>MessageHandler</code> interface.
<h3>Obtaining messages</h3>
Methods for obtaining messages (not sending)
<h4>MessageHandler#get</h4>
<pre><code class="hljs language-java">String message = messageHandler.get(entity, messagePath, /* optional, varargs */ jitEntities);
</code></pre>
where <code>message</code> is the obtained message, <code>entity</code> is the used entity for placeholders and
language specification (it can be an entity that will be resolved to another entity, <code>messagePath</code>
is the message location in a file, commonly separating by dots <code>.</code> for internal sections
(depending on <code>NodeFile</code>) and <code>jitEntities</code> are the just-in-time entities, used to replace
placeholders only in that method call.
For example:
<pre><code class="hljs language-java">MailList userMailList = mails.getRecentMails(user);
String message = messageHandler.get(user, "message.welcome", userMailList);
</code></pre>
where <code>userMailList</code> is a Just-In-Time entity, and it will call a <code>PlaceholderProvider</code> registered
for type <code>MailList</code> and identifier specified in the message at <code>message.welcome</code> message
<h4>MessageHandler#replacing</h4>
<pre><code class="hljs language-java">String message = messageHandler.replacing(entity, messagePath, /* var-args */ replacementPack);
</code></pre>
Same as above, but replaces literal strings specified in code. Where <code>replacementPack</code> is a
var-args array of <code>Object</code>. It's a pair array of <code>String</code> and <code>Object</code>. I mean, you must add
a <code>String</code> and then an <code>Object</code>, and so on. Elements in even indexes are replaced by the elements
in odd indexes in the message. It's util for just-in-time replacements that aren't necessary
entities.
See this example in a 'command' using a command manager with parametric commands support
(like <a href="https://github.com/unnamed/command-flow/">command-flow</a>)
<pre><code class="hljs language-java">// command: setmoney &#x3C;money>
@Command(name = "setmoney")
void setMoney(@Sender User user, int money) {
 String message = messageHandler.replacing(
 user, "message.updated-money",
 "{{added}}", money,
 "{{total}}", user.getBalance() + money
 );
 // send the message
}
</code></pre>
<h3>Sending messages</h3>
Sending has a similar definition. They have the prefix <code>send</code> and then <code>replacing</code> (or not, if no
replacements are required), they also accept a string <code>mode</code> when the method name ends with <code>in</code>.
For example: <code>messageHandler.sendIn(target, "message.path", "title-mode");</code>

Convenience Methods

<h2>Getting Started</h2>
Welcome to the <code>nmessage</code> documentation.
<code>nmessage</code> is a simple, flexible and helpful library to handle messages with
internationalization support for multiple platforms like Bukkit (Minecraft)
<h3>Features</h3>
<ul>
<li>Use any message source (file, database, JAR file resources, etc.)</li>
<li>VERY helpful, just use <code>handler.send(receiver, "message.node")</code> and let
nmessage do the translation, sending and formatting job</li>
</ul>

<h2>Installation</h2>
You can add nmessage to your project using <a href="https://gradle.org/">Gradle</a>
(recommended), <a href="https://maven.apache.org/">Maven</a> or manually downloading
the JAR files
<h3>Gradle</h3>
Add our repository
<pre><code class="hljs language-kotlin">repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}
</code></pre>
Add the necessary dependencies
<pre><code class="hljs language-kotlin">dependencies {
 // Core API, necessary for everything
 implementation("me.yushust.message:core:7.1.3")
 
 // .PROPERTIES source type
 implementation("me.yushust.message:sourcetype-properties:7.1.3")
 
 // .JSON source type
 implementation("me.yushust.message:sourcetype-gson-json:7.1.3")
 
 // Bukkit YAML source type and helpers
 implementation("me.yushust.message:sourcetype-bukkit-yml:7.1.3")
 
 // BungeeCord YAML source type and helpers
 implementation("me.yushust.message:sourcetype-bungee-yml:7.1.3")
}
</code></pre>
<h3>Maven</h3>
Add our repository
<pre><code class="hljs language-xml">&#x3C;repository>
 &#x3C;id>unnamed-public&#x3C;/id>
 &#x3C;url>https://repo.unnamed.team/repository/unnamed-public/&#x3C;/url>
&#x3C;/repository>
</code></pre>
Add the necessary dependencies
<pre><code class="hljs language-xml">&#x3C;!-- Core API, necessary for everything -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>core&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- .PROPERTIES source type -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-properties&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- .JSON source type -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-gson-json&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- Bukkit YAML source type and helpers -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-bukkit-yml&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>

&#x3C;!-- BungeeCord YAML source type and helpers -->
&#x3C;dependency>
 &#x3C;groupId>me.yushust.message&#x3C;/groupId>
 &#x3C;artifactId>sourcetype-bungee-yml&#x3C;/artifactId>
 &#x3C;version>7.1.3&#x3C;/version>
&#x3C;/dependency>
</code></pre>

<h2>Linguist</h2>
It is responsible for obtaining the language of a specific entity
<h3>Definition</h3>
<pre><code class="hljs language-java">public interface Linguist&#x3C;E> {
 @Nullable
 String getLanguage(E entity);
}
</code></pre>
You must implement the interface and set it to the <code>MessageHandler</code> to use it.
If the <code>getLanguage</code> method returns null, the default language is used.
<h3>Implementation</h3>
This is an example of an imaginary class 'User'
<pre><code class="hljs language-java">public class UserLinguist implements Linguist&#x3C;User> {
 @Override
 @Nullable
 public String getLanguage(User entity) {
 // get the language of "entity" and return it
 }
}
</code></pre>
<h3>Configuring</h3>
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {

 // using setLinguist(Linguist)
 config.specify(User.class)
 .setLinguist(new UserLinguist());

 // you can specify multiple linguist for
 // specific entity types
 config.specify(SomeOtherEntity.class)
 .setLinguist(new SomeOtherEntityLinguist());

 // you can also use lambda method references for this
 config.specify(ExampleUsingLambdaEntity.class)
 .setLinguist(ExampleUsingLambdaEntity::getLanguage);
 }
);
</code></pre>

Linguist

<h1>Message Sender</h1>
It sends messages to a specific entity according to a mode
<h3>Definition</h3>
<pre><code class="hljs language-java">public interface MessageSender&#x3C;E> {
 
 default void send(E receiver, String mode, StringList messages) {
 send(receiver, mode, messages.join("\n"));
 }
 
 void send(E receiver, String mode, String message);

}
</code></pre>
The method provides the <code>receiver</code> (the entity that must receive the given <code>message</code>),
the <code>mode</code> (how to send the message, this will be explained later), and the sent <code>message</code>.
<h3>Implementation</h3>
<pre><code class="hljs language-java">public class UserMessageSender implements MessageSender&#x3C;User> {
 @Override
 public void send(User receiver, String mode, String message) {
 // you can also add "outputs" (ex. window message, console message, etc)
 switch (mode) {
 case "info":
 receiver.send(message);
 break;
 case "warn":
 receiver.warn(message);
 break;
 case "severe":
 receiver.severe(message);
 break;
 }
 }
}
</code></pre>
<h3>Configuring</h3>
Set the <code>Messenger</code> for a specific type while constructing <code>MessageHandler</code>
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {
 // set the message sender
 config.specify(User.class)
 .setMessageSender(new UserMessageSender())
 // it's a fluent API, you can also set the linguist here
 .setLinguist(new UserLinguist());
 }
);
</code></pre>

Message Sender

<h2>Placeholder Providers</h2>
It's responsible for getting a value using a specific 'variable' in messages
For example, if we set <code>{receiver_name}</code> in a message, we can replace it with
the receiver name using a <code>PlaceholderProvider</code>.
In that variable, the parts are identifier (<code>receiver</code>) and the parameters
(<code>name</code>), they are delimited by <code>_</code>. And we resolve that implementing a
<code>PlaceholderProvider</code>
<h3>Definition</h3>
<code>PlaceholderProvider</code> is
<pre><code class="hljs language-java">public interface PlaceholderProvider&#x3C;E> {
 
 @Nullable
 Object replace(ContextRepository ctx, E entity, String parameters);
 
}
</code></pre>
where 'E' is the used entity type. In the above example, we can use a named
class that can receive a message, for example, an <code>User</code>.
<h3>Implementing</h3>
Implementing the placeholder provider for the above example:
<pre><code class="hljs language-java">public class UserPlaceholderProvider implements PlaceholderProvider&#x3C;User> {

 @Override
 @Nullable
 public Object replace(ContextRepository ctx, User entity, String param) {
 switch (param.toLowerCase()) {
 case "name": {
 return entity.getName();
 }
 case "age": {
 return entity.getAge();
 }
 case "another_property": {
 return entity.getAnotherProperty();
 }
 default: return null; // null indicates an invalid parameter
 }
 }

}
</code></pre>
The method return type is <code>Object</code> for convenience. You can return numbers, strings,
booleans and they are converted to a string using <code>Object#toString</code>. Null indicates
that an invalid parameter was provided and the placeholder isn't replaced.
<h3>Registration</h3>
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {
 config.specify(User.class)
 .addProvider("user", new UserPlaceholderProvider())
 .addProvider("idk", new SomeOtherProvider());
 }
);
</code></pre>

Placeholder Providers

<h2>Placeholders</h2>
We can specify placeholder delimiters while creating the <code>MessageHandler</code>. Default
delimiters are <code>%</code> for start, and <code>%</code> for end (same characters)
<pre><code class="hljs language-java">MessageHandler handler = MessageHandler.of(
 source,
 config -> {
 // format is: "{{identifier_parameter}}"
 config.delimiting(
 "{{", // start
 "}}" // end
 );
 }
);
</code></pre>

Let's imagine, let's createWe are Unnamed Team