planet/docs/technical/en/earth-render-layer-order.md

Earth Render Layer Order

This document records the current Earth renderer's layer order and the intent of each layer. When adjusting renderOrder, radius offsets, depth strategy, or pointer interaction, update this document accordingly.

Note: the layer control panel order and the registration / startup load order are two separate semantics.

Order type	Current sequence	Notes
Control panel order	Cables → Satellites → Compute Centers → Vessels → BGP → Terrain → HD Texture → Cloud Layer → Border Lines → Grid	Controlled by displayOrder, sorted by operational relevance; satellite trails moved to Settings and are no longer a layer-list item.
Registration / startup load order	Grid → Border Lines / Land-Ocean Base → HD Texture → Cloud Layer → Cables → Compute Centers → Vessels → BGP → Satellites	Controlled by registration order and startupPriority, sorted surface-to-sky; the startup queue reads persisted layer visibility first, skips normal layers explicitly saved as hidden, and HD Texture does not download the texture when disabled; Border Lines are the exception: the land-ocean base always preloads, while the persisted state only controls interactive border lines and hover; Trails and Terrain are dependency/optional display layers and do not participate in normal startup data loading.

Surface Layer Stack

Order	Layer	Source	Render / Radius Strategy	Depth / Interaction Strategy	Notes
-1000	Celestial background mesh	celestial.js	Background sphere	Not part of surface picking	Behind all Earth content.
-1	Earth occluder sphere	earth.js	Invisible inner sphere	Writes depth buffer	Occludes objects behind the Earth.
0	Earth base sphere	earth.js	CONFIG.earthRadius	Surface picking fallback target	Dark base; still visible when all optional map layers are off.
0.2	Country dark tint	country-boundaries.js	tintAltitudeOffset	Raycast disabled	Used when HD texture is off.
0.86	Land/ocean base fill	country-boundaries.js	landAltitudeOffset; ocean #010609, land #080f1b	Raycast disabled	Base map remains usable even when country borders are off.
0.96	HD Earth texture	earth.js	textureOverlayAltitudeOffset	Surface picking target when visible	HD texture always overlays the land/ocean base fill.
1	Atmospheric glow and clouds	earth.js	Atmosphere / cloud spheres	Not in normal object selection path	Cloud layer controlled by the "Cloud Layer" toggle.
1	Submarine cables	cables.js	CABLE_CONFIG.line.renderOrder	Cable picking path	Preserves existing cable layer level.
1.2	Real terrain	earth.js, terrain.js	TERRAIN_CONFIG.baseRadiusOffset plus terrain displacement	Raycast disabled	Terrain overlays HD texture; temporarily hidden when HD texture is off, restores to prior state when re-enabled.
2.05	Grid lines	earth.js	CONFIG.earthRadius + 0.14	Raycast disabled	Low-opacity lines over HD texture.
2.2	Country borders	country-boundaries.js	lineAltitudeOffset	Raycast disabled	Only needs to stay above HD texture.
2.29	Country border hover glow	country-boundaries.js	Hover radius + glow offset	depthTest: false, raycast disabled	Additive glow to reinforce border edge and terrain hover visibility.
2.3	Country border hover line	country-boundaries.js	hoverAltitudeOffset	depthTest: false, raycast disabled	Neon red-orange hover line; China and Taiwan share the same highlight group.
3	Satellite footprint fill / Iridium coverage ring	satellites.js, iridium-footprint-adapter.js	GROUND_FOOTPRINT_RENDER_ORDER	depth-tested; Iridium adapter fill / ring use the same renderOrder	Footprint above land / texture / terrain and country borders, below compute centers and satellites.
3-5	BGP markers and overlays	bgp.js	Each marker's own renderOrder	BGP picking path	Preserves existing BGP visual level.
4.5	Compute centers	compute-centers.js	COMPUTE_CENTER_RENDER_ORDER	Compute center picking path	Surface facilities, below satellites.
5	Satellite background dot	satellites.js	Fixed renderOrder; by default TLE/SGP4 altitude is compressed to CONFIG.earthRadius + 4..55; with real altitude disabled or propagation failed, uses fallbackAltitudeOffset = 8	Screen-space satellite picking	Below satellite dots.
6	Satellite dots	satellites.js	Same compressed / fallback height as satellite backdrop dots	Screen-space satellite picking	Satellite dots above footprints and compute centers.
12+	Satellite locked ring, halo, predicted orbit	satellites.js	SATELLITE_CONFIG.overlayRenderOrder and offsets; predicted orbit follows the same real-altitude toggle and returns to same-sphere mode when disabled	Satellite overlay path	Used for selected/locked satellite emphasis.
98-100	Sun / moon halo and sprite	celestial.js	Fixed renderOrder	Celestial picking disabled	Foreground celestial sprites.

Toggle Behavior

Toggle	Behavior
HD texture off	Hides HD texture, enables country tint / base surface, disables terrain and day/night toggle interaction, and remembers terrain and day/night previous states.
HD texture on	Restores HD texture and the remembered terrain / day/night states.
Terrain on	Displayed above HD texture, but below country border hover, footprints, satellites, and other emphasis layers.
Cloud layer	Only controls cloud mesh visibility.
Border Lines off	Hides only interactive border lines and hover, clearing hover state; the land/ocean base fill remains as the Earth base map.
Real Satellite Altitude off	Satellite dots, trails, and predicted orbits use the legacy same-sphere height; satellites with missing TLE data or failed propagation also use this fallback height.

Interaction Rules

Interaction	Current Rule
Earth coordinate hover	When HD texture is visible, uses the HD texture overlay as the surface picking target; otherwise uses the Earth base sphere.
Country border hover	Converts surface pick coordinates to lat/lon, then uses GeoJSON point-in-polygon; the border hover line itself does not receive raycasts.
Country border hover visual	On hover, dims normal border lines and draws no-depth-test glow and solid lines.
China / Taiwan hover	CHN and TWN are grouped in the same hover highlight group; the tooltip still shows the actually-hit feature.
Terrain	Acts as a visual layer only; terrain.raycast is disabled.
Satellites	Uses screen-space satellite picking to prevent footprints or surface layers from blocking satellite clicks.