A creative plugin that allows Minecraft servers to show the face of players in the chat, scoreboard, tab, signs, items and everywhere you can write text!

<h2>Developer API Introduction</h2>
<h3>Adding faces to your project</h3>
The first step to using <code>creative-faces</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 faces 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-faces:2.0.1")
}
</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-faces:2.0.1"
}
</code></pre>
<h4>Maven</h4>
If you are using Maven, you have to add our repository and the faces 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-faces&#x3C;/artifactId>
 &#x3C;version>2.0.1&#x3C;/version>
 &#x3C;scope>provided&#x3C;/scope>
 &#x3C;/dependency>
&#x3C;/dependencies>
</code></pre>
<h3>Declaring a dependency on faces</h3>
If you are developing a plugin that uses <code>creative-faces</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-faces</code> is not present
plugin.yml in Bukkit plugins
<pre><code class="hljs language-yaml">name: ...
main: ...
version: ...
...
depend: [creative-faces]
</code></pre>
<h3>Accessing the API</h3>
First of all, you need to obtain an instance of <code>FaceProvider</code>, you can do this by using
your platform's service provider
Using Bukkit's service provider
<pre><code class="hljs language-java">RegisteredServiceProvider&#x3C;FaceProvider> provider = Bukkit.getServicesManager().getRegistration(FaceProvider.class);
if (provider != null) {
 FaceProvider faceProvider = provider.getProvider();
 // ...
}
</code></pre>
Now that we have a <code>FaceProvider</code> instance, we can get to the next step

Developer API Introduction

<h2>Developer API Usage</h2>
Now that we have a <code>FaceProvider</code> instance, we can use it to get the faces of any
player.
Note that faces are represented by <code>PlayerFaceComponent</code> instances, they implement
<code>ComponentLike</code> so you can just use <code>asComponent()</code> to convert them to components.
<h3><code>FaceProvider</code> Methods</h3>
<pre><code class="hljs language-java">FaceProvider provider = ...;

PlayerFaceComponent face = provider.get(Player);
// (this is the one you will use the most)
// this method obtains the face from cache, fetches
// it if it is not cached yet, or returns a default
// minecraft head (like Alex head or Steve head)

@Nullable PlayerFaceComponent face = provider.getOrFind(Player);
// this method is similar to the previous one, but returns
// null if the player doesn't have a skin, instead of returning
// a default one

@Nullable PlayerFaceComponent face = provider.getCached(Player);
// this method is similar to the previous ones too, but only
// finds the head in cache, and returns null if it is not present

@Nullable PlayerFaceComponent face = provider.fetch(Player);
// this method fetches the player face, doesn't check for heads
// in cache. Returns null if the face couldn't be found
</code></pre>
<h3><code>PlayerFaceComponent</code></h3>
The <code>PlayerFaceComponent</code> instances are components containing the player's
face. So you can use it just like a component! You can even explicitly convert
it to a component using <code>asComponent()</code> method.
<pre><code class="hljs language-java">PlayerFaceComponent face = ...;
Component component = face.asComponent();

// sends the face to a player via chat
player.sendMessage(component);

// shows the face to a player via action bar
player.sendActionBar(component);

// you can also concatenate components and send them
player.sendMessage(
 Component.text()
 .append(Component.text("Hey this is your face: "))
 .append(face)
 .build()
);
</code></pre>
You can also serialize/deserialize <code>PlayerFaceComponent</code> instances so you can
store them and use them later
<pre><code class="hljs language-java">PlayerFaceComponent face = ...;
int[][] data = face.pixels(); // &#x3C;-- Here we obtain the important data

// Now we can just convert the face pixels to Base64
String serialized = Faces.pixelsToBase64(data);

// Then we can deserialize them
int[][] deserializedData = Faces.base64ToPixels(serialized);

// And convert the pixels to a face component using the FaceProvider
PlayerFaceComponent deserializedFace = faceProvider.fromPixels(deserializedData);
</code></pre>
And that's it! Happy coding!

Developer API Usage

<h2>creative-faces</h2>
Welcome to the <code>creative-faces</code> documentation, creative-faces is a plugin
to allow Minecraft servers to show the face of a player in the chat. <code>creative-faces</code>
uses <a href="https://unnamed.team/docs/creative">creative</a>, the library for resource-packs, and
<a href="https://unnamed.team/docs/creative-central">creative-central</a>, the plugin that unifies resource-packs
<code>creative-faces</code> supports multiple placeholder systems like <a href="https://github.com/MiniPlaceholders/MiniPlaceholders">MiniPlaceholders</a>
and <a href="https://github.com/PlaceholderAPI/PlaceholderAPI">PlaceholderAPI</a>
<img src="https://github.com/unnamed/creative-faces/raw/main//.github/screenshot.png" alt="Screenshot">
<h3>Features</h3>
<ul>
<li>Add faces to the chat, signs, anvils, items, guis, everywhere!</li>
<li>Uses <code>creative-central</code> so you have all its features:</li>
<li>
<ul>
<li>Automatically generates the server's resource-pack</li>
</ul>
</li>
<li>
<ul>
<li>Automatically upload the resource-pack to a server or host it locally</li>
</ul>
</li>
<li>
<ul>
<li>Automatically send the resource-pack to everyone</li>
</ul>
</li>
<li>Easy to use</li>
<li>
<ul>
<li>If you use PlaceholderAPI, just use <code>%faces_face%</code> to show the player's head</li>
</ul>
</li>
<li>
<ul>
<li>If you use MiniPlaceholders, just use <code>&#x3C;faces_face></code></li>
</ul>
</li>
<li>Developers API</li>
</ul>

creative-faces

<h2>Usage</h2>
<code>creative-faces</code> cannot be used by itself, you must use a supported placeholder
system like <a href="https://github.com/MiniPlaceholders/MiniPlaceholders">MiniPlaceholders</a>
or <a href="https://github.com/PlaceholderAPI/PlaceholderAPI">PlaceholderAPI</a>. You can also use
the developers API.
How to use:
<ul>
<li>Download <code>creative-central</code>, <code>creative-faces</code> and your favorite placeholders plugin</li>
<li>Use the <code>%faces_face%</code> placeholder anywhere</li>
<li>Done!</li>
</ul>
<h3>Configuration</h3>
In the <code>config.yml</code> file you can set:
<ul>
<li>The characters you want to use for the plugin.</li>
<li>The font</li>
<li>The namespace</li>
</ul>
Everything is configurable!
<h3>Commands</h3>
There is only one command: <code>/faces</code>. It reloads the plugin configuration and
re-generates the resource-pack. The permission to use this command is <code>creativefaces.reload</code>

Usage

<h2>Developer API Introduction</h2>
<h3>Adding faces to your project</h3>
The first step to using <code>creative-faces</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 faces 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-faces:2.0.0")
}
</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-faces:2.0.0"
}
</code></pre>
<h4>Maven</h4>
If you are using Maven, you have to add our repository and the faces 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-faces&#x3C;/artifactId>
 &#x3C;version>2.0.0&#x3C;/version>
 &#x3C;scope>provided&#x3C;/scope>
 &#x3C;/dependency>
&#x3C;/dependencies>
</code></pre>
<h3>Declaring a dependency on faces</h3>
If you are developing a plugin that uses <code>creative-faces</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-faces</code> is not present
plugin.yml in Bukkit plugins
<pre><code class="hljs language-yaml">name: ...
main: ...
version: ...
...
depend: [creative-faces]
</code></pre>
<h3>Accessing the API</h3>
First of all, you need to obtain an instance of <code>FaceProvider</code>, you can do this by using
your platform's service provider
Using Bukkit's service provider
<pre><code class="hljs language-java">RegisteredServiceProvider&#x3C;FaceProvider> provider = Bukkit.getServicesManager().getRegistration(FaceProvider.class);
if (provider != null) {
 FaceProvider faceProvider = provider.getProvider();
 // ...
}
</code></pre>
Now that we have a <code>FaceProvider</code> instance, we can get to the next step

<h2>Developer API Usage</h2>
Now that we have a <code>FaceProvider</code> instance, we can use it to get the faces of any
player.
Note that faces are represented by <code>PlayerFaceComponent</code> instances, they implement
<code>ComponentLike</code> so you can just use <code>asComponent()</code> to convert them to components.
<h3><code>FaceProvider</code> Methods</h3>
<pre><code class="hljs language-java">FaceProvider provider = ...;

PlayerFaceComponent face = provider.get(Player);
// (this is the one you will use the most)
// this method obtains the face from cache, fetches
// it if it is not cached yet, or returns a default
// minecraft head (like Alex head or Steve head)

@Nullable PlayerFaceComponent face = provider.getOrFind(Player);
// this method is similar to the previous one, but returns
// null if the player doesn't have a skin, instead of returning
// a default one

@Nullable PlayerFaceComponent face = provider.getCached(Player);
// this method is similar to the previous ones too, but only
// finds the head in cache, and returns null if it is not present

@Nullable PlayerFaceComponent face = provider.fetch(Player);
// this method fetches the player face, doesn't check for heads
// in cache. Returns null if the face couldn't be found
</code></pre>
<h3><code>PlayerFaceComponent</code></h3>
The <code>PlayerFaceComponent</code> instances are components containing the player's
face. So you can use it just like a component! You can even explicitly convert
it to a component using <code>asComponent()</code> method.
<pre><code class="hljs language-java">PlayerFaceComponent face = ...;
Component component = face.asComponent();

// sends the face to a player via chat
player.sendMessage(component);

// shows the face to a player via action bar
player.sendActionBar(component);

// you can also concatenate components and send them
player.sendMessage(
 Component.text()
 .append(Component.text("Hey this is your face: "))
 .append(face)
 .build()
);
</code></pre>
You can also serialize/deserialize <code>PlayerFaceComponent</code> instances so you can
store them and use them later
<pre><code class="hljs language-java">PlayerFaceComponent face = ...;
int[][] data = face.pixels(); // &#x3C;-- Here we obtain the important data

// Now we can just convert the face pixels to Base64
String serialized = Faces.pixelsToBase64(data);

// Then we can deserialize them
int[][] deserializedData = Faces.base64ToPixels(serialized);

// And convert the pixels to a face component using the FaceProvider
PlayerFaceComponent deserializedFace = faceProvider.fromPixels(deserializedData);
</code></pre>
And that's it!