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.

Important

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 deserializes: number of deserializations, deserializations per second, average deserialization time, minimum deserialization time, and maximum deserialization time.
    • Measures the time spent parsing chunk NBT into Minecraft’s in-memory chunk representation after it has been read from disk.
  • 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.

graph

Graphs one or more of LinearReader’s benchmark statistics over time and exports the resulting graph(s) as SVG files.

If benchmark collection is not already enabled, starting a graph automatically enables it and begins a new benchmark measurement window.

The graph command looks as follows: graph <duration|until-stopped> <interval> <single-graph|multiple-graphs> <stat> [stat2 ...]. To break it down:

• <duration|until-stopped> - defines the number of seconds for which LinearReader should collect data. Must be a whole number or until-stopped. Running until-stopped will keep LinearReader collecting data until graph stop is run, at which LinearReader generates the graph(s).
• <interval> - defines how often (in seconds) LinearReader samples the selected statistics. Must be a whole number.
• <single-graph|multiple-graphs> - tells LinearReader whether to graph all stats included in the command on one graph, or whether to give each stat its own file. Only matters if more than one stat is being graphed but is always required, even if only one stat is being graphed.
• <stat> [stat2 ...] - select which stat(s) from the list to graph. Most statistics shown by the bench and health commands can be graphed.

Running graph status will show the current recording status.

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.

Note

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. Previously exported files are skipped if exporting is restarted later. Run export-mca to see the status of the export process.

voxy-compat

Important

Only available on Fabric 1.21.11-26.2 when the mod "Voxy" is installed.

This command essentially replaces Voxy's import current command, since Voxy cannot read .linear files. By running voxy-compat auto, LinearReader temporarily converts copies of the .linear region files into .mca files for Voxy to import. When it is completed LinearReader deletes all staged .mca files. No conversion happens to the original .linear region files.

Tip

If LinearReader says that the importing was successful but no Voxy LODs were generated, try deleting the linearreader-voxy-compat-state.properties file in the region folder and re-run /linearreader voxy-compat auto.