Upstream/FastAsyncWorldedit
1
0
Fork 0
mirror of https://github.com/boy0001/FastAsyncWorldedit.git synced 2024-11-22 10:36:01 +01:00
Code Issues Projects Releases Wiki Activity

Updated API (markdown)

Jesse Boyd 2016-07-12 18:10:49 +10:00
parent 6aaddc952a
commit eb9839e67f
1 changed files with 115 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
API.md

@ -1,20 +1,24 @@
# 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).
# Note:
- Using the WE API will have the same behavior with 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:
- Learn about concurency if you haven't already.
# The FaweAPI
The FaweAPI has some various methods that may be useful:
### Minecraft + Async
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:
- https://github.com/boy0001/FastAsyncWorldedit/blob/master/core/src/main/java/com/boydti/fawe/object/FawePlayer.java
# Wrappers for Bukkit API
### 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")); // Or create a new world
AsyncWorld world = AsyncWorld.create(new WorldCreator("MyWorld"));
// 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:
- 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
Getting the WE World object:
```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
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
### 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();
```