Struct File

pub struct File { /* private fields */ }

Available on crate features je and je-region only.

An object for handling region files with any NBT content, works with both .mcr and .mca files.

Allows for random access reading to any chunk in the file using serde::Deserialize implementations and writing with serde::Serialize implementations.

Examples

Copying the entities from one chunk to another:

use flate2::{read::ZlibDecoder, write::ZlibEncoder};
 
let file = OpenOptions::new()
   .read(true)
   .write(true)
   .open("test/r.0.0.mca")?;
let mut region = RegionFile::new(file)?;

struct CompHandler {}
impl CompressionHandler for CompHandler {
  fn decompress<'r, R: Read + 'r>(read: R, c: Compression) -> Box<dyn Read + 'r> {
       match c {
           Compression::Zlib => Box::new(ZlibDecoder::new(read)),
           _ => panic!("Should of been zlib compressed")
       }
   }
 
   fn compress<'w, W: Write + 'w>(write: W) -> (Box<dyn Write + 'w>, Compression) {
       (
           Box::new(ZlibEncoder::new(write, flate2::Compression::default())),
           Compression::Zlib
       )
   }
}
#[derive(Serialize, Deserialize, Debug, Clone)]
#[serde(rename_all="PascalCase")]
#[serde(deny_unknown_fields)]
struct EntityChunk {
   data_version: i32,
   #[serde(with="nbt::int_array")]
   position: [i32; 2],
   entities: Vec<nbt::Compound>
}
match region.read_chunk::<EntityChunk, CompHandler>(0, 0)? {
   Some(chunk) => {
       let mut new_chunk = chunk.clone();
       new_chunk.position = [1, 0];
       let mut i = 0;
       for entity in &mut new_chunk.entities {
           match entity.get_mut("Pos") {
               Some(tag) => {
                   match tag {
                       nbt::Tag::List(nbt::List::Double(pos)) => {
                           pos[0] += 16.0;
                       }
                       _ => {}
                   }
               },
               None => {}
           }

           match entity.get_mut("UUID") {
               Some(uuid) => {
                   *uuid = nbt::Tag::IntArray(vec![0, 0, 0, i]);
               },
               None => {}
           }
           i += 1;
       }

       region.write_chunk::<EntityChunk, CompHandler>(1, 0, &new_chunk, "")?;
   },
   None => println!("No chunk data")
}

Implementations

impl File

pub fn new(file: File) -> Result<Self>

Creates a new region File object from rust’s std::fs::File object

Makes the underlying rust file a multiple of 4KiB as per specification

pub fn dealloc_chunk(&mut self, chunk: u16) -> Result<()>

Deallocates the chunk with id chunk

This method only frees up the space in the file taken up by the chunk to be used by future chunk writes that fit in the space, it doesn’t remove the data.

pub fn read_chunk<'de, T: Deserialize<'de>, C: CompressionHandler>( &mut self, chunk: u16, ) -> Result<Option<T>>

Attempts to read the chunk with table id chunk as T, C turns the compressed data from the file and turns it into decompressed data depending on the compression type passed in.

If there is no data for the chunk it returns None, if it fails to deserialize into T it returns an Err.

pub fn write_chunk<T: Serialize, C: CompressionHandler>( &mut self, chunk: u16, v: &T, name: &'static str, ) -> Result<()>

Writes the chunk data v to the chunk with id chunk with the root name name, C turns the uncompressed data into compressed data before writing it to the file.

pub fn flush(&mut self) -> Result<()>

Makes sure any internal state of the region file is written

pub fn chunks(&self) -> &[u16]

Returns a slice of chunk ids that have chunk data

pub fn sync_all(&mut self) -> Result<()>

Runs File::sync_all on the underlying file

Can be used to block code execution until all io operations on the file are finished

pub fn normalize_size(&mut self) -> Result<u64>

Ensures that the file is a multiple of 4KiB as per specification.

Returns the new file size in bytes.