事件大全

所属：开发者　·　同组：QinhRuinsAPI · 词缀脚本 · 数据存储 返回：核心概念

QR 在遗迹生命周期的关键节点抛出 Bukkit 事件，供你监听、拦截、改写。全部在包 com.qinhuai.ruins.api 下。本页逐个列出：何时触发、字段、是否可取消。

---

事件速查表

事件	时机	可取消	用途
RuinPreSpawnEvent	选址后、粘贴结构 前	✅	拦截某地 / 某模板的生成
RuinSpawnEvent	锚点生成 后	❌	知会、登记、外部联动
RuinClearEvent	遗迹通关时	❌	发奖励、广播、记录
RuinLootEvent	派发容器战利品前	✅	改 / 拦战利品

取消（setCancelled(true)）只对 可取消事件 有效。RuinSpawnEvent / RuinClearEvent 是知会型（Event 无 Cancellable），改不了结果。

---

1. RuinPreSpawnEvent —— 可取消（拦截生成）

选好坐标、即将粘贴结构 之前 触发。取消 = 这次生成作废。用来在保护区 / 玩家领地 / 特定维度禁止遗迹生成。

class RuinPreSpawnEvent(
    val templateId: String,  // 准备生成的模板
    val location: Location,  // 选中的生成点（已 clone）
) : Event(), Cancellable

• isCancelled() / setCancelled(cancel)：取消即拦截，结构不会被粘贴、不产生锚点。

---

2. RuinSpawnEvent —— 不可取消（生成后知会）

一座锚点生成完成后触发。携带尺寸，可算出包围盒。

class RuinSpawnEvent(
    val templateId: String,
    val anchorId: String,    // 新锚点 id
    val location: Location,  // 锚点原点（最小角）
    val width: Int = 0,
    val height: Int = 0,
    val depth: Int = 0,
) : Event() {
    fun minPoint(): Location  // = location 克隆（包围盒最小角）
    fun maxPoint(): Location  // = location + (w-1, h-1, d-1)（包围盒最大角）
}

• minPoint() / maxPoint()：返回遗迹包围盒的两角，方便做区域注册（WorldGuard 区、保护、PVP 标记等）。尺寸为 0 时按单点处理。

---

3. RuinClearEvent —— 不可取消（通关知会）

遗迹被通关时触发。用来发额外奖励、广播、写统计。

class RuinClearEvent(
    val templateId: String,
    val anchorId: String,
    val location: Location,
) : Event()

---

4. RuinLootEvent —— 可取消（改 / 拦战利品）

容器战利品派发给玩家前触发。items 是 可变列表，直接增删改即可改写掉落；取消则整批拦下（不发任何东西）。

class RuinLootEvent(
    val player: Player,               // 领取者
    val anchorId: String,             // 来自哪座遗迹
    val tableName: String,            // 战利品表名
    val items: MutableList<ItemStack>,// 即将发放的物品（可改）
) : Event(), Cancellable

• 想 加料：往 items 里 add。
• 想 过滤 / 替换：改写 items 的元素或 removeIf。
• 想 整批拦截：setCancelled(true)。

战利品表与成长度缩放见 战利品系统。

---

5. 监听示例

Kotlin：按区域拦截生成

import com.qinhuai.ruins.api.RuinPreSpawnEvent
import org.bukkit.event.EventHandler
import org.bukkit.event.Listener

object MyRuinGuard : Listener {
    @EventHandler
    fun onPreSpawn(e: RuinPreSpawnEvent) {
        // 出生点 200 格内不许生成遗迹
        val spawn = e.location.world?.spawnLocation ?: return
        if (e.location.distanceSquared(spawn) < 200.0 * 200.0) {
            e.isCancelled = true
        }
    }
}

Java：改写战利品

@EventHandler
public void onLoot(RuinLootEvent e) {
    // 高塔遗迹额外塞一个钻石
    if (e.getAnchorId().startsWith("ancient_tower")) {
        e.getItems().add(new ItemStack(Material.DIAMOND, 1));
    }
    // 新手保护区拦掉危险产出
    if (isNoob(e.getPlayer())) {
        e.getItems().removeIf(it -> it.getType() == Material.TNT);
    }
}

Java：生成后注册保护区

@EventHandler
public void onSpawn(RuinSpawnEvent e) {
    Location min = e.minPoint();
    Location max = e.maxPoint();
    myProtectionPlugin.protect(e.getAnchorId(), min, max);
}

---

6. 注册监听器

Bukkit.getPluginManager().registerEvents(new MyListener(), myPlugin);

server.pluginManager.registerEvents(MyRuinGuard, myPlugin)

所有事件都提供静态 getHandlerList()，符合 Bukkit 事件规范。

---

下一步

• QinhRuinsAPI — 程序化生成 / 查询遗迹
• 词缀脚本 — 秘境激活时跑 JS（事件之外的另一个扩展口）