diff --git a/doc/plugin_basics.rst b/doc/plugin_basics.rst index 5cfc729..0f30579 100644 --- a/doc/plugin_basics.rst +++ b/doc/plugin_basics.rst @@ -1,6 +1,33 @@ Plugin basics ============= +Plugin Structure +---------------- + +A plugin is defined to be a Python module. A module can take several forms. The simplest +is a single python file, such as `my_plugin.py` that contains plugin class definitions. + +For larger plugins, or plugins that include other support files, you may choose to create +a Python package, which is a folder that contains (at the very least) an `__init__.py` +file. For example:: + + my_plugin/ + __init__.py + helpers.py + header_image.png + footer_image.png + +TBD: In the future, it will be possible to package your plugin as a zip file for easy +installation. + +.. _undo-history + +Undo History +------------ + +NOTE: The following only applies to plugin types other than `SimpleCommandPlugin`. Plugins +derived from `SimpleCommandPlugin` will automatically manage the undo history for you. + Plugins that edit the world must make it possible for these edits to be undone. This is done by enclosing your editing commands within a call to `editorSession.beginSimpleCommand`. This creates a new entry in the undo history and tells the editorSession to begin recording @@ -13,3 +40,10 @@ editing will not be possible. For example:: +Registering Plugin Classes +-------------------------- + +When defining a plugin class, you must also call a function to register it with MCEdit's +plugin handling system. This is usually as simple as placing a decorator such as +`@registerCommandPlugin` before the class definition. See the examples for each of the +:doc:`plugin_types`. \ No newline at end of file diff --git a/doc/plugin_types.rst b/doc/plugin_types.rst index 8e6a070..d1e4564 100644 --- a/doc/plugin_types.rst +++ b/doc/plugin_types.rst @@ -9,12 +9,31 @@ display windows, dialog boxes, and other UI elements. :doc:`plugins/tool` are a way to add new editor tools. Each editor tool will display a panel of options while it is selected, and will respond to mouse actions within the world view such as clicking and dragging. Tool plugins are free to edit the world and to display -windows, dialog boxes, and other UI elements. +windows, dialog boxes, and other UI elements. Before creating a Tool plugin, consider if +what you want to accomplish can be done using a :doc:`plugins/brush_mode` instead. :doc:`plugins/brush_shape` are used to provide new shapes for use with the Brush and Selection tool (and any other tools that may ask the user to choose a shape). Shape plugins may not edit the world and may only return a SelectionBox object that defines the shape. +:doc:`plugins/brush_mode` are used to provide new actions for use with the Brush tool. +For instance, you could make a Brush Mode that sets the name of any entity within the +affected area to "Dinnerbone". Brush modes are expected to edit the world, and since the +:ref:`undo-history` is managed by the Brush tool, you do not need to manage it yourself. + +:doc:`plugins/inspector` are used to create user interfaces for editing entities and +tile entities. Since inspectors for all of the base Minecraft entities are included with +MCEdit, this plugin type is intended for adding support for Minecraft mods. For instance, +a plugin for inspecting chests from the IronChests mod would inherit from the base Chest +inspector and change the number of slots in the chest. + +:doc:`plugins/tile_entity` are a low-level plugin that does not directly interact with the +user. These plugins provide TileEntityRef classes that wrap the underlying NBT structures +for tile entities and may add meaning to numerical constants, validate tag types, or +expose ItemStacks that are stored in a nonstandard manner. These plugins are expected to +accompany the Inspector plugins for mod-added tile entities. + +The future of :doc:`plugins/generate` is uncertain. .. toctree:: plugins/command diff --git a/doc/plugins/brush_mode.rst b/doc/plugins/brush_mode.rst new file mode 100644 index 0000000..58fbe7a --- /dev/null +++ b/doc/plugins/brush_mode.rst @@ -0,0 +1,4 @@ +Brush Mode Plugins +================== + +TODO: Describe Brush mode plugins. See `mcedit2.editortools.brush.modes` for examples. \ No newline at end of file diff --git a/doc/plugins/generate.rst b/doc/plugins/generate.rst new file mode 100644 index 0000000..d72ac6f --- /dev/null +++ b/doc/plugins/generate.rst @@ -0,0 +1,6 @@ +Generate Plugins +================ + +TODO: Come up with a use case for Generate plugins that doesn't overlap with Command, +Brush Shape, or Brush Mode plugins. Rename these plugins to avoid confusion with "Chunk +Generation". See `hilbert.py`, `koch.py`, and `city.py` in the `plugins` folder for examples. \ No newline at end of file diff --git a/doc/plugins/inspector.rst b/doc/plugins/inspector.rst new file mode 100644 index 0000000..8dc0f83 --- /dev/null +++ b/doc/plugins/inspector.rst @@ -0,0 +1,5 @@ +Inspector Plugins +================= + +TODO: Describe Inspector plugins. See `mcedit2.widgets.inspector.tileentities` for +examples. \ No newline at end of file diff --git a/doc/plugins/tile_entity.rst b/doc/plugins/tile_entity.rst new file mode 100644 index 0000000..34b050b --- /dev/null +++ b/doc/plugins/tile_entity.rst @@ -0,0 +1,5 @@ +Tile Entity Plugins +=================== + +TODO: Describe Tile Entity plugins, and also describe the EntityRef/TileEntityRef system. +See `mceditlib.anvil.entities` for examples. \ No newline at end of file