Merge pull request #3 from EngineHub/feature/developer-docs

Add developer docs

Author: octylFractal

source/api/concepts/actors.rst

@@ -0,0 +1,8 @@
+Actors
+======
+
+An ``Actor`` is anything that uses WorldEdit commands or certain APIs. Typically, an actor is a player, but they can
+also be a command block, the console, or perhaps an entity. As should be clear, an actor does not need a location
+in the world, although many actors also implement ``Locatable`` to provide this. A mod/plugin does not usually need
+to provide an actor to use the WorldEdit API, but actors may be provided in certain hooks such as
+``EditSessionEvent``, allowing for customization based on who/what an actor is.

source/api/concepts/adapters.rst

@@ -0,0 +1,15 @@
+Adapters
+========
+WorldEdit works across many Minecraft modding platforms. This implies that WorldEdit's API does not use any platform's
+API types, such as Bukkit's ``Player`` or Sponge's ``World``. Instead, WorldEdit has its own set of API types,
+and the platform-specific library (see :ref:`api-libraries`) contains an `adapter` class to turn the platform's
+API types into WorldEdit's API types, and vice versa. For example, you can turn an
+``org.bukkit.entity.Player`` into a ``com.sk89q.worldedit.entity.Player`` like so
+
+.. code-block:: java
+
+    org.bukkit.entity.Player player = /* get a player */;
+    Player wePlayer = BukkitAdapter.adapt(player);
+
+Nearly every other WorldEdit type has a similar conversion from the platform type. These are best discovered by
+looking at the methods in the adapter classes in your IDE.

source/api/concepts/blocks.rst

@@ -0,0 +1,26 @@
+Blocks
+======
+
+Blocks are broken into two parts, `type` and `state`. These are represented by the ``BlockType`` and
+``BlockState`` classes. An example of block type is ``minecraft:oak_log``, and a state would be the
+combination of the type ``minecraft:oak_log`` and the `properties` ``[axis=y]``.
+
+You can get a ``BlockState`` from a ``BlockType`` using either ``getDefaultState()`` or providing the
+correct property mappings to ``getState(Map)``.
+
+For example, to get the state for ``minecraft:oak_log[axis=y]``
+
+.. code-block:: java
+
+    BlockType oakLog = Objects.requireNonNull(BlockTypes.OAK_LOG);
+    BlockState yFacingOakLog = oakLog.getState(ImmutableMap.of(
+        oakLog.getProperty("axis"), "y"
+    ));
+    System.err.println("State: " + yFacingOakLog);
+
+
+Some blocks include NBT_, and these are represented by the ``BaseBlock`` type.
+
+You can get a ``BaseBlock`` from a ``BlockState`` using ``toBaseBlock(CompoundTag)``.
+
+.. _NBT: https://minecraft.gamepedia.com/NBT_format

source/api/concepts/edit-sessions.rst

@@ -0,0 +1,8 @@
+Edit Sessions
+=============
+An ``EditSession`` handles the configuration for getting and placing blocks, entities, and biomes. It sets up the
+chain of extents to place blocks properly. It also handles turning on and off reorder mode, fast mode, and buffering.
+Every operation will use an ``EditSession`` at some point to ensure that block placement is done properly and quickly.
+
+Edit sessions must be closed once all operations are complete, to ensure that block queues are flushed.
+They are not re-usable, and must be re-created for each individually operation.

source/api/concepts/extents.rst

@@ -0,0 +1,18 @@
+Extents
+=======
+
+Extents form the backbone of WorldEdit's block manipulation. Extents are generally split into three categories:
+input, output, and both. Although extents provide and receive block and biome information, they are not always
+associated with a world / dimension.
+
+Input extents are responsible for providing block and biome information for a given location. They do not provide
+a way to set blocks.
+
+Output extents are responsible for receiving block and biome information for a given location. They do not provide
+a way to get blocks.
+
+Most or all extents in WorldEdit implement both ``*Extent`` interfaces, typically through the ``Extent`` interface.
+``Extent`` instances also provide a minimum and maximum point, as well as entity manipulation methods.
+
+Some examples of extents are worlds and clipboards. Many block placement features in WorldEdit - such as fast and
+reorder mode - are implemented using ``AbstractDelegateExtent`` and hooking into ``setBlock``.

source/api/concepts/index.rst

@@ -0,0 +1,17 @@
+API Concepts
+============
+
+WorldEdit uses some simple concepts to create flexible operations. These concepts are detailed below, and should
+be read in the order provided, as later concepts sometimes reference earlier concepts.
+
+.. toctree::
+    :maxdepth: 2
+
+    actors
+    blocks
+    patterns-and-masks
+    extents
+    regions
+    registries
+    edit-sessions
+    adapters

source/api/concepts/patterns-and-masks.rst

@@ -0,0 +1,14 @@
+Patterns and Masks
+==================
+
+Patterns and masks are the same as described in :doc:`/usage/general/patterns` and :doc:`/usage/general/masks`.
+The only difference is that they must be constructed via their respective classes, rather than from formatted strings.
+
+A single block pattern can be represented using a ``BlockStateHolder``, such as ``BlockState`` and ``BaseBlock``.
+Other patterns types are fairly obvious from their names, such as ``TypeApplyingPattern`` or ``RandomStatePattern``.
+Use your IDE to find subclasses of ``Pattern``.
+
+Masks are a slightly different story. Exact and fuzzy block `state` masks are done using ``BlockMask``, but you can
+also mask only over block `type` (``BlockTypeMask``) or only the `properties` (``BlockStateMask``).
+There are also some utility masks in the ``Masks`` class. Again, using your IDE to find ``Mask`` subclasses is
+recommended.

source/api/concepts/regions.rst

@@ -0,0 +1,17 @@
+Regions
+=======
+
+WorldEdit uses regions to define where an operation works. A ``Region`` is a set of positions, potentially associated
+with a ``World``. There is no requirement that a region be fully continuous.
+
+Regions implement ``Iterable<BlockVector3>``, meaning that the best way to get all the points of `any` region is to
+use a ``for-each`` loop, e.g. ``for (BlockVector3 point : region)``. In addition to this, there are convenience
+methods to retrieve the minimum, maximum, center, area, width, height, length, chunks, and cubic chunks.
+You can also easily ``expand()``, ``contract()``, and ``shift()`` regions, which work like the commands of the same
+name. Note that these methods `do not` change any blocks.
+
+Creating a region is as simple as calling the appropriate constructor of the region you want. Typically you want a
+``CuboidRegion``, but there are other subclasses for each of the selection types in WorldEdit, or you can implement
+your own!
+
+Some common region usages are the actor's selection and clipboard bounds.

source/api/concepts/registries.rst

@@ -0,0 +1,18 @@
+Registries
+==========
+
+Almost everything in Minecraft uses the same format for identifying a particular type, such as ``minecraft:stone``.
+This is known as a `namespaced ID <https://minecraft.gamepedia.com/Namespaced_ID>`_ (see page for details).
+WorldEdit keeps some `registries` that allow access to blocks, items, biomes, entities, fluids, and more from the
+current Minecraft platform using their ID in a platform-independent way.
+
+These registries are available on most classes named ``*Type``, such as ``BlockType`` and ``ItemType``.
+However, it is recommended to use the ``*Types`` classes instead, which either provide potentially-null constants
+or a ``get`` method for retrieving types that aren't built-in, such as modded blocks.
+
+.. note::
+    The constants on these registries may be ``null`` because the API does not change across Minecraft versions,
+    and this means that some blocks won't exist on earlier Minecraft versions, or like in 1.13, were renamed
+    from their ID in 1.12 and WorldEdit no longer recognizes the block properly. If you require a block, you should
+    wrap the access to the constant in ``Objects.requireNonNull`` or a similar check to properly communicate that
+    you do not expect the constant to be missing at runtime.

source/api/examples/clipboard.rst

@@ -0,0 +1,95 @@
+Clipboard Examples
+==================
+
+.. note::
+    This documentation covers the API for using clipboards.
+    See :doc:`/usage/clipboard` for in-game usage & explanations of what clipboards are.
+
+Concepts used in these examples: :doc:`../concepts/regions`, :doc:`../concepts/edit-sessions`,
+:doc:`../concepts/extents`
+
+Copying
+-------
+Copying is the most common way to create a clipboard. To do it, you'll need a ``Region``, a target ``Clipboard``,
+and an ``EditSession``. In this example we use a ``CuboidRegion`` and the standard ``BlockArrayClipboard``.
+Then, all you need to do is pass the parameters to the ``ForwardExtentCopy``, apply configuration (such as calling
+``setCopyingEntities(true))`` to copy entities), and call ``Operations.complete``.
+
+.. code-block:: java
+
+    CuboidRegion region = new CuboidRegion(world, min, max);
+    BlockArrayClipboard clipboard = new BlockArrayClipboard(region);
+
+    try (EditSession editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(world, -1)) {
+        ForwardExtentCopy forwardExtentCopy = new ForwardExtentCopy(
+            editSession, region, clipboard, region.getMinimumPoint()
+        );
+        // configure here
+        Operations.complete(forwardExtentCopy);
+    }
+
+You may want to :ref:`save <Saving>` the clipboard after this.
+
+Pasting
+-------
+Pasting is the only way to move blocks from a ``Clipboard`` to another ``Extent``, typically a ``World``.
+To paste, you'll need a ``World``, an ``EditSession`` and a ``Clipboard``. Create a ``ClipboardHolder``
+with your clipboard, then get a ``PasteBuilder`` by calling ``createPaste`` with the ``EditSession``.
+Call ``.to`` to set the position at which you want to paste (this will be offset by the clipboard offset,
+see the clipboard page above for more information). Add any other configuration you want (masks, paste entities,
+paste biomes, etc.), and then call ``build()`` to get an operation. Complete the operation, and all the blocks
+will be pasted.
+
+Full example:
+
+.. code-block:: java
+
+    try (EditSession editSession = WorldEdit.getInstance().getEditSessionFactory().getEditSession(world, -1)) {
+        Operation operation = new ClipboardHolder(clipboard)
+                .createPaste(editSession)
+                .to(BlockVector3.at(x, y, z))
+                // configure here
+                .build();
+        Operations.complete(operation);
+    }
+
+You may want to :ref:`load <Loading>` a clipboard before this.
+
+Schematic Examples
+==================
+This section deals with schematics, which are a related but distinct concept. Schematics
+specifically refer to a saved clipboard, not a clipboard in-memory.
+
+.. _saving:
+
+Saving
+------
+A ``Clipboard`` can be saved to disk very easily. All you need is a ``ClipboardFormat``, a ``Clipboard``, and an
+``OutputStream``. Then you can call ``getWriter`` on the format and ``write`` on the writer with
+your ``Clipboard``. Here's an example for saving a clipboard to file.
+
+.. code-block:: java
+
+    File file = /* figure out where to save the clipboard */;
+
+    try (ClipboardWriter writer = BuiltInClipboardFormat.SPONGE_SCHEMATIC.getWriter(new FileOutputStream(file))) {
+        writer.write(clipboard);
+    }
+
+.. _loading:
+
+Loading
+-------
+Loading a ``Clipboard`` is nearly as simple. You can either force a specific ``ClipboardFormat``, or have WorldEdit
+discover the format of the schematic you want to load. The example does the latter. Then you can call ``getReader``
+on the format and ``read`` on the reader to get a ``Clipboard`` instance.
+
+.. code-block:: java
+
+    Clipboard clipboard;
+
+    ClipboardFormat format = ClipboardFormats.findByFile(file);
+    try (ClipboardReader reader = format.getReader(new FileInputStream(file))) {
+        clipboard = reader.read();
+    }
+    /* use the clipboard here */