MCEdit 2 Plugin Development

MCEdit 2插件开发

A plugin for MCEdit 2 is a Python module that defines one or more Plugin classes and then registers them with MCEdit. These classes are instantiated once for each Editor Session and called on by MCEdit in response to various user actions.

mcedit 2的插件是一个python模块，它定义一个或多个插件类，然后将它们注册到mcedit。这些类为每个编辑器会话实例化一次，并由mcedit响应各种用户操作调用。

·Plugin basics 插件基础

··Plugin Structure 插件结构

··Undo History 撤消历史记录

··Registering Plugin Classes 正在注册插件类

·Plugin Tasks 插件任务

··World Dimensions 世界维度

··Editing Blocks 编辑块

··Editing Entities 编辑实体

··Creating entities 创建实体

·Types of plugins 插件类型

··Command Plugins 命令插件

··Simple Commands 简单命令

···Simple Command Inputs 简单命令输入

····Input Types 输入类型

··Tool Plugins 工具插件

···Mouse Handlers 鼠标处理程序

··Brush Shape Plugins 画笔形状插件

···As a boolean array 作为布尔数组

···As a Selection object 作为选择对象

·Plugin Examples 插件示例

··Simple Options 简单选项

··World Editing 世界编辑

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.

插件被定义为Python模块。一个模块可以有多种形式。最简单的是一个单独的python文件，比如包含插件类定义的my_plugin.py。

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:

对于更大的插件或包含其他支持文件的插件，您可以选择创建一个Python包，该包是一个文件夹，其中至少包含一个__init__.py文件。例如：

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.

TBD：将来，可以将您的插件打包为zip文件，以便安装。

Undo History 撤消历史记录

NOTE: The following mainly applies to the full-featured CommandPlugin. Plugins derived from SimpleCommandPlugin or BrushMode will automatically manage the undo history for you.

注：以下主要应用于功能齐全的CommandPlugin。从SimpleCommandPlugin或BrushMode派生的插件将自动为您管理撤消历史记录。

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 undo information. If this function is not called, the world will be in read-only mode and editing will not be possible. For example:

编辑世界的插件必须使这些编辑得以撤销。这是通过将编辑命令封闭在对editorSession.beginSimpleCommand的调用中来完成的。这将在撤消历史记录中创建一个新条目，并通知editorSession开始记录撤消信息。如果不调用此函数，则世界将处于只读模式，无法进行编辑。例如：

def changeOneBlock():

    with editorSession.beginSimpleCommand("Change One Block"):

        editorSession.currentDimension.setBlock(1, 2, 3, "minecraft:dirt")

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 Types of plugins.

定义一个插件类时，还必须调用一个函数，以便在MCEdit的插件处理系统中注册它。这通常与将诸如@registerCommandPlugin之类的修饰符放在类定义之前一样简单。请参阅每个插件类型的示例。

Plugin Tasks 插件任务

A Minecraft world contains several different kinds of data. The blocks in the world are fundamentally different from the monsters and animals that wander through it, and some blocks contain data that is more complex than a single block ID. Blocks and entities are organized into chunks, and there is additional data that applies to each entire chunk, and there is also metadata that describes the world dimension that contains these chunks, and that describes the save file as a whole. These tasks will guide you in editing each of these different aspects of the save file.

一个Minecraft世界包含几种不同的数据。世界里的方块与在其中漫游的怪物和动物有着根本的不同，有些方块包含的数据比单个方块ID更复杂。方块和实体被组织成区块，并且有附加的数据应用于每个区块，还有描述世界维度的包含这些区块并将保存文件描述为一个整体的元数据。这些任务将指导您编辑保存文件的这些不同方面。

World Dimensions 世界维度

A Minecraft save file contains several world dimensions, which include the Overworld, The Nether, The End, and any other dimensions added by game mods. MCEdit only allows the user to view and edit one of the world’s dimensions at any time, so plugins will often be given a dimension object that refers to the world dimension that the user is currently editing. All of the following tasks will refer to this dimension object.

一个Minecraft保存文件包含多个世界维度，其中包括超世界、下界、末地以及游戏mod添加的任何其他维度。MCEdit只允许用户在任何时候查看和编辑世界维度之一，因此插件通常会被赋予一个维度对象，该对象引用用户当前正在编辑的世界维度。以下所有任务都将引用此维度对象。

Editing Blocks 编辑方块

Blocks are the defining element of a Minecraft dimension and are the simplest to deal with. Blocks are stored in a three dimensional grid extending from the bottom of the world to the build height - in other words, from Y=0 to Y=255. Every position in the grid will have a block. If a block appears to be empty, it will really contain the block air.

方块是Minecraft维度的定义元素，是处理起来最简单的。方块存储在从世界底部延伸到建造高度的三维网格中——换句话说，从y=0到y=255。网格中的每个位置都会有一个方块。如果一个方块似乎是空的，它将真正包含空气方块。

The position of a block is given by its X, Y, and Z coordinates. The type of the block at that position is given by its identifier, which is a short string of text such as minecraft:air, minecraft:stone, or minecraft:stone[variant=diorite]. Internally, this identifier is stored as a pair of integers. When editing the world, you may use either the string of text or the pair of integers to specify a block type, but it is recommended to use the string of text, for both readability and for compatibility.

方块的位置由其X、Y和Z坐标给出。在该位置的方块的类型由其标识符给出，该标识符是一个简短的文本字符串，如minecraft:air、minecraft:stone或minecraft:stone[variant=diorite]。在内部，这个标识符存储为一对整数。在编辑世界时，您可以使用文本字符串或整数对来指定方块类型，但建议使用文本字符串，以提高可读性和兼容性。

NOTE: When using block types added by mods, you must use the text identifier, because the integer IDs will vary from world to world.

注意：当使用由mod添加的方块类型时，您必须使用文本标识符，因为整数ID将因世界而异。

Alternately, you may pass a BlockType instance. A BlockType instance may be obtained by presenting a block type input to the user (e.g. using an option with type="blocktype"in a SimpleCommandPlugin or by constructing a BlockTypeButton yourself). BlockTypes may also be found by looking up a textual or numeric ID in the dimension’s blocktypes. To wit:

或者，您可以传递一个BlockType实例。可以通过向用户提供方块类型输入（例如，在SimpleCommandPlugin中使用带有type=“blocktype”的选项或自己构造BlockTypeButton）来获取一个BlockType实例。BlockType也可以通过在维度的blocktypes中查找文本或数字ID来找到。也就是说：

stone = dimension.blocktypes['minecraft:stone']

granite = dimension.blocktypes['minecraft:stone[variant=granite]']

cobblestone = dimension.blocktypes[1]  # don't do this!

podzol = dimension.blocktypes[3, 2]    # don't do this either!

 

dimension.setBlock(0, 0, 0, granite)   # etc.

To discover which block is at a given position, call dimension.getBlock, which will return a BlockType instance.

要发现哪个方块位于给定位置，请调用dimension.getBlock，它将返回一个BlockType实例。

WorldEditorDimension.getBlock(x, y, z)[source]

Returns the block at the given position as an instance of BlockType. This instance will have id, meta, and internalName attributes that uniquely identify the block’s type, and will have further attributes describing the block’s properties. See BlockType for a full description.

以BlockType实例的形式返回给定位置的方块。此实例将具有唯一标识方块类型的id、meta和internalName属性，并将具有描述方块属性的更多属性。有关完整描述，请参见BlockType。

If the given position is outside the generated area of the world, the minecraft:air BlockType will be returned.

如果给定位置在世界生成区域之外，则返回minecraft:air BlockType。

Parameters:

·x (int) –

·y (int) –

·z (int) –

Returns:

block

Return type:

BlockType

To change the block at a given position, call dimension.setBlock 

要在给定位置更改方块，请调用dimension.setBlock

WorldEditorDimension.setBlock(x, y, z, blocktype)[source]

Changes the block at the given position. The blocktype argument may be either a BlockType instance, a textual identifier, a tuple containing a textual identifier and a block metadata value, or a tuple containing a block ID number and a block metadata value.

在给定位置更改方块。blocktype参数可以是BlockType实例、文本标识符、包含文本标识符和方块元数据值的数组，也可以是包含方块ID号和方块元数据值的数组。

This function will change both the ID value and metadata value at the given position.

此函数将更改给定位置的ID值和元数据值。

It is recommended to pass either a BlockType instance or a textual identifier for readability and compatibility.

为了可读性和兼容性，建议传递BlockType实例或文本标识符。

Parameters:

x (int) –

y (int) –

z (int) –

blocktype (BlockType | str | (str, int) | (int, int)) –

Returns:

block

Return type:

BlockType

Array-based, high performance variants of these two methods are available. When given parallel arrays of x, y, z coordinates, dimension.getBlocks will return an array of the same size containing the block IDs at those coordinates. If requested, it will also return the block metadata values, light values, and/or biome values for those coordinates at the same time.

这两种方法的基于阵列的高性能变体是可用的。当给定x、y、z坐标、dimension.getBlocks的并行数组时，将返回一个大小相同的数组，其中包含这些坐标处的方块ID。如果需要，它还将同时返回这些坐标的方块元数据值、灯光值和/或生物群系值。

Likewise, dimension.setBlocks may be given parallel arrays of x, y, z coordinates along with arrays of any of the following: block IDs, block metadata values, light values, biome values. To set all coordinates to the same value, you may pass a single value instead of an array.

同样，可以为dimension.setBlock提供x、y、z坐标的并行数组以及以下任意数组：方块ID、方块元数据值、灯光值、生物群系值。要将所有坐标设置为相同的值，可以传递单个值而不是数组。

WorldEditorDimension.getBlocks(x, y, z, return_Blocks=True, return_Data=False, return_BlockLight=False, return_SkyLight=False, return_Biomes=False)[source]

WorldEditorDimension.setBlocks(x, y, z, Blocks=None, Data=None, BlockLight=None, SkyLight=None, Biomes=None, updateLights=True)[source]

Editing Entities 编辑实体

Entities are the free-roaming elements of a Minecraft world. They are not bound to the block grid, they may be present at any position in the world, and may even overlap. Animals, monsters, items, and experience orbs are examples of entities.

实体是Minecraft世界的自由漫游元素。它们没有绑定到方块网格，它们可能存在于世界里的任何位置，甚至可能重叠。动物、怪物、物品和经验球都是实体的例子。

Since entities may be at any position, you cannot specify an entity with a single x, y, z coordinate triple. Instead, you may create a BoundingBox (or any other SelectionBox object) and ask MCEdit to find all of the entities within it. You may even ask it to find only the entities which have specific attributes, such as id="Pig" to find only Pigs, or name="Notch" to find entities named “Notch”. This is all done by calling dimension.getEntities

由于实体可能位于任何位置，因此您不能指定具有单一x、y、z三坐标的实体。相反，您可以创建一个BoundingBox（或任何其他SelectionBox对象），并要求MCEdit查找其中的所有实体。您甚至可以要求它仅查找具有特定属性的实体，例如id=“pig”仅查找Pigs，或name=“notch”查找名为“Notch”的实体。这一切都是通过调用dimension.getEntities完成的。

WorldEditorDimension.getEntities(selection, **kw)[source]

Iterate through all entities within the given selection. If any keyword arguments are passed, only yields those entities whose attributes match the given keywords.

遍历给定选择中的所有实体。如果传递了任何关键字参数，则只生成那些属性与给定关键字匹配的实体。

For example, to iterate through only the zombies in the selection:

例如，要仅遍历所选内容中的僵尸：

for entity in dimension.getEntities(selection, id=”Zombie”):

# do stuff

Parameters:

selection (SelectionBox) –

kw (Entity attributes to match exactly.) –

Returns:

entities

Return type:

Iterator[EntityRef]

It is important to know that this function only returns an iterator over the found entities. If you assign one of these entities to another variable (or put it into a container such as a list or dict) then that entity will keep its containing chunk loaded, which may possibly lead to out-of-memory errors. Thus, it is best to simply modify the entities in-place while iterating through them rather than hold references to them.

重要的是要知道这个函数只返回找到实体的迭代器。如果将这些实体中的一个分配给另一个变量（或将其放入容器，如list或dict），则该实体将保持包含它的区块被加载，这可能导致“内存不足”错误。因此，最好是在迭代实体时简单地在适当的位置修改它们，而不是保留对它们的引用。

The entities are returned as instances of EntityRef. An EntityRef is a wrapper around the underlying NBT Compound Tag that contains the entity’s data. The EntityRef allows you to change the values of the entity’s attributes without having to deal with the individual tags and tag types that represent those attributes.

实体作为EntityRef的实例返回。EntityRef是包含实体数据的基础NBT复合标记的包装器。EntityRef允许您更改实体属性的值，而不必处理表示这些属性的单个标记和标记类型。

In other words, instead of writing:

换句话说，不是写：

entity["Name"] = nbt.TAG_String("codewarrior0")

You only have to write:

你只需要写：

entity.Name = "codewarrior0"

However, it may occasionally be useful to access the entity’s NBT tags directly. This can be done using the entity.raw_tag attribute. After modifying the raw_tag, you must always mark the entity as dirty by doing entity.dirty = True to ensure your changes are saved:

但是，有时直接访问实体的NBT标记可能很有用。这可以使用entity.raw_tag属性来完成。修改raw_tag后，必须始终通过执行entity.dirty=True将实体标记为 dirty ，以确保更改被保存：

import nbttag = entity.raw_tag()tag["Name"] = nbt.TAG_String("codewarrior0")entity.dirty = True

Creating entities 创建实体

TODO: Describe creating entities, either by calling dimension.worldEditor.EntityRef.create(entityID) or by crafting the entity’s tag by hand.

TODO:通过调用dimension.worldEditor.EntityRef.create（entityID）或手工创建实体的标记来描述创建实体。