tinyworld-opacity-torch
GitHub管理Tiny World中幽灵板与预览板的可见性逻辑,实现基于相机视角的渐进式揭示及持久化状态,控制透明度、缩放过渡及交互限制。
Trigger Scenarios
Install
npx skills add jasonkneen/tiny-world-builder --skill tinyworld-opacity-torch -g -y
SKILL.md
Frontmatter
{
"name": "tinyworld-opacity-torch",
"description": "Use when changing ghost boards, multiplayer preview boards, panning, ghost visibility, jigsaw reveal, or any visibility behavior around the active Tiny World board."
}
Tiny World Visibility — Sticky Preview Reveal
The opacity torch is gone. The home board is always fully rendered; Preview cells reveal one-by-one as the camera pans into them, and stay revealed forever after that (a breadcrumb trail behind the user).
Mental model:
- Every user has one editable home board (size
GRID, default 8). - The home
GRID x GRIDregion is always at full opacity, full color, full scale — never fades, never pops. - Preview boards surround the home board and preview other users' content.
- Nothing is rendered in grayscale — all tiles use their full color.
- A Preview cell is hidden until it enters the visible square around
target.x/z(renderVisibleSizewide). Once revealed, the cell is sticky:root.userData.revealed = trueand it stays revealed for the rest of the session. Its final display opacity is controlled by the user-facing Preview opacity / floors / objects sliders.
Reveal rules:
opacityAtWorldPosition(x, z)returns:1inside the home GRID square,1inside the visible window around the camera target,0otherwise.
revealOpacityFor(root)wrapsopacityAtWorldPositionand adds stickiness. Once it sees a positive opacity for a root it setsuserData.revealed = trueand returns1from then on. Per-frame update loops (updateGhostRenderBubble,updateHomeBoardFade) call this instead ofopacityAtWorldPositiondirectly so revealed cells don't disappear when the camera moves away.updateHomeBoardFadeshort-circuits in-grid cells to opacity1— they never go through the reveal path.tickOpacityTransitions(dt)eases each root'scurrentOpacitytowardtargetOpacityat ratedt * 20for a snappy snap-in.- During the transition, root scale follows
0.6 + 0.4 * currentOpacity, so revealed tiles grow from 60 % to full size in <200 ms. At opacity 1 the scale is exactly 1 — static home tiles and previously-revealed cells stay untouched. userData.landing(drop-in animator) takes priority — skip the scale pop while landing.desaturateMaterial()is now a no-op; all Preview / out-of-bounds tiles render in full color.
Interaction rules:
- Left-click edits only the central home board through
pickTile. - Preview board meshes must not set
userData.gx/gzon their tile/object roots in a way that lets them be edited. - Right-drag pans. Space+drag pans. Left-drag orbits.
- Panning is unrestricted:
clampTargetToHomeBoard()is no longer called from the pan paths (panCameraByPixels/panCameraByCellsin02-cameras-lighting.js) or the minimap click-to-go (30-ui-boot-wiring.js), so the camera target can move anywhere regardless of Autoexpand. The clamp helper is retained only for the explicit Autoexpand-OFF reset (which recenters to the home board). Note: with Autoexpand off, panning beyond the home board shows empty water/sky becausemaybeEnsureGhostBoardsAroundTargetearly-returns whenrenderAutoExpandis false — turn Autoexpand on to reveal preview boards.
The home board has a thin dark ground-line border (see
buildHomeBorder() in the home board border section) so the user can
always see where the editable region ends, regardless of how much of
the Preview world has been revealed around it.
- Preview distance/window auto-scale from
GRIDon first load and whenever board size changes: small boards can preview farther; large boards keep neighbour preload distance/window tighter for performance. Users can still override those settings from Settings → World. - Landscape-mode ghost-board suppression must be scoped to an actually active
isLandscapeMeshActive()engine. If the user leaves terrain/landscape mode, normal Autoexpand should immediately restore classic Preview ghost boards. - Preview objects must always stay full-fidelity. Do not render ghost-board
houses/trees/crops/rocks/animals as cheap proxy boxes, cones, or pyramids at
any zoom level. If a grid size is too expensive for full Preview boards,
reduce/disable preview rings through
renderBudgetForGrid()instead.
Validation:
- The home
GRID x GRIDboard never fades and never scale-pops. - Panning forward should reveal new Preview pieces one cell at a time with a tiny scale-up pop.
- Panning back over previously-revealed territory should keep that territory at full opacity (no re-fade, no re-pop).
- Out-of-range cells the camera has never seen should be
root.visible = false. - No tile should appear washed-out / desaturated.
pickTile()over a Preview board should still returnnull.- Home board outline should remain visible at every grid size (8 / 12 / 16 / 20).
Continuous Landscape Mode Visibility & Panning
When landscapeMeshMode is active (procedural Canyon landscape style):
- Clipped Diorama: If the user has not panned the camera yet, the landscape is clipped strictly to the home board (
GRIDsize) to present a clean, sliced diorama look. - Dynamic Panning: Unlike standard mode (which clamps camera panning to the home board), landscape mode allows the camera to pan freely.
- Dynamic Clip Bounds: On the first camera pan,
hasUserPannedis set totrue, and the landscape clipping radius expands torenderVisibleSizewithin the 20x20 home-board cap and centers on the camera target. This allows continuous terrain chunks to generate and "paint in" dynamically as the user explores the surrounding landscape, while the 8x8 home grid remains centered and intact. - Reset to Diorama: When a new scene is generated, loaded, or reset,
hasUserPannedis reset tofalse, restoring the clean sliced diorama look centered on0, 0until the user starts panning again. - Pixel Outline Clipping: During normal/depth outline passes, the active clipping planes are copied to
pixelState.normalMaterial.clippingPlanesto prevent out-of-bounds clipped mesh segments from rendering outline "ghosts".
Version History
- 2ffaf91 Current 2026-07-06 00:20


