diff --git a/doc/apidocs.rst b/doc/apidocs.rst deleted file mode 100644 index f82cdca..0000000 --- a/doc/apidocs.rst +++ /dev/null @@ -1,16 +0,0 @@ -MCEdit2 class and module reference -================================== - -.. toctree:: - :maxdepth: 5 - - apidoc/mcedit2 - apidoc/mceditlib - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/editorsession.rst b/doc/editorsession.rst new file mode 100644 index 0000000..4b2c889 --- /dev/null +++ b/doc/editorsession.rst @@ -0,0 +1,40 @@ + +EditorSession +============= + +An EditorSession contains the entire state and behavior of the world editor for a single + world. It contains references to the current selection, undo history, the UI widgets, + and the WorldEditor instance underlying the session. + +.. attribute:: currentDimension + :type: WorldEditorDimension + + The dimension currently displayed in the editor window. + +.. attribute:: currentSelection + :type: SelectionBox | None + + The current selection made by the user with the Select tool. Unlike MCEdit 1.0, + a selection is not always a rectangular box. Shaped and disjoint selections are + possible now. + +.. _session-undo-history: + +Undo History +============ + +The session's undo history is managed as a stack of QUndoCommands. The revision system +provided by :ref:`worldeditor` is used to manage changes to the world's data. Simple +access to the revision system is provided by the `beginSimpleCommand` method of the +`EditorSession` + +.. automethod:: mcedit2.editorsession.EditorSession.beginSimpleCommand + +This method returns an object to be used in a `with` statement. Any changes to the +WorldEditor within the `with` statement's block are captured by a new revision in the +revision system, and a new entry is added to the session's undo history. For example:: + + def changeOneBlock(): + with editorSession.beginSimpleCommand("Change One Block"): + editorSession.currentDimension.setBlock(1, 2, 3, "minecraft:dirt") + diff --git a/doc/index.rst b/doc/index.rst index 59df858..ec9279b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -8,6 +8,9 @@ MCEdit 2 Documentation .. toctree:: plugins + editorsession + selection + worldeditor Indices and tables diff --git a/doc/plugins/command.rst b/doc/plugins/command.rst index 16b5ac1..f7cbd86 100644 --- a/doc/plugins/command.rst +++ b/doc/plugins/command.rst @@ -33,7 +33,7 @@ A basic command plugin:: You can do nearly anything you want in the `perform()` function. To operate on the world and dimension being edited and the current selection, use `self.editorSession`. See -:ref:`EditorSession`, :ref:`WorldEditor`, and :ref:`WorldEditorDimension` for details +:doc:`editorsession`, :doc:`worldeditor`, and :ref:`world-editor-dimension` for details about what can be edited and how. Simple Commands @@ -41,7 +41,7 @@ Simple Commands MCEdit 1.0's "filter" plugins all follow the same pattern: They prompt the user for some inputs, and then call a `perform()` function which is given the current world, the current -selection, and the inputs provided by the user. :ref:`SimpleCommandPlugin` fills the same +selection, and the inputs provided by the user. `SimpleCommandPlugin` fills the same role in MCEdit 2.0. This class automatically adds a menu item to the Plugins menu. When the item is chosen, @@ -94,25 +94,29 @@ Further keys are available depending on the type of input: - `int`: A numeric input for integer values, within the range +/- two billion or so. If both the `min` and `max` keys are given, also creates a slider for selecting a value from within this range + - `min`: Minimum allowed value. Optional. - `max`: Maximum allowed value. Optional. - `float`: Identical to the `int` input, but provides a floating point value (within the - range allowed by double-precision floating point).If + range allowed by double-precision floating point). If both the `min` and `max` keys are given, also creates a slider for selecting a value from within this range + - `min`: Minimum allowed value. Optional. - `max`: Maximum allowed value. Optional. - `bool`: A checkbox that can be either on or off. - `text`: A text field that can input a single line of text. + - `placeholder`: Displays this text in a light grey color if the text field is empty. Optional. - `choice`: A pop-up menu that offers multiple choices for the user to select from. Each choice is associated with a value that you define in the element's `choices` list. This is the value you will receive as this option's value in the `perform()` function. + - `choices`: A list of tuples of the form `(text, value)`. For examples of all possible simple command inputs, see the `simple_options.py` file in diff --git a/doc/selection.rst b/doc/selection.rst new file mode 100644 index 0000000..dd3540b --- /dev/null +++ b/doc/selection.rst @@ -0,0 +1,2 @@ +Selections +========== diff --git a/doc/worldeditor.rst b/doc/worldeditor.rst new file mode 100644 index 0000000..90ddcdb --- /dev/null +++ b/doc/worldeditor.rst @@ -0,0 +1,25 @@ +WorldEditor +=========== + +A `WorldEditor` object is used to edit all parts of a Minecraft world. It contains a +:ref:`WorldEditorMetadata` object containing info about the world's name, seed, and other +data found in the `level.dat` file, and a collection of :ref:`WorldEditorDimension`s + which provides access to the chunks, blocks, and entities in each dimension. + +`WorldEditor` also provides a revisioning system used to implement MCEdit's undo history. +When editing a world opened in MCEdit, you should use the :ref:`session-undo-history` + + +.. method:: mceditlib.worldeditor.getDimension + +.. _world-editor-dimension + +WorldEditorDimension +==================== + +All blocks, chunks, and entities in a world are contained in a `WorldEditorDimension`. +A world may have one or more dimensions. One of these dimensions is always the +"overworld" or default dimension and may be obtained by calling `WorldEditor.getDimension()` +with no arguments. + +