minecraft-builder-mcp/docs/FLOATING-ISLANDS.md

Floating-island geometry

scripts/voxel-island.py is a deterministic offline Python helper. It returns solid vertical columns for a floating island. It does not contact Minecraft, place blocks, or register an MCP tool. Surface grading, materials, buildings and gameplay remain the caller's responsibility.

Run this example from the MCP checkout:

import importlib.util
from pathlib import Path

spec = importlib.util.spec_from_file_location("islands", Path("scripts/voxel-island.py"))
islands = importlib.util.module_from_spec(spec)
spec.loader.exec_module(islands)

columns = islands.columns(
    cx=120, cz=-80, radius_x=18, radius_z=13,
    surface_y=144, depth=30, seed=27, contour=0.055,
)
for (x, z), column in columns.items():
    for y in range(column["bottom"], column["top"] + 1):
        pass  # Add this coordinate to an offline blueprint, with a chosen material.

bottom and top are inclusive integer block coordinates. radial is normalized distance from the shaped outline: zero at the centre, one at the rim. The top is flat; modify it deliberately for circulation instead of adding surface noise by default. Keep generated volumes bounded before expanding columns into voxels.

Shape and noise

The outline starts with an ellipse. After dividing offsets by the two radii, the angular boundary is 1 + contour * (sin(3θ + phase) + 0.45*sin(7θ - phase)). Low-frequency lobes establish a readable silhouette; the weaker seventh harmonic adds smaller variations. Accepted contour strength is 0..0.2. The boundary therefore remains positive and at most 1.29 times the base ellipse; the helper's 1.3-radius sampling envelope contains it.

The underside uses a radial taper, (1 - radial**1.55)**0.62, multiplied by correlated value noise sampled every 7.5 blocks. A smaller field sampled every 3.8 blocks adds hanging ribs. Smoothstep interpolation makes neighbouring samples coherent. Thickness is rounded once and is at least three blocks. depth controls the main taper, not an exact maximum thickness: the base and ribs add several blocks. Read the returned bounds instead of predicting a fixed lowest Y.

Use broad noise fields for material bands as well. Independent random material choices at every block create speckles and conceal the shape. Keep the seed and generator version with the resulting blueprint. The underside noise is anchored in world X/Z: moving the centre preserves the translated outline but can change its thickness field.

This column model is a structural starting point. A flat top with many similarly tall perimeter columns can look like a cut cylinder even when the outline and tip are irregular. Inspect an actual oblique close view before adding more noise. Use a few connected clefts, varied rock ribs and restrained edge vegetation to break the sidewall silhouette. Keep a clear fighting or walking surface where the design needs one; sculpting the underside does not require roughening every usable floor. Preserve a versioned baseline and validate support again after the decorative pass.

Checks before placing a blueprint

• Flood-fill the intended top footprint using four-neighbour adjacency. The continuous outline is radial, but discrete connectivity should still be checked for the chosen radii and seed. Check separate islands remain separate.
• Require the entire base of each pier, stair approach and planter to have support. Testing only the centre of a building misses unsupported outer piers. Never skip unavailable foundation cells and then place the complete building above them. Move the feature inward or author a connected plinth first.
• Check plant substrates and lantern attachment faces against the final combined blueprint. Hanging lamps need a real beam/chain; slabs and stairs need their actual state and collision height considered.
• Verify each spawn has its intended floor and four clear blocks above it. Check routes through the final furnishings with their actual standing heights; drawing a ring in the floor does not prove that the ring remains traversable.
• Measure all intended gaps and landing areas. A block count is geometric evidence, not proof that sprinting, knockback or a configured double jump can cross the gap. Confirm those interactions on the running server.
• For void arenas, inspect every exposed standing surface below the main deck. Place the elimination threshold to prevent unintended recovery ledges or sheltered camping pockets, while leaving the visible underside intact.

The supplied regression checks cover reproducibility, negative coordinates, sampling bounds, solid column intervals and representative discrete connectivity:

python3 -m unittest discover -s scripts -p 'test_voxel_island.py'

Use the normal checked MCP editing path to modify an existing world. Loading an offline blueprint as the initial generator of a new world is a separate operation; it does not acquire block-by-block editor undo simply because this helper produced the geometry.