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
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