Skip to content

Config

Jump to bottom
Bugfunbug edited this page Jul 14, 2026 · 6 revisions

LinearReader's config file can be found at config/linearreader-server.toml. In order for changes to take effect the server either needs to be restarted or /reload needs to be run.

The default config values have been tuned for general use, so edits to the config may not be necessary.

Some settings interact with each other, especially cache size and flushing behavior, so keep that in mind when tuning values.

For a more in-depth explanation of all of LinearReader's features, see the Features page.

Performance

compressionLevel

Defines the baseline level of compression for the initial compression of .linear files. LinearReader’s adaptive runtime policy may temporarily raise or lower the live compression level depending on server load and storage pressure. Very high levels of compression should probably be avoided, and instead the recompressor should be used. Must be a whole number value between 1 and 22.

  • Default value = 4
  • Lower value = faster saves and less CPU work, but larger files
  • Higher value = slower saves and more CPU work, but smaller files

regionCacheSize

Defines how many region files can be in the cache. A value between 128-512 is likely best, though it all depends on the server. Must be a whole number between 8 and 1024.

  • Default value = 256
  • Lower value = constant disk reads, which may cause worse performance
  • Higher value = more RAM usage, but may improve performance if many regions are accessed

Saving Behavior

regionsPerSaveTick

Defines the baseline save budget used by the adaptive flush policy. LinearReader may temporarily raise or lower the effective flush budget depending on backlog pressure, server activity, and runtime conditions. Must be a whole number between 1 and 64.

  • Default value = 4
  • Lower value = reduces per-tick load but may cause backlogs
  • Higher value = reduces backlogs but increases per-tick load

pressureFlushMinDirtyRegions / pressureFlushMaxDirtyRegions

Defines the baseline dirty-region pressure range used by the adaptive flush system. Together, these values control when LinearReader forces regions to be saved, and they prevent too many unsaved regions from building up in memory. LinearReader may dynamically adjust flushing aggressiveness depending on runtime pressure and maintenance state.

  • Default value (pressureFlushMinDirtyRegions) = 4
  • Default value (pressureFlushMaxDirtyRegions) = 16
  • Lower values = more aggressive flushing
  • Higher values = allows for more batching before flushing

Backups

backupEnabled

Defines whether backups should be created and maintained. If enabled, backups are automatically created after a region is first flushed and later refreshed over time based on region activity. Must be either true or false.

  • Default value = true

backupMinChangedChunks

Defines the minimum number of unique chunk changes before a backup refresh can occur.

  • Default value = 32
  • Lower values = generally more recent backups, but more disk writes
  • Higher values = generally less disk writes, but older backups

backupMinChangedKb

Defines the minimum amount of changed data (in KB) required before a backup refresh can occur.

  • Default value = 2048
  • Lower values = generally more recent backups, but more disk writes
  • Higher values = generally less disk writes, but older backups

backupMaxAgeMinutes

Defines the maximum time (in minutes) a backup can wait before being refreshed if changes exist.

  • Default value = 30
  • Lower values = fresher backups, but more disk writes
  • Higher values = less disk writes, but older backups

backupQuietSeconds

Defines the minimum amount of time (in seconds) since last region activity before a backup refresh can occur. Set to 0 to disable.

  • Default value = 60

Monitoring

slowIoThresholdMs

Defines how long (in milliseconds) a read/write must take for it to be logged. Can help detect lag or disk issues. Set to -1 to disable.

  • Default value = 500

diskSpaceWarnGb

Defines how much free disk space (in gigabytes) needs to be left to warn in the logs that disk space is low. Can help prevent unexpected disk-full crashes. Set to -1 to disable.

  • Default value = 1

Recompression

autoRecompressEnabled

Defines whether auto-recompression is enabled. Auto-recompression runs in the background during sufficiently quiet periods and is additionally gated by runtime pressure, maintenance budgets, and overall server load. Must be either true or false.

  • Default value = true

idleThresholdMinutes

Defines how long (in minutes) chunk I/O must be idle for before auto-recompression is engaged. This contributes to LinearReader’s quietness evaluation used to determine when background recompression may begin. Must be a whole number between 5 and 1440.

  • Default value = 20
  • Lower value = starts sooner
  • Higher value = waits longer

recompressMinFreeRamPercent

Defines the minimum percent of free memory required in order for recompression to continue, otherwise recompression will be paused. This is to prevent recompression from using too much memory. Must be a whole number between 5 and 50.

  • Default value = 15
  • Lower value = recompression can use more RAM
  • Higher value = recompression can't use as much RAM

MCA Conversion

bulkConvertOnLoad

Defines when LinearReader should convert all .mca files found in the region folders to .linear. If set to true then the bulk conversion will occur during world loading. If set to false then the bulk conversion will occur once the world has loaded. This should really only be set to false if world loading must be completed quickly, (such as if a server provider will terminate the world loading if it takes too long). Must be either true or false.

  • Default value = true

Misc

confirmWindowSeconds

Defines how long (in seconds) LinearReader will wait for confirmation after running the prune-chunks or sync-backups commands. Must be a whole number between 10 and 3600.

  • Default value = 60

Clone this wiki locally