Tinyworld Island And Planes

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.