Maintenance script: UtilityBiome wiki

2026-10-19T07:06:59Z

UtilityBiome wiki

New page

Utility Biome is meant to be built on. It has three parts:
{| class="wikitable"
! Part !! Package !! Runs !! What it does
|-
| Runtime API || <code>api</code>, <code>api.structure</code> || in the game || [[UtilityBiome:Chunk Features|Chunk features]] (your code on newly generated chunks), [[UtilityBiome:Structures|structures]] from text blueprints, biome lookup
|-
| Build-time tools || <code>tools.*</code> || in your Gradle build and tests || Generate biome, cave, ore, resource and spawn files from vanilla and check all references. See [[UtilityBiome:Build-Time Tools|Build-Time Tools]].
|-
| Gradle plugin || <code>utilitybiome.content</code> || in your Gradle build || Tasks <code>generateBiomes</code>, <code>checkGeneratedAssets</code>, <code>validateAssets</code>, <code>devAssetPack</code>, <code>freshWorld</code>
|}
All packages live under <code>com.cyberpiratepenguin.utilitybiome</code>.

== Contract ==
* <code>api</code> and <code>tools</code> are the public contract. Never import from <code>internal</code>, it can change in any release.
* <code>UtilityBiomeAPI.API_VERSION</code> names the version of the contract. In 1.0.0 it is <code>0.6.0-Alpha</code>.
* <code>tools</code> has no Hytale imports, so it runs in plain JUnit and in CI.

== Adding the dependency ==
Utility Biome is used as a Git submodule and a Gradle composite build:
<pre>
git submodule add https://github.com/Fxbixn03/UtilityBiome.git modules/utilitybiome
</pre>

<code>settings.gradle.kts</code>:
<pre>
pluginManagement {
if (file("modules/utilitybiome/gradle-plugin/settings.gradle.kts").exists()) {
includeBuild("modules/utilitybiome/gradle-plugin")
}
}
includeBuild("modules/utilitybiome") {
dependencySubstitution {
substitute(module("com.cyberpiratepenguin:utilitybiome")).using(project(":"))
}
}
</pre>

<code>gradle.properties</code> (in a project based on the same mod template, this creates both the Gradle dependency and the manifest dependency):
<pre>
utility_dependencies = com.cyberpiratepenguin:utilitybiome:1.0.0
</pre>

Two rules matter:
* Add Utility Biome as a '''dependency in your manifest'''. The server then finishes Utility Biome's <code>setup()</code> before yours runs.
* Use <code>vineImplementation</code>, '''never''' <code>implementation</code>. Utility Biome is a plugin itself. With <code>implementation</code> its classes are loaded twice, and its registries are silently empty.

=== Build time only ===
A mod that only generates content (ores, resources, spawns, biomes) and never calls the runtime API does not need Utility Biome in the game. Leave <code>utility_dependencies</code> empty and add the library to the <code>biomes</code> source set only:
<pre>
dependencies {
"biomesImplementation"("com.cyberpiratepenguin:utilitybiome:1.0.0")
}
</pre>
Players then do not need to install Utility Biome. As soon as you register a chunk feature or call <code>UtilityBiomeAPI</code>, switch to the runtime dependency.

== UtilityBiomeAPI ==
The entry point for everything at runtime.
{| class="wikitable"
! Method !! Purpose
|-
| <code>isReady()</code> || <code>true</code> once Utility Biome has run its <code>setup()</code>. If it is <code>false</code> in your own <code>setup()</code>, the manifest dependency is missing or you used <code>implementation</code>.
|-
| <code>runtimeVersion()</code> || The running version of the library, or <code>null</code> while it is not up.
|-
| <code>registerChunkFeature(ChunkFeature)</code> || Registers a chunk feature. Throws if the ID is already taken. See [[UtilityBiome:Chunk Features|Chunk Features]].
|-
| <code>chunkFeatures()</code> || All registered chunk features, in the order they run.
|-
| <code>biomeAt(worldName, x, z)</code> || The biome the world generator produces at a block column, also in chunks that were not generated yet.
|}

<pre>
@Override
protected void setup() {
if (!UtilityBiomeAPI.isReady()) {
getLogger().at(Level.WARNING).log("UtilityBiome is not loaded");
return;
}
// register chunk features here
}
</pre>

=== Biome lookup ===
<code>biomeAt</code> can be called from any thread. Pass <code>null</code> as the world name for the default world. It returns an empty <code>Optional</code> when the world does not exist, has no regular world generator, or the library is not running.
<pre>
Optional<BiomeSample> sample = UtilityBiomeAPI.biomeAt(null, x, z);
sample.ifPresent(s -> {
String zone = s.zone(); // e.g. "Zone1_Tier1"
String biome = s.biome(); // e.g. "Forest_Birch"
boolean custom = s.custom(); // true for a Custom biome
String file = s.fileName(); // "Tile.Forest_Birch"
});
</pre>
<code>BiomeSample.toString()</code> gives <code>Zone/Tile.Name</code> or <code>Zone/Custom.Name</code>, the same form that the commands show and that biome globs match.

Use it for machines, quests or anything else that should only work in certain biomes.

{{UtilityBiome Nav}}

UtilityBiome:Modding API - Revision history

Maintenance script: UtilityBiome wiki