Updated API (markdown)

API.md

@@ -1,20 +1,24 @@
-# Note:
+# Note: 
- - FastAsyncWorldEdit (FAWE) is not a replacement for WorldEdit (WE). 
+ - Using the WE API will have the same behavior with FAWE (it would just be faster). 
- - 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.
- 
+ - Learn about concurency if you haven't already.
-##### I'll first go over some stuff in FAWE, then I'll include some normal WE examples:
 
-# The FaweAPI
+### Minecraft + Async
-The FaweAPI has some various methods that may be useful:
+The Minecraft server for the most part is single threaded and usually can't be modified or read async
+ - Setting a block async (if it weren't blocked) would likely crash the server
+ 
+The FAWE API can abstract most things so that they can safely be used async.
+ - Requests will be made to the main thread when needed
+
+### The FaweAPI class has some various methods that may be useful:
+ - upload
+ - load
  - getEditSessionBuilder
  - getTaskManager
  - wrapPlayer
  - createQueue
  - getWorld
- - upload
- - load
  - getMaskManagers
  - isMemoryLimited
  - getFastRandom
@@ -33,17 +37,14 @@ The FaweAPI has some various methods that may be useful:
 
 Source: https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/FaweAPI.java
 
-See also: 
+### Wrappers for Bukkit API
- - 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
 TaskManager.IMP.async(new Runnable() {
     @Override
     public void run() {
-        AsyncWorld world = AsyncWorld.wrap(bukkitWorld);
+        AsyncWorld world = AsyncWorld.create(new WorldCreator("MyWorld"));
-        // AsyncWorld world = AsyncWorld.create(new WorldCreator("MyWorld")); // Or create a new world
+        // AsyncWorld world = AsyncWorld.wrap(bukkitWorld); // Or wrap existing world
         Block block = world.getBlockAt(0, 0, 0);
         block.setType(Material.BEDROCK);
         // When you are done
@@ -52,12 +53,101 @@ TaskManager.IMP.async(new Runnable() {
 });
 ```
 Source: https://github.com/boy0001/FastAsyncWorldedit/tree/master/bukkit0/src/main/java/com/boydti/fawe/bukkit/wrapper
+ 
+### WorldEdit Player/World
+WorldEdit has its own Player and World classes which will be needed for some methods.
 
-See also:
+Getting the WE World object:
- - https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/wrappers/PlayerWrapper.java
+```Java
- - https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/wrappers/WorldWrapper.java
+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);
+// Alternative with FAWE
+FawePlayer.wrap(uuid or username or actor or player object here).getPlayer();
+```
 
-# The FaweQueue
+For use async see e.g. `PlayerWrapper.wrap(player)`
+ - [PlayerWrapper (WorldEdit Player)](https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/wrappers/PlayerWrapper.java)
+ - [WorldWrapper (WorldEdit World)](https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/wrappers/WorldWrapper.java)
+
+### The EditSession
+The EditSession is used by WorldEdit to make and record changes to the World. The EditSessionBuilder gives you full control over it. 
+ - A world must be provided, see `FaweAPI.getWorld(...)`
+
+Example:
+```Java
+EditSession editSession = new EditSessionBuilder(world)
+.fastmode(true)
+.build;
+```
+Unset values will revert to their default:
+ - player: The player doing the edit (defaults to to null)
+ - limit: Block/Entity/Action limit (defaults to player limit or unlimited)
+ - changeSet: Stores changes (defaults to config.yml value)
+ - allowedRegions: Allowed editable regions (defaults to player's allowed regions, or everywhere)
+ - autoQueue: Changes can occur before flushQueue() (defaults true)
+ - fastmode: bypasses history (defaults to player fastmode or config.yml console history)
+ - checkMemory: If low memory checks are enabled (defaults to player's fastmode or true)
+ - combineStages: If history is combined with dispatching (defaults to config value)
+ - blockBag: The blockbag to use (defaults to null)
+ - eventBus: The eventBus to use (defaults to null)
+ - event: The event to call (defaults to null)
+
+See: https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/util/EditSessionBuilder.java
+
+Here's a non FAWE example:
+```Java
+// If no player is doing the changes
+EditSession editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(worldEditWorld, -1);
+// For a specific player
+editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(worldEditWorld, -1, actor);
+
+// 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();
+```
+
+### The FawePlayer
+To get a new Player use `FawePlayer.wrap(player, uuid, username, etc)`
+
+Here are the methods
+ - getWorld
+ - getLocation
+ - sendTitle
+ - resetTitle
+ - getLimit
+ - getName
+ - getUUID
+ - hasPermission
+ - setPermission
+ - sendMessage
+ - executeCommand
+ - getPlayer
+ - getSession
+ - getSelection
+ - setSelection
+ - getCurrentRegions
+ - getLargestRegion
+ - hasWorldEditBypass
+ - setMeta
+ - getMeta
+ - deleteMeta
+ - getNewEditSession
+ - runIfFree
+ - runAsyncIfFree
+ 
+See: https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/object/FawePlayer.java
+ 
+### The FaweQueue
 The FaweQueue is a basic queue for modifying the world from async threads
  - Use it to modify whole chunks or individual blocks efficiently
  - See EditSession or AsyncWorld which will be easier to use but slower
@@ -77,10 +167,10 @@ chunk.setLoc(queue, 5, 6);
 chunk.addToQueue();
 ```
 
-# Quickly run something on the main thread
+### Tasks
 With the FAWE TaskManager 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.
+// E.g. Get a player's inventory but you are currently on an async thread.
 PlayerInventory inventory = TaskManager.IMP.sync(new RunnableVal<PlayerInventory>() {
     @Override
     public void run(PlayerInventory value) {
@@ -90,48 +180,7 @@ PlayerInventory inventory = TaskManager.IMP.sync(new RunnableVal<PlayerInventory
 ```
 See: https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/util/TaskManager.java
 
-# WE uses its own player and world objects
+### Pasting a schematic
-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);
-// Alternative
-FawePlayer.wrap(uuid or username or actor or player object here).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
-// If no player is doing the changes
-EditSession editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(worldEditWorld, -1);
-// For a specific player
-editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(worldEditWorld, -1, actor);
-// If you have FAWE, the EditSessionBuilder is preferred as you can specify what functionality you need
-editSession = new EditSessionBuilder(world)
-// Any settings you want here
-.build();
-
-// 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();
-```
-
-See: https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/util/EditSessionBuilder.java
-
-# Pasting a schematic
 ```Java
 File file = new File("path/to/schematic");
 boolean noAir = false;
@@ -145,10 +194,12 @@ boolean allowUndo = true;
 EditSession editSession = SCHEMATIC.load(file).paste(world, position, allowUndo, !noAir, (Transform) null);
 ```
 
-# Undoing an EditSession
+### Undoing an EditSession
 Where `editSession` is what you are undoing.
 ```Java
+// Create a new EditSession however you want
 EditSession newEditSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(editSession.getWorld(), -1, null, null);
+// Undo it
 editSession.undo(newEditSession);
 editSession.flushQueue();
 ```