Commands

LinearReader has many commands which either provide information and statistics, or perform certain actions. These commands are meant for server owners (or for use in singleplayer) and require operator level permissions to run them.

All commands are run by typing /linearreader followed by the desired command.

Monitoring/Info Commands

cache_info

Returns the number of regions currently open, current number of dirty regions, and an estimate for how much RAM is currently being used by the cache. For more information about the cache, see here.

storage

Returns the number of .linear and .bak files that exist for this world, how much storage each of those takes up, and total storage used by chunk data.

pos

Returns the player's current block coordinate (x, y, z), chunk coordinate (both the chunk's coordinates (i.e. 400, 400), and the player's chunk coordinates (i.e. 9, 9)), and which region file the chunk is stored in, along with whether that file is cached or not.

bench

Benchmark collection is disabled until bench reset is run. Running bench reset also clears previous statistics and starts a new measurement window.

Provides a runtime performance and storage behavior breakdown of LinearReader by providing the following information:

• How long the current measurement window has been active. Run bench reset to reset the window and start measuring anew.
• Chunk Activity:
  • Chunk reads: number of reads, reads per second, average read time, minimum read time, and maximum read time.
  • Chunk writes: number of writes, writes per second, average write time, minimum write time, and maximum write time.
• Disk Activity:
  • Region loads: how many region files (.linear files) were loaded into memory, average load time, minimum load time, and maximum load time.
  • Region flushes: how many regions were saved and written back on to the disk, average flush time, minimum flush time, and maximum flush time.
• Compression:
  • Uncompressed data size: of the total data written this session, how large would it be if it was raw, uncompressed data.
  • Compressed data size: of the total data written this session, how large is it after being compressed to the .linear format.
  • Storage saved percentage: the percentage of storage saved when compressing the raw data to .linear.
• Cache Behavior:
  • Linear cache: how often data was already decoded and ready to be reused.
  • Region wrapper cache: how often region files were already loaded into memory and used without requiring disk access.
    • A high wrapper cache rate is expected during normal gameplay since regions are kept in memory while players are nearby.
  • Resident reloads: number of regions in memory that were reloaded without being evicted.
  • Evictions: number of regions removed from memory due to cache limits.

bench debug

Provides all the information from bench, along with detailed timing information for different phases of region loading and saving. This command is mainly intended for debugging or advanced performance analysis.

• Additional load timing phases:
  • Read: time spent reading the .linear file from disk.
  • Verify: time spent validating checksums and file structure.
  • Zstd: time spent decompressing the region data.
  • Parse: time spent parsing chunk/NBT data into memory.
• Additional flush timing phases:
  • Snapshot: time spent copying region data into a save snapshot.
  • Build: time spent building the new .linear file structure.
  • Zstd: time spent compressing region data.
  • CRC: time spent generating checksums.
  • Write: time spent writing the file to disk.
  • Sync: time spent waiting for the operating system to fully flush data to disk.
  • Rename: time spent replacing the old region file with the newly written one.

health

Displays the current state of LinearReader’s adaptive runtime policy system, including:

• Current compression mode and load profile
• Active compression level
• Flush budget per tick
• Quietness and pressure scores
• Tick strain and cache churn
• Maintenance state and maintenance budget
• Maintenance debt levels
• Region heat statistics
• Resident cache targets and trimming statistics

This command is primarily intended for diagnosing storage pressure, deferred maintenance buildup, cache pressure, or overly aggressive recompression behavior.

health debug

Provides all information from health, along with additional internal policy and recompressor state:

• Last policy transition and transition reason
• Last recompressor decision
• Recompression scan statistics
• Low-RAM pause count
• Detailed maintenance debt values
• Internal maintenance budgets and resident cache targets

This command is mainly intended for debugging or advanced tuning.

pins

Lists all current regions pinned in the cache. See the Features page for more details.

verify

Runs in the background and scans all .linear files, validates file structure and checksums when present, and reports any files that show signs of corruption. This may take some time.

Action Commands

For more detailed information on all these features, see the Features page of this wiki.

Some of these commands may take a while to complete.

pin/unpin

Pins/unpins a region in the cache. A specific region file can be stated in the command. For example, running pin 1 -2 would pin the region file r.1.-2.linear. If no specific region is stated, it will pin the region the player is located in. Pinned regions are never evicted from the resident cache unless explicitly unpinned.

afk-compress

Running afk-compress start begins recompression, and afk-compress stop stops it. Running just afk-compress will return the current status of the recompression.

prune-chunks

Running this command does a dry-run of all region files, and determines which can safely be deleted or not. It will return a list of which files will be edited, and a short list of example chunks that will be deleted. In order to actually delete chunks you must run the command prune-chunks confirm within the configured confirmation window, otherwise the chunk pruning will be cancelled.

sync-backups

Running this command syncs all backup files to the current region files. Since it edits files, it does a dry-run first. To actually proceed with the backup syncing you must run sync-backups confirm within the configured confirmation window.

export-mca

Running export-mca start begins exporting all .linear files in Minecraft's .mca format to a folder next to the world folder. Running export-mca stop will stop it. Already-exported files are skipped if exporting is restarted later.. Run export-mca to see the status of the export process.