tinyworld-island-and-planes

name	tinyworld-island-and-planes
description	Use when changing the home island layout, edge dressing, undersides, autoincentive sponsor banner (now a top-left logo-adjacent DOM banner), plane/crop-duster flight paths, banner streamers, or which side of the island is "front".

Tiny World Island & Planes

Coordinate system + camera-facing side

• The home island is centred at world origin. Top of grass = y = 0. Underside of dirt slab + inverted stepped underside extends down from there.
• GRID (default 8, max 20, ranges from HOME_GRID_MIN to HOME_GRID_MAX) × TILE (=1) sets the edge length. Half-width = (GRID * TILE) / 2.
• DIRT_H = 0.55 — visible dirt block height.
• Default camera: DEFAULT_AZIMUTH = π * 0.32, DEFAULT_POLAR = π * 0.30 → camera sits in the +X +Z quadrant looking back at origin. The +Z face is the "front" of the island (most camera-facing side).

buildHomeBorder() flow

Defined ~line 16340. Rebuilds the island's undersides and edge dressing every time the home grid changes:

clear homeBorderGroup children
vbox(... underside slab ...)
voxelInvertedSteppedRoof(... cascading underside ...)
addIslandRocketEngines(homeBorderGroup)
addIslandEdgeDressing(homeBorderGroup)    // tufts, rocks, dirt accents
(island front drape removed — autoincentive now a top-left logo-adjacent DOM banner)
prepareHomeBorderForRender(homeBorderGroup)
buildDistantWorlds()
buildUnderIslandClouds() (if defined)

Anything you add that should live on the island should be appended inside buildHomeBorder() so it rebuilds correctly when the user changes #render-home-grid (the home board size selector).

Some of the round underside pipes emit a faint output from their outer (side-facing) end — clear water, murky brown water, or steam — via the pipe-emitter system in 23-particles-clouds.js (registerPipeEmitter / updatePipeEmitters, ticked next to updateSmoke). addIslandUtilityUnderside (13-distant-dressing-ghost.js) registers ~32% of pipe runs (split water/murky/steam) at their end; buildHomeBorder calls clearPipeEmitters first. Emitter coords are local to homeBorderGroup; particles live in xrWorldRoot, are capped at 140, and only spawn when camera.position.y < 4 (underside in view). Water/murky fall under gravity; steam rises and expands.

The home island underside (slab + voxelInvertedSteppedRoof), the island edges (addIslandSideBacking), and the underside greebles (addIslandUtilityUnderside trays/clamps) now honour the Voxel bevel setting (renderVoxelBevel): their vbox calls no longer pass noBevel/skip* (which would route to the un-beveled getOpenBoxGeometry). voxelInvertedSteppedRoof is shared, so editable islands and the new-island stamp underside bevel too. Cost note: at max bevel (0.06) the merged homeBorder geometry grows ~13× (the many tiny greebles each round), so keep bevel modest. The distant ghost-island dressing (tiny far preview islands) intentionally stays noBevel for perf.

Island shell materials (M.boardSide, M.boardSideEdge, M.islandUnder, M.islandUnderD) opt into the world-UV shader pass in 04-textures.js. Grass tile risers use M.boardSide and should read as dirt/soil directly under the grass cap, not rock; keep that material on the soil-side texture family. The dedicated strata side backing (M.boardSideEdge) can still show deeper soil-to-rock banding lower down, while underside materials use textures/island-underside-voxel.png (texIslandUndersideVoxel) so the bottom reads as larger dark beveled voxel blocks; keep replacement shell art seamless and power-of-two because Three.js repeats it with mipmaps. The shader pass darkens a coarse horizontal/vertical side grid and lightly modulates each block/underside cell in the fragment shader. It uses world position/normal varyings, so the large merged side slabs read as chunky voxel blocks without adding geometry or draw calls. islandShellMaterial() in 03-geometry-materials.js copies Lambert onBeforeCompile hooks and explicitly preserves ShaderMaterial uniforms/source so the side-backing clone keeps the same coarse grid/strata shader instead of falling back to a black shell.

Island edge strata is shader-driven on the side backing only: addIslandSideBacking uses the dedicated M.boardSideEdge shader material for lower dirt/rock backing. Do not restore the old continuous green grass-cap carrier at the top edge: it reads as a thin floating strip around the island in Build/tilt-down views. Per-cell terrain and mesh-terrain side walls own the top edge; the backing should stay darker/lower behind greebles. Keep the four backing faces widened by the edge outset so corners meet cleanly, and keep hidden faces stripped with skipTop / skipBottom / interior-side skips. Keep the side-carrier meshes out of static base merging so the shader stays inspectable; do not add separate overlay panels or per-tile decal geometry for this effect. The dirt/brown band in island-side-strata-gpt.png should match the darker soil-side/M.dirtRich greeble palette, not bright orange. Keep the band near the dark brown family used by side greeble blocks so the bitmap and geometry read as one material.

Underside pipes and water details are material-driven: M.utilityPipe, M.utilityPipeD, and M.utilityClamp use the internal pipe-metal canvas texture; M.waterFoam and M.waterfallFoamPuff use the internal water-froth canvas texture. Keep these procedural unless the user asks for a specific bitmap, because they apply to many tiny utility meshes and particles.

Editable-island LOD + whole-island select/delete

• Two gates decide an editable island's LOD: a distance gate (editableIslandBaseDesiredLod, full within max(40, span*5.2)) and a count budget (editableIslandFullLodBudget, now +8: all full up to 14 islands, then 12/11/10). Both were widened so a placed cluster of ~8 islands keeps its real base + per-cell surface instead of dropping to the flat proxyGroup (which is what "island without a base / different surface" was).
• Click an island's side (no cell/object there) with the Select tool to select the WHOLE island: pickEditableIslandBody (18-scene-pick-xr.js) walks up to userData.editableIslandId (excludes home). It outlines the island (setIslandSelectionOutline, a box-edges LineSegments child of island.group so it follows move/rotate) and raises the move gizmo.
• Delete/Backspace on a selected island (no cell selection) calls removeEditableIsland — undoable, because the world-history snapshot includes serializeEditableIslands(). It clears the island's board cells, moorings anchored to it, registries, and selection.

Island placement: 4-side holograms

With the Island tool active, hovering an island shows a blank-island hologram on each of its 4 free cardinal sides at once (37-island-placement-holos.js, reuses islandPlacementSlots(anchor).slice(0,4) + makeBlankIsland + makeGhostHoloMaterial). Occupied sides and the home origin are filtered out ("minus blocked by anything"). Hovering a hologram highlights it (uBase 0.10->0.36, brighter blue, slight scale-up) via a per-frame raycast in updateIslandPlacementHolos(x,y); clicking a hologram places there. GOTCHA: hover-test the holos first and keep the anchor sticky — pickTile ignores the holos, so recomputing the anchor while hovering a hologram flips it to whatever (home/other island) sits behind it and rebuilds the holos out from under the cursor (they "disappear" on click). Only re-anchor when hovering a different island; keep holos over empty space (applyToolToCell checks islandPlacementHoloHoveredSlot() first, before any island-select). selectTool clears the holos when switching away; the holo shader uTime ticks via tickIslandPlacementHolos. The single snap-to-slot hologram path is bypassed for the Island tool. GOTCHA: when cloning the ghost-outline hull, collect mesh nodes before o.add(hull) — adding during traverse recurses into the new hull forever (stack overflow).

Newly placed editable islands warp in instead of popping into place. The effect lives in 14-editable-islands-moorings.js: startEditableIslandWarpArrival() starts a short blue-white streak/tunnel + arrival flash, and tickEditableIslandWarpArrivals(dt) runs after updateEditableIslandLods() so it can override LOD visibility during the arrival. Default creation triggers the effect, while restored/imported/stress-demo islands with skipSave: true do not; use warpIn: true explicitly for future multiplayer join arrivals. The final saved transform remains island.positionX/Y/Z + rotationY; the warp only moves/scales the render group temporarily.

The home island is not movable: its editable surface lives in the shared world grid (worldGroup, picked by logical gx/gz), while only homeBorderGroup (the base) is its transform group — so dragging it would shift the base away from the locked surface. updateTransformGizmo (12-selection-tool.js) refuses to bind the move gizmo when selectedEditableIsland().__home is set (selecting a home engine sets selectedEditableIslandId = 'home', which previously let the gizmo grab it). Sky/editable islands stay movable. Making the home island truly relocatable as one piece would require re-parenting the home cells into a movable group and routing their picking through that transform (as editable islands do).

Island engines (home + editable, userData.editableIslandEngineId) can only be selected from underneath: pickEditableIslandEngine (18-scene-pick-xr.js) early-returns null when camera.position.y >= 0. Otherwise a pick ray from above passes through the board and grabs the engine hanging behind it. Mirrors pickTile's "refuse picks from below the surface" convention, inverted.

Home-island rocket engines keep their chunky voxel casing, but the animated jet plume is a small set of static or simply X-flipped shader sheets. Do not rebuild it as many per-layer flame cubes; the sheet approach keeps the underside readable while staying cheap for large-island scenes. Keep older voxel object builders as inactive legacy helpers rather than deleting them; they may be useful again for alternate engine styles or detail settings. The jet plume sheets are underside-only effects: tickIslandRocketEngines hides rocketPlumeSheet meshes when the camera is above the engine/island surface gate, and their compact sheet dimensions are guarded by tools/check.js. Do not let them billboard through the board or become a surface-level white/cyan cloud in normal build/play views.

Autoincentive sponsor banner

The PNG/JPG ships inline as AUTOINCENTIVE_BANNER_DATA_URL (~41 KB base64 JPEG) so there's no extra HTTP. Same data URL feeds:

1. A fixed DOM banner next to the top-left Tiny World wordmark (assets/twlogo-wordmark.png, logo-only crop with the island removed) on wide screens, dropping below the logo at medium widths and hiding on phone widths (<a id="brand-banner"><img id="brand-banner-img">), src set by the applyAutoincentiveSponsorLogo IIFE. Clickable, opens https://x.com/Autoincentiv3. Hidden in showcase + XR via .brand-banner rules in styles/tiny-world.css.
2. The sponsor logo in the Workspace settings panel (<img id="sponsor-logo-autoincentive">, populated by the same IIFE).

The old 3D island front-facing drape (buildIslandFrontBanner / tickIslandBanners, a flapping cloth mesh on the +Z side) has been removed from the scene: the call in buildHomeBorder() (13-distant-dressing-ghost.js) is gone, so the functions remain defined but inert (legacy). tickIslandBanners still ticks but is a no-op while islandBannerEntry stays null.

If the user changes art, swap the data URL and the 2.5:1 aspect — width fits ~GRID * 0.7.

Plane / crop-duster system

Defined in the crop duster route / state section (~line 26200).

• 3-plane pool (planes[]), shown in formations or solo.
• Persisted setting tinyworld:render:planesEnabled controls the whole system and defaults off for now. When off, the GLB/textures are not loaded and hidden banners/crop-dust particles are cleared.
• Two run kinds chosen randomly each cycle:
  • startDustingRun() — uses planDustingCurve() to sweep over crop cells.
  • startBannerRun() — uses planBannerCurve() to fly behind the island so the towed text banner reads against the sky.
• planBannerCurve() places the path at target.z - (GRID * 0.5) - (GRID * 2) — i.e. ~2 island lengths behind the back edge. Altitude is Math.max(renderCloudHeight + 0.2, FLIGHT_CRUISE_ALT - 1.6) — a touch lower than the dusting cruise altitude.
• Engine sound is jet/rocket — use foley-rocket-engines-1..4, NOT foley-propellers-* or large-prop-engine-* (the model is a jet).

The towed banner cloth uses updatePlaneBannerFlap (per-vertex sine wave travelling along the X axis). Banner messages come from BANNER_MESSAGES.

When changing layout

• "Front" side of island = +Z. North/South/East/West correspond to ±X / ±Z; do not assume Y-up screen coordinates.
• The new-island tool creates an editable duplicate island board, not a cell object. It keeps its own logical board coordinates so normal tools keep using setCell(), while the island group handles X/Y/Z positioning and Y rotation through the gizmo. Do not expose scale for island-board transforms.
• New editable islands should not seed every default grass cell through setCell(). Keep default grass virtual, add one pickable default-surface mesh for the board, and materialize sparse per-cell meshes only after the user edits a cell.
• Duplicate island undersides use static voxel lift engines ported from voxel_lift_engine.html: propellers face downward and the thrust/plume/glow system remains off. Do not register these with islandRocketFlames or islandRocketEngines.
• For duplicate-island lift engines, the engine wrapper rotates local axes downward. Keep propeller local X/Y offsets at 0 so it stays centred on the visible lift shaft; use local Z (currently EDITABLE_ISLAND_PROP_LOCAL_Z = -2.84) for the lower shaft mount, and keep the short non-spinning spindle sleeve at EDITABLE_ISLAND_PROP_SPINDLE_LINK_Z so the propeller visibly connects to the shaft. Keep the legacy large outer hub cap and old two-cube hub blocks behind opt-in flags; the default propeller should not show block lumps on top of the shader/blur disc. High-RPM readability comes from the shared dark shader blur/strobe disc, while the voxel blade groups are a startup/slow-spin visual.
• Duplicate island lift engines are island attachments, not board cells. Persist their engines state on the island record, stamp engine meshes with editableIslandEngineId for raycast selection, and tick their propellers from the central animation loop.
• Mooring cables are point-to-point world decorations, not board cells. Store only anchor records in moorings (scope: home|island, optional islandId, and local {x,y,z}), rebuild their TubeGeometry under the non-pickable mooringGroup, and include them in undo/export/save state. When placing a cable, raycast exact surface points rather than pickTile() so underside picks work, and reject routes that pass through registered propeller, jet engine, or rocket plume hazard spheres.
• Mooring anchors are tied to the current board/island surface topology. Clear them with clearMooringCables() on home-grid changes, starter-scene resets, and demo paths that replace islands; imports can then restore valid saved cables with replaceMooringCables() after islands have been recreated.
• Number duplicate-island engine slots around the island. Slots 1 and 3 spin clockwise; slots 2 and 4 spin anticlockwise, so diagonal props match while adjacent props counter-rotate.
• Duplicate island bases should reuse the home-island greeble layers: addIslandUtilityUnderside() for underside pipes/cables/boxes and addIslandEdgeDressing() for grassy/dirt/rock edge chunks.
• Any new edge dressing must be added inside addIslandEdgeDressing() (per the existing per-edge loop with cellRand noise) so it stays consistent across all four sides.
• Anything anchored to the island that animates must be ticked from the central animation loop (call sites near updateCropDuster(dt) in renderer.setAnimationLoop(animate)).
• Duplicate islands use LOD: selected/near islands show full base/content, mid/far islands show cheap proxy slabs, and hidden islands skip content, underside detail, and engine propeller ticks. Preserve this before adding new per-island animation or decoration.

Validation

After island/plane changes:

• node tools/check.js
• Visually check at default 8×8 grid and after toggling to 20×20 — sizes rebuild the island.
• Confirm planes fly behind the island, banner stays readable against the sky, and engine sound (if positional audio active) pans correctly L↔R as the plane crosses the camera.

Mooring "Connect" cables — styles + interaction

• The infra tool is labelled "Connect" (id stays mooring, t.mooring).
• Each placed cable carries a style in MOORING_STYLES (14-editable-islands-moorings.js): power (amber), water (blue), waste (green), data (purple), mooring (default dark). style is normalized (normalizeMooringStyleId), persisted via serializeMooringCables, and drives the tube material (mooringStyleMaterial). Change it with the global setMooringCableStyle(id, style) (rebuilds + saveState).
• Cables stay noPointerPick for the placement raycast. 36-mooring-interaction.js runs its own raycast against mooringGroup (only while the Select tool is active): hover swaps the cable's meshes to mooringHoverMaterial (blue); a click opens a radial (.radial-menu.mooring-radial, reuses radial CSS) to pick the style. While that radial is open a full-screen .mooring-radial-backdrop (z 45, below the buttons at z 46) preventDefault+ stopPropagations every pointer/wheel event and closes on outside click, so canvas pan/orbit cannot fire and the type buttons stay clickable. (The menu container is pointer-events:none, so without the backdrop a miss between buttons falls through to the canvas and pans.) Verify pickability with 3D math (project tube vertices → raycast mooringGroup), not screenshots.