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 = 0.32; ocean #010609, land #080f1b	Raycast disabled	Base map remains usable even when country borders are off; radius is separated from the base sphere to avoid far-zoom z-fighting.
0.96	HD Earth texture	earth.js	textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48	Surface picking target when visible	HD texture always overlays the land/ocean base fill; radius must stay above the land/ocean base and far enough from the base sphere.
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 = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48; claim lines have no extra lift	Raycast disabled	Line geometry still has its own renderOrder, but it shares the exact same radius as the HD texture shell to avoid parallax while the globe rotates.
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 = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48	depthTest: false, raycast disabled	Neon red-orange hover line; aligned with the normal borders and HD texture shell to avoid ghosting or floating; 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..25; 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 fixes the lock-time globe pose to draw a closed inertial orbit; returns to same-sphere mode when real altitude is 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.

Depth Spacing Rules

The Earth surface is not a single mesh. It is a stack of near-concentric shells: base sphere, land/ocean base, HD texture, terrain, clouds, atmosphere, and the occluder. Radius offsets that look harmless at close zoom can collapse into the same depth-buffer pixels at zoomed-out views such as 50%, causing z-fighting that appears as black blocks, snow, or flicker.

Maintenance rules:

• Do not reach first for hiding layers at far zoom. Check neighboring shell altitudeOffset, renderOrder, depthTest, and depthWrite first.
• Whole-globe overlays such as the land/ocean base and HD texture must keep explicit separation from CONFIG.earthRadius; the current stable values are landAltitudeOffset = 0.32 and textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48.
• Country borders, coastlines, claim lines, and country hover lines must use EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET, exactly matching the HD texture shell. Do not give border lines an independent lower or higher offset, because globe rotation will make the lines appear to drift relative to the surface texture.
• Any new whole-globe or near-whole-globe surface overlay must be screenshot-verified at 50% zoom and at common close zooms, with no black blocks, snow, flicker, or obvious floating.
• If these radii change, update this document and the intent around the constants in frontend/public/earth/js/constants.js.

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.