UtilityBiome:Structures

The package com.cyberpiratepenguin.utilitybiome.api.structure places small buildings and shapes with chunk features, without writing a placer from scratch.

• Blueprint: a building described as text.
• StructureFeature: turns a blueprint into a chunk feature. Finding a site, rotation and foundation are handled for you.
• Structures, Shapes, Terrain: the building blocks, for your own placers.

A chunk feature only sees and writes its own chunk (32 × 32 blocks), so a structure has to fit into one chunk. For ready-made prefab files placed as rare structures through world-generation files, use ResourceSpec.prefabs on Build-Time Tools.

Blueprint

A blueprint is a stack of layers, bottom layer first. Each layer is a list of rows along z, each character in a row is one block along x, looked up in the palette.

• A space leaves the existing block unchanged.
• A dot . sets air, for example to clear the inside of a hut.

Blueprint hut = Blueprint.builder()
        .palette('W', "Wood_Softwood_Planks")
        .palette('R', "Wood_Softwood_Roof")
        .layer("WWW", "W.W", "WWW")
        .layer("WWW", "W.W", "W W")
        .layer("RRR", "RRR", "RRR")
        .build();

• width(), height(), depth(): size in x, y and z.
• cells(): all blocks with their position relative to the corner (0, 0, 0).
• rotated(quarterTurns): rotated by 90° steps clockwise (seen from above), corner back at (0, 0). In 1.0.0 only the positions turn. A rotation in the block key (such as Yaw=90) is not turned with them.
• A character that is not in the palette, or a blueprint without layers, throws when you call build().

StructureFeature

UtilityBiomeAPI.registerChunkFeature(
        StructureFeature.of("mymod:hut", hut)
                .inBiomes("Zone1_Tier2/Tile.Plains_*")
                .chance(0.02)
                .foundation("Rock_Stone_Cobble")
                .build());

Setting	Default	Meaning
inBiomes(globs...)	all biomes	Same globs as for chunk features.
chance(p)	0.05	Share of matching chunks that try to place the structure.
order(n)	10	Run order among all chunk features.
maxSlope(blocks)	2	Largest height difference allowed on the site.
margin(blocks)	3	Distance to the chunk border and to anything built.
sink(blocks)	0	How deep the structure is set into the ground.
noRotation()	rotate	Turns off the random rotation.
allowNearBuildings()	avoid	Also allow sites in or next to built things, for example for additions to ruins.
airOnly()	off	Only place blocks into air, so the terrain stays (half-buried ruins).
foundation(block)	natural	Fills below the bottom layer down to the ground with this block.

What happens in each chunk:

1. The blueprint is rotated at random (unless noRotation()).
2. A flat site is searched: natural ground, no water, the slope within maxSlope, margin blocks away from the chunk border and, unless allowed, from anything built or a settlement biome. If there is none, nothing is placed.
3. The blueprint is placed on the highest ground block of the site, lowered by sink.
4. Below the bottom layer a foundation is filled down to the ground, at most 24 blocks: with the foundation block if set, otherwise with the natural ground block of each column (grass becomes dirt). With sink above 0 and no foundation block, no foundation is added.

Structures

The steps above, for use in your own placer:

Method	Purpose
findFlatSite(chunk, width, depth, maxSlope, margin, avoidBuildings, random)	A random suitable site (as Site(x, y, z), y = ground height), or empty.
fits(blueprint, x, y, z)	Whether the blueprint fits into the chunk at that corner.
place(chunk, blueprint, x, y, z, airOnly)	Places the blueprint. Throws if it does not fit, which in a chunk feature means nothing is applied.
naturalFoundation(chunk, blueprint, x, y, z)	Foundation from the ground block of each column.
foundation(chunk, blueprint, x, y, z, block)	Foundation from a given block.

Shapes

Basic shapes in chunk coordinates. Parts outside the chunk are skipped. With airOnly only air is replaced. Each method returns the number of blocks set.

Method	Shape
box(chunk, x0, y0, z0, x1, y1, z1, block, airOnly)	Solid box, corners included.
hollowBox(chunk, x0, y0, z0, x1, y1, z1, block)	Walls, floor and ceiling of block, air inside.
ellipsoid(chunk, cx, cy, cz, rx, ry, rz, block, airOnly)	Ellipsoid around a centre.
cylinder(chunk, cx, y0, cz, y1, radius, block, airOnly)	Upright cylinder.
foundation(chunk, x, fromY, z, block)	Fills downwards until the first solid block, at most 24 blocks.
clearPlantAbove(chunk, x, y, z)	Removes a plant, grass or bush above a block, so it does not float after digging.
inside(x, y, z)	Whether a position lies inside the chunk.

Terrain

Hytale does not remember after generation where prefabs were placed, so Utility Biome recognises built things by their block names.

Method	Purpose
isNatural(block)	Rock (except crystals) or soil, and nothing built.
isBuilt(block)	The block name contains a part such as Brick, Cobble, Plank, Stairs, Roof, Fence, Lantern, Chest, Furniture and similar.
isSettlementBiome(name)	The biome name contains Village, Town, City, Cities, Camp or Outpost.
ground(chunk, x, z)	Highest natural ground block of the column. Leaves, plants and built blocks do not count.
nearBuilding(chunk, minX, minY, minZ, maxX, maxY, maxZ)	Whether anything built stands in the box, or a corner of it lies in a settlement biome.

Built things just across the chunk border cannot be seen, which is why a margin to the border is useful.