JSPrismarine

API reference / @jsprismarine/structures

@jsprismarine/structures ​

The structure template layer: it reads both template formats Mojang ships, translates the Java one into Bedrock block states, places a template under a rotation and a mirror, runs the structure processors over it, and grows a village or a set of trail ruins out of template pools.

Everything it produces is Bedrock-shaped, because that is what the server places.

ts
import {
    assembleJigsaw,
    applyProcessors,
    createLegacyRandom,
    createProcessorList,
    isStructureChunk,
    readJavaStructureTemplate,
    readMcStructure,
    transformTemplate,
    translateJavaTemplate
} from '@jsprismarine/structures';

const { template, losses } = translateJavaTemplate(readJavaStructureTemplate(bytes));
const placed = transformTemplate(template, { rotation: 'clockwise_90', mirror: 'left_right' });

The two formats ​

A Minecraft structure template is NBT, and the two editions disagree about almost every part of it.

Java .nbt. Gzip-compressed, big-endian NBT. The root holds size, a palette of Java block states, a blocks list of {pos, state, nbt?} and an entities list of {pos, blockPos, nbt}. readJavaStructureTemplate reads it, compressed or not.

Two things vary across the corpus. Java 26.3 renamed the palette entry keys from Name and Properties to id and properties; the reader prefers the spelling the file's DataVersion implies and falls back to the other, so a file that disagrees with its own version still reads. The hundred oldest files carry version: 1 and no DataVersion at all, and are read by probing the keys. Twenty files carry palettes, a list of palette variants for the same blocks, which land in paletteVariants.

Bedrock .mcstructure. Uncompressed, little-endian NBT with Bedrock block states. readMcStructure reads it. The format differs in four ways that matter: block indices are a flat array walking x slowest and z fastest rather than a position per block, -1 means "change nothing here", there are two block storage layers rather than one, and entity positions are world coordinates relative to the saved structure_world_origin rather than template coordinates. Each palette entry carries the game version that wrote its state, kept in paletteVersions because the oldest files in the corpus were saved by 1.16.

Both readers produce positions in template space, with the origin corner at (0, 0, 0).

The translation and what it costs ​

translateJavaTemplate maps a Java palette onto Bedrock states through @jsprismarine/mapping and returns a Bedrock-shaped template. It never drops a block quietly: every palette entry that does not map cleanly comes back as a TemplateTranslationLoss with its kind, the Java state and how many blocks of the template use it. Blocks of a lost entry are still placed, as minecraft:unknown where the mapping has no state at all.

Java's waterlogged flag has no Bedrock state to live in, so it moves to Bedrock's second block storage layer as water. That is the one translation that changes the shape rather than the names, and applyWaterlogging: false turns it off.

Measured over the whole shipped corpus, by the gated test in src/corpus.test.ts:

SourceFilesPalette entriesBlocksMappedLost
Java Edition 26.3 server jar15112079111706641170664 (100%)0
Bedrock Dedicated Server 1.26.51.1 zip13111804311377821111645 (97.70%)26137 over 1589 entries

The two rows differ because the Bedrock zip's templates were last saved before Java's 1.13 flattening. Their palettes name 47 identifiers the pinned Java version does not have, among them minecraft:stonebrick with a variant, minecraft:planks, minecraft:log2, minecraft:wool and minecraft:wooden_door.

This package does not carry a 1.12 flattening table, and that is a decision rather than an omission. The plan section 4 sources structures from Java's data generator, and the Java corpus translates with nothing lost at all, so the table would buy nothing the server uses. The Bedrock zip's templates are a cross-check, and their 47 names are reported rather than guessed at. Writing a flattening table is the work to do if those files ever become the source.

Placement transforms ​

transformTemplate(template, { rotation, mirror }) moves the block positions, the entity positions and the direction-valued block states together. The mirror applies before the rotation, as Java does. A quarter turn swaps the template's x and z extents, and positions stay inside the transformed template rather than spreading around a world pivot.

Rotating positions is arithmetic. Rotating states is not, and it is where this would go wrong by hand. Bedrock and Java name their direction axes differently: a Java stair's facing is a Bedrock stair's weirdo_direction integer, a Java log's axis is a Bedrock log's pillar_axis, and a Java door facing north is a Bedrock door whose minecraft:cardinal_direction is east. Java's own rules are also not symmetric. Measured from the pinned server jar, StairBlock.mirror swaps the corner shape for a z-facing stair under left_right and never swaps it under front_back, so mirroring across one axis is not mirroring across the other followed by a half turn.

So the rules are not written here, they are measured. utils/java-dump/DumpBlockTransforms.java compiles against the pinned server jar and records what BlockState.rotate and BlockState.mirror return for all 35723 Java block states. utils/generate/generate-state-transforms.ts replays that through the mapping and writes src/tables/stateTransforms.json, keyed by Bedrock state. Regenerate after a version bump:

sh
pnpm --filter @jsprismarine/bedrock-data run fetch:sources
pnpm exec turbo run build --filter=@jsprismarine/mapping
pnpm --filter @jsprismarine/structures run generate:transforms

The table covers 508 identifiers that move, out of the 15953 Bedrock states the Java palette reaches. Two things it reports rather than hides:

  • No rule. A state no Java block reaches, such as Bedrock's own minecraft:sulfur_spike, has no entry. It is placed unchanged and listed in TransformedTemplate.mismatches with reason no-rule.
  • Ambiguous. 34 transforms over minecraft:brown_mushroom_block and minecraft:red_mushroom_block are ambiguous: Java's six face booleans collapse onto Bedrock's 13-value huge_mushroom_bits, and the collapsed states do not rotate alike. The table keeps the first answer and the placement reports reason ambiguous. AMBIGUOUS_STATE_TRANSFORMS lists them.

verifyStateTransforms() checks the table against itself: every permutation is a bijection, four quarter turns are the identity, the two quarter turns are inverses, and each mirror is its own inverse. A test checks it against the mapping's state domains as well, by turning and reflecting every one of the 15953 palette states and asserting the result is a state the palette declares.

Block entity and entity NBT travels untouched. A jigsaw block entity's final_state names a direction in text, and transforming that is the caller's job.

Processors ​

createProcessorList reads a Java worldgen/processor_list file and applyProcessors runs the chain over a template. All eleven processor types Java 26.3 registers are implemented, along with its ten rule tests, three position tests and four block entity modifiers. The 40 vanilla processor lists use four of the eleven: rule 39 times, protected_blocks 7, block_rot 6 and capped 4.

The draw order matters as much as the rules, because it decides what a seeded placement produces, so the branches and the number of draws per branch were read from the pinned jar's own bytecode. block_age, for instance, builds both its replacement arrays before choosing between them, which costs four draws whichever branch wins.

Everything a processor needs from outside the template is injected through ProcessorContext: the random source, the world block at a position, the surface height for the gravity processor, block tag membership for tag_match and protected_blocks, and whether a state fills its cell for the lava submerged processor. A chain therefore runs in a test with no world.

Two consequences of working in Bedrock states are worth knowing. Block matching compares Bedrock identities, so Java states that collapse onto one Bedrock state match together. And Java's withPropertiesOf, which block_age and blackstone_replace use to carry a stair's facing onto its replacement, copies the state values the two identifiers both declare, read from the same pinned palette.

The jigsaw model ​

A jigsaw block carries a name, a target name, a target pool, a joint type and an orientation. Two jigsaws connect when they face each other, the parent's target is the child's name, and either the joint is rollable or the two share a top facing. Bedrock spells the orientation as a facing_direction and rotation pair where Java spells it as one orientation value, and the package joins the two through the mapping rather than writing the encoding down.

assembleJigsaw(config, sources) picks a rotation, draws an element by weight, and walks the connections breadth first. For each jigsaw of each placed piece it draws candidates from the target pool, then from the pool's fallback, tries the four rotations in a shuffled order, and takes the first candidate whose own jigsaw faces back and whose bounding box shares no block with a piece already placed. maxDepth stops the walk and maxDistanceFromCenter bounds it.

Three things decide where a piece sits vertically. A rigid element hanging off a rigid parent takes the y its jigsaw lands on. Anything else, which is the 183 terrain_matching elements of the village street pools, takes the terrain height at its parent's jigsaw instead, read through JigsawSources.terrainHeight. And use_expansion_hack, which 24 of the 28 vanilla jigsaw structures set, makes a piece whose own jigsaw points back into its own box as tall as the pool that jigsaw targets, so nothing lands in the room it is about to grow into.

The start piece settles the same way: projectStartToHeightmap adds the structure's start height to the terrain at the middle of the piece, and the piece moves so its ground layer, one above its floor, lands there. JigsawAssembly.origin reports the point Java calls the generation point, which is where the structure's biome check is made and what /locate names.

Every draw goes through the injected RandomSource, so a seed and a set of pools always produce the same layout. createLegacyRandom is Java's own java.util.Random generator, reproduced bit for bit and tested against values printed by a JDK.

The result reports what it could not do: rejectedForCollision counts candidate placements a bounding box refused, and unresolvedConnections counts jigsaws that found no pool, no candidate or no room.

Two parts of Java's placer are left out. Its free space is a voxel shape and here it is a list of piece bounding boxes, which rejects a few placements Java's deflated shape accepts. And placement_priority, which only the trial chambers use, does not reorder the queue.

Structure sets and placement ​

parseStructureSet reads a worldgen/structure_set, and isStructureChunk answers whether a structure of that set may start in a chunk for a world seed. All three placement types Java registers are implemented, along with the four frequency reduction methods. The 21 vanilla sets use random_spread 20 times and concentric_rings once, with triangular spread on three and a frequency below one on three.

The expected positions in the tests come from Java itself: a program built the real RandomSpreadStructurePlacement with each vanilla set's fields and printed the chunks it chooses for one seed.

concentricRingChunks produces the ring positions strongholds use. Java then moves each one to the nearest chunk whose biome is in preferred_biomes, which needs a biome source, so these are the unsnapped positions and the caller moves them. Exclusion zones are parsed but not applied, for the same reason: they depend on another set's placement, so StructurePlacement.exclusionZone names the set and the radius and the caller resolves it.

The corpus test ​

src/corpus.test.ts reads every template Mojang ships, in both formats, and prints the counts in the table above. It needs the pinned sources on disk, so it is gated:

sh
pnpm --filter @jsprismarine/bedrock-data run fetch:sources
JSP_STRUCTURE_CORPUS=1 pnpm --filter @jsprismarine/structures exec vitest run corpus

JSP_BDS_PATH and JSP_JAVA_JAR_PATH point at local copies instead.

Classes ​

Interfaces ​

BedrockBlockState ​

Defined in: packages/structures/src/types.ts:69

One Bedrock block state: the identifier and its state values.

Properties ​

name ​

readonly name: string

Defined in: packages/structures/src/types.ts:71

The namespaced Bedrock block identifier.

states ​

readonly states: Readonly<Record<string, string | number>>

Defined in: packages/structures/src/types.ts:73

The Bedrock state values for the identifier.

BedrockStructureTemplate ​

Defined in: packages/structures/src/types.ts:96

A structure template in Bedrock block states, which is the shape the server places. Both readers and the Java translation produce this.

Properties ​

blocks ​

readonly blocks: readonly BedrockTemplateBlock[]

Defined in: packages/structures/src/types.ts:99

entities ​

readonly entities: readonly TemplateEntity[]

Defined in: packages/structures/src/types.ts:100

palette ​

readonly palette: readonly BedrockBlockState[]

Defined in: packages/structures/src/types.ts:98

paletteVersions? ​

readonly optional paletteVersions?: readonly number[]

Defined in: packages/structures/src/types.ts:109

The block state version stamp a .mcstructure palette carries for each entry, parallel to BedrockStructureTemplate.palette. States saved by an older game version need upgrading before placement, and this is the only record of which version wrote them.

size ​

readonly size: TemplatePosition

Defined in: packages/structures/src/types.ts:97

worldOrigin? ​

readonly optional worldOrigin?: TemplatePosition

Defined in: packages/structures/src/types.ts:102

The world position the template was saved from, when the file records one.

BedrockTemplateBlock ​

Defined in: packages/structures/src/types.ts:80

One block of a Bedrock-shaped template, over Bedrock's two storage layers.

Properties ​

extraState ​

readonly extraState: number

Defined in: packages/structures/src/types.ts:85

Palette index for the second layer, which carries waterlogging, or NO_BLOCK.

nbt? ​

readonly optional nbt?: NBTTagCompound

Defined in: packages/structures/src/types.ts:87

The block entity NBT, left as read.

pos ​

readonly pos: TemplatePosition

Defined in: packages/structures/src/types.ts:81

state ​

readonly state: number

Defined in: packages/structures/src/types.ts:83

Palette index for the primary layer, or NO_BLOCK.

tickDelays? ​

readonly optional tickDelays?: readonly number[]

Defined in: packages/structures/src/types.ts:89

Scheduled tick delays a .mcstructure saved for this position, in ticks.

BoundingBox ​

Defined in: packages/structures/src/jigsaw.ts:101

An inclusive box in world space.

Properties ​

maxX ​

readonly maxX: number

Defined in: packages/structures/src/jigsaw.ts:105

maxY ​

readonly maxY: number

Defined in: packages/structures/src/jigsaw.ts:106

maxZ ​

readonly maxZ: number

Defined in: packages/structures/src/jigsaw.ts:107

minX ​

readonly minX: number

Defined in: packages/structures/src/jigsaw.ts:102

minY ​

readonly minY: number

Defined in: packages/structures/src/jigsaw.ts:103

minZ ​

readonly minZ: number

Defined in: packages/structures/src/jigsaw.ts:104

ChunkPosition ​

Defined in: packages/structures/src/structureSets.ts:16

A chunk position, in chunk coordinates.

Properties ​

x ​

readonly x: number

Defined in: packages/structures/src/structureSets.ts:17

z ​

readonly z: number

Defined in: packages/structures/src/structureSets.ts:18

ConcentricRingsPlacement ​

Defined in: packages/structures/src/structureSets.ts:58

A placement that lays structures out on rings around the world origin.

Extends ​

  • CommonPlacement

Properties ​

count ​

readonly count: number

Defined in: packages/structures/src/structureSets.ts:65

How many structures the placement produces in total.

distance ​

readonly distance: number

Defined in: packages/structures/src/structureSets.ts:61

The ring spacing in chunks.

exclusionZone? ​

readonly optional exclusionZone?: object

Defined in: packages/structures/src/structureSets.ts:44

A set whose structures push this one away, with the chunk radius it clears.

chunkCount ​

readonly chunkCount: number

otherSet ​

readonly otherSet: string

Inherited from ​

CommonPlacement.exclusionZone

frequency ​

readonly frequency: number

Defined in: packages/structures/src/structureSets.ts:39

The share of eligible chunks that keep the structure; 1 keeps all of them.

Inherited from ​

CommonPlacement.frequency

frequencyReductionMethod ​

readonly frequencyReductionMethod: FrequencyReductionMethod

Defined in: packages/structures/src/structureSets.ts:40

Inherited from ​

CommonPlacement.frequencyReductionMethod

locateOffset ​

readonly locateOffset: readonly [number, number, number]

Defined in: packages/structures/src/structureSets.ts:42

The block offset /locate reports, which does not move the structure.

Inherited from ​

CommonPlacement.locateOffset

preferredBiomes? ​

readonly optional preferredBiomes?: string

Defined in: packages/structures/src/structureSets.ts:67

The biome tag the real placement snaps each position to.

salt ​

readonly salt: number

Defined in: packages/structures/src/structureSets.ts:37

Mixed into the seed so two sets in one region draw different positions.

Inherited from ​

CommonPlacement.salt

spread ​

readonly spread: number

Defined in: packages/structures/src/structureSets.ts:63

How many structures the first ring holds.

type ​

readonly type: "minecraft:concentric_rings"

Defined in: packages/structures/src/structureSets.ts:59

DimensionOriginPlacement ​

Defined in: packages/structures/src/structureSets.ts:71

A placement that puts one structure at the dimension's origin chunk.

Extends ​

  • CommonPlacement

Properties ​

exclusionZone? ​

readonly optional exclusionZone?: object

Defined in: packages/structures/src/structureSets.ts:44

A set whose structures push this one away, with the chunk radius it clears.

chunkCount ​

readonly chunkCount: number

otherSet ​

readonly otherSet: string

Inherited from ​

CommonPlacement.exclusionZone

frequency ​

readonly frequency: number

Defined in: packages/structures/src/structureSets.ts:39

The share of eligible chunks that keep the structure; 1 keeps all of them.

Inherited from ​

CommonPlacement.frequency

frequencyReductionMethod ​

readonly frequencyReductionMethod: FrequencyReductionMethod

Defined in: packages/structures/src/structureSets.ts:40

Inherited from ​

CommonPlacement.frequencyReductionMethod

locateOffset ​

readonly locateOffset: readonly [number, number, number]

Defined in: packages/structures/src/structureSets.ts:42

The block offset /locate reports, which does not move the structure.

Inherited from ​

CommonPlacement.locateOffset

salt ​

readonly salt: number

Defined in: packages/structures/src/structureSets.ts:37

Mixed into the seed so two sets in one region draw different positions.

Inherited from ​

CommonPlacement.salt

type ​

readonly type: "minecraft:dimension_origin"

Defined in: packages/structures/src/structureSets.ts:72

JavaBlockState ​

Defined in: packages/structures/src/types.ts:15

One Java Edition block state: a namespaced identifier and its property values.

Properties ​

name ​

readonly name: string

Defined in: packages/structures/src/types.ts:17

The namespaced Java block identifier, for example minecraft:oak_stairs.

properties ​

readonly properties: Readonly<Record<string, string>>

Defined in: packages/structures/src/types.ts:19

Property values by property name; empty for a block with no properties.

JavaStructureTemplate ​

Defined in: packages/structures/src/types.ts:44

A Java Edition structure template, as the .nbt file holds it.

Properties ​

author? ​

readonly optional author?: string

Defined in: packages/structures/src/types.ts:63

blocks ​

readonly blocks: readonly JavaTemplateBlock[]

Defined in: packages/structures/src/types.ts:57

dataVersion? ​

readonly optional dataVersion?: number

Defined in: packages/structures/src/types.ts:60

Mojang's world data version, absent in the oldest files, which carry version instead.

entities ​

readonly entities: readonly TemplateEntity[]

Defined in: packages/structures/src/types.ts:58

palette ​

readonly palette: readonly JavaBlockState[]

Defined in: packages/structures/src/types.ts:51

The block state palette the blocks index into. For a file with randomized palettes this is the first variant.

paletteKeySpelling ​

readonly paletteKeySpelling: JavaPaletteKeySpelling

Defined in: packages/structures/src/types.ts:65

The palette entry key spelling the file actually used.

paletteVariants? ​

readonly optional paletteVariants?: readonly (readonly JavaBlockState[])[]

Defined in: packages/structures/src/types.ts:56

Every variant of a palettes list, in file order. Absent for the common file that carries a single palette.

size ​

readonly size: TemplatePosition

Defined in: packages/structures/src/types.ts:46

The template's extent in blocks.

version? ​

readonly optional version?: number

Defined in: packages/structures/src/types.ts:62

The pre-DataVersion format number; 1 in the files that carry it.

JavaTemplateBlock ​

Defined in: packages/structures/src/types.ts:23

One block of a Java template: where it sits, which palette entry it uses, and its block entity.

Properties ​

nbt? ​

readonly optional nbt?: NBTTagCompound

Defined in: packages/structures/src/types.ts:28

The block entity NBT the template carries, left as read.

pos ​

readonly pos: TemplatePosition

Defined in: packages/structures/src/types.ts:24

state ​

readonly state: number

Defined in: packages/structures/src/types.ts:26

Index into the template's palette.

JigsawAssembly ​

Defined in: packages/structures/src/jigsaw.ts:138

The result of an assembly, with the count of candidates the boxes rejected.

Properties ​

origin? ​

readonly optional origin?: TemplatePosition

Defined in: packages/structures/src/jigsaw.ts:145

Java's generation point: the middle of the start piece at the height it settled to. This is the position the structure's biome check is made at, and what /locate reports.

pieces ​

readonly pieces: readonly PlacedPiece[]

Defined in: packages/structures/src/jigsaw.ts:140

The placed pieces, the start piece first, then in the order they were placed.

rejectedForCollision ​

readonly rejectedForCollision: number

Defined in: packages/structures/src/jigsaw.ts:147

How many candidate placements were rejected because their box overlapped a placed piece.

unresolvedConnections ​

readonly unresolvedConnections: number

Defined in: packages/structures/src/jigsaw.ts:149

Jigsaw connections that found no pool, no candidate or no room.

JigsawBlockInfo ​

Defined in: packages/structures/src/jigsaw.ts:80

One jigsaw block inside a template, with the connection it declares.

Properties ​

finalState ​

readonly finalState: string

Defined in: packages/structures/src/jigsaw.ts:95

The block state left where the jigsaw block was.

front ​

readonly front: Direction

Defined in: packages/structures/src/jigsaw.ts:84

The direction the connection points, which is where the next piece attaches.

joint ​

readonly joint: JointType

Defined in: packages/structures/src/jigsaw.ts:93

name ​

readonly name: string

Defined in: packages/structures/src/jigsaw.ts:88

This jigsaw's name, which a parent's target matches against.

placementPriority ​

readonly placementPriority: number

Defined in: packages/structures/src/jigsaw.ts:97

pool ​

readonly pool: string

Defined in: packages/structures/src/jigsaw.ts:92

The template pool the next piece is drawn from.

pos ​

readonly pos: TemplatePosition

Defined in: packages/structures/src/jigsaw.ts:82

The block's position inside the template.

selectionPriority ​

readonly selectionPriority: number

Defined in: packages/structures/src/jigsaw.ts:96

target ​

readonly target: string

Defined in: packages/structures/src/jigsaw.ts:90

The jigsaw name this connection looks for in the next piece.

top ​

readonly top: Direction

Defined in: packages/structures/src/jigsaw.ts:86

The jigsaw's own up direction, which an aligned joint must match.

JigsawConfig ​

Defined in: packages/structures/src/jigsaw.ts:195

The structure fields that drive an assembly.

Properties ​

maxDepth ​

readonly maxDepth: number

Defined in: packages/structures/src/jigsaw.ts:200

How many connections deep the assembly may go.

maxDistanceFromCenter? ​

readonly optional maxDistanceFromCenter?: number

Defined in: packages/structures/src/jigsaw.ts:204

How far from the start position, in blocks, a piece may sit.

projectStartToHeightmap? ​

readonly optional projectStartToHeightmap?: string

Defined in: packages/structures/src/jigsaw.ts:210

The heightmap the start piece settles onto, Java's project_start_to_heightmap. The structure's own start height is added to it, so a village lands on the surface and trail ruins land fifteen blocks under it.

startJigsawName? ​

readonly optional startJigsawName?: string

Defined in: packages/structures/src/jigsaw.ts:198

The jigsaw name in the start piece that lands on the start position.

startPool ​

readonly startPool: string

Defined in: packages/structures/src/jigsaw.ts:196

startPosition ​

readonly startPosition: TemplatePosition

Defined in: packages/structures/src/jigsaw.ts:202

The world position the start piece is placed at.

useExpansionHack? ​

readonly optional useExpansionHack?: boolean

Defined in: packages/structures/src/jigsaw.ts:215

Java's use_expansion_hack: a piece whose own jigsaw points back into itself reserves vertical room for whatever that jigsaw will grow, so two houses never end up stacked.

JigsawJunction ​

Defined in: packages/structures/src/jigsaw.ts:128

The source coordinates Java's beardifier reads from a jigsaw junction.

Properties ​

sourceGroundY ​

readonly sourceGroundY: number

Defined in: packages/structures/src/jigsaw.ts:132

The source ground y coordinate Java records for this endpoint.

sourceX ​

readonly sourceX: number

Defined in: packages/structures/src/jigsaw.ts:130

The source x coordinate Java records for this endpoint.

sourceZ ​

readonly sourceZ: number

Defined in: packages/structures/src/jigsaw.ts:134

The source z coordinate Java records for this endpoint.

JigsawSources ​

Defined in: packages/structures/src/jigsaw.ts:175

What an assembly draws on, all injected so a run is reproducible.

Properties ​

pool ​

readonly pool: (identifier) => TemplatePool | undefined

Defined in: packages/structures/src/jigsaw.ts:177

Resolves a template pool identifier.

Parameters ​
identifier ​

string

Returns ​

TemplatePool | undefined

poolAliases? ​

readonly optional poolAliases?: ReadonlyMap<string, string>

Defined in: packages/structures/src/jigsaw.ts:182

Pool identifiers this run replaces with another, from the structure's pool_aliases.

random ​

readonly random: RandomSource

Defined in: packages/structures/src/jigsaw.ts:180

template ​

readonly template: (location) => BedrockStructureTemplate | undefined

Defined in: packages/structures/src/jigsaw.ts:179

Resolves a structure template identifier to a Bedrock-shaped template.

Parameters ​
location ​

string

Returns ​

BedrockStructureTemplate | undefined

terrainHeight? ​

readonly optional terrainHeight?: (x, z, heightmap) => number

Defined in: packages/structures/src/jigsaw.ts:191

Java's ChunkGenerator.getFirstFreeHeight: the bare terrain height of a column, before anything is decorated.

Absent for a caller with no world, which is what a test has. Without it a projected start stays at the y it was given and a terrain-matching element sits where a rigid one would, which is the flat-ground answer.

Parameters ​
x ​

number

z ​

number

heightmap ​

string

Returns ​

number

JigsawStart ​

Defined in: packages/structures/src/jigsaw.ts:161

A start piece placed, with the rest of the structure still to grow.

Java's JigsawPlacement.addPieces returns a Structure.GenerationStub: the generation point, paired with a Consumer<StructurePiecesBuilder> that Structure.generate only runs once findValidGenerationPoint has accepted the biome there. JigsawStart.expand is that consumer, so a caller can read JigsawStart.origin, decide the structure does not belong here, and never pay for the expansion.

Properties ​

expand ​

readonly expand: () => JigsawAssembly

Defined in: packages/structures/src/jigsaw.ts:171

Grows the structure from the start piece.

Call it at most once, and before anything else draws from JigsawSources.random: the expansion continues the stream the start piece left off at, which is what Java's shared WorldgenRandom does.

Returns ​

JigsawAssembly

origin? ​

readonly optional origin?: TemplatePosition

Defined in: packages/structures/src/jigsaw.ts:163

Java's generation point, absent when no start piece could be placed at all.

PlacedPiece ​

Defined in: packages/structures/src/jigsaw.ts:111

One piece the assembler placed.

Properties ​

boundingBox ​

readonly boundingBox: BoundingBox

Defined in: packages/structures/src/jigsaw.ts:118

depth ​

readonly depth: number

Defined in: packages/structures/src/jigsaw.ts:120

How many jigsaw connections away from the start piece this piece sits.

element ​

readonly element: PoolElement

Defined in: packages/structures/src/jigsaw.ts:114

groundLevelDelta? ​

readonly optional groundLevelDelta?: number

Defined in: packages/structures/src/jigsaw.ts:122

Java's PoolElementStructurePiece.getGroundLevelDelta.

junctions? ​

readonly optional junctions?: JigsawJunction[]

Defined in: packages/structures/src/jigsaw.ts:124

Java's terrain adaptation points created by accepted connections to this piece.

location ​

readonly location: string

Defined in: packages/structures/src/jigsaw.ts:113

The template identifier, or the feature identifier for a feature element.

position ​

readonly position: TemplatePosition

Defined in: packages/structures/src/jigsaw.ts:116

The world position of the piece's origin corner.

rotation ​

readonly rotation: Rotation

Defined in: packages/structures/src/jigsaw.ts:117

Placement ​

Defined in: packages/structures/src/transform.ts:48

How a template is placed: the mirror applies first, then the rotation, as Java does.

Properties ​

mirror? ​

readonly optional mirror?: Mirror

Defined in: packages/structures/src/transform.ts:50

rotation? ​

readonly optional rotation?: Rotation

Defined in: packages/structures/src/transform.ts:49

PoolElement ​

Defined in: packages/structures/src/jigsaw.ts:57

One element of a template pool.

Properties ​

elements? ​

readonly optional elements?: readonly PoolElement[]

Defined in: packages/structures/src/jigsaw.ts:70

The members of a list element, all placed at the same position.

feature? ​

readonly optional feature?: string

Defined in: packages/structures/src/jigsaw.ts:68

The placed feature identifier, for a feature element.

location? ​

readonly optional location?: string

Defined in: packages/structures/src/jigsaw.ts:60

The structure template identifier, for the two single element types.

processors? ​

readonly optional processors?: PoolElementProcessors

Defined in: packages/structures/src/jigsaw.ts:65

The processor chain the element is placed through, as an identifier or an inline list. The 245 vanilla pools write it inline 1439 times and by identifier 757.

projection ​

readonly projection: Projection

Defined in: packages/structures/src/jigsaw.ts:66

type ​

readonly type: "minecraft:empty_pool_element" | "minecraft:feature_pool_element" | "minecraft:legacy_single_pool_element" | "minecraft:list_pool_element" | "minecraft:single_pool_element"

Defined in: packages/structures/src/jigsaw.ts:58

ProcessorBlock ​

Defined in: packages/structures/src/processors.ts:71

One block as a processor sees it: a position in template space and a Bedrock state.

Properties ​

extraState? ​

readonly optional extraState?: BedrockBlockState

Defined in: packages/structures/src/processors.ts:79

Bedrock's second block layer, which carries waterlogging. Java has no such layer and no processor speaks about it, so processors carry it through untouched.

nbt? ​

readonly optional nbt?: NBTTagCompound

Defined in: packages/structures/src/processors.ts:81

The block entity NBT, which a rule's block entity modifier may replace.

pos ​

readonly pos: TemplatePosition

Defined in: packages/structures/src/processors.ts:72

state ​

readonly state: BedrockBlockState

Defined in: packages/structures/src/processors.ts:73

ProcessorContext ​

Defined in: packages/structures/src/processors.ts:88

What a processor needs from outside the template. Every dependency is injected, so a processor chain runs in a test with no world and no clock.

Properties ​

blockAt? ​

readonly optional blockAt?: (pos) => BedrockBlockState | undefined

Defined in: packages/structures/src/processors.ts:94

The block already in the world at a world position, for the location and protection tests.

Parameters ​
pos ​

TemplatePosition

Returns ​

BedrockBlockState | undefined

hasTag? ​

readonly optional hasTag?: (identifier, tag) => boolean

Defined in: packages/structures/src/processors.ts:98

Whether a Bedrock block identifier carries a block tag, for tag_match and protected_blocks.

Parameters ​
identifier ​

string

tag ​

string

Returns ​

boolean

heightAt? ​

readonly optional heightAt?: (heightmap, x, z) => number | undefined

Defined in: packages/structures/src/processors.ts:96

The surface height of a world column for the named heightmap, for the gravity processor.

Parameters ​
heightmap ​

string

x ​

number

z ​

number

Returns ​

number | undefined

isFullBlock? ​

readonly optional isFullBlock?: (state) => boolean

Defined in: packages/structures/src/processors.ts:100

Whether a Bedrock state fills its whole cell, for the lava submerged processor.

Parameters ​
state ​

BedrockBlockState

Returns ​

boolean

origin ​

readonly origin: TemplatePosition

Defined in: packages/structures/src/processors.ts:90

The world position the template's origin corner is placed at.

placement? ​

readonly optional placement?: Placement

Defined in: packages/structures/src/processors.ts:110

The rotation and mirror the template was prepared under.

Java turns a template's states after its processors have run, so a state a processor introduces by name - a jigsaw block's final_state, a rule's output_state - turns with the building. This chain runs over a template that is already turned, so an introduced state has to be turned here instead; left out, it is placed as written, which is only right for a template placed unturned.

random ​

readonly random: RandomSource

Defined in: packages/structures/src/processors.ts:92

The random source; every processor that draws takes its draws from here.

RandomSource ​

Defined in: packages/structures/src/random.ts:10

The random source structure placement and the processors draw from.

Java Edition seeds structure placement with WorldgenRandom over its legacy java.util.Random generator, so the same world seed puts the same village in the same chunk. Everything in this package takes its randomness through this interface, which is what makes an assembly reproducible in a test.

Methods ​

fork() ​

fork(): RandomSource

Defined in: packages/structures/src/random.ts:21

A new source seeded from this one, so a sub-task cannot disturb the parent's stream.

Returns ​

RandomSource

nextBoolean() ​

nextBoolean(): boolean

Defined in: packages/structures/src/random.ts:19

Returns ​

boolean

nextDouble() ​

nextDouble(): number

Defined in: packages/structures/src/random.ts:16

A uniform double in [0, 1) with 53 bits of precision.

Returns ​

number

nextFloat() ​

nextFloat(): number

Defined in: packages/structures/src/random.ts:14

A uniform float in [0, 1) with 24 bits of precision, as Java's nextFloat has.

Returns ​

number

nextInt() ​

nextInt(bound?): number

Defined in: packages/structures/src/random.ts:12

A uniform integer in [0, bound), or a full 32-bit signed integer when no bound is given.

Parameters ​
bound? ​

number

Returns ​

number

nextLong() ​

nextLong(): bigint

Defined in: packages/structures/src/random.ts:18

A uniform 64-bit signed integer.

Returns ​

bigint

RandomSpreadPlacement ​

Defined in: packages/structures/src/structureSets.ts:48

A placement that scatters one structure per spacing by spacing region.

Extends ​

  • CommonPlacement

Properties ​

exclusionZone? ​

readonly optional exclusionZone?: object

Defined in: packages/structures/src/structureSets.ts:44

A set whose structures push this one away, with the chunk radius it clears.

chunkCount ​

readonly chunkCount: number

otherSet ​

readonly otherSet: string

Inherited from ​

CommonPlacement.exclusionZone

frequency ​

readonly frequency: number

Defined in: packages/structures/src/structureSets.ts:39

The share of eligible chunks that keep the structure; 1 keeps all of them.

Inherited from ​

CommonPlacement.frequency

frequencyReductionMethod ​

readonly frequencyReductionMethod: FrequencyReductionMethod

Defined in: packages/structures/src/structureSets.ts:40

Inherited from ​

CommonPlacement.frequencyReductionMethod

locateOffset ​

readonly locateOffset: readonly [number, number, number]

Defined in: packages/structures/src/structureSets.ts:42

The block offset /locate reports, which does not move the structure.

Inherited from ​

CommonPlacement.locateOffset

salt ​

readonly salt: number

Defined in: packages/structures/src/structureSets.ts:37

Mixed into the seed so two sets in one region draw different positions.

Inherited from ​

CommonPlacement.salt

separation ​

readonly separation: number

Defined in: packages/structures/src/structureSets.ts:53

The chunks at the far edge of a region that the structure never lands in.

spacing ​

readonly spacing: number

Defined in: packages/structures/src/structureSets.ts:51

The region size in chunks.

spreadType ​

readonly spreadType: SpreadType

Defined in: packages/structures/src/structureSets.ts:54

type ​

readonly type: "minecraft:random_spread"

Defined in: packages/structures/src/structureSets.ts:49

StructureProcessor ​

Defined in: packages/structures/src/processors.ts:118

One processor in a chain. process runs per block and returns the replacement or undefined to drop it; finalize runs once over the whole list, which is what capped needs to count its replacements.

Properties ​

type ​

readonly type: "minecraft:blackstone_replace" | "minecraft:block_age" | "minecraft:block_ignore" | "minecraft:block_rot" | "minecraft:capped" | "minecraft:gravity" | "minecraft:jigsaw_replacement" | "minecraft:lava_submerged_block" | "minecraft:nop" | "minecraft:protected_blocks" | "minecraft:rule"

Defined in: packages/structures/src/processors.ts:119

Methods ​

finalize()? ​

optional finalize(processed, context): (ProcessorBlock | undefined)[]

Defined in: packages/structures/src/processors.ts:121

Parameters ​
processed ​

readonly (ProcessorBlock | undefined)[]

context ​

ProcessorContext

Returns ​

(ProcessorBlock | undefined)[]

process() ​

process(block, context): ProcessorBlock | undefined

Defined in: packages/structures/src/processors.ts:120

Parameters ​
block ​

ProcessorBlock

context ​

ProcessorContext

Returns ​

ProcessorBlock | undefined

StructureSet ​

Defined in: packages/structures/src/structureSets.ts:79

A worldgen/structure_set: a placement and the weighted structures it places.

Properties ​

placement ​

readonly placement: StructurePlacement

Defined in: packages/structures/src/structureSets.ts:80

structures ​

readonly structures: readonly object[]

Defined in: packages/structures/src/structureSets.ts:81

TemplateEntity ​

Defined in: packages/structures/src/types.ts:32

One entity of a template, with its fractional position and the block it was anchored to.

Properties ​

blockPos? ​

readonly optional blockPos?: TemplatePosition

Defined in: packages/structures/src/types.ts:35

The block position the entity was saved against; absent in .mcstructure files.

nbt? ​

readonly optional nbt?: NBTTagCompound

Defined in: packages/structures/src/types.ts:37

The entity NBT, left as read.

pos ​

readonly pos: EntityPosition

Defined in: packages/structures/src/types.ts:33

TemplatePool ​

Defined in: packages/structures/src/jigsaw.ts:74

A worldgen/template_pool: weighted elements and the pool to fall back to.

Properties ​

elements ​

readonly elements: readonly object[]

Defined in: packages/structures/src/jigsaw.ts:75

fallback ​

readonly fallback: string

Defined in: packages/structures/src/jigsaw.ts:76

TemplateTranslationLoss ​

Defined in: packages/structures/src/translate.ts:23

One Java palette entry that the translation could not map cleanly.

Properties ​

blockCount ​

readonly blockCount: number

Defined in: packages/structures/src/translate.ts:31

How many blocks of the template use this palette entry.

javaState ​

readonly javaState: JavaBlockState

Defined in: packages/structures/src/translate.ts:26

kind ​

readonly kind: TemplateLossKind

Defined in: packages/structures/src/translate.ts:27

loss? ​

readonly optional loss?: BlockLoss

Defined in: packages/structures/src/translate.ts:29

The mapping's reviewed loss row, present when kind is reviewed.

paletteIndex ​

readonly paletteIndex: number

Defined in: packages/structures/src/translate.ts:25

The entry's index in the Java template palette.

TransformMismatch ​

Defined in: packages/structures/src/transform.ts:54

A palette state the transform could not resolve, with the reason.

Properties ​

reason ​

readonly reason: "no-rule" | "ambiguous"

Defined in: packages/structures/src/transform.ts:57

state ​

readonly state: BedrockBlockState

Defined in: packages/structures/src/transform.ts:55

transform ​

readonly transform: "clockwise_90" | "clockwise_180" | "counterclockwise_90" | "left_right" | "front_back"

Defined in: packages/structures/src/transform.ts:56

TransformedTemplate ​

Defined in: packages/structures/src/transform.ts:68

The result of transforming a template, with everything the transform could not resolve.

Properties ​

mismatches ​

readonly mismatches: readonly TransformMismatch[]

Defined in: packages/structures/src/transform.ts:71

Palette states placed unchanged because the table has no rule or no ambiguity-free answer.

template ​

readonly template: BedrockStructureTemplate

Defined in: packages/structures/src/transform.ts:69

TranslateOptions ​

Defined in: packages/structures/src/translate.ts:47

How to translate one Java template.

Properties ​

applyWaterlogging? ​

readonly optional applyWaterlogging?: boolean

Defined in: packages/structures/src/translate.ts:54

Whether a Java waterlogged=true state puts water on Bedrock's second block layer, which is where that information goes. Defaults to true.

paletteVariant? ​

readonly optional paletteVariant?: number

Defined in: packages/structures/src/translate.ts:49

Which variant of a randomized palettes list to use; defaults to the first.

TranslatedTemplate ​

Defined in: packages/structures/src/translate.ts:35

A translated template with the full account of what the translation cost.

Properties ​

losses ​

readonly losses: readonly TemplateTranslationLoss[]

Defined in: packages/structures/src/translate.ts:39

One row per Java palette entry that did not map cleanly, in palette order.

lostBlocks ​

readonly lostBlocks: number

Defined in: packages/structures/src/translate.ts:43

Blocks whose palette entry produced a TemplateTranslationLoss.

mappedBlocks ​

readonly mappedBlocks: number

Defined in: packages/structures/src/translate.ts:41

Blocks whose palette entry mapped cleanly.

template ​

readonly template: BedrockStructureTemplate

Defined in: packages/structures/src/translate.ts:37

The Bedrock-shaped template, which is what the server places.

Type Aliases ​

Direction ​

Direction = "down" | "up" | "north" | "south" | "east" | "west"

Defined in: packages/structures/src/jigsaw.ts:33

A facing, in Java's own vocabulary, which both jigsaw fields use.

EntityPosition ​

EntityPosition = readonly [x: number, y: number, z: number]

Defined in: packages/structures/src/types.ts:7

A fractional position, as entity coordinates are stored.

FrequencyReductionMethod ​

FrequencyReductionMethod = "default" | "legacy_type_1" | "legacy_type_2" | "legacy_type_3"

Defined in: packages/structures/src/structureSets.ts:25

Which rule thins a placement whose frequency is below one.

JavaPaletteKeySpelling ​

JavaPaletteKeySpelling = "Name" | "id"

Defined in: packages/structures/src/types.ts:41

Which spelling of the palette entry keys a Java template file used.

JointType ​

JointType = "rollable" | "aligned"

Defined in: packages/structures/src/jigsaw.ts:36

Whether two jigsaws must share a top facing (aligned) or may not (rollable).

Mirror ​

Mirror = "none" | "left_right" | "front_back"

Defined in: packages/structures/src/tableShape.ts:10

A reflection of the template: left_right flips the z axis, front_back the x axis.

PoolElementProcessors ​

PoolElementProcessors = string | { processors: readonly unknown[]; }

Defined in: packages/structures/src/jigsaw.ts:54

A processor chain named by identifier, or written inline as Java 26.3 lets a field be.

PoolElementType ​

PoolElementType = typeof POOL_ELEMENT_TYPES[number]

Defined in: packages/structures/src/jigsaw.ts:51

One of the five pool element types.

ProcessorType ​

ProcessorType = typeof PROCESSOR_TYPES[number]

Defined in: packages/structures/src/processors.ts:68

One of the registered processor types.

Projection ​

Projection = "rigid" | "terrain_matching"

Defined in: packages/structures/src/jigsaw.ts:39

How a pool element sits in the world.

Rotation ​

Rotation = "none" | "clockwise_90" | "clockwise_180" | "counterclockwise_90"

Defined in: packages/structures/src/tableShape.ts:7

A rotation about the template's vertical axis.

SpreadType ​

SpreadType = "linear" | "triangular"

Defined in: packages/structures/src/structureSets.ts:22

How a random spread placement picks the offset inside a region.

StructurePlacement ​

StructurePlacement = RandomSpreadPlacement | ConcentricRingsPlacement | DimensionOriginPlacement

Defined in: packages/structures/src/structureSets.ts:76

One of the three placement types.

TemplateLossKind ​

TemplateLossKind = "reviewed" | "unknown" | "passthrough"

Defined in: packages/structures/src/translate.ts:14

Why one Java palette entry did not translate into a plain Bedrock state.

TemplatePosition ​

TemplatePosition = readonly [x: number, y: number, z: number]

Defined in: packages/structures/src/types.ts:4

An integer position in template space, relative to the template's origin corner.

TransformName ​

TransformName = typeof TRANSFORM_NAMES[number]

Defined in: packages/structures/src/tableShape.ts:22

One of the transforms the state table stores.

Variables ​

AMBIGUOUS_STATE_TRANSFORMS ​

const AMBIGUOUS_STATE_TRANSFORMS: readonly object[]

Defined in: packages/structures/src/transform.ts:332

The Bedrock states whose transform is ambiguous, because several Java states that do not transform alike collapse onto them. The table keeps the first of those answers; a template placing one of these states gets a ambiguous mismatch.

BLOCK_ENTITY_MODIFIER_TYPES ​

const BLOCK_ENTITY_MODIFIER_TYPES: readonly ["minecraft:append_loot", "minecraft:append_static", "minecraft:clear", "minecraft:passthrough"]

Defined in: packages/structures/src/processors.ts:60

The four rule_block_entity_modifier types Java 26.3 registers.

MCSTRUCTURE_FORMAT_VERSION ​

const MCSTRUCTURE_FORMAT_VERSION: 1 = 1

Defined in: packages/structures/src/bedrockTemplate.ts:25

The only format_version Mojang has published for .mcstructure files.

NO_BLOCK ​

const NO_BLOCK: -1 = -1

Defined in: packages/structures/src/types.ts:77

The palette index that means "this layer holds no block".

PALETTE_KEY_RENAME_DATA_VERSION ​

const PALETTE_KEY_RENAME_DATA_VERSION: 5023 = 5023

Defined in: packages/structures/src/javaTemplate.ts:19

The first DataVersion observed to spell palette entries id/properties instead of Name/Properties. Java 26.3 writes 5023 and uses the new spelling; the newest file in the pinned Bedrock Dedicated Server zip writes 5009 and uses the old one. The exact release that renamed the keys lies between those two and is not observable from the pinned data, so this constant only picks which spelling to look for first: a file whose entries disagree still reads, through readJavaStructureTemplate's probe.

POOL_ELEMENT_TYPES ​

const POOL_ELEMENT_TYPES: readonly ["minecraft:empty_pool_element", "minecraft:feature_pool_element", "minecraft:legacy_single_pool_element", "minecraft:list_pool_element", "minecraft:single_pool_element"]

Defined in: packages/structures/src/jigsaw.ts:42

The five worldgen/template_pool element types Java 26.3 registers.

POS_RULE_TEST_TYPES ​

const POS_RULE_TEST_TYPES: readonly ["minecraft:always_true", "minecraft:axis_aligned_linear_pos", "minecraft:linear_pos"]

Defined in: packages/structures/src/processors.ts:53

The three pos_rule_test types Java 26.3 registers.

PROCESSOR_TYPES ​

const PROCESSOR_TYPES: readonly ["minecraft:blackstone_replace", "minecraft:block_age", "minecraft:block_ignore", "minecraft:block_rot", "minecraft:capped", "minecraft:gravity", "minecraft:jigsaw_replacement", "minecraft:lava_submerged_block", "minecraft:nop", "minecraft:protected_blocks", "minecraft:rule"]

Defined in: packages/structures/src/processors.ts:24

The eleven worldgen/structure_processor types Java 26.3 registers.

RULE_TEST_TYPES ​

const RULE_TEST_TYPES: readonly ["minecraft:all_of", "minecraft:always_true", "minecraft:any_of", "minecraft:block_match", "minecraft:blockstate_match", "minecraft:height_match", "minecraft:not", "minecraft:random_block_match", "minecraft:random_blockstate_match", "minecraft:tag_match"]

Defined in: packages/structures/src/processors.ts:39

The ten rule_test types Java 26.3 registers.

STATE_TRANSFORM_VERSIONS ​

const STATE_TRANSFORM_VERSIONS: object

Defined in: packages/structures/src/transform.ts:41

The pinned versions the transform table was generated from.

Type Declaration ​

bedrockVersion ​

readonly bedrockVersion: string = transformTable.bedrockVersion

geyserMappingsCommit ​

readonly geyserMappingsCommit: string = transformTable.geyserMappingsCommit

javaVersion ​

readonly javaVersion: string = transformTable.javaVersion

STRUCTURE_PLACEMENT_TYPES ​

const STRUCTURE_PLACEMENT_TYPES: readonly ["minecraft:concentric_rings", "minecraft:dimension_origin", "minecraft:random_spread"]

Defined in: packages/structures/src/structureSets.ts:28

The three structure_placement types Java 26.3 registers.

TRANSFORM_NAMES ​

const TRANSFORM_NAMES: readonly ["clockwise_90", "clockwise_180", "counterclockwise_90", "left_right", "front_back"]

Defined in: packages/structures/src/tableShape.ts:13

The five transforms the state table stores, which is every one that moves a state.

Functions ​

applyProcessors() ​

applyProcessors(template, processors, context): BedrockStructureTemplate

Defined in: packages/structures/src/processors.ts:706

Runs a processor chain over a template, in Java's order: every processor sees every block in turn, then the chain's finalize passes run.

The result keeps the template's shape, with dropped blocks removed and the palette rebuilt from the blocks that survived.

Parameters ​

template ​

BedrockStructureTemplate

processors ​

readonly StructureProcessor[]

context ​

ProcessorContext

Returns ​

BedrockStructureTemplate

assembleJigsaw() ​

assembleJigsaw(config, sources): JigsawAssembly

Defined in: packages/structures/src/jigsaw.ts:625

Grows a structure from a start pool.

The walk is breadth first from the start piece, the same order Java's JigsawPlacement uses, and every draw comes from JigsawSources.random, so the same seed and the same pools produce the same layout.

This is startJigsaw with the expansion run straight away. A caller that wants to look at the generation point before paying for the expansion asks for the start instead.

Parameters ​

config ​

JigsawConfig

sources ​

JigsawSources

Returns ​

JigsawAssembly

The placed pieces and a count of what the bounding boxes and the pools rejected, which is how a caller sees a pool that cannot close.

boxesOverlap() ​

boxesOverlap(left, right): boolean

Defined in: packages/structures/src/jigsaw.ts:531

Whether two inclusive boxes share any block. Boxes that only touch do not.

Parameters ​

left ​

BoundingBox

BoundingBox

Returns ​

boolean

canAttach() ​

canAttach(parent, child): boolean

Defined in: packages/structures/src/jigsaw.ts:424

Whether a child jigsaw can attach to a parent one: the two must face each other, an aligned joint must also share a top facing, and the parent's target must be the child's name.

Parameters ​

parent ​

JigsawBlockInfo

child ​

JigsawBlockInfo

Returns ​

boolean

concentricRingChunks() ​

concentricRingChunks(placement, seed): ChunkPosition[]

Defined in: packages/structures/src/structureSets.ts:270

The ring positions a concentric rings placement produces, which is how strongholds are laid out.

Java then snaps each position to the nearest chunk whose biome is in preferred_biomes. That search needs a biome source, so these are the unsnapped positions and the caller moves them.

Parameters ​

placement ​

ConcentricRingsPlacement

seed ​

bigint

Returns ​

ChunkPosition[]

createLegacyRandom() ​

createLegacyRandom(seed): RandomSource

Defined in: packages/structures/src/random.ts:86

A random source seeded the way new java.util.Random(seed) is.

Parameters ​

seed ​

number | bigint

Returns ​

RandomSource

createProcessor() ​

createProcessor(definition): StructureProcessor

Defined in: packages/structures/src/processors.ts:567

Builds one processor from its Java worldgen/processor_list element.

Parameters ​

definition ​

unknown

Returns ​

StructureProcessor

Throws ​

When the definition names an unknown type or a block state the pinned Java version does not have.

createProcessorList() ​

createProcessorList(definition): StructureProcessor[]

Defined in: packages/structures/src/processors.ts:689

Builds a chain from a Java worldgen/processor_list file or from its processors array.

Parameters ​

definition ​

unknown

Returns ​

StructureProcessor[]

isGzip() ​

isGzip(bytes): boolean

Defined in: packages/structures/src/javaTemplate.ts:24

Whether the bytes start with a gzip member header.

Parameters ​

bytes ​

Uint8Array

Returns ​

boolean

isStructureChunk() ​

isStructureChunk(placement, seed, chunkX, chunkZ): boolean

Defined in: packages/structures/src/structureSets.ts:224

Whether a structure of this set may start in the given chunk for a seed.

Exclusion zones are not applied here, because they depend on another set's placement; StructurePlacement.exclusionZone names the set and the radius so the caller can apply it.

Parameters ​

placement ​

StructurePlacement

seed ​

bigint

chunkX ​

number

chunkZ ​

number

Returns ​

boolean

jigsawBlocksOf() ​

jigsawBlocksOf(template): JigsawBlockInfo[]

Defined in: packages/structures/src/jigsaw.ts:363

The jigsaw blocks a Bedrock-shaped template holds, read from the palette entries named minecraft:jigsaw and their block entity NBT.

Both spellings of the pool field are accepted: Java writes pool and Bedrock's own .mcstructure jigsaw block entities write target_pool.

Parameters ​

template ​

BedrockStructureTemplate

Returns ​

JigsawBlockInfo[]

jigsawOrientationOf() ​

jigsawOrientationOf(state): { front: Direction; top: Direction; } | undefined

Defined in: packages/structures/src/jigsaw.ts:305

The front and top facings a Bedrock jigsaw block state encodes.

Parameters ​

state ​

BedrockBlockState

Returns ​

{ front: Direction; top: Direction; } | undefined

jigsawStateFor() ​

jigsawStateFor(front, top): BedrockBlockState | undefined

Defined in: packages/structures/src/jigsaw.ts:309

The Bedrock jigsaw block state for a front and top facing pair.

Parameters ​

front ​

Direction

top ​

Direction

Returns ​

BedrockBlockState | undefined

largeFeatureSeed() ​

largeFeatureSeed(seed, x, z): bigint

Defined in: packages/structures/src/random.ts:106

The seed Java's WorldgenRandom.setLargeFeatureSeed derives, used by the legacy frequency reduction methods. Unlike the salted form it mixes two draws of the world seed into the region coordinates.

Parameters ​

seed ​

bigint

x ​

number

z ​

number

Returns ​

bigint

largeFeatureWithSaltSeed() ​

largeFeatureWithSaltSeed(seed, x, z, salt): bigint

Defined in: packages/structures/src/random.ts:98

The seed Java's WorldgenRandom.setLargeFeatureWithSalt derives for a structure region, which is what decides whether a region holds a structure and where in it.

Parameters ​

seed ​

bigint

x ​

number

The region's x index, which is the chunk x divided by the spacing.

z ​

number

The region's z index.

salt ​

number

The structure set's own salt, so two sets in one region draw differently.

Returns ​

bigint

mcStructureIndex() ​

mcStructureIndex(size, x, y, z): number

Defined in: packages/structures/src/bedrockTemplate.ts:32

The index a .mcstructure uses for a block, which walks x slowest and z fastest. Measured against the sulfur spring templates, whose saved block entity coordinates pin the order.

Parameters ​

size ​

TemplatePosition

x ​

number

y ​

number

z ​

number

Returns ​

number

mcStructurePosition() ​

mcStructurePosition(size, index): TemplatePosition

Defined in: packages/structures/src/bedrockTemplate.ts:36

The template position a .mcstructure block index refers to.

Parameters ​

size ​

TemplatePosition

index ​

number

Returns ​

TemplatePosition

mirrorBedrockState() ​

mirrorBedrockState(state, mirror): BedrockBlockState

Defined in: packages/structures/src/transform.ts:183

Mirrors one Bedrock block state.

Parameters ​

state ​

BedrockBlockState

mirror ​

Mirror

Returns ​

BedrockBlockState

oppositeDirection() ​

oppositeDirection(direction): Direction

Defined in: packages/structures/src/jigsaw.ts:238

The facing opposite another.

Parameters ​

direction ​

Direction

Returns ​

Direction

parseBlockStateString() ​

parseBlockStateString(source): BedrockBlockState | undefined

Defined in: packages/structures/src/processors.ts:669

Parses the minecraft:block[prop=value,...] form a jigsaw block entity stores in final_state, returning the Bedrock state it maps to.

Parameters ​

source ​

string

Returns ​

BedrockBlockState | undefined

parseOrientation() ​

parseOrientation(value): { front: Direction; top: Direction; } | undefined

Defined in: packages/structures/src/jigsaw.ts:261

Splits a Bedrock orientation value, which Java calls FrontAndTop, into its two facings: down_east is front down and top east, west_up is front west and top up.

Parameters ​

value ​

string

Returns ​

{ front: Direction; top: Direction; } | undefined

parsePoolAliases() ​

parsePoolAliases(definition, random?): Map<string, string>

Defined in: packages/structures/src/jigsaw.ts:928

Reads the pool_aliases list a jigsaw structure may carry, as a map from the alias pool to the pool it stands for in this run.

Java registers three binding types and the trial chambers, the only vanilla structure with aliases at all, use all three: six direct bindings that always stand for the same pool, two random ones that draw a pool, and one random_group that draws a whole set of bindings. The two that draw need a random source, and without one they contribute nothing, which leaves their connections to close through the pool's fallback.

Parameters ​

definition ​

unknown

random? ​

RandomSource

The stream the draws come from. Java forks a positional one from the world seed and the structure's position; a caller that wants the same aliases every time for a structure passes a source seeded the same way.

Returns ​

Map<string, string>

parseStructurePlacement() ​

parseStructurePlacement(definition): StructurePlacement

Defined in: packages/structures/src/structureSets.ts:113

Reads a structure_placement object from a Java worldgen/structure_set.

Parameters ​

definition ​

unknown

Returns ​

StructurePlacement

Throws ​

When the type is not one of the three Java registers.

parseStructureSet() ​

parseStructureSet(definition): StructureSet

Defined in: packages/structures/src/structureSets.ts:149

Reads a worldgen/structure_set file.

Parameters ​

definition ​

unknown

Returns ​

StructureSet

Throws ​

When the file has no placement or no structure list.

parseTemplatePool() ​

parseTemplatePool(definition): TemplatePool

Defined in: packages/structures/src/jigsaw.ts:340

Reads a worldgen/template_pool file.

Parameters ​

definition ​

unknown

Returns ​

TemplatePool

Throws ​

When the file has no element list or names an unknown element type.

pickStructure() ​

pickStructure(set, random): string | undefined

Defined in: packages/structures/src/structureSets.ts:301

The structure a set places in one chunk, drawn by weight.

Parameters ​

set ​

StructureSet

random ​
nextInt ​

(bound) => number

Returns ​

string | undefined

The chosen structure's identifier, or undefined for an empty set.

potentialStructureChunk() ​

potentialStructureChunk(placement, seed, chunkX, chunkZ): ChunkPosition

Defined in: packages/structures/src/structureSets.ts:170

The one chunk in a region that a random spread placement would use, whether or not the given chunk is that one.

Parameters ​

placement ​

RandomSpreadPlacement

seed ​

bigint

chunkX ​

number

Any chunk in the region, in chunk coordinates.

chunkZ ​

number

Returns ​

ChunkPosition

readJavaStructureTemplate() ​

readJavaStructureTemplate(bytes): JavaStructureTemplate

Defined in: packages/structures/src/javaTemplate.ts:75

Reads a Java Edition structure template: the gzip-compressed, big-endian NBT that both Mojang's server jar and the Bedrock Dedicated Server zip ship for structure pieces. Uncompressed bytes are accepted too.

Palette entries are read under whichever key spelling the file uses. DataVersion picks which spelling to try first, since Java 26.3 renamed Name/Properties to id/properties, and the other spelling is a fallback, so a file that disagrees with its own version still reads.

Parameters ​

bytes ​

Uint8Array

Returns ​

JavaStructureTemplate

Throws ​

When the bytes are not a structure template.

readMcStructure() ​

readMcStructure(bytes): BedrockStructureTemplate

Defined in: packages/structures/src/bedrockTemplate.ts:112

Reads a Bedrock .mcstructure template: uncompressed little-endian NBT with Bedrock block states, two block storage layers and world-coordinate entity positions. Fifteen of these ship in the Bedrock Dedicated Server zip, where everything else is the Java format.

Positions where both layers hold no block are left out of BedrockStructureTemplate.blocks, since the format uses them for "change nothing here".

Parameters ​

bytes ​

Uint8Array

Returns ​

BedrockStructureTemplate

Throws ​

When the bytes are not a .mcstructure.

rotateBedrockState() ​

rotateBedrockState(state, rotation): BedrockBlockState

Defined in: packages/structures/src/transform.ts:179

Rotates one Bedrock block state about the vertical axis.

Parameters ​

state ​

BedrockBlockState

rotation ​

Rotation

Returns ​

BedrockBlockState

rotateDirection() ​

rotateDirection(direction, rotation): Direction

Defined in: packages/structures/src/jigsaw.ts:231

Turns a facing about the vertical axis; up and down do not move.

Parameters ​

direction ​

Direction

rotation ​

Rotation

Returns ​

Direction

startJigsaw() ​

startJigsaw(config, sources): JigsawStart

Defined in: packages/structures/src/jigsaw.ts:643

Places a structure's start piece and leaves the expansion to the caller.

Everything that decides the generation point happens here: the start rotation and element are drawn, the piece is anchored and settled onto the terrain, and its middle becomes JigsawStart.origin. Java splits at exactly this line. JigsawPlacement.addPieces returns a GenerationStub carrying that position and a closure over the breadth-first walk, and Structure.generate only runs the closure once the biome at the position has been accepted, so a village drawn into the wrong biome costs a start piece rather than a village.

Parameters ​

config ​

JigsawConfig

sources ​

JigsawSources

Returns ​

JigsawStart

structureSetCandidates() ​

structureSetCandidates(placement, seed, region): ChunkPosition[]

Defined in: packages/structures/src/structureSets.ts:248

Every chunk in a rectangle of chunks where a structure of this set may start, in scan order.

Parameters ​

placement ​

StructurePlacement

seed ​

bigint

region ​
maxChunkX ​

number

maxChunkZ ​

number

minChunkX ​

number

minChunkZ ​

number

Returns ​

ChunkPosition[]

transformBedrockState() ​

transformBedrockState(state, placement): BedrockBlockState

Defined in: packages/structures/src/transform.ts:173

Transforms one Bedrock block state under a placement. Direction-valued states follow Java Edition's own rotate and mirror rules, measured from the pinned server jar and keyed by Bedrock state, so the two editions' different axis names on stairs, logs and slabs never have to be lined up by hand.

A state the table has no rule for comes back unchanged; use transformTemplate when the unresolved states matter.

Parameters ​

state ​

BedrockBlockState

placement ​

Placement

Returns ​

BedrockBlockState

transformEntityPosition() ​

transformEntityPosition(size, __namedParameters, placement): EntityPosition

Defined in: packages/structures/src/transform.ts:220

Moves a fractional entity position under a placement. Entities sit between blocks, so the reflection is about the template edge rather than the last block's index.

Parameters ​

size ​

TemplatePosition

__namedParameters ​

EntityPosition

placement ​

Placement

Returns ​

EntityPosition

transformPosition() ​

transformPosition(size, __namedParameters, placement): TemplatePosition

Defined in: packages/structures/src/transform.ts:196

Moves a block position under a placement, keeping the result inside the transformed template rather than around Java's world-space pivot.

Parameters ​

size ​

TemplatePosition

__namedParameters ​

TemplatePosition

placement ​

Placement

Returns ​

TemplatePosition

transformTemplate() ​

transformTemplate(template, placement): TransformedTemplate

Defined in: packages/structures/src/transform.ts:249

Places a template under a rotation and a mirror, moving both the block positions and the direction-valued block states.

The palette is transformed once per entry rather than once per block, and every state the transform could not resolve comes back in TransformedTemplate.mismatches instead of being changed silently. Block entity and entity NBT is carried across untouched: the direction a jigsaw block entity names in final_state is the caller's to transform.

Parameters ​

template ​

BedrockStructureTemplate

placement ​

Placement

Returns ​

TransformedTemplate

transformedSize() ​

transformedSize(size, placement): TemplatePosition

Defined in: packages/structures/src/transform.ts:187

The extent a template has after a placement: a quarter turn swaps the x and z extents.

Parameters ​

size ​

TemplatePosition

placement ​

Placement

Returns ​

TemplatePosition

translateJavaTemplate() ​

translateJavaTemplate(template, options?): TranslatedTemplate

Defined in: packages/structures/src/translate.ts:120

Translates a Java template's palette into Bedrock block states through @jsprismarine/mapping, producing the Bedrock-shaped template the server places.

Nothing is dropped quietly: every palette entry that does not map cleanly becomes a TemplateTranslationLoss with the number of blocks it affects, and its blocks are still placed, as minecraft:unknown where the mapping has no state at all. Java's waterlogged flag, which no Bedrock state carries, moves to the second block layer as water.

Parameters ​

template ​

JavaStructureTemplate

options? ​

TranslateOptions = {}

Returns ​

TranslatedTemplate

verifyStateTransforms() ​

verifyStateTransforms(): string[]

Defined in: packages/structures/src/transform.ts:286

Checks the generated transform table against itself: every permutation is a bijection over its identifier's states, four quarter turns are the identity, the two quarter turns are inverses, and each mirror is its own inverse. Returns one message per failure, empty when the table is sound.

The identifiers in AMBIGUOUS_STATE_TRANSFORMS are skipped. Their permutations cannot be bijections, because several Java states that do not transform alike collapse onto one Bedrock state, and that loss is reported through the ambiguity list instead.

Returns ​

string[]