UtilityBiome:Modding API

Utility Biome is meant to be built on. It has three parts:

Part	Package	Runs	What it does
Runtime API	api, api.structure	in the game	Chunk features (your code on newly generated chunks), structures from text blueprints, biome lookup
Build-time tools	tools.*	in your Gradle build and tests	Generate biome, cave, ore, resource and spawn files from vanilla and check all references. See Build-Time Tools.
Gradle plugin	utilitybiome.content	in your Gradle build	Tasks generateBiomes, checkGeneratedAssets, validateAssets, devAssetPack, freshWorld

All packages live under com.cyberpiratepenguin.utilitybiome.

Contract

• api and tools are the public contract. Never import from internal, it can change in any release.
• UtilityBiomeAPI.API_VERSION names the version of the contract. In 1.0.0 it is 0.6.0-Alpha.
• tools 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:

git submodule add https://github.com/Fxbixn03/UtilityBiome.git modules/utilitybiome

settings.gradle.kts:

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(":"))
    }
}

gradle.properties (in a project based on the same mod template, this creates both the Gradle dependency and the manifest dependency):

utility_dependencies = com.cyberpiratepenguin:utilitybiome:1.0.0

Two rules matter:

• Add Utility Biome as a dependency in your manifest. The server then finishes Utility Biome's setup() before yours runs.
• Use vineImplementation, never implementation. Utility Biome is a plugin itself. With implementation 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 utility_dependencies empty and add the library to the biomes source set only:

dependencies {
    "biomesImplementation"("com.cyberpiratepenguin:utilitybiome:1.0.0")
}

Players then do not need to install Utility Biome. As soon as you register a chunk feature or call UtilityBiomeAPI, switch to the runtime dependency.

UtilityBiomeAPI

The entry point for everything at runtime.

Method	Purpose
isReady()	true once Utility Biome has run its setup(). If it is false in your own setup(), the manifest dependency is missing or you used implementation.
runtimeVersion()	The running version of the library, or null while it is not up.
registerChunkFeature(ChunkFeature)	Registers a chunk feature. Throws if the ID is already taken. See Chunk Features.
chunkFeatures()	All registered chunk features, in the order they run.
biomeAt(worldName, x, z)	The biome the world generator produces at a block column, also in chunks that were not generated yet.

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

Biome lookup

biomeAt can be called from any thread. Pass null as the world name for the default world. It returns an empty Optional when the world does not exist, has no regular world generator, or the library is not running.

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"
});

BiomeSample.toString() gives Zone/Tile.Name or Zone/Custom.Name, 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.