96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
# Floating-island geometry
|
|
|
|
[`scripts/voxel-island.py`](../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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
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.
|