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.
Some dependencies are required:
- TrueZip provides snapshot reading
- Bukkit is a SMP plugin API
- GroupUsers provides an permission system for Bukkit
- Permissions provides an permission system for Bukkit
For links to downloads, check out http://wiki.sk89q.com/wiki/WorldEdit/Development
To compile a .jar, use the Ant build file with the 'jar' target.
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.
The entry point for all of WorldEdit is in
This is where all the events and chat commands are handled. The commands
themselves are found in the
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
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.EditSessions, while the clipboard is a copy of
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
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
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
if you are using Bukkit. However,
com.sk89q.worldedit.dev.DocumentationPrinter is a program that will
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.
com.sk89q.worldedit.WorldEdit.getBlock handles the block syntax
com.sk89q.worldedit.WorldEdit.getBlockPattern handles the pattern
syntax (such as
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.migrationhas classes to handle permissions for Bukkit plugins until Bukkit attains built-in permissions support
com.sk89q.utilhas some utility classes
com.sk89q.util.commandshas some base command handling code (commands in WorldEdit are defined using Java annotations)
com.sk89q.worldedithas core WorldEdit classes
com.sk89q.worldedit.bagshas support for block sources and sinks such as inventory (which allows blocks to be taken from a player's inventory)
com.sk89q.worldedit.blocksabstracts blocks from the game (such as chest blocks, etc.) and has support for all block data
com.sk89q.worldedit.bukkitcontains the implementation of WorldEdit for Bukkit as a plugin
com.sk89q.worldedit.commandshas all of WorldEdit's chat commands
com.sk89q.worldedit.datacontains classes to read Minecraft's world files directly from disk
com.sk89q.worldedit.devcontains a class to generate documentation and other development-related files
com.sk89q.worldedit.filterscontains filters used for the smoothing algorithm
com.sk89q.worldedit.patternscontains the pattern support (such as for
com.sk89q.worldedit.regionscontains 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.scriptingcontains scripting engines
com.sk89q.worldedit.snapshotscontains snapshot loading code (but actual world file reading code is in
com.sk89q.worldedit.superpickaxecontains the code for the different super pickaxe modes
com.sk89q.worldedit.superpickaxe.brushcontains the different brush shapes for the brush super pickaxe tools
com.sk89q.worldedit.utilhas some utility classes
org.jnbtis the JNBT library to read JNBT formatted files
How to Add a Command
- 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
- Add a new method, named anything.
- Add the
@Commandannotation to signify that it is a command. The
aliasesproperty contains a list of command aliases and the first one in the list is the main alias.
usagecontains parameter usage information.
descis a short description.
flagsis an optional string of flags (each flag is only one character long).
minis the minimum number of arguments.
maxis the maximum number of arguments and it can be -1 to allow an unlimited number.
@CommandPermissionscauses permissions to be checked for the command. Only one permission needs to be satisfied in the list.
- Write the command.
- If using Bukkit, update
com.sk89q.worldedit.dev.DocumentationPrinterto generate it for you.
- Compile and test!