Maintenance script: UtilityBiome wiki

2026-10-19T07:06:58Z

UtilityBiome wiki

New page

The <code>tools</code> packages generate Hytale world-generation files (biomes, caves, ores, resources, spawns) from Java code and check every reference before a file reaches a server. They run in your Gradle build and tests, never in the game, and contain no Hytale imports. Gson comes from the server jar.

Generated files only refer to vanilla and your own files. A mod that uses nothing else from Utility Biome does not need it at runtime, see [[UtilityBiome:Modding API#Build time only|Modding API]].

== Gradle plugin ==
The plugin <code>utilitybiome.content</code> wires everything up. It is included through the submodule (see [[UtilityBiome:Modding API|Modding API]]).
<pre>
// build.gradle.kts
plugins { id("utilitybiome.content") }

utilityBiome {
prefix = "MyMod_" // every generated file and ID carries it
content = "com.example.mymod.content.MyModContent" // your ContentPack
}
</pre>

{| class="wikitable"
! Setting !! Default !! Meaning
|-
| <code>prefix</code> || required for <code>validateAssets</code> || Mod prefix with underscore, for example <code>BetterBiomes_</code>.
|-
| <code>content</code> || required for generation || Fully qualified <code>ContentPack</code> class in the <code>biomes</code> source set.
|-
| <code>resources</code> || <code>src/main/resources</code> || Where files are generated to and what is validated.
|-
| <code>devResources</code> || <code>src/dev/resources</code> || Files only for the dev server, never in the jar.
|-
| <code>vanillaIndex</code> || <code>modules/utilitybiome/vanilla-index/<server_version>.txt</code> || Vanilla index for the validator.
|-
| <code>dependencyPacks</code> || Utility Biome's own pack in the submodule || Asset packs your files may refer to.
|}

The plugin adds the source set <code>biomes</code> (<code>src/biomes/java</code>). It sees the server API and Utility Biome and is never packed into the jar. The tasks:
{| class="wikitable"
! Task !! Does
|-
| <code>generateBiomes</code> || Writes the files of your <code>ContentPack</code> into <code>resources</code>. Check them in.
|-
| <code>checkGeneratedAssets</code> || Fails if the checked-in files differ from what the content generates (hand edits or a Hytale update). Part of <code>check</code>. Skipped when <code>Assets.zip</code> is not available, for example in CI.
|-
| <code>validateAssets</code> || Runs the asset validator over your packs. Part of <code>check</code>.
|-
| <code>devAssetPack</code> || Zips <code>resources</code> and <code>devResources</code> for the dev server. <code>runServer</code> depends on it.
|-
| <code>freshWorld</code> || Deletes the dev world <code>run/universe/worlds/default</code> but keeps its seed. With <code>-PnewSeed</code> the seed goes too.
|}
Generation reads vanilla files from your local Hytale installation. Set <code>hytaleHomeOverride</code> in <code>~/.gradle/gradle.properties</code> to the Hytale home folder.

== ContentPack and Mod ==
A <code>ContentPack</code> (package <code>tools.content</code>) returns everything your mod generates. It needs a public constructor without parameters.
<pre>
public final class MyModContent implements ContentPack {
private static final Mod MOD = Mod.of("MyMod");

@Override
public List<GeneratedAsset> assets(VanillaAssets vanilla) {
List<GeneratedAsset> out = new ArrayList<>();
out.addAll(OreSpec.named("MyMod_Tin")
.rarity(Rarity.UNCOMMON).vein(VeinShape.MEDIUM).heights(20, 90)
.zone("Zone1", "MyMod_Ore_Tin_Stone")
.zone("Zone3", "MyMod_Ore_Tin_Shale")
.build());
out.add(BiomeSpec.tile("Zone1_Tier1", MOD.id("Birch_Glade"),
vanilla.biome("Zone1_Tier1", "Tile.Forest_Birch"))
.covers(c -> c.remove(Select.placing("Plant_Flower_*"))));
return out;
}
}
</pre>

<code>Mod</code> builds names, seeds and paths from one place, so no name without the prefix slips through. The mod name may not contain <code>_</code>, <code>-</code> or <code>.</code>.
<pre>
Mod mod = Mod.of("FrostMod");
mod.id("Ice_Forest") // FrostMod_Ice_Forest
mod.seed("Icicles") // FrostMod-Icicles
mod.path("PrefabPatterns", "Ice") // Zones.FrostMod.PrefabPatterns.Ice
Mod.file(mod.path("PrefabPatterns", "Ice")) // Server/World/Default/Zones/FrostMod/PrefabPatterns/Ice.json
</pre>
Never rename a seed afterwards: a changed seed moves things in existing worlds.

<code>VanillaAssets</code> reads vanilla files from <code>Assets.zip</code>: <code>biome(zone, fileName)</code> for a biome, <code>file(path)</code> for any JSON file and <code>files(prefix)</code> to list JSON files under a path.

== Biomes ==
Package <code>tools.biome</code>. Hytale has no inheritance between biomes, so <code>BiomeSpec</code> copies a vanilla biome and changes it step by step. What you do not touch (relief, water, environment, monuments) stays as in the original, so the biome behaves like its model at the edges.
<pre>
BiomeSpec.tile("Zone1_Tier1", "MyMod_Forest_Dead", vanilla.biome("Zone1_Tier1", "Tile.Forest_Birch"))
.replaceBlocks(Map.of("Soil_Grass", "Soil_Grass_Dry"))
.covers(c -> c.remove(Select.placing("Plant_Flower_*")))
.mapColor("#8f8456");
</pre>
{| class="wikitable"
! Method !! Purpose
|-
| <code>tile(zone, name, source)</code> || A main biome of the zone (<code>Tile.<name>.json</code>), spread by weight.
|-
| <code>custom(zone, name, source)</code> || A biome placed on top of others (<code>Custom.<name>.json</code>). Needs <code>customGenerator</code>.
|-
| <code>customGenerator(noiseMask, priority, biomes...)</code> || Where a Custom biome appears: inside which biomes, at which spots, and above which other Custom biomes.
|-
| <code>replaceBlocks(map)</code> || Swaps blocks in covers and layers, all at once (no chains).
|-
| <code>covers(edit)</code>, <code>layers(group, edit)</code>, <code>prefabs(edit)</code> || Edit lists of entries with <code>EntryList</code>.
|-
| <code>monumentsOf(source)</code> || Takes the monuments (dungeons, outposts) of another biome.
|-
| <code>environmentOf(source)</code> || Takes the environment (enemies, weather) of another biome.
|-
| <code>tint(edit)</code>, <code>mapColor(hex)</code>, <code>weight(n)</code>, <code>comment(text)</code> || Tint, map colour, weight (Tile only), comment.
|-
| <code>set(path, value)</code> || Anything else, by JSON path.
|}

Helpers:
* <code>Select.placing(globs)</code>, <code>Select.placingOnly(globs)</code>, <code>Select.pattern(globs)</code> pick entries by content instead of position. A selection that matches nothing stops generation, since it is almost always a typo or a changed vanilla file.
* <code>EntryList</code>: <code>edit</code>, <code>remove</code>, <code>keep</code>, <code>clear</code>, <code>add</code>, <code>insertAfter</code>.
* <code>Cover</code> and <code>PrefabEntry</code> build new cover and prefab entries.
* <code>Palettes.DRY_GRASSLAND</code> is a ready-made block swap for dry grassland.
* <code>RegionGrid</code> lays a cell grid for large Custom biomes. Its <code>allocator()</code> hands out shares of the cells, so biomes on the same grid never overlap. <code>natural()</code> or <code>Warp</code> distort the round areas into natural shapes.
* <code>VanillaTiers</code> and <code>VanillaPriorities</code> hold vanilla facts per zone and tier and the priorities of vanilla's Custom biomes.

Every generated file carries a <code>$Comment</code> that names its source. Do not edit generated files by hand.

Utility Biome's own pack contains one shared noise, <code>Zones.UtilityBiome.Noise.Tint.Forest_Patchy</code>, a patchy tint noise for forests. Mods that refer to it need Utility Biome at runtime.

== Caves ==
Package <code>tools.cave</code>. <code>CaveSpec</code> describes a cave for several tiers and produces the nodes, the cave type and one modifier per tier.
<pre>
CaveSpec hollow = CaveSpec.of(mod, "Frozen_Hollow")
.inTiers(CaveTier.ZONE3_TIER1, CaveTier.ZONE3_TIER2)
.entryTo("Chamber")
.node("Chamber", "Ice chamber", tier -> """
{"Type": "ELLIPSOID", "RadiusX": [8, 12], "RadiusY": [5, 7], "RadiusZ": [8, 12]}""")
.type("Frozen cave", tier -> """
"EntryPoints": {"Seed": "%s", "Density": [0, 0.3], "Scale": 0.005, "Jitter": 0.5},
"FixedEntryHeight": [70, 90], "Pitch": 90""".formatted(mod.seed("Frozen-Hollow")));
List<GeneratedAsset> assets = CaveSpec.build(mod, List.of(hollow));
</pre>
* <code>entryTo(child)</code> creates a safe, empty entry node. The entry node must never be an <code>ELLIPSOID</code>: that crashes chunk generation and kicks players. The validator checks this.
* <code>CaveTier</code> has constants for every tier with its cave environment, for example <code>ZONE1_TIER1</code> with <code>Env_Zone1_Caves_Plains</code>.
* <code>CaveKit</code> is the lower-level version with the default block and prefab masks.

== Ores ==
Package <code>tools.ore</code>. <code>OreSpec</code> creates an ore the way vanilla does: per zone a vein node, a placement and a modifier that adds it to all tiers of the zone.
<pre>
List<GeneratedAsset> tin = OreSpec.named("MyMod_Tin")
.rarity(Rarity.UNCOMMON)
.vein(VeinShape.MEDIUM)
.heights(20, 90)
.zone("Zone1", "MyMod_Ore_Tin_Stone")
.zone("Zone3", "MyMod_Ore_Tin_Shale")
.build();
</pre>
{| class="wikitable"
! Rarity !! Like in vanilla !! About
|-
| <code>COMMON</code> || copper in zone 1 || 40 veins per chunk
|-
| <code>UNCOMMON</code> || iron in zone 1 || 10 per chunk
|-
| <code>RARE</code> || cobalt || 2–3 per chunk
|-
| <code>EPIC</code> || gold || one per 4 chunks
|-
| <code>LEGENDARY</code> || silver || one per 25 chunks
|}
The ore block per zone should match the rock of that zone and must exist as a block, either in vanilla or in your own assets. Vein shapes: <code>SMALL</code> (a lump like silver), <code>MEDIUM</code> (core with optional casing like iron, see <code>casing(block)</code>), <code>LARGE</code> (mostly thin veins, rarely a large one, very rarely a motherlode, like copper). Defaults: <code>UNCOMMON</code>, <code>MEDIUM</code>, heights 20–100. <code>hostRock(blocks...)</code> changes which blocks the ore may replace. Because the steps come from vanilla, an ore "as rare as gold" is equally rare in every mod that uses Utility Biome.

== Resources ==
Package <code>tools.resource</code>. <code>ResourceSpec</code> adds covers (plants, stones) or prefabs (buildings, rocks, skeletons) to existing biomes through a modifier, without touching vanilla files.
<pre>
ResourceSpec.prefabs("MyMod_Watchtowers")
.into("Zones.Zone1_Tier*.Tile.Plains_*")
.prefab("Monuments.Encounter.City_Ruins.Towers.*", 1)
.grid(0.01, 0.05) // cells of ~100 blocks, 5 % of them
.parents("Soil_Grass", "Soil_Grass_Full")
.build();
</pre>
<code>into</code> takes globs on the dotted path of the biome. Further options: <code>fitHeightmap()</code>, <code>submerge()</code>, <code>sink(blocks)</code>, <code>mask(json)</code>. For covers use <code>ResourceSpec.cover(name, coverJson)</code>.

== Spawns ==
Package <code>tools.spawn</code>. <code>SpawnSpec</code> writes a world NPC spawn file. Spawns have no modifiers, a new file is enough, and the prefix keeps it from replacing a vanilla file.
<pre>
SpawnSpec.named("MyMod_Spawns_Forest_Boars")
.environments("Env_Zone1_Forests", "Env_Zone1_Autumn")
.npc("Boar", 10, "Group_Small")
.onBlocks("Soil")
.dayTime(6, 18)
.build();
</pre>
<code>light(min, max)</code> limits the light level (0–100).

== Asset validator ==
<code>AssetValidator</code> (package <code>tools</code>) checks world-generation and modifier files before they reach a server. The task <code>validateAssets</code> runs it, or call it from a JUnit test:
<pre>
AssetValidator.Report report = AssetValidator.forPrefix("MyMod_")
.vanilla(VanillaIndex.load(Path.of("modules/utilitybiome/vanilla-index/0.7.0.txt")))
.pack(Path.of("src/main/resources"))
.dependency(Path.of("modules/utilitybiome/src/main/resources"))
.validate();
assertTrue(report.isOk(), report.format());
</pre>
It reports:
* JSON that cannot be read,
* <code>"File"</code> references that point nowhere (the world would not load),
* prefab globs that match no prefab,
* unknown block, item and environment IDs,
* biome and modifier files without the mod prefix, and files that hide or disable a vanilla file,
* cave types whose entry node is an <code>ELLIPSOID</code>,
* biomes whose tint or environment has a different number of entries than weights, or two or more entries without a noise,
* biome masks that name no Tile biome of the zone,
* modifiers with wrong enum values (a wrong value stops the whole server), no rules or no operations.

<code>VanillaIndex</code> lists everything that exists in vanilla, as one text file per Hytale version (<code>vanilla-index/<version>.txt</code>). References can then be checked without <code>Assets.zip</code>, for example in CI, and a Hytale update shows up as a diff.

{{UtilityBiome Nav}}

UtilityBiome:Build-Time Tools - Revision history

Maintenance script: UtilityBiome wiki