Updated API (markdown)

API.md

@@ -1,10 +1,144 @@
-### FaweAPI class:
-https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/FaweAPI.java
+# Note:
+ - FastAsyncWorldEdit (FAWE) is not a replacement for WorldEdit (WE). 
+ - Using normal WE classes will have the same behavior with or without FAWE (it would just be faster). 
+ - Having FAWE installed allows most classes to be used from an async thread.
+ - The FAWE API offers some additional functionality not already present in WE.
+ 
+##### I'll first go over some stuff in FAWE, then I'll include some normal WE examples:
 
-> FaweAPI.[some method]
+# The FaweAPI
+The FaweAPI has some various methods that may be useful:
+ - getNewEditSession
+ - getTaskManager
+ - wrapPlayer
+ - createQueue
+ - getWorld
+ - getMaskManagers
+ - isMemoryLimited
+ - getFastRandom
+ - getRegions
+ - cancelEdit
+ - addMaskManager
+ - getChangeSetFromFile
+ - getBDFiles
+ - getChangeSetFromDisk
+ - checkVersion
+ - fixLighting
+ - streamSchematic
+ - addTask
+ - addMemoryLimitedTask
+ - addMemoryPlentifulTask
+ - getTranslations
 
-The FAWE API isn't intended to replace the WorldEdit API. You may still freely use the latter for most purposes.
+Source: https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/FaweAPI.java
 
-### Using the WorldEdit API
-With FAWE installed you can use the WorldEdit API from an async thread:
- - e.g. Get or set blocks using the EditSession from an async task.
+See also: 
+ - https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/object/FawePlayer.java
+
+# Wrappers for Bukkit API
+FAWE offers some async wrappers for the Bukkit API:
+```Java
+final AsyncWorld world = AsyncWorld.wrap(bukkitWorld);
+TaskManager.IMP.async(new Runnable() {
+    @Override
+    public void run() {
+        Block block = world.getBlockAt(0, 0, 0);
+        block.setType(Material.BEDROCK);
+        // When you are done
+        world.commit();
+    }
+});
+```
+Source: https://github.com/boy0001/FastAsyncWorldedit/tree/master/bukkit0/src/main/java/com/boydti/fawe/bukkit/wrapper
+
+See also:
+ - https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/wrappers/PlayerWrapper.java
+ - https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/wrappers/WorldWrapper.java
+
+# The FaweQueue
+The FaweQueue is a basic queue for modifying the world:
+ - Use it to modify whole chunks or individual blocks
+ - It is very implementation specific i.e. it relies heavily on chunks and block ids
+ - Can be used from an async thread
+
+```Java
+// Auto queuing will mean blocks start to place before it is flushed
+FaweQueue queue = FaweAPI.createQueue(worldName, autoQueue);
+queue.setBlock(0, 0, 0, id, data);
+queue.setBiome(0, 0, biome);
+// Set entire chunks
+FaweChunk<?> chunk = queue.getFaweChunk(5, 5);
+chunk.fill(id, data);
+chunk.addToQueue();
+// Repeat the same for position
+chunk = chunk.copy(true);
+chunk.setLoc(queue, 5, 6);
+chunk.addToQueue();
+```
+
+# Quickly run something on the main thread
+With FAWE you can temporarily switch to the main thread to do something
+```Java
+// E.g. Get a player's inventory but you are on an async thread.
+PlayerInventory inventory = TaskManager.IMP.sync(new RunnableVal<PlayerInventory>() {
+    @Override
+    public void run(PlayerInventory value) {
+        this.value = player.getInventory();
+    }
+});
+```
+
+# WE uses its own player and world objects
+Getting the WE World object
+```Java
+// WE has its own classes for Player(s) and World(s) which will be needed
+WorldEdit.getInstance().getServer().getWorlds();
+// Or for Bukkit specifically
+BukkitUtil.getLocalWorld(bukkitWorld);
+```
+Getting the player
+```Java
+// Bukkit
+WorldEditPlugin worldEdit = (WorldEditPlugin) Bukkit.getServer().getPluginManager().getPlugin("WorldEdit");
+worldedit.wrapPlayer(bukkitPlayer);
+// Forge
+ForgeWorldEdit.inst.wrap(entityPlayer);
+// Or with FAWE
+FawePlayer.wrap(uuid or username or actor or player object).getPlayer();
+```
+
+# Creating an EditSession:
+The EditSession is a WE class which is used to make and record changes to a world.
+ - If you just want to make simple block changes without history, see the FaweQueue or AsyncWorld example above
+ - With FAWE, the EditSession (and most other WE classes) can be used off the main thread
+```Java
+// Without FAWE
+EditSession editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(worldEditWorld, -1);
+// Or for a specific player
+editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(worldEditWorld, -1, actor);
+// With FAWE
+editSession = FaweAPI.getNewEditSession(worldEditWorld);
+// Or for a specific player
+editSession = FaweAPI.getNewEditSession(fawePlayer);
+
+// Do stuff with the EditSession
+editSession.setBlock(new Vector(x, y, z), new BaseBlock(id, data));
+// All changes will have been made once flushQueue is called
+editSession.flushQueue();
+```
+
+# Pasting a schematic
+```Java
+File file = new File("path/to/schematic");
+boolean noAir = false;
+boolean entities = true;
+Vector position = new Vector(0, 0, 0);
+SchematicFormat.getFormat(file).load(file).paste(editSession, position, noAir, entities);
+```
+
+# Undoing an EditSession
+Where `editSession` is what you are undoing.
+```Java
+EditSession newEditSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(editSession.getWorld(), -1, null, null);
+editSession.undo(newEditSession);
+```