Configuration

Configure imagery providers, caching behavior, and performance settings.

XEarthLayer is configured through an INI file located at ~/.xearthlayer/config.ini. This page covers the essential settings to get flying, followed by advanced tuning sections for users who want more control.

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
dds_disk_ratio = 0.6
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

Generation

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

[generation]
threads = 8
timeout = 10

Executor

The executor is the core tile processing engine. These settings control how many tiles are processed at once and how chunk downloads are retried.

Each 4096x4096 scenery tile is assembled from 256 chunks — a 16x16 grid of 256x256 source images — so a single stalled chunk is what max_retries and request_timeout_secs exist to recover from.

Failed chunk downloads are retried with exponential backoff: the first attempt is immediate, then 100 ms, 200 ms and 400 ms.

[executor]
max_concurrent_jobs = 12
request_timeout_secs = 10
max_retries = 3
retry_base_delay_ms = 100

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

Package Manager

Controls where regional scenery packages are downloaded, installed and linked. Most users never need to change these — the setup wizard writes them.

disable_overlays is a runtime control, not an install-time one. When set to true, xearthlayer run removes the consolidated yzXEL_overlay/ folder from Custom Scenery on startup so X-Plane does not load XEarthLayer overlays. The overlay packages stay on disk — setting it back to false and restarting reinstates them with no re-download. Use this when you are running third-party overlay scenery that conflicts with XEarthLayer’s.

[packages]
install_location = ~/.xearthlayer/packages
auto_install_overlays = true
disable_overlays = false

Update Check

[general]
update_check = true

Obsolete Settings

Configuration files written by older versions may contain settings that XEarthLayer no longer uses. They are ignored rather than rejected, so an old file still loads, but they describe nothing the software does.

To remove them:

xearthlayer config upgrade --dry-run   # Preview
xearthlayer config upgrade             # Apply

A timestamped backup of your existing file is written before anything is changed.