Maintenance script: UtilityBiome wiki

2026-10-19T07:06:58Z

UtilityBiome wiki

New page

A '''chunk feature''' is a piece of Java code that Utility Biome runs once on every newly generated chunk whose biome matches. Waterfalls, overhangs, boulders or small ruins can be made this way, things the vanilla world generator cannot produce from its JSON files alone. [[BetterBiomes:Main Page|Better Biomes]] uses chunk features for many of its details, for example <code>betterbiomes:waterfall</code> and <code>betterbiomes:overhang</code>.

All types on this page are in the package <code>com.cyberpiratepenguin.utilitybiome.api</code>.

== Registering a feature ==
Register features in your own <code>setup()</code>. A feature only affects chunks generated after it was registered. Chunks that already exist stay as they are.
<pre>
@Override
protected void setup() {
UtilityBiomeAPI.registerChunkFeature(ChunkFeature.named("mymod:boulders")
.inBiomes("Zone1_Tier*/Tile.Plains_*")
.chance(0.1) // share of matching chunks
.order(10) // lower runs first
.placer((chunk, random) -> {
int x = random.nextInt(ChunkAccess.SIZE);
int z = random.nextInt(ChunkAccess.SIZE);
int y = chunk.height(x, z) + 1;
chunk.setBlock(x, y, z, "Rock_Stone_Cobble");
}));
}
</pre>

{| class="wikitable"
! Setting !! Default !! Meaning
|-
| <code>named(id)</code> || required || Unique ID with your mod's namespace, <code>mod:name</code>. An ID without <code>:</code> is rejected.
|-
| <code>inBiomes(globs...)</code> || all biomes || Globs on the biome at the '''centre''' of the chunk, written as <code>Zone/Tile.Name</code> or <code>Zone/Custom.Name</code>. <code>*</code> matches any number of characters, <code>?</code> exactly one. The glob must match the whole name.
|-
| <code>chance(p)</code> || 1 || Share of matching chunks that get the feature, from 0 to 1.
|-
| <code>order(n)</code> || 0 || Features run in ascending order, ties by ID.
|-
| <code>placer(...)</code> || required || The code that places the feature. Finishes the builder and returns the <code>ChunkFeature</code>.
|}

== What a placer may do ==
A <code>ChunkPlacer</code> gets a <code>ChunkAccess</code> for the new chunk and a random generator.
* '''Only this chunk.''' Local coordinates are 0–31 for x and z and 0–319 for y. Writing outside throws.
* '''Not on the world thread.''' Placers run in parallel for several chunks. Only read and write <code>chunk</code>, and do not change any shared state of your own.
* '''All randomness from <code>random</code>.''' It is derived from the world seed, the feature ID and the chunk position. The same world always gives the same result, which matters because Hytale regenerates chunks that were never saved.
* '''All or nothing.''' Writes are collected and only applied when the placer returns. If it throws, nothing of it is applied, a warning goes to the server log, and the chunk loads normally. Other features still run.

=== ChunkAccess ===
{| class="wikitable"
! Method !! Purpose
|-
| <code>chunkX()</code>, <code>chunkZ()</code> || Chunk position. Block x = <code>chunkX * 32 + x</code>.
|-
| <code>height(x, z)</code> || Highest non-transparent block of the column. Leaves count.
|-
| <code>block(x, y, z)</code> || Block key without rotation, <code>"Empty"</code> for air.
|-
| <code>isSolid(x, y, z)</code> || Whether the block is solid.
|-
| <code>fluid(x, y, z)</code> || Fluid key, or <code>null</code>.
|-
| <code>biome(x, z)</code> || Zone and biome of the column, as a <code>BiomeSample</code>.
|-
| <code>setBlock(x, y, z, key)</code> || Sets a block. Keys are written as in the assets, with rotation if needed: <code>"Rock_Stone"</code>, <code><nowiki>"Rock_Ice_Icicles|Pitch=180"</nowiki></code>.
|-
| <code>setFluid(x, y, z, key)</code> || Sets a fluid at full level, for example <code>"Water_Source"</code>.
|}
Constants: <code>ChunkAccess.SIZE</code> = 32, <code>ChunkAccess.HEIGHT</code> = 320.

Notes:
* Fluids live in their own layer next to the blocks. The block at that spot must be air or non-solid, otherwise the water disappears. Water set by a feature flows when the chunk loads.
* Inside a placer, <code>block</code> and <code>fluid</code> already see your own writes. <code>height</code> and <code>isSolid</code> show the state before your placer ran.
* In 1.0.0, blocks placed by a chunk feature get no block entity. A chest placed this way has no storage, and crops do not grow. See [[UtilityBiome:Version History|Version History]].

For boxes, spheres, building sites and terrain checks, see [[UtilityBiome:Structures|Structures]].

== Checking features in the game ==
* <code>/ub features</code> lists all registered features, their chance, their biomes and how often each was placed since the server started.
* <code>/ub feature <id></code> teleports you to a spot where the feature was placed.
* Every placement is written to the server log with its position and number of changes. Every 30 seconds at most, a summary line shows how many chunks were generated, how many features were placed or failed and the slowest time per chunk.
See [[UtilityBiome:Commands|Commands]].

=== Test features ===
For developing Utility Biome itself, the environment variable <code>UTILITYBIOME_TEST_FEATURES</code> (any value) registers two test features at start:
* <code>ub:test_pillar</code>: in 5 % of chunks, a white crystal pillar in the middle of the chunk with a water source on top.
* <code>ub:test_broken</code>: throws on purpose in 2 % of chunks, to check that nothing is applied and a warning is logged.
Never set it on a server people play on.

{{UtilityBiome Nav}}

UtilityBiome:Chunk Features - Revision history

Maintenance script: UtilityBiome wiki