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.

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

Provides a real-time performance 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.

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 and reports any that show signs of corruption as it runs. 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.

afk-compress

Running afk-compress start begins the compression, 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 60 seconds of running prune-chunks, 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 60 seconds of running the sync-backups command.

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. Run export-mca to see the status of the export process.