# Minecraft Structure

> Minecraft Structure Definition 结构定义格式：Definition Format 定义格式（STRUCTURE 注册表、data/<namespace>/worldgen/structure/ 数据包路径、tags/worldgen/structure/ 标签）、Common Fields 通用字段（biomes 结构可生成生物群系 ID/列表/标签、spawn_overrides 生物生成覆盖 bounding_box piece/full spawns列表 type/weight/minCount/maxCount、step 装饰阶段 11个阶段 raw_generation到top_layer_modification、terrain_adaptation 地形适应 none/beard_thin/beard_box/bury/encapsulate、type 结构类型）、Structure Types 结构类型（jigsaw 拼图结构模板：start_pool 起始模板池、start_jigsaw_name 起始拼图方块名、start_height 起始高度提供器 project_start_to_heightmap 投影到高度图、use_expansion_hack 允许次要片段超出基础片段Y尺寸、size 生成深度1-20、max_distance_from_center 距离中心最大3D切比雪夫距离、pool_aliases 模板池映射 direct/random/random_group、dimension_padding 垂直填充、liquid_settings 液体设置 apply_waterlogging/ignore_waterlogging；mineshaft 矿井 硬编码 mineshaft_type normal/mesa；nether_fossil 下界化石 高度提供器 放置扫描区块；ocean_ruin 海洋废墟 biome_temp cold/warm large_probability cluster_probability；ruined_portal 废弃传送门 setups 加权列表 placement/air_pocket_probability/mossiness/overgrown/vines/can_be_cold/replace_w

- Skill: `zmjjkk123-hub/minecraft-structure` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zmjjkk123-hub/minecraft-structure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmjjkk123-hub/minecraft-structure/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ZMJJKK123-hub (https://skillmd.com/u/zmjjkk123-hub)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zmjjkk123-hub/minecraft-structure

---


# Structure Definition

Structure definition files are the data-driven definitions of **structure features** (the structures controlled by the "Generate structures" world option). Java Edition only.

## Definition Format

Registry `STRUCTURE`, data pack path `worldgen/structure` (files in `data/<namespace>/worldgen/structure/`; tags in `tags/worldgen/structure/`).

Common fields:

- `biomes` (required) — biomes where the structure can generate (ID / list / tag).
- `spawn_overrides` (required) — overrides mob spawning in the structure's biomes: per spawn category: `bounding_box` (`piece` — the pieces' regions, or `full` — the whole structure region) and `spawns` (list of `{type` (entity ID; "other" category spawns pigs only), `weight`, `minCount` (>0), `maxCount` (>0)`; empty list = no spawns of that category).
- `step` (required) — the decoration stage the structure generates in (structure pieces generate before features within the same stage): `raw_generation`, `lakes`, `local_modifications`, `underground_structures`, `surface_structures`, `strongholds`, `underground_ores`, `underground_decoration`, `fluid_springs`, `vegetal_decoration`, `top_layer_modification`.
- `terrain_adaptation` (default `none`) — `none`; `beard_thin` (add terrain under, remove inside; pillager outposts, villages, abandoned camps); `beard_box` (stronger beard_thin; ancient cities); `bury` (bury in terrain; strongholds, trail ruins); `encapsulate` (stronger bury; trial chambers).
- `type` (required) — the structure type.

## Structure Types

- `jigsaw` — structure templates assembled via jigsaw blocks:
  - `start_pool` (required) — starting template pool.
  - `start_jigsaw_name` — name of the jigsaw block connecting the start template (missing → generation fails).
  - `start_height` (required) — height provider; `project_start_to_heightmap` — a heightmap (`WORLD_SURFACE_WG`, `WORLD_SURFACE`, `OCEAN_FLOOR_WG`, `OCEAN_FLOOR`, `MOTION_BLOCKING`, `MOTION_BLOCKING_NO_LEAVES`) to project onto, offset by `start_height`.
  - `use_expansion_hack` (required) — allow secondary pieces to exceed the base piece's Y size.
  - `size` (required, 1–20) — generation depth.
  - `max_distance_from_center` — max 3D Chebyshev distance from the start (int = horizontal only, 1–128; with terrain_adaptation 1–116; `horizontal` also 1–4096, default 4096).
  - `pool_aliases` — template pool mappings: `direct` (`alias` → `target`), `random` (`alias` + weighted `targets`), `random_group` (weighted groups of nested mappings).
  - `dimension_padding` (≥0, default 0; `bottom`/`top` or int) — vertical padding to keep structures out of bedrock.
  - `liquid_settings` (default `apply_waterlogging`) — `apply_waterlogging` (waterlog waterloggable blocks) or `ignore_waterlogging` (replace liquids directly).
  - Empty start pool also fails generation. Pieces connect jigsaw-to-jigsaw ("face to face"); jigsaw blocks become their `final_state` during worldgen. Inward-pointing jigsaws forbid the secondary piece exceeding the base piece; outward-pointing ones forbid overlap or exceeding the vertical padding. Generation stops past the depth/max distance. Selection: highest selection priority first; placement: highest placement priority first; fall back to lower priorities; stop when none connect.
- `mineshaft` — hardcoded mineshaft: `mineshaft_type` = `normal` (oak) or `mesa` (dark oak). Pieces never generate in `#mineshaft_blocking` biomes or liquid areas.
- `nether_fossil` — Nether fossils from templates: `height` (required height provider). Placement scans the chunk, placing on soul-sand-like or full-top-surface blocks above sea level touching air; 50% chance to place a desiccated ghast at the bottom layer.
- `ocean_ruin` — ocean ruins: `biome_temp` (`cold`/`warm`), `large_probability` (0–1), `cluster_probability` (0–1 — a cluster instead of a single ruin).
- `ruined_portal` — ruined portals: `setups` (non-empty, weighted list of `{weight, placement (see below), air_pocket_probability (0–1), mossiness (0–1, `block_age` processor param), overgrown (jungle leaves), vines, can_be_cold (lava → netherrack when cold instead of 20% magma blocks), replace_with_blackstone (`blackstone_replace` processor)}`). Placement methods define min/max Y (random between, or the min if max < min), using h0 = highest non-air block at the point, h1 = the template's height (see the wiki for per-method formulas).
- `shipwreck` — shipwrecks: `is_beached` — true: on the highest non-air block; false: on the highest motion-blocking block.

## Behavior

Structure definitions load once at server startup (`/reload` doesn't reload them — restart). Structures generate via structure sets in "Generate structures" worlds or directly via `/place structure <id>`.