Maintenance script: UtilityBiome wiki

2026-10-19T07:06:59Z

UtilityBiome wiki

New page

The package <code>com.cyberpiratepenguin.utilitybiome.api.structure</code> places small buildings and shapes with [[UtilityBiome:Chunk Features|chunk features]], without writing a placer from scratch.

* '''<code>Blueprint</code>''': a building described as text.
* '''<code>StructureFeature</code>''': turns a blueprint into a chunk feature. Finding a site, rotation and foundation are handled for you.
* '''<code>Structures</code>''', '''<code>Shapes</code>''', '''<code>Terrain</code>''': 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 <code>ResourceSpec.prefabs</code> on [[UtilityBiome:Build-Time Tools|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''' <code>.</code> sets air, for example to clear the inside of a hut.
<pre>
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();
</pre>
* <code>width()</code>, <code>height()</code>, <code>depth()</code>: size in x, y and z.
* <code>cells()</code>: all blocks with their position relative to the corner (0, 0, 0).
* <code>rotated(quarterTurns)</code>: 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 <code>Yaw=90</code>) is not turned with them.
* A character that is not in the palette, or a blueprint without layers, throws when you call <code>build()</code>.

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

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

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

== Structures ==
The steps above, for use in your own placer:
{| class="wikitable"
! Method !! Purpose
|-
| <code>findFlatSite(chunk, width, depth, maxSlope, margin, avoidBuildings, random)</code> || A random suitable site (as <code>Site(x, y, z)</code>, y = ground height), or empty.
|-
| <code>fits(blueprint, x, y, z)</code> || Whether the blueprint fits into the chunk at that corner.
|-
| <code>place(chunk, blueprint, x, y, z, airOnly)</code> || Places the blueprint. Throws if it does not fit, which in a chunk feature means nothing is applied.
|-
| <code>naturalFoundation(chunk, blueprint, x, y, z)</code> || Foundation from the ground block of each column.
|-
| <code>foundation(chunk, blueprint, x, y, z, block)</code> || Foundation from a given block.
|}

== Shapes ==
Basic shapes in chunk coordinates. Parts outside the chunk are skipped. With <code>airOnly</code> only air is replaced. Each method returns the number of blocks set.
{| class="wikitable"
! Method !! Shape
|-
| <code>box(chunk, x0, y0, z0, x1, y1, z1, block, airOnly)</code> || Solid box, corners included.
|-
| <code>hollowBox(chunk, x0, y0, z0, x1, y1, z1, block)</code> || Walls, floor and ceiling of <code>block</code>, air inside.
|-
| <code>ellipsoid(chunk, cx, cy, cz, rx, ry, rz, block, airOnly)</code> || Ellipsoid around a centre.
|-
| <code>cylinder(chunk, cx, y0, cz, y1, radius, block, airOnly)</code> || Upright cylinder.
|-
| <code>foundation(chunk, x, fromY, z, block)</code> || Fills downwards until the first solid block, at most 24 blocks.
|-
| <code>clearPlantAbove(chunk, x, y, z)</code> || Removes a plant, grass or bush above a block, so it does not float after digging.
|-
| <code>inside(x, y, z)</code> || 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.
{| class="wikitable"
! Method !! Purpose
|-
| <code>isNatural(block)</code> || Rock (except crystals) or soil, and nothing built.
|-
| <code>isBuilt(block)</code> || The block name contains a part such as Brick, Cobble, Plank, Stairs, Roof, Fence, Lantern, Chest, Furniture and similar.
|-
| <code>isSettlementBiome(name)</code> || The biome name contains Village, Town, City, Cities, Camp or Outpost.
|-
| <code>ground(chunk, x, z)</code> || Highest natural ground block of the column. Leaves, plants and built blocks do not count.
|-
| <code>nearBuilding(chunk, minX, minY, minZ, maxX, maxY, maxZ)</code> || 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.

{{UtilityBiome Nav}}

UtilityBiome:Structures - Revision history

Maintenance script: UtilityBiome wiki