Plex-FAWE/README.md

142 lines
6.6 KiB
Markdown
Raw Normal View History

WorldEdit
=========
WorldEdit is a voxel and block manipulation library for Minecraft. It is
primarily a library but bindings to Bukkit (included) and SPC (external)
are available.
Compiling
---------
You need to have Maven installed (http://maven.apache.org). Once installed,
simply run:
mvn clean package install
Maven will automatically download dependencies for you. Note: For that to work,
be sure to add Maven to your "PATH".
Contributing
------------
We happily accept contributions. The best way to do this is to fork
WorldEdit on GitHub, add your changes, and then submit a pull request. We'll
look at it, make comments, and merge it into WorldEdit if everything
works out.
Your submissions have to be licensed under the GNU General Public License v3.
General Concepts
----------------
The entry point for all of WorldEdit is in `com.sk89q.worldedit.WorldEdit`.
This is where all the events and chat commands are handled. The commands
themselves are found in the `com.sk89q.worldedit.commands` package.
Each user has a _session_ that stores session-related data, including
history and clipboard. The class that handles session data is
`com.sk89q.worldedit.LocalSession`. A copy of it is created when needed
by the `getSession` method of `WorldEdit` and it's also stored on
`WorldEdit` in a hash map. The history is merely a list of
`com.sk89q.worldedit.EditSession`s, while the clipboard is a copy of
`com.sk89q.worldedit.CuboidClipboard`.
Now, one of the most important classes in WorldEdit is
`com.sk89q.worldedit.EditSession`. Nearly all block sets and gets are routed
through it because it automatically records a log of operations (for undo),
handles block placement order, and does a lot of magic to make sure things
come out the way it is intended. However, to make sure that block placement
order is adhered, remember to call `EditSession.enableQueue()` and later
`EditSession.flushQueue()`. Also, to actually an edit session in a player's
history, it has to be passed to `LocalSession.remember(EditSession)`.
Blocks in WorldEdit are entirely abstracted. Block types and block data not
simply passed around; rather, because blocks can contain a lot more data
(such as with signs and such), all blocks are an instance of
`com.sk89q.worldedit.blocks.BaseBlock`. For special block types, there's
a `SignBlock`, a `ChestBlock`, etc. Blocks are __detached__ from the world,
meaning they don't know where they are. You can pass them around freely
if you want (this is why syntax like `//set sign:3|Hi|there!` can work).
If you are making a command, you need to add the new command to `plugin.yml`
if you are using Bukkit. However,
`com.sk89q.worldedit.dev.DocumentationPrinter` is a program that will
generate `plugin.yml` by using Java reflection on the command classes.
Commands are given an edit session automatically (with queue
enabled) and so there's not much to set up. If you want to add a new class
altogether that contains commands, you need to update the constructor of
`com.sk89q.worldedit.WorldEdit` load your class.
### Core Routines ###
`com.sk89q.worldedit.WorldEdit.getBlock` handles the block syntax
(such as `sign:3|Hi|there!`).
`com.sk89q.worldedit.WorldEdit.getBlockPattern` handles the pattern
syntax (such as `90%rock,10%brick` or `#clipboard`).
Package Summary
---------------
WorldEdit is well organized and uses abstraction heavily to make adding new
things easy. An explanation of WorldEdit's package layout is as follows:
* `com.sk89q.bukkit.migration` has classes to handle permissions for
Bukkit plugins until Bukkit attains built-in permissions support
* `com.sk89q.util` has some utility classes
* `com.sk89q.util.commands` has some base command handling code
(commands in WorldEdit are defined using Java annotations)
* `com.sk89q.worldedit` has core WorldEdit classes
* `com.sk89q.worldedit.bags` has support for block sources and sinks
such as inventory (which allows blocks to be taken from a player's
inventory)
* `com.sk89q.worldedit.blocks` abstracts blocks from the game
(such as chest blocks, etc.) and has support for all block data
* `com.sk89q.worldedit.bukkit` contains the implementation of WorldEdit
for Bukkit as a plugin
* `com.sk89q.worldedit.commands` has all of WorldEdit's chat commands
* `com.sk89q.worldedit.data` contains classes to read Minecraft's world
files directly from disk
* `com.sk89q.worldedit.dev` contains a class to generate documentation
and other development-related files
* `com.sk89q.worldedit.filters` contains filters used for the smoothing
algorithm
* `com.sk89q.worldedit.patterns` contains the pattern support
(such as for `//set 90%rock,10%air` or `//set #clipboard`)
* `com.sk89q.worldedit.regions` contains the selection regions for
WorldEdit; there's only one at the moment (a cuboid), but different
region shapes can be added easily
* `com.sk89q.worldedit.scripting` contains scripting engines
* `com.sk89q.worldedit.snapshots` contains snapshot loading code (but
actual world file reading code is in `com.sk89q.worldedit.data`)
* `com.sk89q.worldedit.superpickaxe` contains the code for the different
super pickaxe modes
* `com.sk89q.worldedit.superpickaxe.brush` contains the different brush
shapes for the brush super pickaxe tools
* `com.sk89q.worldedit.util` has some utility classes
* `org.jnbt` is the JNBT library to read JNBT formatted files
Task Tutorials
--------------
### How to Add a Command ###
1. If you want to add your command to an existing category of commands
(check out the classes in `com.sk89q.worldedit.commands`) then you
can just re-use one. If you want to create a new class, create a new
class (it does not have to inherit or implement anything) and add it
to the constructor of `com.sk89q.worldedit.WorldEdit`.
2. Add a new method, named anything.
3. Add the `@Command` annotation to signify that it is a command. The
`aliases` property contains a list of command aliases and the first
one in the list is the main alias. `usage` contains parameter usage
information. `desc` is a short description. `flags` is an optional
string of flags (each flag is only one character long).
`min` is the minimum number of arguments. `max` is the maximum number of
arguments and it can be -1 to allow an unlimited number.
4. Adding `@CommandPermissions` causes permissions to be checked for the
command. Only one permission needs to be satisfied in the list.
5. Write the command.
6. If using Bukkit, update `plugin.yml` or run
`com.sk89q.worldedit.dev.DocumentationPrinter` to generate it for you.
7. Compile and test!