The seam, layer by layer

Where a ported base meets freshly generated land, the old terrain and the new one never line up: they come from different world generators. Tinfoil doesn't hide the step, it turns it into a place: a calm, sunlit river forest round every base, with still water a few blocks below the base's edge, green islets, jungle trees hung with lianas, ruins of a lost golden city and water that glows at night. This page explains how that landscape is built, from the chunks the porter keeps to the biome the last pass paints. The same machinery grows the Ley Falls sites in any world.

The commands to run a fold are in Folds; this page is about what happens inside one.

#The idea in one picture

Every column of land around a base gets a zone and a target height from the planner. Read outwards from the base: a narrow lip at the base's own height, zero to two low terrace pools, the lagoon (wide, still water with islets and a slow channel), a bank, and an outer slope that eases down (or up) to the new land. A green belt of river forest grows along the water, and the whole seam is painted with its own biome so grass, leaves and water have the same warm colours whatever the generator put there.

#Layer 0: what comes over (the porter)

The porter decides which chunks of the old world are kept. Each base's chunks with player builds come over, plus a margin of natural ground around them:

The last rule matters most for a calm seam: a big height step has to be folded away somewhere, and the further out the edge lies where the two terrains already agree, the less the fold has to do. On the release world it halved the typical step left at the edge (from 12 to 6 blocks at the 75th percentile). Growing the margin evenly in every direction doesn't help (the step stays the same three rings out); only growing towards agreeing ground does.

Margin chunks hold no player builds, so the fold is allowed to reshape them: before planning, the margin wears away along a wandering line 6-24 blocks from the nearest build where the base meets dry land (and under water), so the edge of the base never runs along a chunk line. Where the base meets the sea, the sea stays its seam.

#Layer 1: the survey

The fold job reads every column of its grid (the mask plus a band of 160 blocks round it): the ground height (top solid block, ignoring plants, leaves and logs), the top block and whether the column is under water. While reading it also decides what it must leave alone:

• Structures (villages, temples, the Ancient Islands, other mods' buildings) are protected piece by piece, each with a margin of 3-12 blocks that wanders, so the bank that forms round them is round, not boxy. Empty markers are ignored; little things (a raft, a pile, a sign: fewer than 40 built blocks) are cleared away, unless players live there.
• Lived-in chunks (a Ley Falls site in a world with players: chunks with more than five minutes of player time) are left alone like structures.
• Trees standing in the way are noted, to be felled whole later (never half buried, never left hanging).

#Layer 2: the plan

The planner is pure logic (no Minecraft code), so the whole layout can be computed and drawn offline in a second from a saved survey (./gradlew seamPreview). Its steps:

1. Distance field. Every band column learns its distance to the base and which edge column of the base is nearest. The distance is domain-warped by noise, so shores and terrace rims never trace the base's outline.

2. Edge heights. Each edge column of the base gets a height: the median of the base's border nearby (a tower on the edge doesn't count), smoothed again over a 24-block stretch, so the water levels around the ring change slowly, not at every step of a jagged built edge.

3. Levels. The lagoon's level is the edge height minus 4-7 blocks, rounded to a 4-block grid. Where the edge changes height, the boundary between two levels wanders (two warped look-ups interlock) instead of running straight out from the base. By the coast the lagoon never sinks below the sea; a low base gets a moat a few blocks below its lip.

4. Zones, by warped distance:

   zone	width	what it becomes
   LIP	2	ground at the base's height: where falls pour off
   TERRACE	7-12 each, 0-2 of them	a pool one step (4 blocks) below the one before; against a steep stretch of edge they are dry grass shelves
   LAGOON	60-100 % of the lagoon width (44)	still water, floor 2-8 deep, a 6-deep channel along the middle
   ISLET		green islets in pools and lagoon (their outlines wander too)
   BANK	4	one or two above the water
   OUTER	the rest of the band	a smooth fall-off to the new land, about 3 blocks out per block down

5. Making it hold. Every water column must be held: each neighbour is water at the same level or ground at least one above it, or the low ground is raised into bank. Water never touches lower water: steps of one or two between neighbouring pools merge, and where two waters lie further apart (a terrace above the lagoon, a pool on a high stretch of edge beside a lagoon held at sea level) the higher pool gives up a 4-block strip along the step to a bank between them. The fold sets its water without updates, so water beside lower water would stand as a slab or a wall of still water over it. Falls pour on purpose only off the lip. Where a bank would stand as a wall over the land behind it, that land is raised into an embankment falling about a block per block, so no dam faces show.

Rock pinnacles in the lagoon and rock buttresses splitting falls into curtains exist in the planner but are off in the calm style. The first fold's look (a deep gorge, tall tiers, falls round every base) is still one setting away; see The knobs.

#Layer 3: terrain

The plan is applied column by column. Raised ground is built of calm rock: plain stone with broad patches of mossy stone, no block-by-block mix of stone kinds; then two blocks of dirt and a grass top (snow stays snow). Carved ground is cut down to its target and, under the sea or a lake, the cut fills with water instead of air. A tree that would be buried or left in the air is felled whole: its logs (connected corner to corner, branches included) and, later, its leaves; trees with a log in a base or a protected structure keep their canopy.

#Layer 4: water

Pools and the lagoon fill to their levels. The floor is dressed with sand, gravel, clay and moss, now and then a sea lantern glowing up through the water; the lagoon's walls are made solid down to the floor so nothing drains into caves. Lily pads, flowering pads and duckweed float in a few loose patches (about one column in twenty), open water between them; in the shallows stand cattails.

Lights. At night the lagoon glows, sparingly (about one column in ten): glow anemones in small reefs on the floor, a few lumen jellies drifting in deeper water, thin clouds of sea sparkle between, all waterlogged. Each comes in six colours (teal, gold, rose, violet, lime, azure); the colour is chosen per patch of about 20 blocks with wandering borders, so one reef or cloud glows in one colour and the next in another.

Falls. A few chosen runs of the lip pour over into the water below (about a sixth of the lip, never where an upper pool lies right below it, never more than 10 blocks down, and only where the old land behind holds the water). Where a tall stretch of base edge stands over a lagoon held at sea level, the lip stays dry: a sheet pouring 30 blocks would be a wall of water, not a fall. A separate falls pass adds a few more where water really spills over a cliff edge, each with a plunge pool.

#Layer 5: overgrowth

Faces. Where a cliff face is six or more blocks tall, it is bare, clean stone: the face's dirt, granite, ores and mossy patches become stone (deepslate below y 0), one block deep, and nothing grows on it. Lower walls get vines, signal moss and glow lichen. Steep slopes show rock instead of grass.

The belt. Along the water, out to 16 blocks past the bank, grows the river forest:

• small jungle trees (a trunk 4-7 tall, a round crown, lianas hanging from its rim, a cocoa pod or two) and jungle bushes;
• Ley bonsai, the whimsical note, more often on islets, and weeping figs;
• undergrowth as dense as an average forest floor (about a third of the ground): grass, ferns, now and then a large fern or tall grass, moss carpet and azaleas, bare grass and moss between;
• flowers in drifts, one kind per drift, in warm colours: hibiscus, day lilies, proteas, Incan lilies, orchids, torchflowers, tulips, dandelions (a single cool orchid as the accent);
• now and then a stone lantern on a garden islet.

Further out, on grass, the same plants grow more sparsely.

Ruins. Every 48 blocks or so (a jittered grid) a ruin is tried on level enough ground, a block clear of the water; plaza pieces get a small level site. About two in three are Eldorado pieces in warm sandstone with a little gold: stepped sun terraces with a gilded sun disc, small idol shrines with a golden idol on the altar and gilded roof corners. The rest are Atlantean: broken arches, colonnades, fountains that still run, temple steps, a giant ammonite, fallen columns, in sea-worn marble or Bermuda stone. Plants on a ruin get soil under them.

#Layer 6: clean-up

Blocks are set without neighbour updates (fast, and nothing pops off half-way), so the fold cleans up itself: anything left hanging in the air (a plant over a carved hollow, sand over a hole, leaves whose log went) is found as a group that touches neither the ground nor anything outside the band, and removed; natural leaves with no log within six decay at once; a second tidy takes what hung from them. Dropped items in the band are cleared, never in kept ground.

#Layer 7: the biome and life

The biome. The seam is painted with its own biome, tinfoil:ley_seam: the colours of the Ley Falls biome (grass, leaves, jade water, a warm haze) with the overworld's usual animals and monsters. Painting works on Minecraft's biome cells (4×4×4 blocks): a cell takes the biome if all its columns lie in the band, none is in the base or kept ground, and it lies within the seam proper (the water, the bank, the belt and 16-36 blocks beyond, along a wandering line), from 12 blocks below the ground upwards, so caves deep down keep their own biomes. Players' clients get the new biomes at once.

Every block the seam places is checked against this palette (warm yellow-greens, ochre and earth, neutral stone; the lights and flowers as accents) by a probe that reads each block's texture and applies the biome tint.

Life. Tropical fish in the pools and the lagoon, axolotls in the deep water, frogs on the shores, glow squid in the deepest water, parrots in the trees; all persistent, each with its natural variant.

#Undo

After every pass the job saves what it changed, per chunk: each block's old state, the data of any block entity it replaced (a chest keeps its contents), the old biome of every painted cell, and the dimension. /tinfoil fold undo <name> puts all of it back, so a fold can be tried, judged and redone.

#Ley Falls sites

In a world without a port, Ley Falls brings the same landscape: when a site's chunk first loads, a ruined citadel is built and an ordinary fold job grows round it (the same planner and dressing, sparing chunks players live in). When it finishes, the site becomes the Ley Falls biome itself, which, unlike the seam, has no monsters and earns its own advancement.

#The knobs

The layout reads config/tinfoil-fold.json (written with the defaults on first use; edit it and redo a fold, no restart). The main ones:

In tinfoil-common.toml ([folds]): bandWidth 160, lagoonWidth 44, fissureDepth (the channel) 6, fallsPer100Blocks 0.4, seamBelt 16, ruinSpacing 48, overgrowth 1.0, seamBiome true. A config written by the first fold with its defaults untouched moves to these values by itself.