查看“WorldEdit/开发与API”的源代码

[[分类:开发教程]]

{{待翻译}}

==简介==

WorldEdit为其他Mod和插件开发提供了一个稳定的公共接口, 这个接口提供了平台独立的接口和类去让你使用Minecraft内部的方块, 生物群系, 和世界的操作, 也支持一部分的实体操作

===API支持===

你可以在[https://help.sonatype.com/repomanager3/repository-manager-concepts/an-example---maven-repository-format Maven仓库]下载到API, 兼容[https://maven.apache.org/ Maven], [https://gradle.org/ Gradle]和[https://www.scala-sbt.org/ sbt]等构建工具, Maven仓库可以在[https://maven.enginehub.org/repo/ 这里https://maven.enginehub.org/repo/]下载到

WorldEdit的库在com.sk89q.worldedit包下面, 根据你需要的不同API, 你可以选择下面这些库来使用

* worldedit-core: 核心的API库, 不依赖于任何的平台, 也不提供任何平台的相互兼容
* worldedit-bukkit: Bukkit的接口实现, 依赖于Bukkit, 使用BukkitAdapter来提供Bukkit和WorldEdit两个平台的相互兼容
* worldedit-fabric-mcXYZ: Fabric接口实现, 依赖于Facric API, 使用FabricAdapter来提供Facric和WorldEdit两个平台的相互兼容, XYZ应该换成对应Minecraft的版本
* worldedit-forge-mcXYZ: Forge接口实现, 依赖于Forge, 使用ForgeAdapter来提供Forge和WorldEdit两个平台的相互兼容, XYZ应该换成对应Minecraft的版本
* worldedit-sponge-mcXYZ: Sponge接口实现, 依赖于Sponge API, 使用SpongeAdapter来提供Sponge和WorldEdit两个平台的相互兼容, XYZ应该换成对应Minecraft的版本(因为Sponge还没出新版Minecraft支持, 所以最新只支持到Minecraft1.12.2)
* worldedit-cli: 命令行接口实现, 当做依赖来用不太方便, 但是可以在Minecraft外部来调用WorldEdit

应该依据你使用的Minecraft版本来选择对应的WorldEdit API版本, WorldEdit6支持1.12.2以下的版本, WorldEdit7是给1.13+用的, 我们只给最新的WorldEdit和Minecraft的提供支持与更新, 但通常来说API跨了版本也是很相似的, 所以说使用方式和例子也很相似, 虽然你还能找到旧版的文档, 但是你现在看到的内容只包括了最新版本的WorldEdit内容

接下来你可以开始使用这些API了, 这里可以浏览[[#API概论]], 一些常用的API的用法在[[#API实例]]里面介绍, 在开发的时候, 记得留意[#内部API]来保证你在使用受支持的API

==API概论==

WorldEdit使用了一些很简单的概念来灵活的操作元素和组件, 下面是一些具体的概念的细节, 你应该按顺序来读, 因为后面的概念通常需要你理解前面的概念才能读懂

===发动者 (Actors)===

'''Actor'''是使用某些API的时候会用到的东西, 通常来说, '''Actor'''可以是一个玩家, 也可以是命令方块、控制台或实体, 你需要明白的是, 虽然提供'''Actor'''的玩家、命令方块等等一般都有对应的坐标位置, 但是'''Actor'''本身不表示世界上的一个具体位置.

Mod和插件使用WorldEdit API的时候一般都不需要提供'''Actor'''作为参数, 但你监听某些事件(比如说EditSessionEvent)的时候, 事件所返回的参数中会提供一个'''Actor'''对象, 来让你判断和操作这个'''Actor'''所对应的玩家或命令方块等

===方块 (Blocks)===

方块被拆分成了两部分, Type(方块类型)和State(方块状态), 拆成具体的类也就是'''BlockType'''和'''BlockState'''类, '''BlockType'''举个例子可以是 "minecraft:oak_log" 而BlockState一般是'''类型'''(像这样的type: minecraft:oak_log)和'''属性'''(像这样的properties [axis=y])的一个组合

如果你想从BlockType中获取到一个BlockState, 你可以调用'''getDefaultState()'''方法, 或者提供对应的属性的Mapping来获取, 使用的是'''getState(Map)'''方法

下面举个例子, 获取''minecraft:oak_log[axis=y]''这个属性

<source lang="java">
BlockType oakLog = Objects.requireNonNull(BlockTypes.OAK_LOG);
BlockState yFacingOakLog = oakLog.getState(ImmutableMap.of(
    oakLog.getProperty("axis"), "y"
));
System.err.println("State: " + yFacingOakLog);
</source>

一些包含[https://minecraft.gamepedia.com/NBT_format NBT]的方块, 是用'''BaseBlock'''类的实例来表示的

调用BlockState的'''toBaseBlock(NBTCompoundTag)'''方法可以得到对应的'''BaseBlock'''实例

===图案和蒙版 (Patterns and Masks)===

对于图层和蒙版的描述和[http://mineplugin.org/WorldEdit#.E5.9B.BE.E6.A1.88 主页面条目]里面相同. 唯一的不同点是API中要操作对应的类来构建图层和蒙版, 不再使用字符串格式了

单方块的图案可以用像是'''BlockState'''和'''BaseBlock'''这样的'''BlockStateHolder'''来表示, 像是'''TypeApplyingPattern'''和'''RandomStatePattern'''这样其他的图案, 类名就直接是它们的名字了. 当然, 你也可以用你的IDE去找'''Pattern'''类的子类

蒙版就完全不是这么简单的了, 使用'''BlockMask'''类可以直接精确匹配或者模糊匹配对应的'''BlockState''', 但你也可以只通过'''BlockType(BlockTypeMask)''''或者是'''Properties(BlockStateMask)'''来选取目标, 在'''Masks'''类中有一些预设的实用蒙版, 你可以去使用一下. 当然我们还是推荐你用IDE去找找'''Mask'''的子类 

===Extents接口(Extents)===

Extent接口形式是WorldEdit方块处理的骨干部分. '''Extent'''通常被分成三类: (输入)'''Input''', (输出)'''output''', (输入输出)'''both''', 虽然Extents接收和提供方块和生物群系的信息, 但它不与世界和维度相关联

'''Input'''的Extent是用来为给定的位置设置方块和生物群系的, 但是你不能用它来设置方块

'''Output'''的Extent是用来从给定的位置获取方块和生物群系的, 但是你不能用它来获取方块

几乎WorldEdit中所有的Extent都实现了'''*Extent接口'''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.