Terraforming

Terraforming

You shape natural environments — terrain, water, and scenery — in a live Minecraft Bedrock world. Natural-looking terrain is not "random"; it follows rules. Apply them deliberately. The single biggest difference between amateur and expert terrain is discipline about the rules below, not effort.

For a named real-world natural wonder (the Grand Canyon, Niagara, Uluru, Halong Bay), use the natural-landmarks skill instead — it composes recognizable wonders from formation primitives, building on the technique here. For an intentionally designed outdoor space — a formal garden, a park, a plaza, a hedge maze — use the landscape-architect skill: that is the geometric opposite of this skill, which is deliberately naturalistic. This skill handles generic, natural-looking terrain and scenery.

Connection

If an mc_* call fails because the MCP server is unreachable, stop and tell the user to run the minecraft-mcp-setup agent.

Hard rules — read first

These two rules sit above the non-negotiables. They come from the Cape Aurelia terrain v1 disaster: a static plan of stacked rectangular fills produced a flat-topped ziggurat that had to be demolished and re-built, then the rectangular underwater foundation had to be naturalised in a third pass. Three iterations. The target is one.

1. Heightmap-or-live-sculpt for anything over ~30 blocks of extent. Stacked or nested rectangular mc_block_fill calls — even when "stepped by elevation" — produce terraces, flat tops, and rectangular outlines by construction. They cannot satisfy the non-negotiables below. For any landform larger than ~30 blocks in either horizontal axis, use one of two methods only:

   • Per-column heightmap — multi-octave value noise + radial mass falloff
     • organic blob lakes/coves + blended build pads, generated offline, baked to RLE arrays, placed as mc_structure_* tiles. This is the default for non-trivial terrain. See reference/landforms.md § The heightmap method.
   • Live sculpt — alternate mc_block_fill / mc_block_set / mc_block_get_top in a feedback loop with the user, never a static plan handed to the worker. Use for terrain that has to respond to the user's eye in real time, or to naturalise an existing mass.

   Refuse to write a static plan.toon of stacked rectangular fills as the terrain plan. If a generated plan looks like nested rectangles stepped by Y, that is the wrong method — regenerate as a heightmap or live-sculpt.

2. Foundations are terrain — including underwater. Any core mass, base, or foundation under a built landform must obey every non-negotiable. Never leave a rectangular foundation visible above or below water. Either naturalise it with banded talus skirts, corner knolls, and side mounds (reference/landforms.md § Naturalising an existing rectangular mass), or bury it completely beneath naturalistic terrain with no flat face exposed. The lit underwater band runs from the seabed to roughly seabed + 20; below that, fog black hides detail. Above sea level and within the lit underwater band, every face counts.

   The same rule binds the orchestrator: if the planner or blueprinter tries to spec a separate rectangular "corestone megablock" beneath a headland, that block was the seed of the Cape Aurelia artifact. Refuse it. Terrain owns its foundation.

3. Water columns reach the seabed. Any terrain tile that includes coastline or harbour must extend from the seabed up. Water columns carry real water all the way to the floor — never a void-over-rock dry shelf at the waterline.

Prototype-first — no large terrain without a visual checkpoint

Before committing to a terrain area over 100 blocks of extent, build a representative **20×20 prototype patch** of the planned technique (same heightmap, same palette, same module set, just smaller). Sample it, then ask the user to glance before scaling up. One quick "looks good" prevents a full demolition; the Cape Aurelia v1 ziggurat would have died as a 20×20 patch instead of as the whole headland.

This is mandatory, not optional. Quality and craftsmanship are the bar — a five-minute checkpoint that prevents a multi-hour demolition is always worth the time.

The non-negotiable rules

These apply to every terrain pass. Violating them is what makes terrain read as "kindergarten":

1. The 7-block rule. Never place more than ~7 blocks in a straight line on anything organic — an edge, a ridgeline, a coastline, a riverbank. Break the line: jitter laterally by 1–3 blocks every 4–7 blocks. (Builder BlueNerd, via minecraft.net.)
2. Double-layer everything. Always ≥2 blocks of substrate under a surface — dirt under grass, sandstone under sand. A single layer reads as paint and one Enderman punches a hole in it.
3. No monoculture. A surface that is 100% one block reads as paint. Mix 4–8 variants at calibrated ratios (see reference/palettes.md).
4. No straight lines, no pure 45° slopes. Nothing in nature is as square as you think. Use curves and compound slopes (convex near ridges, concave near valleys).
5. Asymmetry. No symmetric cones, no circular lakes, no rectangular anything. Irregular outlines, offset peaks, multi-lobed water.
6. Exaggerate scale. A 1-block player needs 30–50-block hills to feel "tall", 80–150 for mountainous. Vertical exaggeration and keeping trees short and away from mountain feet sells the illusion.
7. Grow trees, never place them. Never build a tree block by block or stamp the same tree twice — duplicated trees are an instant tell. Plant biome-appropriate saplings with proper spacing and light, then grow them with bone meal or a temporary randomTickSpeed boost. See reference/weathering.md.

The five-pass workflow

Build terrain in passes, not all at once. Each pass is a plan phase the worker executes; keeping them separate lets the user iterate ("make it taller") by re-running one pass.

1. Silhouette — rough the 3D shape with a single placeholder block (one stone variant). Get the outline and massing right before any detail. See reference/landforms.md.
2. Rock strata — band exposed rock and cliffs with mixed stone variants; add scree and talus. See reference/landforms.md.
3. Water — carve or fill rivers, lakes, falls, wetlands; naturalize banks and beds. See reference/water.md.
4. Biome palette — apply the biome-appropriate surface palette to the shaped land, with blended transitions. See reference/palettes.md.
5. Weathering & detail — speckling, vegetation clusters, fallen logs, moss, dripstone, bare patches. The largest quality multiplier per block of effort. See reference/weathering.md.

For isolated features (a hill on a plain) build up; for valleys, canyons, and lake basins carve down from a raised landmass.

Reference library

Read the file for the pass you are on — do not load them all up front:

How terraforming feeds the pipeline

You produce the terrain portions of the build, in the same shapes the rest of the minecraft-builder workflow already uses:

• Plan — write the five passes as phases in .minecraft-builder/<project>/plan.toon, using the standard steps table (op/a/b/block/note). Every fill must already be tiled to a safe volume (see reference/command-budget.md) — the worker runs Haiku and does no arithmetic. Resolve all coordinates to absolutes. For any landform over ~30 blocks of extent, the plan body must reference the heightmap method (one structure-place per tile, generated offline) — not a static stack of rectangular fills.
• Modules — save reusable terrain pieces (a hill core, a scree skirt, a cliff-strata block, a tree, a rock cluster) as named structures mcb:<project>_terrain_<element> (colon namespace — required by mc_structure_create_from_blocks; an underscore-only ID is rejected) via mc_structure_*, exactly as the blueprinter does. Reuse one module many times with different rotation, mirror, and integrity to get variety from one definition — this is the main force-multiplier for medium and large terrain.
• Quality contract — every terrain phase emits the silhouette / edge / mix-ratio rows from reference/non-negotiable-enforcement.md into the plan's quality_contract block, so the inspector checks the non-negotiables automatically and a violation is caught before the user has to call it out. Terrain inspection must also sample below sea level — pad walls, foundation faces, and the seabed profile, not just the above-water silhouette.
• Registry — record terrain builds and modules in the mcbuilder:registry world dynamic property like any other build.

Scale tiers

Match effort to size (full detail in reference/command-budget.md):

• 10–30 blocks — single rocks, ponds, garden features: manual placement.
• 30–100 blocks — one hill, a small lake, a river segment: a handful of tiled fills + 1–2 modules.
• 100–500 blocks — mountains, valleys, lake systems: many tiled fills, 3–6 reusable modules, a ticking area, silhouette-first.
• 500+ blocks — biomes and ranges: plan as a grid of cells, run each cell as a 100–500 job, reuse modules heavily, pace the work across many ticks.

Anti-patterns — refuse to produce these

Hand off

State the terrain plan back to the user in plain language and confirm it before building. The terrain phases are now in plan.toon for the worker, and any terrain modules are registered. Report what you shaped, where, and which modules are reusable for later iteration.