查看“PlotSquared/Dev”的源代码

这里是PlotSquared的开发文档界面~

[[https://github.com/IntellectualSites/PlotSquared/wiki/Developer-documentation-(WIP) 原文地址]]
==有用的类==
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Bukkit/src/main/java/com/intellectualcrafters/plot/api/PlotAPI.java 地皮API]]
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/object/PlotPlayer.java 地皮玩家]]
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/object/Plot.java 地皮]]
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/flag/FlagManager.java 标志管理]]
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/util/MainUtil.java MainUtil]]
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/util/SchematicHandler.java 模型处理]]
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/util/ChunkManager.java 区块管理]]
* [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/util/UUIDHandler.java UUID处理]]

==教程==
===使用Java语言编码===
====总览====
* 脚本放到 PlotSquared/scripts 目录下
* 语言请使用Java语言
====指令====
* /plot debugexec run <script> [args...]
* /plot debugexec runasync <script> [args...]
* /plot debugexec <code goes here>
====示例脚本====
* [[https://github.com/IntellectualSites/PlotSquared/wiki/Merging-all-plots 合并所有地皮]]
* [[https://github.com/IntellectualSites/PlotSquared/wiki/Setting-all-signs 设置所有标志]]
* [[https://github.com/IntellectualSites/PlotSquared/wiki/Resetting-plot-biomes 重设置地皮生物群系]]
* [[https://github.com/IntellectualSites/PlotSquared/wiki/Allowing-a-player-to-claim-more-plots 允许一个玩家认领更多地皮]]
* [[https://github.com/IntellectualSites/PlotSquared/wiki/Printing-the-furthest-plot 打印出最远的地皮]]
* [[https://github.com/IntellectualSites/PlotSquared/wiki/Startup-script---commands 安装脚本和命令]]
=====其他脚本=====
* [[https://www.dropbox.com/s/cfg24xb2t4x9apl/fixborder.js?dl=0 地皮边界]]
* [[https://www.dropbox.com/s/xzjfhavselyrf2m/addsigns.js?dl=0 地皮标志]]

写了你自己的脚本？想发到这里？[[https://github.com/IntellectualSites/PlotSquared/issues 欢迎！]]

===一个PlotSquared的附属插件实例===
<pre>
import com.intellectualcrafters.plot.api.PlotAPI;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.plugin.PluginManager;

public class Main extends JavaPlugin {
    public PlotAPI api;

    @Override
    public void onEnable() {
        PluginManager manager = Bukkit.getServer().getPluginManager();
        final Plugin plotsquared = manager.getPlugin("PlotSquared");

        // 如果插件没有安装的话就关闭这个插件

        // If you move any PlotSquared related tasks to en external class you 
        // wouldn't have to disable the plugin if PlotSquared wasn't installed

        if(plotsquared != null && !plotsquared.isEnabled()) {
            PS.log(null, "&c[ExamplePlugin] Could not find PlotSquared! Disabling plugin...");
            manager.disablePlugin(this);
            return;
        }

        // Do PlotSquared related stuff
        api = new PlotAPI();

        // 现在你就可以使用这个API了
    }
}
</pre>
===增加一个子命令===
当玩家输入 /plot help <category> 时会展示你增加的子命令。
CATEGORY 为你添加子命令时选择的类型
====增加命令====
下面是一个例子
<pre>
@CommandDeclaration(
    // 你所添加命令的名字
    command = "test",
    
    // 若要运行你所添加的命令，你需要的权限
    permission = "plots.music",
    
    // 你所添加的命令的描述
    description = "Player music in a plot",
    
    // 你所添加的命令的使用方法
    usage = "/plot music",
    
    // 你所添加的命令的类型
    category = CommandCategory.ACTIONS,
    
    // 需要的命令执行者 (NONE 允许控制台执行)
    requiredType = RequiredType.NONE
)
public class TestCommand extends SubCommand {
        public TestCommand() {
            // 你可以在这儿或者其他地方自定义命令
            MainCommand.getInstance().addCommand(this);
            
            // Then just call:
            // new TestCommand();
            // 在游戏中使用 ：  /plot test
        }

        // 下面是这个指令是干嘛的
    @Override
    public boolean onCommand(final PlotPlayer player, final String[] args) {
        Location loc = player.getLocation();
        Plot plot = Plot plot1 = MainUtil.getPlot(loc);
        if (plot1 == null) {
            sendMessage(player, C.NOT_IN_PLOT);
            return false;
        }
        Plot plot = MainUtil.getCurrentPlot(plr);
        MainUtil.sendMessage(player, "You are in plot " + plot.getId());
        return true;
    }
}
</pre>
====动态命令添加====
<pre>
Command<PlotPlayer> cmd = new Command<PlotPlayer>(String command, String usage, String description, String permission, String[] aliases, RequiredType requiredType) {

    @Override
    public boolean onCommand(PlotPlayer plr, String[] arguments) {
        Location loc = player.getLocation();
        Plot plot = Plot plot1 = MainUtil.getPlot(loc);
        if (plot1 == null) {
            sendMessage(player, C.NOT_IN_PLOT);
            return false;
        }
        Plot plot = MainUtil.getCurrentPlot(plr);
        MainUtil.sendMessage(player, "You are in plot " + plot.getId());
        return true;
    }
};

MainCommand.getInstance().addCommand(cmd);
</pre>

===增加自定义标志===
<pre>
import org.bukkit.Bukkit;
import org.bukkit.ChatColor;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.Plugin;
import org.bukkit.plugin.java.JavaPlugin;

import com.intellectualcrafters.plot.AbstractFlag;
import com.intellectualcrafters.plot.Flag;
import com.intellectualcrafters.plot.Plot;
import com.intellectualcrafters.plot.api.PlotAPI;
import com.intellectualcrafters.plot.events.PlayerEnterPlotEvent;

public class Main extends JavaPlugin implements Listener {
    PlotAPI plotAPI = null;
    @Override
    public void onEnable() {

        // 获取插件
        Plugin plotSquaredPlugin = getServer().getPluginManager().getPlugin("PlotSquared");

        //检查PS插件是否被启动
        if (plotSquaredPlugin!=null && plotSquaredPlugin.isEnabled()) {

            // 这儿我们来获取一些带有有趣事情的API
            plotAPI = new PlotAPI((JavaPlugin) plotSquaredPlugin);
        }
        else {

            // 当PS没有启用时 给控制台发送一条消息然后关闭这个插件吧！
            // 当然你也可以把PS的代码移到另一个类中，这样你就不要单独写停止PS的部分了。
            getServer().getConsoleSender().sendMessage("Plugin 'PlotSquared' not found. Disabling MyPlugin");
            Bukkit.getPluginManager().disablePlugin(this);
        }

        //增加一个 AbstractFlag (标志的关键)
        AbstractFlag abFlag = new AbstractFlag("greeting") {

            // 下面的东西是可选的 并允许你限制哪些玩家可以设置这个标志:

            @Override
            public String parseValue(String value) {

                // Only accept woof, dog, cat, meow for the greeting flag

                switch (value.toLowerCase()) {
                    case "woof":
                    case "dog":
                        return "dog"; 
                    case "cat":
                    case "meow":
                        return "cat";
                    default:
                        return null; // Return null the value is invalid
                }

                // 你也可以使用一些简单的IF语句 例子如下：

                /*
                if (value.equals("hello")) {
                    return value;
                }
                return null;
                */
            }


            @Override
            public String getValueDesc() {
                return "You are currently only allowed to set the greeting to: woof, dog, cat, meow"; 
            }
        };
        // 现在我们要注册标志了
        plotAPI.addFlag(abFlag);

        // 别忘记注册一个消息然后我们才可以给控制台发消息
        getServer().getPluginManager().registerEvents(this, this);
    }

    // 这儿是 PlayerEnterPlotEvent, 同时也有其他你可以接入的事件。这些会在网页中列举出来。
    @EventHandler
    public void onPlayerEnterPlot(PlayerEnterPlotEvent event) {
        Plot plot = event.getPlot();
        Player player = event.getPlayer();

        // checking if the plot has that flag
        if (plot.settings.getFlag("greeting")!=null) {

            // Get the message
            String message = plot.settings.getFlag("greeting").getValue();

            // Only send a message if it's not blank.
            if (!message.equals("")) {

                // Send the player the message set for that plot
                player.sendMessage(ChatColor.translateAlternateColorCodes('&', message));
            }
        }
    }
}
</pre>

===使用 PlotAPI 类===
PlotAPI API = new PlotAPI(null);

Plot plot = API.getPlot(final Location l);

输入：


com.intellectualcrafters.plot.api.PlotAPI

com.intellectualcrafters.plot.object.Plot
===使用PlotPlayer类===
总览：

[[https://github.com/IntellectualSites/PlotSquared/blob/master/src/main/java/com/intellectualcrafters/plot/object/PlotPlayer.java PlotPlayer.java]] 是用于表现服务器上的玩家的一个语言。

获取 PlotPlayer 从 org.bukkit.entity.Player 处:

<nowiki>BukkitUtil.getPlayer(Player player)</nowiki>

或

<nowiki>PlotPlayer.wrap(Player player)</nowiki>

获取 PlotPlayer 从 org.bukkit.OfflinePlayer:

<nowiki>BukkitUtil.getPlayer(OfflinePlayer offline)</nowiki>

或

<nowiki>PlotPlayer.wrap(OfflinePlayer player)</nowiki> 你可能会把这个链接到 BukkitPlayer 如果你需要它的帮助的话。

注意：一些功能作为一个离线玩家可能不会正常工作，尤其是他们从没加入过游戏的情况。

使用 PlotPlayer 你可以做什么:

* 将他们在各种各样的PlotSquared功能中使用
* 设置持久属性: Plotplayer.setAttribute(String attribute)
* Set session only metadata: plotplayer.setMeta(String key, Object value)
* 获取UUID： plotplayer.getUUID()
===增加一个自定义的世界生成器===
如果你不熟悉如何快速自定义世界生成器的话，请看这里的快速教程链接——
* [[https://bukkit.org/threads/basic-creating-custom-world-generators.24569/ 基础示例]]
* [[https://bukkit.org/threads/how-to-create-custom-world-generators.79066/ 更多详情]]
====如何在PlotSquared上工作====
每个世界都有它自己的配置文件。这为你定向到了 PlotWorld 类。 PlotWorld 类也有一些硬性设定，但是不多。

PlotSquared 默认为一个 HybridPlotWorld 类，没有包括任何我们需要的基础设置。你可以随意使用它【通过API】，或者只是复制它来做一些简要的修改。

每个生成器也会有它自己的 PlotManager 类，这些类决定着一些类似于地皮清理等基础的事情，可以在每个 PlotWorld 类中找到。

PlotSquared 使用 HybridPlotManager , 当然你也可以使用它，用它来制作一些你需要的 PlotSquared 附属插件。

这儿当然也有一些其他几个 PlotWorld 和 PlotManager 类来供你需要的地皮生成器的依赖选择。

对于方形的地皮，你就不需要提供你自己的清除算法，因为 PlotSquared 可以为你做那的所有事情。详情请看 SquarePlotManager 类。

记得让你的 PlotManager 类和 PlotWorld 类对应起来，如，如果你选择了我们的 SquarePlotManager 类, 你最好搭配一个 SquarePlotWorld 或更好的类。

====PlotSquared 区块生成器====

有了 PlotSquared, 取而代之延伸 ChunkGenerator ，你会想延伸 PlotGenerator. 这可以在我们的 HybridGen 类中找到。

你可以注册这个 PlotGenerator 作为一个在你主类中的普通的 ChunkGenerator :
<pre>

@Override
public ChunkGenerator getWorldGenerator(String worldName, String id) {
    return new YourPlotGenerator(worldName);
}
</pre>
====示例 PlotGenerator 类====
(随意来使用/修改一个PlotSquared的附属插件)
PlotSquared: 最标准的生成器
* HybridGen
* 这个生成器结合了普通的生成器和一些 AdvPlots 插件中的特性，这是为了便利，高性能和高自由度可配置的地皮生成。
* 这可能很凌乱，并且这儿有许多可以自定义配置的东西，并且 PlotSquared 会自动做一些你不需要自己做的东西。

BasicPlots:每个区块一块地皮
* BasicGen
* 当他安装时，创建区块是很迅速的，并且为每个区块返回相同的大小。
* 不好的一面是地皮的大小必须是一个区块的大小，所以不能自定义。

PlotSquaredMG: 使用区域文件来创建
* MegaGen
* 加载会很需要事件，但是允许自定义地形且允许大型的区域。
* 因为它使用区域文件，在读取世界是可以简单的预加载地图，并且地皮的大小是 16 的倍数，它可以在读取时计算区块。
* 这个生成器显著的缺点是读取时会耗费大量的时间，并且地皮必须很大（512 +）

AdvPlots generator: 模型创建
* SchemGen
* 这说明了在 PlotSquared 中你不需要限制地皮一定是方形的。
* 它证明了模型创建器可以和地皮合并一起工作。
* 事实上你可以编码，你应该提供你想要的地皮位置的一些坐标，并且不必要是网格状的。

不是PlotGenerator的一个生成器，但是也很有用，在这里：
ClassicGen: PlotSquared使用的最早生成器之一

ClassicGen
* 它不简单，但有点是在循环时没有逻辑区块的检查，这使插件十分有效果。
* 是与 PlotMe 相反的类型，在循环时放置一些逻辑在其中。
* 这个的不好的一面是它在写地皮区域等时是难以置信的困难，所以模型创建在这个问题之外。
这里是我用你期望的地皮生成器写的基础生成器：[[https://gist.github.com/boy0001/e12ff4a80ad06a15ff24 资源]]
它并不继承 PlotGenerator，但它已被文档化并且展示了一些基础的自定义功能。

==开发用物==
[[https://github.com/IntellectualSites/PlotSquared 源代码]]
==特有词汇==
===地皮区域===
地皮区域是指 PlotSquared 将会管理的一个区域。如果这是整个地皮世界的话，整个地皮世界就会被视为一个地皮区域。

如果你使用地皮群的话，只有世界的地皮的的那一部分会被视为地皮区域，并且在那地皮区域之外的区域不会被 PlotSquared 管理。

查看：[[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/util/MainUtil.java  MainUtil.java#isPlotArea(...)]]

===地皮群===
地皮群可以在地皮区域中创建，或者它们可以在原先的一个不是地皮世界的世界创建，并且只会创建它自己的地皮区域。

查看： 译者注 原作者指向的页面已经删除

(地皮群的一些东西目前在编码方面有一点复杂，这会在日后缓解。)

===道路===
道路是分隔每个区域的地方，并且 包括 地皮周围的墙。尝试在这里获得地皮区域不会返回任何东西。

查看：[[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/util/MainUtil.java  MainUtil.java#isPlotRoad(...)]]

===地皮===

一个地皮可以被领取或者被放弃。在这里使用获取位置代码，如果是没有认领的一块领地会返回一个新的没有主人的领地。

查看： [[https://github.com/IntellectualSites/PlotSquared/blob/master/Core/src/main/java/com/intellectualcrafters/plot/util/MainUtil.javaMainUtil.java#getPlot(...)]]
==作者的话==
如果你制作了一个教程，或者为PlotSquared制作了一个附属插件，并且愿意让我们把链接放到这里的话，请发一张 TICKET。

我们真的非常欣赏它！