diff --git a/API.md b/API.md index e402f90..0614000 100644 --- a/API.md +++ b/API.md @@ -202,4 +202,51 @@ EditSession newEditSession = WorldEdit.getInstance().getEditSessionFactory().get // Undo it editSession.undo(newEditSession); editSession.flushQueue(); -``` \ No newline at end of file +``` + +### Streaming NBT files (e.g. Schematics) +With FAWE you can stream a schematic, or any NBT stream without having to store the whole thing into memory. + - You have to do this if a file is too large to fit in memory + - Or if you just want to obtain some information from the stream + +```Java +// Let's stream some info from a schematic file without having to load the whole thing into memory +// Schematics are compressed, so we need to use a GZIPInputStream before the NBTInputStream +File file = new File("blah.schematic"); +NBTInputStream is = new NBTInputStream(new GZIPInputStream(new FileInputStream(file))); +NBTStreamer streamer = new NBTStreamer(is); + +// Get the height,width,length +final Map dimensions = new HashMap<>(); +// You need to know the structure of the NBT file, these specific values are all shorts +streamer.addReader(new NBTStreamer.NBTStreamReader() { + @Override + public void run(Integer index, Short value) { + // The index is unimportant for this, but for Lists, or Arrays it might be useful + dimensions.put(getNode(), value); // Put e.g. Schematic.Width -> 53 + } +}, "Schematic.Width", "Schematic.Height", "Schematic.Length"); + +// Let's get the Entities, I know that they will be of type CompoundTag +streamer.addReader("Schematic.Entities.#", new NBTStreamer.NBTStreamReader() { + @Override + public void run(Integer index, CompoundTag entity) { + // For the .# and normal readers, it will always be Index, Value + // Here we can do something with each entitiy + } +}); + +// Get some info about the Blocks section (which contains the ids) (there's also AddBlocks, and Data) +streamer.addReader("Schematic.Blocks.?", new NBTStreamer.NBTStreamReader() { + @Override + public void run(Integer length, Integer type) { + Class clazz = NBTConstants.getClassFromType(type); + // Here we can do something knowing the length of the section and its type + } +}); + +// Now that we have the readers we want, we can read through the file +streamer.readFully(); +System.out.println("Dimensions are: " + dimensions); +``` +See: https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/jnbt/SchematicStreamer.java \ No newline at end of file