跳到主要内容

开发者 API

其他插件可以用星月造物的 API 打开奖池、替玩家抽奖、拿宝箱物品与钥匙、读保底次数，并监听开箱与中奖事件。 API 都在套件 dev.starplugins.crate.api。

加入依赖​

把 StarCrate-<版本>-簡體授權版.jar 放进你的项目（例如 libs/），只在编译时依赖，不要打包进你的 jar。

Gradle

dependencies {
    compileOnly files('libs/StarCrate-1.0.0-簡體授權版.jar')
}

Maven

<dependency>
    <groupId>dev.starplugins</groupId>
    <artifactId>starcrate</artifactId>
    <version>1.0.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/StarCrate-1.0.0-簡體授權版.jar</systemPath>
</dependency>

plugin.yml

softdepend: [StarCrate]   # 必须要有星月造物才能运作的话，改成 depend: [StarCrate]

StarCrateAPI​

全部是静态方法。除了 available() 与 crates()，其他方法在星月造物没有启用或授权还没通过时会抛出 IllegalStateException，请先检查 available()。

方法回传说明
available()boolean星月造物已启用且授权已通过
crates()Collection<String>所有奖池 ID
open(Player p, String crate)boolean为玩家打开奖池预览（自选奖池打开选择界面）。奖池不存在时回传 false
draw(Player p, String crate, int count, boolean free)boolean替玩家抽奖，会播放动画、发放奖励、计入保底与记录。count 为 10 以上 = 十连，其他 = 单抽。free = true 时不扣任何花费，也不检查开启权限与每日上限。奖池不存在时回传 false
crateItem(String crate, int amount)ItemStack这个奖池的宝箱物品（数量最多一组）。奖池不存在时回传 null
keyItem(String crate, int amount)ItemStack这个奖池的钥匙（数量最多一组）。奖池不存在时回传 null
pity(UUID uuid, String crate)int玩家在这个奖池的保底次数。只对在线玩家有效，离线玩家回传 0

奖池 ID 不分大小写。open 与 draw 会排进玩家所在的线程执行（支持 Folia），回传 true 只代表奖池存在、已经排入执行； 抽奖是否成功（花费够不够、有没有权限）会直接提示玩家。

import dev.starplugins.crate.api.StarCrateAPI;

public void reward(Player player) {
    if (!StarCrateAPI.available()) return;
    // 签到奖励：免费十连
    StarCrateAPI.draw(player, "xinghui", 10, true);
}

public void giveCrate(Player player) {
    if (!StarCrateAPI.available()) return;
    ItemStack box = StarCrateAPI.crateItem("xinghui", 1);
    if (box != null) player.getInventory().addItem(box);
}

事件​

CrateOpenEvent​

玩家开始一次抽奖、扣除花费之前触发，可以取消。

方法说明
getPlayer()抽奖的玩家
crate()奖池 ID
count()抽奖时是 1 或 10；自选奖池是这次选了几个奖品
via()从哪里开启：MENU（结果界面等）、BLOCK（抽奖方块打开的预览）、ITEM（宝箱物品打开的预览）、COMMAND（/sc open、/sc draw、API）、FREE（免费代抽）
setCancelled(true)取消这次抽奖：不扣费、不抽奖，也不会给玩家任何提示（请自己发消息说明原因）

触发时机：

  • 抽奖：奖池的开启权限、是否允许十连、有没有奖品都已经检查过；每日上限、剩余可抽数量与花费还没检查。
  • 自选奖池：玩家按「确认选择」、通过开启权限检查之后触发（每日上限与花费还没检查），via() 是打开选择界面的方式。
@EventHandler
public void onOpen(CrateOpenEvent e) {
    // 战斗中不能开箱
    if (combat.isTagged(e.getPlayer()) && !e.via().equals("FREE")) {
        e.setCancelled(true);
        e.getPlayer().sendMessage("§c战斗中不能抽奖");
    }
}

PrizeWinEvent​

每抽到一个奖品触发一次（十连触发 10 次，自选奖池每个选中的奖品各一次）。在结果抽出之后（同时开始写入数据库）、动画播放之前触发，只用来通知，不能取消。

方法说明
getPlayer()抽奖的玩家
crate()奖池 ID
prize()奖品编号（例如 p7）
item()奖品物品（复制品，修改它不会影响奖励）
rarity()稀有度 ID
grand()是否终极大奖

因为在动画之前触发，请不要用它向全服宣布结果（会比动画先剧透）；需要公告时使用星月造物内置的 全服公告。

@EventHandler
public void onWin(PrizeWinEvent e) {
    if (e.grand()) {
        // 记录终极大奖到自己的统计
        stats.addGrand(e.getPlayer().getUniqueId(), e.crate(), e.prize());
    }
}

两个事件都在玩家所在的线程触发（Folia 上是玩家所在区域的线程）。

最后于 更新