From 376c64f5ef61f445eae74eb046152b8beea73ff7 Mon Sep 17 00:00:00 2001
From: Jesse Boyd <boy0001@users.noreply.github.com>
Date: Sun, 20 Aug 2017 16:38:00 +1000
Subject: [PATCH] Updated Anvil API (markdown)

---
 Anvil-API.md | 88 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 63 insertions(+), 25 deletions(-)

diff --git a/Anvil-API.md b/Anvil-API.md
index b6b90ee..44d2521 100644
--- a/Anvil-API.md
+++ b/Anvil-API.md
@@ -1,18 +1,56 @@
-The Anvil API is for modifying unloaded MCA files (`<world>/region`)
+# Overview
+The Anvil API is for modifying MCA files (`<world>/region`). If used properly, it is the fastest method to modify the world, however it is considerably more complicated than the [other methods](https://github.com/boy0001/FastAsyncWorldedit/wiki/API#modify-the-world-async-or-load-it).
 
-Relevant package:
-https://github.com/boy0001/FastAsyncWorldedit/tree/master/core/src/main/java/com/boydti/fawe/jnbt/anvil
-# Using with a FaweQueue
+# Using the MCAQueue (extends FaweQueue)
+#### Creating an MCAQueue with a loaded world
+If a world is loaded, the MCAQUeue must wrap the implementation FaweQueue. 
+The default queue will assist the MCAQUeue in modifying world files that are in use. 
 ```Java
-String worldName = "world";
-boolean hasSky = true;
-File root = new File(worldName + File.separator + "region");
-MCAWorld world = new MCAWorld(worldName, root, hasSky);
-MCAQueue queue = world.getQueue();
-// Do stuff here with the FaweQueue
+FaweQueue defaultQueue = SetQueue.IMP.getNewQueue(folder, true, false);
+MCAQueue mcaQueue = new MCAQueue(defaultQueue);
 ```
+#### Create an MCAQueue from an unloaded world
+If the world is unloaded, we just need to provide the world name, directory and tell it if it has sky light.
+```Java
+String world = "world"; // The name of the world
+File folder = new File(world + File.separater + "region");
+boolean hasSky = true; // If the world has sky
+MCAQueue mcaQueue = new MCAQueue(world, folder, hasSky);
+```
+### Using it like a normal FaweQueue
+```Java
+// Set a block at a position
+mcaQueue.setBlock(x, y, z, FaweCache.getBlock(BlockID.Stone, 0));
+mcaQueue.flushQueue();
+```
+### Using it in an EditSession or AsyncWorld
+Change the queue used by an EditSession when constructing it with the [`EditSessionBuilder#queue(mcaQueue)`](https://github.com/boy0001/FastAsyncWorldedit/wiki/WorldEdit-EditSession)
+
+Change the queue used by an AsyncWorld in the constructor `new AsyncWorld(world, queue)`
+### MCAQueue filtering
+A [MCAFilter](https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/jnbt/anvil/MCAFilter.java) lets you modify large areas very quickly by making use of multiple cores and using a structure that reduces lookup costs. The world is filtered from the least expensive to modify, to the most (Path, File, MCAFile, MCAChunk, BaseBlock). I.e. it is much quicker to replace an entire file or chunk than it is to modify individual blocks. 
+
+To use an existing filter, see [**here**](https://github.com/boy0001/FastAsyncWorldedit/tree/master/core/src/main/java/com/boydti/fawe/jnbt/anvil/filters).
+You can see them being used in the [**AnvilCommands**](https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/command/AnvilCommands.java) class
+```Java
+// If the world is loaded (use RegionWrapper.Global() for the entire world)
+MCAFilter result = mcaQueue.filterCopy(filter, region);
+// OR If the world is unloaded
+// MCAFilter result = mcaQueue.filterRegion(filter, region);
+// OR If the world is unloaded AND you want to filter the entire world
+// MCAFilter result = mcaQueue.filterWorld(filter, region);
+```
+
+### Copying from another MCAQueue
+Blocks can be copied/pasted from another MCAFile. 
+Note: If you just want to replace the entire world, it would be faster to use a filter to replace the entire `.mca` files. 
+```Java
+mcaQueue.pasteRegion(mcaQueueFrom, regionFrom, Vector offset);
+```
+
 # Generating MCA files
 See [HeightMapMCAGenerator](https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/jnbt/anvil/HeightMapMCAGenerator.java)    
+Or for more control, the [MCAWriter](https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/jnbt/anvil/MCAWriter.java)
 ```Java
 File dir = new File("TestWorld/region");
 // Create a new generator from a heightmap
@@ -45,21 +83,6 @@ System.out.println(gen.getLazyBlock(0, 255, 0)); // Get a specific block
 // Done, let's generate the world!
 gen.generate();
 ```
-# Using with an EditSession
-```Java
-String worldName = "world";
-boolean hasSky = true;
-File root = new File(worldName + File.separator + "region");
-MCAWorld world = new MCAWorld(worldName, root, hasSky);
-EditSession editSession = new EditSessionBuilder(world)
-    .checkMemory(false)
-    .allowedRegionsEverywhere()
-    .fastmode(true)
-    .changeSetNull()
-    .limitUnlimited()
-    .build();
-// Do stuff here with the editSession (non generated sections of the world cannot be modified)
-```
 
 # Replacing blocks
 ```Java
@@ -127,3 +150,18 @@ queue.filterWorld(new MCAFilter() {
 });
 ```
 
+# Using an MCAWorld
+```Java
+String worldName = "world";
+boolean hasSky = true;
+File root = new File(worldName + File.separator + "region");
+MCAWorld world = new MCAWorld(worldName, root, hasSky);
+EditSession editSession = new EditSessionBuilder(world)
+    .checkMemory(false)
+    .allowedRegionsEverywhere()
+    .fastmode(true)
+    .changeSetNull()
+    .limitUnlimited()
+    .build();
+// Do stuff here with the editSession (non generated sections of the world cannot be modified)
+```