鹤造工坊

Appearance

视效脚本 ​

什么是视效？ ​

「视效」是插件内置的一套可在游戏中创建动态视觉特效的系统。你可以用它来显示：

  • 伤害数字（浮动全息字）
  • 暴击特效
  • Buff/Debuff 提示
  • 粒子效果

核心概念 ​

视效基于 GroovyEffect 基类。每个视效有三个生命周期阶段：

创建 → spawn() → onTick() 每帧运行 → 时间到 → despawn()
  • onSpawn()：效果创建时执行一次。在这里初始化资源（创建全息字、发射粒子等）
  • onTick()：每个游戏刻（tick）执行一次。在这里更新位置、播放动画
  • onDespawn()：持续时间结束后执行一次。在这里清理资源（删除全息字、停止粒子等）

重要： 必须在 onDespawn() 中清理所有创建的资源，否则会造成内存泄漏！

第一个视效 ​

一个最简单的视效——显示一条消息，2秒后自动消失：

Groovy
package scripts.expansions

import groovy.transform.CompileStatic
import org.bukkit.entity.Entity
import org.bukkit.entity.Player
import scripts.libs.GroovyEffect

@CompileStatic
class SimpleNotification extends GroovyEffect {

    private String message

    SimpleNotification(Player looker, Entity entity, String message, long duration) {
        super(looker, entity, duration)
        this.message = message
    }

    @Override
    void onSpawn() {
        if (looker != null && looker.isOnline()) {
            looker.sendMessage(message)
        }
    }

    @Override
    void onTick() {
        // 简单通知不需要每帧更新
    }

    @Override
    void onDespawn() {
        if (looker != null && looker.isOnline()) {
            looker.sendMessage("§7[通知结束]")
        }
    }
}

// 使用方式：
// new SimpleNotification(player, entity, "§e注意！", 40).spawn()

DecentHolograms 视效 ​

插件内置了一个基于 DecentHolograms 的完整视效示例 DHEffect.groovy。它创建一段浮动文字，向上飘起后消失——常用于显示伤害数字和治疗数字。

核心实现要点：

Groovy
class DHEffect extends GroovyEffect {

    List<String> text
    Hologram hologram          // 全息字对象
    Location currentLocation   // 当前位置
    double velocityY = 0.3     // 向上速度
    double gravity = 0.04      // 模拟重力

    @Override
    void onSpawn() {
        // 1. 计算生成位置（实体头顶上方）
        Location spawnLocation = entity.location.clone()
            .add(0, entity.height / 2 + 0.5, 0)

        // 2. 创建全息字
        hologram = DHAPI.createHologram(
            UUID.randomUUID().toString(), spawnLocation, false, text
        )
        // 3. 只对特定玩家显示
        hologram.show(looker, 0)
        currentLocation = spawnLocation.clone()
    }

    @Override
    void onTick() {
        // 4. 每帧：向上移动 + 减速（模拟重力）
        currentLocation.add(0, velocityY, 0)
        velocityY -= gravity
        DHAPI.moveHologram(hologram, currentLocation)
    }

    @Override
    void onDespawn() {
        // 5. 必须删除全息字！
        if (hologram != null) {
            hologram.delete()
        }
    }
}

在属性中使用视效 ​

在属性脚本中调用视效：

Groovy
// 在 onAttackAndDefense 中创建伤害显示
@Override
boolean onAttackAndDefense(LivingEntity attacker, LivingEntity entity, AttackAndDefenseHandler handler) {
    double damage = handler.getRandomValue(attacker, "物理攻击")

    if (damage > 0 && attacker instanceof Player) {
        // 创建伤害全息字
        Utils.createDHEffect(
            attacker as Player,           // 观察者
            entity,                        // 显示位置（目标实体上方）
            "§c-${String.format("%.0f", damage)}",  // 显示文本
            40                              // 持续时间（tick）
        )
    }
    return true
}

Utils.createDHEffect 是 scripts/libs/Utils.groovy 中预设的快捷方法。

编写自己的视效 ​

编写自定义视效的步骤：

  1. 在 scripts/expansions/ 下创建 .groovy 文件
  2. 继承 GroovyEffect
  3. 实现 onSpawn()、onTick()、onDespawn() 三个方法
  4. 在属性脚本中 new YourEffect(...).spawn() 来使用

关键原则：

  • 所有资源（全息字、粒子、音效等）在 onSpawn() 中创建
  • 持续变化的逻辑在 onTick() 中更新
  • 所有资源必须在 onDespawn() 中销毁

注意事项 ​

  1. duration 单位是 tick，20 tick = 1 秒
  2. 所有操作必须在主线程执行（onSpawn、onTick、onDespawn 都已在主线程调用）
  3. 使用前检查 looker 和 entity 是否有效（非 null、在线）
  4. 默认内置的 DHEffect 依赖 DecentHolograms 插件，如果没装这个插件，createDHEffect 会报错

参考 ​