The Problem

Traditional orthophoto scenery for X-Plane requires downloading entire regions upfront:

• Hundreds of gigabytes per continent, even if you only fly a few routes
• Hours of download and installation time before you can fly
• Large disk space requirements for scenery you may never use

The Solution

XEarthLayer takes a just-in-time streaming approach:

1. Virtual Filesystem: Creates a FUSE file system that X-Plane uses to read scenery tiles
2. Just-In-Time Fetching: When X-Plane requests tile resources, XEarthLayer fetches it from satellite providers in real-time and then returns the tile dependencies
3. Two Tier Caching: Downloaded tiles are cached to memory as X-Plane can request the same tile multiple times in succession. The map image chunks that are used to construct tiles are cached to disk, saving time when revisiting the same location multiple times.

You only download the scenery you actually fly over. No wasted bandwidth or disk space on areas you’ll never visit.

Architecture

Scenery Request Pipeline Stages

1. Request: X-Plane requests a DSF from XEarthLayer
2. Image Resource: X-Plane decodes DSF and creates requests for textures
3. Cache Check: XEarthLayer first checks memory cache for completed tile DDS image, then disk cache for image chunks required to create DDS image. If either is found they are returned to X-Plane
4. Download: If not cached, XEarthLayer downloads requires tile chunks from the provider to prepare for assembly
5. Assembly: Combine 256 small image chunks into a 4096×4096 DDS image
6. Encode: Compress 4096×4096 image into DDS format (BC1/BC3) using one of three backends — Software (pure Rust), ISPC SIMD (default, 5–10× faster), or GPU compute shaders (fastest, requires a wgpu-compatible GPU)
7. Cache: Store completed DDS image in memory and cache image chunks to disk
8. Serve: Return the DDS texture to X-Plane

Prefetching

XEarthLayer reads your aircraft’s position and heading directly from X-Plane’s built-in Web API — no configuration required. On X-Plane 12.1.1 and later, the Web API is enabled by default, so prefetching works out of the box.

The prefetch system uses two strategies, selected automatically based on flight phase:

• Ground (ground speed < 40 kt): Loads a ring of tiles around the perimeter of X-Plane’s already-loaded scenery area. Since the aircraft could taxi in any direction, the ring is symmetric — no heading bias.
• Cruise (airborne): Maintains a sliding prefetch box biased in the direction of travel. The box covers roughly 9° per axis, overlapping X-Plane’s ~6×6 DSF load area so tiles are ready before the simulator crosses into the next region. The forward bias slides proportionally with heading — at cardinal headings the primary axis gets up to 80/20 bias, while at diagonals both axes share equal bias.

A brief transition phase bridges the two: when a takeoff is detected (ground speed exceeds 40 kt), prefetching is suppressed until the aircraft climbs 1,000 ft above the departure elevation (or a 90-second timeout elapses). This reserves system resources for X-Plane while it loads departure scenery. Once cruise is confirmed, prefetching ramps up gradually from 25% to full rate over 30 seconds to avoid flooding the pipeline.

Consolidated Mounting

XEarthLayer uses a single FUSE mount point (zzXEL_ortho) for all of your installed scenery packages. Whether you have one region or a dozen, they are all merged into one virtual folder that X-Plane reads from. Custom tile patches (for airport add-ons, for example) are included in the same mount and automatically take priority over regional package tiles. This means your scenery_packs.ini only needs one ortho entry, and resource usage stays low regardless of how many regions you have installed.

Performance

• Scene load: 1-2 minutes with cached data (down from 5+ minutes when downloading chunks)
• Cache hits: <10ms response time
• Cold download: 1-2 seconds per tile with 1 Gig+ internet connection

Technical Details

XEarthLayer is written in Rust for performance and memory safety. Key technologies:

• fuse3: Async FUSE filesystem implementation
• tokio: Async runtime for concurrent I/O
• reqwest: HTTP client with connection pooling
• image: JPEG decoding and manipulation

Prerequisites

• X-Plane 12 installed on your system
• Linux (Debian/Ubuntu, Fedora/RHEL, or Arch Linux) with FUSE support
• At least 2GB free RAM for the memory cache
• Internet connection for streaming imagery

Installation

git clone https://github.com/samsoir/xearthlayer.git && cd xearthlayer && make install

wget https://github.com/samsoir/xearthlayer/releases/download/v0.4.6/xearthlayer-0.4.6-1.fc44.x86_64.rpm && sudo rpm -i xearthlayer-0.4.6-1.fc44.x86_64.rpm

wget https://github.com/samsoir/xearthlayer/releases/download/v0.4.6/xearthlayer_0.4.6-1_amd64.deb && sudo dpkg -i xearthlayer_0.4.6-1_amd64.deb

curl -sL https://github.com/samsoir/xearthlayer/releases/download/v0.4.6/%!s(<nil>) | bsdtar -xf- -C /tmp && cd /tmp && makepkg -si

Initial Setup

1. Run the setup wizard (recommended for first-time users):

   xearthlayer setup

   The wizard will guide you through:

   • Detecting your X-Plane 12 installation
   • Choosing package and cache locations
   • Configuring optimal settings for your hardware

2. Install a regional scenery package:

   List available regional scenery packages:

   xearthlayer packages check

   Install a package (e.g., Europe):

   xearthlayer packages install EU

   Or North America:

   xearthlayer packages install NA

3. Start XEarthLayer:

   xearthlayer

   This defaults to the run command. You can also use xearthlayer run explicitly. Leave this terminal running while you fly in X-Plane.

4. Launch X-Plane and fly! You should see satellite imagery streaming in as you move around.

Stopping the Service

When you are done flying, close X-Plane first. Then stop XEarthLayer cleanly by pressing the q key in the terminal and following the prompt to confirm.

Verifying It Works

When XEarthLayer is running, you’ll see a real-time dashboard showing:

• Cache statistics (memory and disk usage)
• Download activity (tiles being fetched)
• Aircraft position (when connected to X-Plane via the Web API)
• Pipeline health (download, assembly, encode stages)

If you see tiles being downloaded and cache hits increasing, XEarthLayer is working correctly.

Next Steps

• Configure X-Plane 12 for optimal performance
• Configure providers and caching
• Install more regional packages
• Learn how XEarthLayer works

Getting Started with Configuration

If you prefer manual configuration, create the default config file with:

xearthlayer init

The config file lives at:

See CLI Reference for commands to view and modify configuration settings from the terminal.

Minimum Settings

These four sections are all you need to configure before your first flight.

X-Plane Scenery Directory

Tell XEarthLayer where your X-Plane Custom Scenery folder is. If left empty, it auto-detects from ~/.x-plane/x-plane_install_12.txt.

[xplane]
scenery_dir = /home/user/X-Plane 12/Custom Scenery

Imagery Provider

Choose which satellite imagery source to use.

[provider]
type = bing

For providers that need an API key, add the key in the same section:

[provider]
type = mapbox
mapbox_access_token = pk.eyJ1...your-token-here

[provider]
type = google
google_api_key = AIzaSy...your-key-here

Cache

Controls how much memory and disk space XEarthLayer uses for caching tiles. Larger caches mean fewer repeat downloads.

[cache]
memory_size = 2 GB
disk_size = 20 GB
directory = ~/.cache/xearthlayer

Texture Format

Controls the DDS compression format used for scenery tiles.

[texture]
format = bc1

Advanced Settings

The sections below cover advanced tuning. Each is self-contained with sensible defaults that work for most systems. Only change these if you have a specific reason to.

DDS Encoding

Controls the compression backend used to encode satellite imagery into DDS textures.

The gpu backend is ideal for systems with both an integrated and discrete GPU. Set gpu_device = integrated to use the iGPU for encoding while the discrete GPU handles X-Plane rendering. This eliminates CPU contention between encoding and the simulator.

Run xearthlayer diagnostics to see available GPU adapters on your system.

[texture]
format = bc1
compressor = gpu
gpu_device = integrated

Prefetch Tuning

Controls the Adaptive Prefetch System, which pre-loads tiles ahead of the aircraft to reduce scenery pop-in during flight. The system self-calibrates based on your network and hardware performance.

Mode selection is based on calibration throughput:

Flight phase transitions:

The prefetch system detects three flight phases and adjusts behavior automatically:

• Ground (GS < 40 kt): Full-rate prefetch using ring strategy around current position
• Transition (takeoff detected): Prefetch suppressed while X-Plane loads takeoff scenery
• Cruise (climb confirmed): Prefetch ramps up from 25% to full rate over 30 seconds

[prefetch]
enabled = true
mode = auto

Cache Warming (Prewarm)

Pre-loads tiles around a departure airport before X-Plane starts, reducing initial scenery load times on a cold cache.

The default 3x4 grid (12 tiles) matches X-Plane’s typical scenery window of ~3 degrees latitude by ~4 degrees longitude at mid-latitudes.

Use the --airport flag when launching to activate prewarming:

xearthlayer run --airport KJFK

[prewarm]
grid_rows = 3
grid_cols = 4

Download Settings

Controls the network timeout for downloading imagery tiles.

Each 4096x4096 scenery tile requires downloading 256 chunks (a 16x16 grid of 256x256 source tiles). HTTP concurrency is automatically tuned based on your CPU count. Retry behavior is configured in the Resource Pools (Executor) section.

[download]
timeout = 30

Generation

Controls parallel tile generation (assembling and encoding downloaded chunks into DDS textures).

[generation]
threads = 8
timeout = 10

Control Plane

Manages concurrent tile processing jobs and provides health monitoring with stall detection.

On-demand requests from X-Plane block up to semaphore_timeout_secs waiting for a slot, while prefetch jobs are silently skipped if no slots are available.

[control_plane]
max_concurrent_jobs = 16
stall_threshold_secs = 60

Resource Pools (Executor)

The executor is the core tile processing engine. These settings control concurrency limits for network, CPU, and disk I/O operations.

[executor]
network_concurrent = 128
cpu_concurrent = 10
disk_io_concurrent = 64

Disk I/O Profile

Tunes disk I/O concurrency based on your storage type. This is set in the [cache] section.

When set to auto on Linux, XEarthLayer detects the storage type by checking /sys/block/<device>/queue/rotational. If detection fails, it defaults to the ssd profile as a safe middle-ground.

[cache]
disk_io_profile = auto

FUSE Kernel Parameters

Controls Linux FUSE kernel limits for concurrent background requests. The Linux kernel’s default limits (12 max background / 9 congestion threshold) are far too low for X-Plane’s concurrent scenery reads.

[fuse]
max_background = 256
congestion_threshold = 192

Logging

Controls where XEarthLayer writes its log file.

[logging]
file = ~/.xearthlayer/xearthlayer.log

Run xearthlayer --help or xearthlayer <command> --help for built-in usage information.

Service Management

xearthlayer / xearthlayer run

Start XEarthLayer and mount all installed packages. This is the default command — running xearthlayer with no arguments is equivalent to xearthlayer run.

xearthlayer
xearthlayer run --provider bing --parallel 32
xearthlayer run --airport KJFK

To stop the service, press q in the terminal for a clean shutdown (unmounts FUSE, flushes cache). Ctrl+C also works.

Setup & Configuration

xearthlayer init

Create a default configuration file. Auto-detects your X-Plane installation and writes config.ini.

xearthlayer init

xearthlayer setup

Interactive setup wizard. Detects your X-Plane installation, checks hardware, and recommends settings. Recommended for first-time users.

xearthlayer setup

xearthlayer config get <KEY>

Read a single configuration value. Keys use section.key format.

xearthlayer config get provider.provider_type
xearthlayer config get cache.disk_size

xearthlayer config set <KEY> <VALUE>

Write a configuration value.

xearthlayer config set provider.provider_type bing
xearthlayer config set cache.disk_size 10737418240

xearthlayer config list

Display all configuration settings grouped by section.

xearthlayer config list

xearthlayer config path

Print the full path to the configuration file.

xearthlayer config path

xearthlayer config upgrade

Upgrade your configuration file to the current version. Adds missing settings with defaults and removes deprecated entries. A timestamped backup is created automatically.

xearthlayer config upgrade --dry-run   # Preview changes without modifying
xearthlayer config upgrade             # Apply the upgrade

Package Management

xearthlayer packages list

List all installed packages.

xearthlayer packages list
xearthlayer packages list --verbose

xearthlayer packages check

Check the package library for available updates.

xearthlayer packages check

xearthlayer packages install <REGION>

Install a regional scenery package. Region codes are short identifiers like eu, na, sa.

xearthlayer packages install eu
xearthlayer packages install na --type overlay

xearthlayer packages update [REGION]

Update installed packages. If no region is specified, checks all installed packages for updates.

xearthlayer packages update eu
xearthlayer packages update --all

xearthlayer packages remove <REGION>

Remove an installed package.

xearthlayer packages remove eu
xearthlayer packages remove na --type overlay --force

xearthlayer packages info <REGION>

Show detailed information about an installed package.

xearthlayer packages info eu
xearthlayer packages info na --type overlay

Cache Management

xearthlayer cache stats

Show disk cache location, file count, and total size.

xearthlayer cache stats

xearthlayer cache clear

Delete all cached tiles from the disk cache.

xearthlayer cache clear

Scenery Index

The scenery index maps installed packages to tile coordinates, enabling adaptive prefetching. It is built automatically on startup, but you can manage it manually.

xearthlayer scenery-index status

Show index cache status including version, package count, and tile counts.

xearthlayer scenery-index status

xearthlayer scenery-index update

Rebuild the scenery index from installed packages. Useful after manually adding or removing package files.

xearthlayer scenery-index update

xearthlayer scenery-index clear

Delete the scenery index cache file. It will be rebuilt automatically on the next xearthlayer run.

xearthlayer scenery-index clear

Patches

Patches are pre-built Ortho4XP tiles with custom mesh or elevation data. XEarthLayer overlays them with dynamically generated textures at runtime.

xearthlayer patches list

List installed patches with validation status, priority order, and file counts.

xearthlayer patches list

xearthlayer patches validate

Validate patch directory structure and required files.

xearthlayer patches validate
xearthlayer patches validate --name my-patch

xearthlayer patches path

Print the configured patches directory path.

xearthlayer patches path

Diagnostics

xearthlayer diagnostics

Output system diagnostics including GPU detection, system information, and configuration details. Useful for bug reports.

xearthlayer diagnostics

Available Regions

AF1 in cyan, AF2 in yellowgreen, AS1 in firebrick, AS2 in crimson, AS3 in red, AS4 in palevioletred, EU in orange, EU2 in tangerine, NA in blue, OC in purple, SA in green.

Managing Packages

Use the xearthlayer packages command to list, install, update, and remove regional packages. For example, to install the Europe region:

xearthlayer packages install EU

See the CLI Reference for all package commands and options.

Scenery Ordering

Setting the scenery pack order in your X-Plane 12/Custom Scenery/scenery-packs.ini file is essential to ensure all of your scenery loads with the correct priority relative all others.

Scenery Pack Loading Order

XEarthLayer uses a best effort attempt by using a specific naming convention to ensure scenery is ordered correctly in X-Plane’s scenery pack file. XEarthLayer scenery files are all prefixed zzXEL_<ortho> or yzXEL_<overlay>.

When X-Plane launches for the first time after any change to the Custom Scenery folder, it rebuilds the scenery-packs.ini file based on the scenery packs available. It is likely that this process will result in incorrect ordering of the scenery packs installed.

Ensure you exit from X-Plane before starting a flight, then use the reference below to order your scenery correctly in the scenery pack file.

I
1000 Version
SCENERY

SCENERY_PACK Custom Scenery/{Airports, landmarks, other object based scenery}
SCENERY_PACK Custom Scenery/{Airport Overlays}
SCENERY_PACK Custom Scenery/{Airport Mesh}
SCENERY_PACK Custom Scenery/{Sim Heaven X-World, other layers (SFP Global etc)}
SCENERY_PACK Custom Scenery/X-Plane Airports
SCENERY_PACK *GLOBAL_AIRPORTS*
SCENERY_PACK Custom Scenery/X-Plane Landmarks

# XEarthLayer Start
SCENERY_PACK Custom Scenery/yzXEL_overlay/
SCENERY_PACK Custom Scenery/zzXEL_ortho/
# XEarthLayer End

SCENERY_PACK Custom Scenery/{Libraries}

X-Plane Graphics Settings

X-Plane 12 offers extensive graphics customization, but pushing every slider to maximum will overwhelm even high-end systems. Finding the right balance ensures smooth framerates while still enjoying XEarthLayer’s satellite imagery.

Settings That Matter Most

Texture Resolution — This directly correlates with your GPU’s VRAM capacity. If you exceed your available VRAM, X-Plane will constantly swap textures in and out of memory, causing stutters. As a general guide:

• 8GB VRAM: Medium to High
• 12GB+ VRAM: High to Maximum

Antialiasing — X-Plane offers FSAA and MSAA options. MSAA above 2× will noticeably impact performance even on high-end graphics cards. For most systems, 2× MSAA provides a good balance between image quality and framerate.

FSR (FidelityFX Super Resolution) — AMD’s upscaling technology renders at a lower resolution then upscales the image. This can dramatically improve performance with a modest reduction in image sharpness. If you’re struggling with framerates, try FSR in Quality or Balanced mode before reducing other settings.

World Objects — Controls the density of autogen buildings, vegetation, and other scenery objects. This setting primarily affects CPU performance. Reducing it can help if you experience stutters in densely populated areas.

Rendering Distance — Determines how far X-Plane renders detailed scenery. Higher values increase the visible scenery range but require the system to process more data. XEarthLayer streams tiles based on your position, so moderate draw distances (Medium to High) work well without overwhelming the tile generation pipeline.

General Advice

Start with X-Plane’s default settings for your hardware tier, then adjust individual options based on what you observe. Monitor your framerate in different scenarios—cold and dark at a busy airport, cruise over varied terrain, approach into a detailed city—and tune settings accordingly.

Recommended Add-ons

XEarthLayer provides satellite imagery, but pairing it with quality scenery add-ons enhances the overall visual experience. These add-ons complement XEarthLayer well:

SimHeaven X-World (Recommended)

SimHeaven X-World is a comprehensive free scenery enhancement that uses OpenStreetMap data combined with Microsoft building footprints to place objects realistically across the globe. Unlike automated autogen, objects are positioned based on real-world data, resulting in a more authentic look and feel.

X-World includes:

• Accurately placed buildings based on real-world footprints
• Road networks and infrastructure
• Vegetation and forest coverage
• Continental packages for Europe, North America, South America, Asia, Africa, Australia, and Antarctica

If you’re only going to install one scenery add-on alongside XEarthLayer, we recommend X-World for its comprehensive coverage and seamless integration with satellite imagery.

GeoReality Global Forests V2

Global Forests V2 from Orbx provides scientifically accurate forest coverage worldwide. Real-world forest data has been analyzed to recreate authentic ecosystems with correct tree types, density, and height variations.

Global Forests includes:

• Over 400 unique forest files based on real-world analysis
• Accurate tree species placement by region
• Coverage for Europe, North America, South America, Asia, Oceania, and Africa
• Seamless integration with ortho scenery

This is a paid add-on available through Orbx Central.

X-Codr Airport Enhancement Package (AEP)

Airport Enhancement Package from X-Codr Designs dramatically improves the visual quality of default airports worldwide. Rather than adding new airports, AEP replaces existing textures and objects with high-quality alternatives featuring PBR materials and regional variations.

AEP includes:

• High-quality replacement models for airport buildings, hangars, and facades
• Ultra high-resolution pavement and marking textures
• New 3D vegetation matched to X-Plane 12’s forest system
• Detailed static ground vehicles, runway lights, beacons, and navaids
• Weather-reactive ground textures using X-Plane 12’s weather effects
• Regional variations giving airports a unique local character

AEP is compatible with other airport enhancement libraries and works seamlessly with ortho scenery. This is a paid add-on available from X-Plane.org.

Short Final Design SFD Global

SFD Global from Short Final Design enhances autogen buildings and landmarks across the globe with regionally appropriate variations. The package uses PBR materials and baked ambient occlusion for realistic rendering.

SFD Global includes:

• Eight distinct regional autogen styles: Africa & Middle East, Australia, East Asia, Mediterranean, New England, Scandinavia, South America, and US West Coast
• Unique 3D buildings with PBR materials for each region
• Detailed world-famous landmarks
• 4K photorealistic terrain and forest textures
• Seamless compatibility with ortho scenery overlays

This is a paid add-on available from X-Plane.org.

This is ideal when you want to keep specific zoom levels, custom imagery sources, or hand-tuned scenery for regions you fly most often, while still getting XEarthLayer’s streamed coverage everywhere else.

How Patches Work

A patch is a folder containing standard Ortho4XP output — DSF meshes, terrain definitions, and DDS textures — placed inside the XEarthLayer patches directory. When XEarthLayer starts, it scans the patches directory for valid tile data and registers which 1 degree by 1 degree regions are covered. Any request from X-Plane that falls within a patched region is served directly from your local files rather than being streamed.

Patched regions completely replace package files for those 1 degree by 1 degree areas. There is no blending or mixing — your custom tiles take full priority.

Directory Structure

Place your Ortho4XP output folders inside the patches directory:

~/.xearthlayer/patches/
├── A_MyRegion/
│   ├── Earth nav data/
│   │   └── +40-080/
│   │       └── +41-074.dsf
│   ├── terrain/
│   │   └── *.ter
│   └── textures/
│       └── *.dds
└── B_AnotherRegion/
    └── ...

Each subfolder inside patches/ is one patch. The required contents are:

Configuration

Patches are enabled by default. The relevant settings live in the [patches] section of ~/.xearthlayer/config.ini:

[patches]
enabled = true
directory = ~/.xearthlayer/patches

You can also manage patches from the command line. See the CLI Reference for available xearthlayer patches commands.

Prefetch Integration

XEarthLayer automatically detects which 1 degree by 1 degree regions are covered by your patches and excludes them from streaming and prefetching. This means:

• No bandwidth is spent downloading tiles you already have locally
• Prefetch cycles skip patched regions entirely
• No configuration is needed — detection is automatic based on the DSF files in your patches

Verification

Use the CLI to confirm your patches are correctly set up:

# List all patches and their validation status
xearthlayer patches list

# Validate directory structure and file integrity
xearthlayer patches validate

The list command shows each patch folder, the 1 degree by 1 degree regions it covers, and whether the required files are present. The validate command performs a deeper check on directory structure and file integrity.

In flight, patched areas are easy to spot — your custom tiles appear immediately with no download delay, while streamed areas may take a moment to load on a cold cache.

What is XEarthLayer?

XEarthLayer is a just-in-time satellite imagery streaming system for X-Plane 12. Instead of downloading hundreds of gigabytes of ortho scenery upfront, XEarthLayer streams satellite imagery on-demand as you fly.

Which operating systems are supported?

Currently, XEarthLayer supports Linux only. macOS support may be added in the future if there is enough community interest.

Please add a feature request/up vote on Github if you would like to see XEarthLayer on macOS.

Windows is well supported by alternative products and likely will never be supported.

Is XEarthLayer free?

Yes, XEarthLayer is free and open source software released under the MIT license.

How is XEarthLayer different from other software, like AutoOrtho for example?

XEarthLayer, AutoOrtho, X-Plane Map Enhancement and similar tools all achieve the same objective: streaming satellite orthographic photo scenery into the X-Plane simulator. They all work in largely the same way.

XEarthLayer was designed to be as lightweight and fast as possible, using minimal memory and CPU time to deliver scenery to X-Plane efficiently.

For this reason, Rust was chosen as the implementation language, given its core principles of Performance, Reliability and Productivity. AutoOrtho was implemented in Python, which is popular but not ideally suited for high-throughput runtime environments.

The author of XEarthLayer had been using both AutoOrtho and X-Plane Map Enhancement on a Windows setup previously. When the simulator was migrated to Linux in 2025, the original AutoOrtho was unable to maintain a stable simulator session. XEarthLayer was created in response to not being able to use the alternatives.

Ultimately, all of these systems provide the same in-simulator experience, so which one you use is completely up to you.

As of March 2026

Can XEarthLayer be used with Microsoft Flight Simulator?

No.

Installation

Why won’t XEarthLayer run?

XEarthLayer should provide messages to the command line if there is an issue executing any part of the program. If you are not seeing any output, check your system journal for issues that would prevent XEarthLayer from starting.

# Check kernel log for OOM kills or process terminations
journalctl -k --since "1 hour ago" | grep -iE "oom|killed process|out of memory"

# Check for xearthlayer specific entries
journalctl --since "1 hour ago" | grep -i xearthlayer

These are some factors that could prevent XEarthLayer from launching:

• Incorrect system architecture for the binary
• System killing the process due to out of memory (OOM)
• Failure to initialize fuse mounts

Check XEarthLayer’s own logs for messages that may not be printed to stdout or stderr.

tail -f ~/.xearthlayer/xearthlayer.log

How do I update to the latest version?

Download the latest package for your distribution from the GitHub releases and install it over your existing installation.

Usage

How much bandwidth does XEarthLayer use?

Bandwidth usage depends on many factors: the detail level of the scenery you’re flying over, how much scenery is already cached locally, and your cache size.

Starting from a cold cache, expect to download about 6-10GB of data to initialize the simulator. During flight, you can expect to use 3-5GB per degree of traversal, depending on scenery type.

If you have an internet connection with data limits or caps, increase your disk cache size as much as possible to minimize repeated downloads. However, for metered connections, XEarthLayer’s value diminishes significantly—you may want to consider storing Ortho tiles locally instead.

Can I use XEarthLayer offline?

XEarthLayer requires an internet connection to stream imagery. However, previously downloaded tiles are cached locally, so areas you’ve flown before will load from cache even without connectivity.

Troubleshooting

X-Plane does not load XEarthLayer scenery into the simulator

This is usually because XEarthLayer’s FUSE mounts are not listed in X-Plane’s Custom Scenery/scenery_packs.ini file.

Checklist:

1. Ensure XEarthLayer is fully started and running before launching X-Plane. X-Plane indexes scenery at startup, so starting XEarthLayer afterward means its scenery won’t be detected.
2. Verify that zz_XEL_*_Ortho and zy_XEL_*_Overlay packs are listed in your scenery_packs.ini file. They typically appear at the bottom but can be anywhere in the file.

If the above doesn’t resolve the issue, ask for help on Discord, the X-Plane.org forums, or create a GitHub issue.

Tiles are downloading but not appearing in X-Plane

This can happen for several valid reasons:

1. You are flying in a region outside of XEarthLayer scenery coverage, but within the X-Plane or XEarthLayer loading range. X-Plane loads a large area around the aircraft to ensure scenery tiles are available before you can see them. XEarthLayer loads an even bigger radius to stay ahead of X-Plane.
2. You have a scenery package installed that provides its own mesh. Some third-party scenery providers include custom mesh that overrides XEarthLayer scenery for that specific area.

Help! I am seeing magenta tiles on the scenery when I fly.

Magenta tiles are returned when XEarthLayer is unable to construct a tile within the configured timeout period.

This can be caused by several factors:

• Slow or throttled downloads from the mapping service
• Operating system overhead reducing available CPU and memory
• Configuration that is too aggressive for your system’s capabilities
• Network or disk I/O bottlenecks

The XEarthLayer log outputs information about failed tile construction jobs and chunk downloads, so review it before posting in community channels.

If the situation persists, it is likely caused by configuration that exceeds your system’s capabilities. XEarthLayer deadlocks are rare but can occur if network or disk I/O is exhausted.

Try reducing the following settings by 50% and testing again. If things stabilize, you can slowly increase them one by one:

[cache]
disk_io_profile = auto

[texture]
format = bc1

[download]
timeout = 30
retries = 3

[executor]
network_concurrent = 64       # Default 128, reduce by 50%
cpu_concurrent = 4            # Default is ~num_cpus * 1.25, try half
disk_io_concurrent = 32       # Default 64, reduce by 50%
request_timeout_secs = 10
max_retries = 3

Help! I am seeing white tiles on the scenery when I fly.

This is usually caused by a FUSE mount issue, most commonly the result of the operating system killing the FUSE process due to out of memory (OOM) conditions.

If the operating system did kill the process, it will have added a journal entry of this event.

# Check for OOM killer activity
journalctl -k --since "1 hour ago" | grep -iE "oom|killed process|out of memory"

# Check for fuse-related errors
journalctl --since "1 hour ago" | grep -iE "fuse|xearthlayer"

If your system memory is less than 4GB, consider increasing swap space or upgrading RAM. See the Performance section for cache tuning recommendations.

GPU encoding is not working or the wrong GPU is selected

If you have configured texture.compressor = gpu and are experiencing issues, here are some common causes and solutions.

GPU not detected: Run xearthlayer diagnostics to list available GPU adapters on your system. If no GPUs are listed, ensure your GPU drivers are installed correctly and that Vulkan support is available. See the CLI Reference for more on the diagnostics command.

Wrong GPU selected (integrated vs discrete): On systems with both an integrated GPU (iGPU) and a discrete GPU (dGPU), XEarthLayer may select the wrong adapter. Configure the texture.gpu_device setting to target the correct GPU:

[texture]
compressor = gpu
gpu_device = integrated  ; Use iGPU for encoding while dGPU runs X-Plane

Valid values are integrated, discrete, or an adapter name substring (e.g., Radeon, RTX 5090). Run xearthlayer diagnostics to see available adapters.

Fallback options: If GPU encoding is not available or causes issues, you can always fall back to CPU-based compression. Set texture.compressor = ispc for SIMD-accelerated encoding, or texture.compressor = software for a portable fallback that works on any system.

I found a bug! How do I report it?

First, check the XEarthLayer GitHub issues to see if the bug has already been reported. If so, add your details to the existing issue. If it’s a new issue, follow the issue template to create a new report.

Where can I get help?

The XEarthLayer community is active and happy to help with questions, troubleshooting, and general discussion:

• Discord — Join the XEarthLayer Discord server for real-time chat with other users and the developer
• GitHub Discussions — Post questions and share ideas on GitHub Discussions
• GitHub Issues — Report bugs or request features via GitHub Issues

Performance

How can I improve performance?

Performance optimization is a broad topic that extends well beyond XEarthLayer itself. If you’re experiencing performance issues in X-Plane, they are most likely related to X-Plane’s rendering settings rather than XEarthLayer.

X-Plane settings to review

• Visual effects - Reduce reflection and shadow quality
• Draw distance - Lower the number of objects rendered at distance
• Anti-aliasing - Reduce MSAA or switch to FXAA
• Texture quality - Ensure this matches your VRAM capacity

XEarthLayer-specific tips:

• Ensure adequate disk cache to minimize network downloads during flight
• Use bc1 texture format instead of bc3 if you don’t need alpha transparency (smaller files, faster encoding)
• Monitor the XEarthLayer log for timeout warnings that may indicate bottlenecks
• If running on limited hardware, reduce executor.network_concurrent and executor.cpu_concurrent settings

For detailed configuration guidance, see the Configuration page.

What are the recommended cache settings?

Disk cache: Use as much space as you can reasonably allocate. Larger disk caches reduce network traffic and improve load times for previously visited areas. The default is 20GB; a minimum of 50GB is recommended, with 100GB+ being ideal for frequent flyers. For best results, place the cache on a fast NVMe or SSD that is not the primary system volume.

Memory cache: The default is 2GB. A value of 4-8GB works well for most systems. Adjust based on your available system memory, keeping in mind that X-Plane itself requires around 15GB during initial scene loading.

[cache]
memory_size = 8GB
disk_size = 50GB

Low memory systems: If system memory is limited (less than 32GB total), consider creating swap space to provide additional virtual memory for both XEarthLayer and X-Plane. This is particularly important if your GPU has less than 8GB of VRAM, as the system may need to accommodate texture overflow.

XEarthLayer was created to solve a fundamental problem in flight simulation: the trade-off between visual fidelity and storage requirements. Traditional ortho photo scenery requires downloading terabytes of satellite imagery before you can fly, and you end up storing data for places you may never visit.

XEarthLayer takes a different approach—streaming satellite imagery on-demand, exactly when and where you need it.

The Author

XEarthLayer was created by Sam de Freyssinet in 2025. Sam has been a flight simulator enthusiast for much of his life, ever since his first encounter with Microsoft Flight Simulator 2.0.

After an extended hiatus from flight simulation between 2000 and 2013, Sam returned to his passion. After a couple of years in the Prepar3D ecosystem, he migrated to X-Plane at the tail end of version 10.

Since rediscovering his passion for flying virtually, Sam started flight training for his real private pilot’s license in 2016.

When not piloting virtual or real aircraft, Sam works as a Software Engineering Director at a well-known tech company in the San Francisco Bay Area. He likes to snowboard with his children, cycle, and travel.

Motivation

In the summer of 2025, after many years of running his flight simulator on Microsoft Windows, Sam decided to migrate to Linux. Many factors drove this decision, but the catalyst was Windows 11 corrupting his main system NVMe drive after a routine update.

After successfully rebuilding his flight simulator on Linux and installing X-Plane 12, Sam was disappointed to find that the tools he had previously used for streaming orthophoto scenery into X-Plane were not available on the platform. One only supported Windows, while the other, AutoOrtho, was no longer maintained.

Given the situation, Sam decided to try and fix AutoOrtho on his own system but did not make much progress. Taking a step back, he asked the fateful question: how hard would it be to port AutoOrtho to Rust? As it turns out, quite hard—but not impossible.

XEarthLayer shares no code with AutoOrtho, and there have been many design decisions that resulted in significant changes to how scenery tiles are managed internally. With that said, it would be a disservice not to credit AutoOrtho as the inspiration for this project.

After starting work on XEarthLayer, Sam discovered that AutoOrtho had been forked by the community into AutoOrtho Continued. Definitely check that out if XEarthLayer is not for you.

Five months later, XEarthLayer was ready for its first public release.

Acknowledgments

XEarthLayer wouldn’t be possible without the contributions and support of many people.

Special Thanks

• kubilus1 for creating AutoOrtho, the original inspiration for this project
• xjs36uk for their testing and feedback on low specification systems that significantly improved the performance of XEarthLayer on memory constrained systems

Technologies

XEarthLayer is built with:

• Rust — Systems programming language
• Claude Code — AI assisted pair programming and documentation
• GitHub — Source code repository, CI/CD and hosting services
• Ortho4XP, Shred86 fork used to create regional scenery packages

Imagery Providers

Satellite imagery is sourced from various providers including:

• Apple Maps
• ArcGIS
• Bing Maps
• Google Maps
• MapBox
• USGS

Contact

• GitHub: samsoir/xearthlayer
• Discord: Join the community

License

XEarthLayer is released under the MIT License.