Module fastnbt::de [−][src]
Expand description
This module contains a serde deserializer. It can do most of the things you would expect of a typical serde deserializer, such as deserializing into:
- Rust structs.
- containers like
HashMap
andVec
. - an arbitrary
Value
. - enums. For NBT typically you want either internally or untagged enums.
This deserializer only supports from_bytes
. This is
usually fine as most structures stored in this format are reasonably small,
the largest likely being an individual Chunk which maxes out at 1 MiB
compressed. This allows us to avoid excessive memory allocations.
Avoiding allocations
Due to having all the input in memory, we can avoid allocations for things like strings and vectors, instead deserializing into a reference to the input data.
This deserializer will allow you to deserialize any list of integral value
to a &[u8]
slice to avoid allocations. This includes the ByteArray,
IntArray, LongArray types as well as a List that happens to be only one of
these types. This does however mean some more effort on the implementors
side to extract the real values. The fastanvil
crate can potentially do
some of this for you.
Other quirks
Some other quirks which may not be obvious:
- When deserializing to unsigned types such as u32, it will be an error if a
value is negative to avoid unexpected behaviour with wrap-around. This
does not apply to deserializing lists of integrals to
u8
slice or vectors. - You can deserialize a field to the unit type
()
. This ignores the value but ensures that it existed. - You cannot deserialize bytes directly into anything other than a
struct
or similar object egHashMap
. This is due to a misalignment between the NBT format and Rust’s types. Attempting to will give aNoRootCompound
error.
Example Minecraft types
This section demonstrates writing types for a few real Minecraft structures.
Extracting entities as an enum
This demonstrates the type that you would need to write in order to extract
some subset of entities. This uses a tagged enum in serde, meaning that it
will look for a certain field in the structure to tell it what enum variant
to deserialize into. We use serde’s other
attribute to not error when an
unknown entity type is found.
use serde::Deserialize; #[derive(Deserialize, Debug)] #[serde(tag = "id")] enum Entity { #[serde(rename = "minecraft:bat")] Bat { #[serde(rename = "BatFlags")] bat_flags: i8, }, #[serde(rename = "minecraft:creeper")] Creeper { ignited: i8 }, // Entities we haven't coded end up as just 'unknown'. #[serde(other)] Unknown, }
Capture unknown entities
If you need to capture all entity types, but do not wish to manually type all of them, you can wrap the above entity type in an untagged enum.
use serde::Deserialize; use fastnbt::Value; #[derive(Deserialize, Debug)] #[serde(untagged)] enum Entity { Known(KnownEntity), Unknown(Value), } #[derive(Deserialize, Debug)] #[serde(tag = "id")] enum KnownEntity { #[serde(rename = "minecraft:bat")] Bat { #[serde(rename = "BatFlags")] bat_flags: i8, }, #[serde(rename = "minecraft:creeper")] Creeper { ignited: i8 }, }
Avoiding allocations in a Chunk
This example shows how to avoid some allocations. The Section
type below
contains the block states which stores the state of part of the Minecraft
world. In NBT this is a complicated backed bits type stored as an array of
longs (i64). We avoid allocating a vector for this by storing it as a
&[u8]
instead. We can’t safely store it as &[i64]
due to memory
alignment constraints. The fastanvil
crate has a PackedBits
type that
can handle the unpacking of these block states.
#[derive(Deserialize)] struct Chunk<'a> { #[serde(rename = "Level")] #[serde(borrow)] level: Level<'a>, } #[derive(Deserialize)] struct Level<'a> { #[serde(rename = "Sections")] #[serde(borrow)] pub sections: Option<Vec<Section<'a>>>, } #[derive(Deserialize, Debug)] #[serde(rename_all = "PascalCase")] pub struct Section<'a> { #[serde(borrow)] pub block_states: Option<&'a [u8]>, }
Unit variant enum from status of chunk
use serde::Deserialize; #[derive(Deserialize)] struct Chunk { #[serde(rename = "Level")] level: Level, } #[derive(Deserialize)] struct Level { #[serde(rename = "Status")] status: Status, } #[derive(Deserialize, PartialEq, Debug)] #[serde(rename_all = "snake_case")] enum Status { Empty, StructureStarts, StructureReferences, Biomes, Noise, Surface, Carvers, LiquidCarvers, Features, Light, Spawn, Heightmaps, Full, }
Structs
Deserializer for NBT data. See the de
module for more information.
Functions
Deserialize into a T
from some NBT data. See the de
module for more
information.