UtilityBiome:Chunk Features

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. Better Biomes uses chunk features for many of its details, for example betterbiomes:waterfall and betterbiomes:overhang.

All types on this page are in the package com.cyberpiratepenguin.utilitybiome.api.

Registering a feature

Register features in your own setup(). A feature only affects chunks generated after it was registered. Chunks that already exist stay as they are.

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

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

What a placer may do

A ChunkPlacer gets a ChunkAccess 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 chunk, and do not change any shared state of your own.
• All randomness from random. 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

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

Constants: ChunkAccess.SIZE = 32, ChunkAccess.HEIGHT = 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, block and fluid already see your own writes. height and isSolid 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 Version History.

For boxes, spheres, building sites and terrain checks, see Structures.

Checking features in the game

• /ub features lists all registered features, their chance, their biomes and how often each was placed since the server started.
• /ub feature <id> 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 Commands.

Test features

For developing Utility Biome itself, the environment variable UTILITYBIOME_TEST_FEATURES (any value) registers two test features at start:

• ub:test_pillar: in 5 % of chunks, a white crystal pillar in the middle of the chunk with a water source on top.
• ub:test_broken: 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.