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

Getting Started

<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>

Installation

<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>