Separate map projects and add reusable island and operator camera tools

docs/FLOATING-ISLANDS.md

@@ -0,0 +1,95 @@
+# 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.