@connected-web/terrain-editor 0.1.4 → 0.1.6

package/dist/index.cjs

@@ -398,6 +398,9 @@ async function preprocessMask(file, resolveAssetUrl, imageCache, maskCache) {
 function hexFromRgb(rgb) {
   return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`;
 }
+function isRgbaLayer(layer) {
+  return typeof layer.rgba === "string";
+}
 async function composeLegendTexture(legendData, resolveAssetUrl, imageCache, maskCache, layerState) {
   if (typeof document === "undefined") return null;
   const [width, height] = legendData.size;
@@ -434,6 +437,17 @@ async function composeLegendTexture(legendData, resolveAssetUrl, imageCache, mas
     ctx.globalAlpha = alpha;
     ctx.drawImage(temp, 0, 0, width, height);
   }
+  async function drawRgbaLayer(textureFile, alpha = 1) {
+    let image = null;
+    try {
+      image = await loadLegendImage(textureFile, resolveAssetUrl, imageCache);
+    } catch (err) {
+      console.warn("[WynnalTerrain] Unable to load overlay texture", textureFile, err);
+      return;
+    }
+    ctx.globalAlpha = alpha;
+    ctx.drawImage(image, 0, 0, width, height);
+  }
   const activeBiomes = layerState?.biomes ?? {};
   for (const [name, biome] of Object.entries(legendData.biomes)) {
     if (layerState && activeBiomes[name] === false) continue;
@@ -443,6 +457,14 @@ async function composeLegendTexture(legendData, resolveAssetUrl, imageCache, mas
   for (const [name, overlay] of Object.entries(legendData.overlays)) {
     if (layerState && activeOverlays[name] === false) continue;
     const alpha = DEFAULT_LAYER_ALPHA[name] ?? 1;
+    if (isRgbaLayer(overlay)) {
+      await drawRgbaLayer(overlay.rgba, alpha);
+      continue;
+    }
+    if (!overlay.mask || !overlay.rgb) {
+      console.warn("[WynnalTerrain] Overlay entry missing mask/rgb", name);
+      continue;
+    }
     await drawLayer(overlay.mask, overlay.rgb, alpha);
   }
   const texture = new THREE2.CanvasTexture(canvas);
@@ -812,6 +834,15 @@ async function initTerrainViewer(container, dataset, options = {}) {
       updateLayers: async () => {
       },
       setInteractiveMode: noop2,
+      setMaxPixelRatio: noop2,
+      setRenderScaleMode: noop2,
+      setRenderPaused: noop2,
+      getRenderResolution: () => ({
+        width: 0,
+        height: 0,
+        pixelRatio: 1,
+        renderScale: 1
+      }),
       updateLocations: noop2,
       setFocusedLocation: noop2,
       navigateTo: noop2,
@@ -824,6 +855,8 @@ async function initTerrainViewer(container, dataset, options = {}) {
       },
       setSeaLevel: () => {
       },
+      setHeightScale: () => {
+      },
       invalidateIconTextures: () => {
       },
       invalidateLayerMasks: () => {
@@ -908,7 +941,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
     const { u, v } = pixelToUV(pixel);
     return uvToWorld(u, v, heightSampler, currentHeightScale, seaLevel, terrainDimensions);
   }
-  const heightScale = options.heightScale ?? HEIGHT_SCALE_DEFAULT;
+  const heightScale = options.heightScale ?? legend.height_scale ?? HEIGHT_SCALE_DEFAULT;
   let currentHeightScale = heightScale;
   const waterPercent = THREE2.MathUtils.clamp(
     options.waterLevelPercent ?? WATER_PERCENT_DEFAULT,
@@ -941,10 +974,28 @@ async function initTerrainViewer(container, dataset, options = {}) {
   let viewportWidth = width;
   let viewportHeight = height;
   let viewOffsetPixels = 0;
-  const renderer = new THREE2.WebGLRenderer({ antialias: true, alpha: true });
+  let maxPixelRatio = Math.max(1, options.maxPixelRatio ?? 1.5);
+  const minRenderScale = 0.25;
+  let renderScaleMode = options.renderScaleMode ?? "fixed";
+  let renderScale = clampRenderScale(options.renderScale ?? 1);
+  let currentPixelRatio = 1;
+  function clampRenderScale(value) {
+    return THREE2.MathUtils.clamp(value, minRenderScale, 1);
+  }
+  function resolvePixelRatio() {
+    const deviceRatio = window.devicePixelRatio || 1;
+    const scaledRatio = deviceRatio * renderScale;
+    return Math.min(scaledRatio, maxPixelRatio);
+  }
+  const renderer = new THREE2.WebGLRenderer({
+    antialias: true,
+    alpha: true,
+    preserveDrawingBuffer: options.preserveDrawingBuffer ?? false
+  });
   renderer.toneMapping = THREE2.ACESFilmicToneMapping;
   renderer.toneMappingExposure = 1.08;
-  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  currentPixelRatio = resolvePixelRatio();
+  renderer.setPixelRatio(currentPixelRatio);
   const hostStyle = window.getComputedStyle(container);
   if (hostStyle.position === "static") {
     container.style.position = "relative";
@@ -961,6 +1012,22 @@ async function initTerrainViewer(container, dataset, options = {}) {
   renderer.shadowMap.enabled = true;
   renderer.shadowMap.type = THREE2.PCFSoftShadowMap;
   container.appendChild(renderer.domElement);
+  const renderResolution = {
+    width: 0,
+    height: 0,
+    pixelRatio: currentPixelRatio,
+    renderScale
+  };
+  function updateRenderResolution() {
+    const bufferSize = new THREE2.Vector2();
+    renderer.getDrawingBufferSize(bufferSize);
+    renderResolution.width = Math.round(bufferSize.x);
+    renderResolution.height = Math.round(bufferSize.y);
+    renderResolution.pixelRatio = currentPixelRatio;
+    renderResolution.renderScale = renderScale;
+    options.onRenderSizeChange?.({ ...renderResolution });
+  }
+  updateRenderResolution();
   disposables.push(() => {
     renderer.dispose();
     renderer.domElement.remove();
@@ -1029,19 +1096,42 @@ async function initTerrainViewer(container, dataset, options = {}) {
   }
   const locationWorldCache = /* @__PURE__ */ new Map();
   let markerGeneration = 0;
-  const placementIndicator = new THREE2.Mesh(
-    new THREE2.CylinderGeometry(0.04, 0.01, 0.7, 18),
-    new THREE2.MeshStandardMaterial({
+  const placementIndicatorHeight = 0.26;
+  const placementIndicatorGroup = new THREE2.Group();
+  const placementIndicatorMaterial = new THREE2.MeshStandardMaterial({
+    color: 16735067,
+    transparent: true,
+    opacity: 0.85
+  });
+  const placementStem = new THREE2.Mesh(
+    new THREE2.CylinderGeometry(0.01, 0.01, 0.06, 8),
+    placementIndicatorMaterial
+  );
+  placementStem.position.y = 0.03;
+  const placementDot = new THREE2.Mesh(
+    new THREE2.SphereGeometry(0.014, 10, 10),
+    placementIndicatorMaterial
+  );
+  placementDot.position.y = 5e-3;
+  const placementRing = new THREE2.Mesh(
+    new THREE2.CircleGeometry(0.12, 32),
+    new THREE2.MeshBasicMaterial({
       color: 16735067,
       transparent: true,
-      opacity: 0.8
+      opacity: 0.2
     })
   );
-  placementIndicator.visible = false;
-  scene.add(placementIndicator);
+  placementRing.rotation.x = -Math.PI / 2;
+  placementRing.position.y = 5e-3;
+  placementIndicatorGroup.add(placementRing, placementStem, placementDot);
+  placementIndicatorGroup.visible = false;
+  scene.add(placementIndicatorGroup);
   disposables.push(() => {
-    placementIndicator.geometry.dispose();
-    placementIndicator.material.dispose();
+    placementStem.geometry.dispose();
+    placementDot.geometry.dispose();
+    placementRing.geometry.dispose();
+    placementIndicatorMaterial.dispose();
+    placementRing.material.dispose();
   });
   const loader = new THREE2.TextureLoader();
   const iconTextureCache = /* @__PURE__ */ new Map();
@@ -1267,6 +1357,31 @@ async function initTerrainViewer(container, dataset, options = {}) {
     stemRadius = computeStemRadius(markerTheme.stem);
     setLocationMarkers(currentLocations, currentFocusId);
   }
+  function applyHeightScaleUpdate(nextHeightScale) {
+    if (!heightSampler) {
+      return;
+    }
+    const prevHeightScale = currentHeightScale;
+    const nextScale = Math.max(0, nextHeightScale);
+    currentHeightScale = nextScale;
+    legend.height_scale = nextScale;
+    dataset.legend.height_scale = nextScale;
+    const stats = applyHeightField(terrainGeometry, heightSampler, {
+      seaLevel,
+      heightScale: currentHeightScale
+    });
+    terrainHeightRange = { min: stats.minY, max: stats.maxY };
+    terrainGeometry.attributes.position.needsUpdate = true;
+    terrainGeometry.computeVertexNormals();
+    rebuildRimMesh();
+    rebuildOceanMesh();
+    if (Number.isFinite(prevHeightScale) && prevHeightScale > 0) {
+      const factor = nextScale / prevHeightScale;
+      controls.target.y *= factor;
+      camera.position.y *= factor;
+    }
+    setLocationMarkers(currentLocations, currentFocusId);
+  }
   function applySeaLevelUpdate(nextSeaLevel) {
     if (!heightSampler) {
       return;
@@ -1393,6 +1508,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
     camera.updateProjectionMatrix();
   }
   let animationFrame = 0;
+  let renderPaused = false;
   let frameCount = 0;
   let firstRenderComplete = false;
   const frameTimings = [];
@@ -1450,19 +1566,32 @@ async function initTerrainViewer(container, dataset, options = {}) {
       if (currentLifecycleState === "stabilizing" && stabilizingStartTime !== null) {
         const stabilizingDuration = now - stabilizingStartTime;
         if (stabilizingDuration > STABILITY_TIMEOUT_MS) {
-          console.warn(`[terrainViewer] Framerate did not stabilize after ${STABILITY_TIMEOUT_MS}ms, forcing ready state`);
-          setLifecycleState("ready");
-          stabilizingStartTime = null;
+          if (renderScaleMode === "auto" && renderScale > minRenderScale + 0.01) {
+            renderScale = clampRenderScale(Number((renderScale * 0.6).toFixed(2)));
+            currentPixelRatio = resolvePixelRatio();
+            renderer.setPixelRatio(currentPixelRatio);
+            renderer.setSize(viewportWidth, viewportHeight, false);
+            updateRenderResolution();
+            frameTimings.length = 0;
+            stabilizingStartTime = now;
+            console.warn(
+              `[terrainViewer] Framerate unstable after ${STABILITY_TIMEOUT_MS}ms, reducing render scale to ${renderScale}`
+            );
+          } else {
+            console.warn(`[terrainViewer] Framerate did not stabilize after ${STABILITY_TIMEOUT_MS}ms, forcing ready state`);
+            setLifecycleState("ready");
+            stabilizingStartTime = null;
+          }
         }
       }
     }
-    if (!frameCaptureMode) {
+    if (!frameCaptureMode && !renderPaused) {
       animationFrame = window.requestAnimationFrame(animate);
     }
   }
   animate();
   options.onReady?.();
-  const resizeObserver = new ResizeObserver(() => {
+  function handleResize() {
     const { clientWidth, clientHeight } = container;
     if (!clientWidth || !clientHeight) return;
     viewportWidth = clientWidth;
@@ -1471,8 +1600,17 @@ async function initTerrainViewer(container, dataset, options = {}) {
     viewOffsetPixels = shiftTarget;
     camera.aspect = clientWidth / clientHeight;
     camera.updateProjectionMatrix();
+    const nextPixelRatio = resolvePixelRatio();
+    if (nextPixelRatio !== currentPixelRatio) {
+      currentPixelRatio = nextPixelRatio;
+      renderer.setPixelRatio(currentPixelRatio);
+    }
     renderer.setSize(clientWidth, clientHeight, false);
     applyViewOffset();
+    updateRenderResolution();
+  }
+  const resizeObserver = new ResizeObserver(() => {
+    handleResize();
   });
   resizeObserver.observe(container);
   function setPointerFromEvent(event) {
@@ -1497,22 +1635,26 @@ async function initTerrainViewer(container, dataset, options = {}) {
     const markerId = pickMarkerId();
     if (markerId !== hoveredLocationId) {
       hoveredLocationId = markerId;
+      const hoveredLocation = markerId ? currentLocations.find((location) => location.id === markerId) : void 0;
+      renderer.domElement.title = hoveredLocation?.name || hoveredLocation?.id || "";
       options.onLocationHover?.(markerId);
       updateMarkerVisuals();
     }
   }
   function updatePlacementIndicator() {
     if (!interactiveEnabled) {
-      placementIndicator.visible = false;
+      placementIndicatorGroup.visible = false;
       return;
     }
     const hit = intersectTerrain();
     if (!hit) {
-      placementIndicator.visible = false;
+      placementIndicatorGroup.visible = false;
       return;
     }
-    placementIndicator.visible = true;
-    placementIndicator.position.copy(hit.point).setY(hit.point.y + 0.2);
+    placementIndicatorGroup.visible = true;
+    const target = hit.point.clone();
+    target.y += 0.02;
+    placementIndicatorGroup.position.copy(target);
   }
   function handlePointerMove(event) {
     setPointerFromEvent(event);
@@ -1571,7 +1713,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
       renderer.domElement.classList.add("terrain-pointer-active");
     } else {
       renderer.domElement.classList.remove("terrain-pointer-active");
-      placementIndicator.visible = false;
+      placementIndicatorGroup.visible = false;
     }
   }
   async function updateLayers(state) {
@@ -1641,6 +1783,33 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     updateLayers,
     setInteractiveMode,
+    setMaxPixelRatio: (value) => {
+      maxPixelRatio = Math.max(1, value);
+      handleResize();
+    },
+    setRenderScaleMode: (mode, scale) => {
+      renderScaleMode = mode;
+      if (typeof scale === "number") {
+        renderScale = clampRenderScale(scale);
+      } else if (renderScaleMode === "auto") {
+        renderScale = clampRenderScale(renderScale);
+      }
+      currentPixelRatio = resolvePixelRatio();
+      renderer.setPixelRatio(currentPixelRatio);
+      renderer.setSize(viewportWidth, viewportHeight, false);
+      updateRenderResolution();
+      frameTimings.length = 0;
+      stabilizingStartTime = null;
+    },
+    setRenderPaused: (paused) => {
+      renderPaused = paused;
+      if (paused) {
+        window.cancelAnimationFrame(animationFrame);
+      } else if (!frameCaptureMode) {
+        animationFrame = window.requestAnimationFrame(animate);
+      }
+    },
+    getRenderResolution: () => ({ ...renderResolution }),
     updateLocations: (locations, focusedId) => {
       setLocationMarkers(locations, focusedId);
     },
@@ -1707,6 +1876,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     setTheme: applyThemeUpdate,
     setSeaLevel: applySeaLevelUpdate,
+    setHeightScale: applyHeightScaleUpdate,
     invalidateIconTextures: (paths) => {
       invalidateIconCache(paths);
       setLocationMarkers(currentLocations, currentFocusId);
@@ -1725,7 +1895,9 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     disableFrameCaptureMode: () => {
       frameCaptureMode = false;
-      animationFrame = window.requestAnimationFrame(animate);
+      if (!renderPaused) {
+        animationFrame = window.requestAnimationFrame(animate);
+      }
     },
     captureFrame: (frameNumber, fps = 30) => {
       if (!frameCaptureMode) {
@@ -2953,12 +3125,16 @@ function buildEntries(legend, visibility) {
   }
   for (const [key, layer] of Object.entries(legend.overlays ?? {})) {
     const id = makeLayerId("overlay", key);
+    const color = "rgb" in layer && Array.isArray(layer.rgb) ? layer.rgb : [255, 255, 255];
+    const icon = "rgba" in layer ? "image" : void 0;
     entries.push({
       id,
       kind: "overlay",
       label: layer.label ?? key,
-      mask: layer.mask,
-      color: layer.rgb,
+      mask: "mask" in layer ? layer.mask : void 0,
+      rgba: "rgba" in layer ? layer.rgba : void 0,
+      color,
+      icon,
       visible: visibility.get(id) ?? true
     });
   }

package/dist/index.d.cts

@@ -82,6 +82,7 @@ type TerrainLocation = {
     id: string;
     name?: string;
     icon?: string;
+    description?: string;
     showBorder?: boolean;
     pixel: {
         x: number;
@@ -114,11 +115,16 @@ type LocationPickPayload = {
     };
 };
 type ViewerLifecycleState = 'initializing' | 'loading-textures' | 'building-geometry' | 'first-render' | 'stabilizing' | 'ready';
+type RenderScaleMode = 'auto' | 'fixed';
 type TerrainInitOptions = {
     onReady?: () => void;
     onLifecycleChange?: (state: ViewerLifecycleState) => void;
     heightScale?: number;
     waterLevelPercent?: number;
+    maxPixelRatio?: number;
+    renderScale?: number;
+    renderScaleMode?: RenderScaleMode;
+    onRenderSizeChange?: (payload: RenderResolution) => void;
     layers?: LayerToggleState;
     interactive?: boolean;
     onLocationPick?: (payload: LocationPickPayload) => void;
@@ -127,11 +133,16 @@ type TerrainInitOptions = {
     locations?: TerrainLocation[];
     theme?: TerrainThemeOverrides;
     cameraView?: LocationViewState;
+    preserveDrawingBuffer?: boolean;
 };
 type TerrainHandle = {
     destroy: () => void;
     updateLayers: (state: LayerToggleState) => Promise<void>;
     setInteractiveMode: (enabled: boolean) => void;
+    setMaxPixelRatio: (value: number) => void;
+    setRenderScaleMode: (mode: RenderScaleMode, scale?: number) => void;
+    setRenderPaused: (paused: boolean) => void;
+    getRenderResolution: () => RenderResolution;
     updateLocations: (locations: TerrainLocation[], focusedId?: string) => void;
     setFocusedLocation: (locationId?: string | null) => void;
     navigateTo: (payload: {
@@ -154,6 +165,7 @@ type TerrainHandle = {
     getViewState: () => LocationViewState;
     setTheme: (overrides?: TerrainThemeOverrides) => void;
     setSeaLevel: (level: number) => void;
+    setHeightScale: (scale: number) => void;
     invalidateIconTextures: (paths?: string[]) => void;
     invalidateLayerMasks: (paths?: string[]) => void;
     enableFrameCaptureMode: (fps?: number) => {
@@ -166,18 +178,30 @@ type TerrainHandle = {
     };
 };
 type Cleanup = () => void;
+type RenderResolution = {
+    width: number;
+    height: number;
+    pixelRatio: number;
+    renderScale: number;
+};
 type Resolvable<T> = T | Promise<T>;
-type LegendLayer = {
+type MaskLegendLayer = {
     mask: string;
     rgb: [number, number, number];
     label?: string;
 };
+type RgbaLegendLayer = {
+    rgba: string;
+    label?: string;
+};
+type LegendLayer = MaskLegendLayer | RgbaLegendLayer;
 type TerrainLegend = {
     size: [number, number];
     sea_level?: number;
+    height_scale?: number;
     heightmap: string;
     topology?: string;
-    biomes: Record<string, LegendLayer>;
+    biomes: Record<string, MaskLegendLayer>;
     overlays: Record<string, LegendLayer>;
 };
 type TerrainDataset = {
@@ -346,8 +370,10 @@ type LayerBrowserEntry = {
     id: string;
     kind: 'biome' | 'overlay';
     label: string;
-    mask: string;
+    mask?: string;
+    rgba?: string;
     color: [number, number, number];
+    icon?: string;
     visible: boolean;
 };
 type LayerBrowserState = {
@@ -436,4 +462,4 @@ type EnhancedLocationsResult<T extends TerrainLocation = TerrainLocation> = {
 declare function createIconUrlMap(files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): IconUrlMapResult;
 declare function enhanceLocationsWithIconUrls<T extends TerrainLocation = TerrainLocation>(locations: T[], files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): EnhancedLocationsResult<T>;
 
-export { type BuildWynArchiveOptions, type Cleanup, type CreateIconUrlMapOptions, type DeepPartial, type EnhancedLocationsResult, type HeightSampler, type IconUrlEntry, type IconUrlMapResult, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createIconUrlMap, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, enhanceLocationsWithIconUrls, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };
+export { type BuildWynArchiveOptions, type Cleanup, type CreateIconUrlMapOptions, type DeepPartial, type EnhancedLocationsResult, type HeightSampler, type IconUrlEntry, type IconUrlMapResult, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskLegendLayer, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type RenderResolution, type RenderScaleMode, type RgbaLegendLayer, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createIconUrlMap, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, enhanceLocationsWithIconUrls, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };

package/dist/index.d.ts

@@ -82,6 +82,7 @@ type TerrainLocation = {
     id: string;
     name?: string;
     icon?: string;
+    description?: string;
     showBorder?: boolean;
     pixel: {
         x: number;
@@ -114,11 +115,16 @@ type LocationPickPayload = {
     };
 };
 type ViewerLifecycleState = 'initializing' | 'loading-textures' | 'building-geometry' | 'first-render' | 'stabilizing' | 'ready';
+type RenderScaleMode = 'auto' | 'fixed';
 type TerrainInitOptions = {
     onReady?: () => void;
     onLifecycleChange?: (state: ViewerLifecycleState) => void;
     heightScale?: number;
     waterLevelPercent?: number;
+    maxPixelRatio?: number;
+    renderScale?: number;
+    renderScaleMode?: RenderScaleMode;
+    onRenderSizeChange?: (payload: RenderResolution) => void;
     layers?: LayerToggleState;
     interactive?: boolean;
     onLocationPick?: (payload: LocationPickPayload) => void;
@@ -127,11 +133,16 @@ type TerrainInitOptions = {
     locations?: TerrainLocation[];
     theme?: TerrainThemeOverrides;
     cameraView?: LocationViewState;
+    preserveDrawingBuffer?: boolean;
 };
 type TerrainHandle = {
     destroy: () => void;
     updateLayers: (state: LayerToggleState) => Promise<void>;
     setInteractiveMode: (enabled: boolean) => void;
+    setMaxPixelRatio: (value: number) => void;
+    setRenderScaleMode: (mode: RenderScaleMode, scale?: number) => void;
+    setRenderPaused: (paused: boolean) => void;
+    getRenderResolution: () => RenderResolution;
     updateLocations: (locations: TerrainLocation[], focusedId?: string) => void;
     setFocusedLocation: (locationId?: string | null) => void;
     navigateTo: (payload: {
@@ -154,6 +165,7 @@ type TerrainHandle = {
     getViewState: () => LocationViewState;
     setTheme: (overrides?: TerrainThemeOverrides) => void;
     setSeaLevel: (level: number) => void;
+    setHeightScale: (scale: number) => void;
     invalidateIconTextures: (paths?: string[]) => void;
     invalidateLayerMasks: (paths?: string[]) => void;
     enableFrameCaptureMode: (fps?: number) => {
@@ -166,18 +178,30 @@ type TerrainHandle = {
     };
 };
 type Cleanup = () => void;
+type RenderResolution = {
+    width: number;
+    height: number;
+    pixelRatio: number;
+    renderScale: number;
+};
 type Resolvable<T> = T | Promise<T>;
-type LegendLayer = {
+type MaskLegendLayer = {
     mask: string;
     rgb: [number, number, number];
     label?: string;
 };
+type RgbaLegendLayer = {
+    rgba: string;
+    label?: string;
+};
+type LegendLayer = MaskLegendLayer | RgbaLegendLayer;
 type TerrainLegend = {
     size: [number, number];
     sea_level?: number;
+    height_scale?: number;
     heightmap: string;
     topology?: string;
-    biomes: Record<string, LegendLayer>;
+    biomes: Record<string, MaskLegendLayer>;
     overlays: Record<string, LegendLayer>;
 };
 type TerrainDataset = {
@@ -346,8 +370,10 @@ type LayerBrowserEntry = {
     id: string;
     kind: 'biome' | 'overlay';
     label: string;
-    mask: string;
+    mask?: string;
+    rgba?: string;
     color: [number, number, number];
+    icon?: string;
     visible: boolean;
 };
 type LayerBrowserState = {
@@ -436,4 +462,4 @@ type EnhancedLocationsResult<T extends TerrainLocation = TerrainLocation> = {
 declare function createIconUrlMap(files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): IconUrlMapResult;
 declare function enhanceLocationsWithIconUrls<T extends TerrainLocation = TerrainLocation>(locations: T[], files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): EnhancedLocationsResult<T>;
 
-export { type BuildWynArchiveOptions, type Cleanup, type CreateIconUrlMapOptions, type DeepPartial, type EnhancedLocationsResult, type HeightSampler, type IconUrlEntry, type IconUrlMapResult, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createIconUrlMap, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, enhanceLocationsWithIconUrls, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };
+export { type BuildWynArchiveOptions, type Cleanup, type CreateIconUrlMapOptions, type DeepPartial, type EnhancedLocationsResult, type HeightSampler, type IconUrlEntry, type IconUrlMapResult, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskLegendLayer, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type RenderResolution, type RenderScaleMode, type RgbaLegendLayer, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createIconUrlMap, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, enhanceLocationsWithIconUrls, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };

package/dist/index.js

@@ -345,6 +345,9 @@ async function preprocessMask(file, resolveAssetUrl, imageCache, maskCache) {
 function hexFromRgb(rgb) {
   return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`;
 }
+function isRgbaLayer(layer) {
+  return typeof layer.rgba === "string";
+}
 async function composeLegendTexture(legendData, resolveAssetUrl, imageCache, maskCache, layerState) {
   if (typeof document === "undefined") return null;
   const [width, height] = legendData.size;
@@ -381,6 +384,17 @@ async function composeLegendTexture(legendData, resolveAssetUrl, imageCache, mas
     ctx.globalAlpha = alpha;
     ctx.drawImage(temp, 0, 0, width, height);
   }
+  async function drawRgbaLayer(textureFile, alpha = 1) {
+    let image = null;
+    try {
+      image = await loadLegendImage(textureFile, resolveAssetUrl, imageCache);
+    } catch (err) {
+      console.warn("[WynnalTerrain] Unable to load overlay texture", textureFile, err);
+      return;
+    }
+    ctx.globalAlpha = alpha;
+    ctx.drawImage(image, 0, 0, width, height);
+  }
   const activeBiomes = layerState?.biomes ?? {};
   for (const [name, biome] of Object.entries(legendData.biomes)) {
     if (layerState && activeBiomes[name] === false) continue;
@@ -390,6 +404,14 @@ async function composeLegendTexture(legendData, resolveAssetUrl, imageCache, mas
   for (const [name, overlay] of Object.entries(legendData.overlays)) {
     if (layerState && activeOverlays[name] === false) continue;
     const alpha = DEFAULT_LAYER_ALPHA[name] ?? 1;
+    if (isRgbaLayer(overlay)) {
+      await drawRgbaLayer(overlay.rgba, alpha);
+      continue;
+    }
+    if (!overlay.mask || !overlay.rgb) {
+      console.warn("[WynnalTerrain] Overlay entry missing mask/rgb", name);
+      continue;
+    }
     await drawLayer(overlay.mask, overlay.rgb, alpha);
   }
   const texture = new THREE2.CanvasTexture(canvas);
@@ -759,6 +781,15 @@ async function initTerrainViewer(container, dataset, options = {}) {
       updateLayers: async () => {
       },
       setInteractiveMode: noop2,
+      setMaxPixelRatio: noop2,
+      setRenderScaleMode: noop2,
+      setRenderPaused: noop2,
+      getRenderResolution: () => ({
+        width: 0,
+        height: 0,
+        pixelRatio: 1,
+        renderScale: 1
+      }),
       updateLocations: noop2,
       setFocusedLocation: noop2,
       navigateTo: noop2,
@@ -771,6 +802,8 @@ async function initTerrainViewer(container, dataset, options = {}) {
       },
       setSeaLevel: () => {
       },
+      setHeightScale: () => {
+      },
       invalidateIconTextures: () => {
       },
       invalidateLayerMasks: () => {
@@ -855,7 +888,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
     const { u, v } = pixelToUV(pixel);
     return uvToWorld(u, v, heightSampler, currentHeightScale, seaLevel, terrainDimensions);
   }
-  const heightScale = options.heightScale ?? HEIGHT_SCALE_DEFAULT;
+  const heightScale = options.heightScale ?? legend.height_scale ?? HEIGHT_SCALE_DEFAULT;
   let currentHeightScale = heightScale;
   const waterPercent = THREE2.MathUtils.clamp(
     options.waterLevelPercent ?? WATER_PERCENT_DEFAULT,
@@ -888,10 +921,28 @@ async function initTerrainViewer(container, dataset, options = {}) {
   let viewportWidth = width;
   let viewportHeight = height;
   let viewOffsetPixels = 0;
-  const renderer = new THREE2.WebGLRenderer({ antialias: true, alpha: true });
+  let maxPixelRatio = Math.max(1, options.maxPixelRatio ?? 1.5);
+  const minRenderScale = 0.25;
+  let renderScaleMode = options.renderScaleMode ?? "fixed";
+  let renderScale = clampRenderScale(options.renderScale ?? 1);
+  let currentPixelRatio = 1;
+  function clampRenderScale(value) {
+    return THREE2.MathUtils.clamp(value, minRenderScale, 1);
+  }
+  function resolvePixelRatio() {
+    const deviceRatio = window.devicePixelRatio || 1;
+    const scaledRatio = deviceRatio * renderScale;
+    return Math.min(scaledRatio, maxPixelRatio);
+  }
+  const renderer = new THREE2.WebGLRenderer({
+    antialias: true,
+    alpha: true,
+    preserveDrawingBuffer: options.preserveDrawingBuffer ?? false
+  });
   renderer.toneMapping = THREE2.ACESFilmicToneMapping;
   renderer.toneMappingExposure = 1.08;
-  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  currentPixelRatio = resolvePixelRatio();
+  renderer.setPixelRatio(currentPixelRatio);
   const hostStyle = window.getComputedStyle(container);
   if (hostStyle.position === "static") {
     container.style.position = "relative";
@@ -908,6 +959,22 @@ async function initTerrainViewer(container, dataset, options = {}) {
   renderer.shadowMap.enabled = true;
   renderer.shadowMap.type = THREE2.PCFSoftShadowMap;
   container.appendChild(renderer.domElement);
+  const renderResolution = {
+    width: 0,
+    height: 0,
+    pixelRatio: currentPixelRatio,
+    renderScale
+  };
+  function updateRenderResolution() {
+    const bufferSize = new THREE2.Vector2();
+    renderer.getDrawingBufferSize(bufferSize);
+    renderResolution.width = Math.round(bufferSize.x);
+    renderResolution.height = Math.round(bufferSize.y);
+    renderResolution.pixelRatio = currentPixelRatio;
+    renderResolution.renderScale = renderScale;
+    options.onRenderSizeChange?.({ ...renderResolution });
+  }
+  updateRenderResolution();
   disposables.push(() => {
     renderer.dispose();
     renderer.domElement.remove();
@@ -976,19 +1043,42 @@ async function initTerrainViewer(container, dataset, options = {}) {
   }
   const locationWorldCache = /* @__PURE__ */ new Map();
   let markerGeneration = 0;
-  const placementIndicator = new THREE2.Mesh(
-    new THREE2.CylinderGeometry(0.04, 0.01, 0.7, 18),
-    new THREE2.MeshStandardMaterial({
+  const placementIndicatorHeight = 0.26;
+  const placementIndicatorGroup = new THREE2.Group();
+  const placementIndicatorMaterial = new THREE2.MeshStandardMaterial({
+    color: 16735067,
+    transparent: true,
+    opacity: 0.85
+  });
+  const placementStem = new THREE2.Mesh(
+    new THREE2.CylinderGeometry(0.01, 0.01, 0.06, 8),
+    placementIndicatorMaterial
+  );
+  placementStem.position.y = 0.03;
+  const placementDot = new THREE2.Mesh(
+    new THREE2.SphereGeometry(0.014, 10, 10),
+    placementIndicatorMaterial
+  );
+  placementDot.position.y = 5e-3;
+  const placementRing = new THREE2.Mesh(
+    new THREE2.CircleGeometry(0.12, 32),
+    new THREE2.MeshBasicMaterial({
       color: 16735067,
       transparent: true,
-      opacity: 0.8
+      opacity: 0.2
     })
   );
-  placementIndicator.visible = false;
-  scene.add(placementIndicator);
+  placementRing.rotation.x = -Math.PI / 2;
+  placementRing.position.y = 5e-3;
+  placementIndicatorGroup.add(placementRing, placementStem, placementDot);
+  placementIndicatorGroup.visible = false;
+  scene.add(placementIndicatorGroup);
   disposables.push(() => {
-    placementIndicator.geometry.dispose();
-    placementIndicator.material.dispose();
+    placementStem.geometry.dispose();
+    placementDot.geometry.dispose();
+    placementRing.geometry.dispose();
+    placementIndicatorMaterial.dispose();
+    placementRing.material.dispose();
   });
   const loader = new THREE2.TextureLoader();
   const iconTextureCache = /* @__PURE__ */ new Map();
@@ -1214,6 +1304,31 @@ async function initTerrainViewer(container, dataset, options = {}) {
     stemRadius = computeStemRadius(markerTheme.stem);
     setLocationMarkers(currentLocations, currentFocusId);
   }
+  function applyHeightScaleUpdate(nextHeightScale) {
+    if (!heightSampler) {
+      return;
+    }
+    const prevHeightScale = currentHeightScale;
+    const nextScale = Math.max(0, nextHeightScale);
+    currentHeightScale = nextScale;
+    legend.height_scale = nextScale;
+    dataset.legend.height_scale = nextScale;
+    const stats = applyHeightField(terrainGeometry, heightSampler, {
+      seaLevel,
+      heightScale: currentHeightScale
+    });
+    terrainHeightRange = { min: stats.minY, max: stats.maxY };
+    terrainGeometry.attributes.position.needsUpdate = true;
+    terrainGeometry.computeVertexNormals();
+    rebuildRimMesh();
+    rebuildOceanMesh();
+    if (Number.isFinite(prevHeightScale) && prevHeightScale > 0) {
+      const factor = nextScale / prevHeightScale;
+      controls.target.y *= factor;
+      camera.position.y *= factor;
+    }
+    setLocationMarkers(currentLocations, currentFocusId);
+  }
   function applySeaLevelUpdate(nextSeaLevel) {
     if (!heightSampler) {
       return;
@@ -1340,6 +1455,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
     camera.updateProjectionMatrix();
   }
   let animationFrame = 0;
+  let renderPaused = false;
   let frameCount = 0;
   let firstRenderComplete = false;
   const frameTimings = [];
@@ -1397,19 +1513,32 @@ async function initTerrainViewer(container, dataset, options = {}) {
       if (currentLifecycleState === "stabilizing" && stabilizingStartTime !== null) {
         const stabilizingDuration = now - stabilizingStartTime;
         if (stabilizingDuration > STABILITY_TIMEOUT_MS) {
-          console.warn(`[terrainViewer] Framerate did not stabilize after ${STABILITY_TIMEOUT_MS}ms, forcing ready state`);
-          setLifecycleState("ready");
-          stabilizingStartTime = null;
+          if (renderScaleMode === "auto" && renderScale > minRenderScale + 0.01) {
+            renderScale = clampRenderScale(Number((renderScale * 0.6).toFixed(2)));
+            currentPixelRatio = resolvePixelRatio();
+            renderer.setPixelRatio(currentPixelRatio);
+            renderer.setSize(viewportWidth, viewportHeight, false);
+            updateRenderResolution();
+            frameTimings.length = 0;
+            stabilizingStartTime = now;
+            console.warn(
+              `[terrainViewer] Framerate unstable after ${STABILITY_TIMEOUT_MS}ms, reducing render scale to ${renderScale}`
+            );
+          } else {
+            console.warn(`[terrainViewer] Framerate did not stabilize after ${STABILITY_TIMEOUT_MS}ms, forcing ready state`);
+            setLifecycleState("ready");
+            stabilizingStartTime = null;
+          }
         }
       }
     }
-    if (!frameCaptureMode) {
+    if (!frameCaptureMode && !renderPaused) {
       animationFrame = window.requestAnimationFrame(animate);
     }
   }
   animate();
   options.onReady?.();
-  const resizeObserver = new ResizeObserver(() => {
+  function handleResize() {
     const { clientWidth, clientHeight } = container;
     if (!clientWidth || !clientHeight) return;
     viewportWidth = clientWidth;
@@ -1418,8 +1547,17 @@ async function initTerrainViewer(container, dataset, options = {}) {
     viewOffsetPixels = shiftTarget;
     camera.aspect = clientWidth / clientHeight;
     camera.updateProjectionMatrix();
+    const nextPixelRatio = resolvePixelRatio();
+    if (nextPixelRatio !== currentPixelRatio) {
+      currentPixelRatio = nextPixelRatio;
+      renderer.setPixelRatio(currentPixelRatio);
+    }
     renderer.setSize(clientWidth, clientHeight, false);
     applyViewOffset();
+    updateRenderResolution();
+  }
+  const resizeObserver = new ResizeObserver(() => {
+    handleResize();
   });
   resizeObserver.observe(container);
   function setPointerFromEvent(event) {
@@ -1444,22 +1582,26 @@ async function initTerrainViewer(container, dataset, options = {}) {
     const markerId = pickMarkerId();
     if (markerId !== hoveredLocationId) {
       hoveredLocationId = markerId;
+      const hoveredLocation = markerId ? currentLocations.find((location) => location.id === markerId) : void 0;
+      renderer.domElement.title = hoveredLocation?.name || hoveredLocation?.id || "";
       options.onLocationHover?.(markerId);
       updateMarkerVisuals();
     }
   }
   function updatePlacementIndicator() {
     if (!interactiveEnabled) {
-      placementIndicator.visible = false;
+      placementIndicatorGroup.visible = false;
       return;
     }
     const hit = intersectTerrain();
     if (!hit) {
-      placementIndicator.visible = false;
+      placementIndicatorGroup.visible = false;
       return;
     }
-    placementIndicator.visible = true;
-    placementIndicator.position.copy(hit.point).setY(hit.point.y + 0.2);
+    placementIndicatorGroup.visible = true;
+    const target = hit.point.clone();
+    target.y += 0.02;
+    placementIndicatorGroup.position.copy(target);
   }
   function handlePointerMove(event) {
     setPointerFromEvent(event);
@@ -1518,7 +1660,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
       renderer.domElement.classList.add("terrain-pointer-active");
     } else {
       renderer.domElement.classList.remove("terrain-pointer-active");
-      placementIndicator.visible = false;
+      placementIndicatorGroup.visible = false;
     }
   }
   async function updateLayers(state) {
@@ -1588,6 +1730,33 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     updateLayers,
     setInteractiveMode,
+    setMaxPixelRatio: (value) => {
+      maxPixelRatio = Math.max(1, value);
+      handleResize();
+    },
+    setRenderScaleMode: (mode, scale) => {
+      renderScaleMode = mode;
+      if (typeof scale === "number") {
+        renderScale = clampRenderScale(scale);
+      } else if (renderScaleMode === "auto") {
+        renderScale = clampRenderScale(renderScale);
+      }
+      currentPixelRatio = resolvePixelRatio();
+      renderer.setPixelRatio(currentPixelRatio);
+      renderer.setSize(viewportWidth, viewportHeight, false);
+      updateRenderResolution();
+      frameTimings.length = 0;
+      stabilizingStartTime = null;
+    },
+    setRenderPaused: (paused) => {
+      renderPaused = paused;
+      if (paused) {
+        window.cancelAnimationFrame(animationFrame);
+      } else if (!frameCaptureMode) {
+        animationFrame = window.requestAnimationFrame(animate);
+      }
+    },
+    getRenderResolution: () => ({ ...renderResolution }),
     updateLocations: (locations, focusedId) => {
       setLocationMarkers(locations, focusedId);
     },
@@ -1654,6 +1823,7 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     setTheme: applyThemeUpdate,
     setSeaLevel: applySeaLevelUpdate,
+    setHeightScale: applyHeightScaleUpdate,
     invalidateIconTextures: (paths) => {
       invalidateIconCache(paths);
       setLocationMarkers(currentLocations, currentFocusId);
@@ -1672,7 +1842,9 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     disableFrameCaptureMode: () => {
       frameCaptureMode = false;
-      animationFrame = window.requestAnimationFrame(animate);
+      if (!renderPaused) {
+        animationFrame = window.requestAnimationFrame(animate);
+      }
     },
     captureFrame: (frameNumber, fps = 30) => {
       if (!frameCaptureMode) {
@@ -2900,12 +3072,16 @@ function buildEntries(legend, visibility) {
   }
   for (const [key, layer] of Object.entries(legend.overlays ?? {})) {
     const id = makeLayerId("overlay", key);
+    const color = "rgb" in layer && Array.isArray(layer.rgb) ? layer.rgb : [255, 255, 255];
+    const icon = "rgba" in layer ? "image" : void 0;
     entries.push({
       id,
       kind: "overlay",
       label: layer.label ?? key,
-      mask: layer.mask,
-      color: layer.rgb,
+      mask: "mask" in layer ? layer.mask : void 0,
+      rgba: "rgba" in layer ? layer.rgba : void 0,
+      color,
+      icon,
       visible: visibility.get(id) ?? true
     });
   }

package/documentation/WYN-FILE-FORMAT.md

@@ -48,7 +48,8 @@ Schema: `schemas/legend.schema.json`
     "forest": { "mask": "layers/forest_mask.png", "rgb": [48, 92, 54], "label": "Forest" }
   },
   "overlays": {
-    "water": { "mask": "layers/water_mask.png", "rgb": [34, 92, 124], "label": "Water" }
+    "water": { "mask": "layers/water_mask.png", "rgb": [34, 92, 124], "label": "Water" },
+    "texture": { "rgba": "layers/atlas-texture.png", "label": "Texture" }
   }
 }
 ```
@@ -63,12 +64,18 @@ Schema:
 - `biomes`: Record of biome layers. Keys are layer ids used by the editor/viewer.
 - `overlays`: Record of overlay layers. Keys are layer ids used by the editor/viewer.
 
-Each layer entry:
+Each layer entry (biomes + mask-based overlays):
 
 - `mask`: Path to a PNG mask. The viewer converts the max RGB channel into alpha.
 - `rgb`: `[r, g, b]` integers (0-255) used to colorize the legend composite.
 - `label`: Optional display name in the editor UI.
 
+Overlay texture entries (overlays only):
+
+- `rgba`: Path to a full-color PNG/WebP/etc. The viewer draws the image directly using the
+  image alpha channel.
+- `label`: Optional display name in the editor UI.
+
 ## locations.json (optional)
 
 Array of location markers. Coordinates are expressed in legend pixel space.

package/documentation/schemas/legend.schema.json

@@ -30,15 +30,15 @@
     },
     "biomes": {
       "type": "object",
-      "additionalProperties": { "$ref": "#/definitions/legendLayer" }
+      "additionalProperties": { "$ref": "#/definitions/maskLayer" }
     },
     "overlays": {
       "type": "object",
-      "additionalProperties": { "$ref": "#/definitions/legendLayer" }
+      "additionalProperties": { "$ref": "#/definitions/overlayLayer" }
     }
   },
   "definitions": {
-    "legendLayer": {
+    "maskLayer": {
       "type": "object",
       "additionalProperties": false,
       "required": ["mask", "rgb"],
@@ -61,6 +61,26 @@
           "type": "string"
         }
       }
+    },
+    "rgbaLayer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rgba"],
+      "properties": {
+        "rgba": {
+          "type": "string",
+          "minLength": 1
+        },
+        "label": {
+          "type": "string"
+        }
+      }
+    },
+    "overlayLayer": {
+      "oneOf": [
+        { "$ref": "#/definitions/maskLayer" },
+        { "$ref": "#/definitions/rgbaLayer" }
+      ]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connected-web/terrain-editor",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Reusable viewer/editor utilities for Wyn terrain files.",
   "type": "module",
   "main": "dist/index.cjs",