AttributePlus Pro API 文档

概述

AttributePlus Pro 是一个 Minecraft 服务器插件，提供属性系统 API。本文档重点介绍 API 用法、包名和核心功能。

核心 API

1. AttributeAPI 主类

包名: org.serverct.ersha.api.AttributePlus

主要方法:

/* 获取实体的属性数据 */
fun getAttrData(entity: LivingEntity): AttributeData = 
    AttributePlus.attributeManager.getAttributeData(entity.uniqueId, entity)

/* 延迟任务 - ID相同的任务会被覆盖 */
fun runEntityTask(millis: Long, id: String, entity: LivingEntity, block: () -> Unit)

/* 获取物品上的 AttributeSource 数据 */
fun getAttributeSource(itemStack: ItemStack, async: Boolean): AttributeSource

/* 获取 List 上的 AttributeSource 数据 */
fun getAttributeSource(list: List<String>, async: Boolean): AttributeSource

/* 增加一个源的属性数据 */
fun addSourceAttribute(attributeData: AttributeData, source: String, attr: AttributeSource, async: Boolean = false)
fun addSourceAttribute(attributeData: AttributeData, source: String, itemStack: ItemStack?, async: Boolean = false)
fun addSourceAttribute(attributeData: AttributeData, source: String, list: List<String>?, async: Boolean = false)
fun addSourceAttribute(attributeData: AttributeData, source: String, attribute: HashMap<String, Array<Number>>?, async: Boolean = false)

/* 删除一个源的属性数据 */
fun takeSourceAttribute(attributeData: AttributeData, source: String)

/* 造成一次伤害，该伤害不会触发 AttributePlus 属性伤害处理 */
fun attackTo(entity: LivingEntity, attacker: LivingEntity, damage: Double)

/* 执行一次无事件触发且经过 AttributePlus 属性处理的实体攻击 */
fun runAttributeAttackEntity(attacker: LivingEntity, entity: LivingEntity, damage: Double, callBeforeEvent: Boolean, callCancel: Boolean)

/* 创建静态属性源 - 不触发 AttributeReadEvent 等事件 */
fun createStaticAttributeSource(content: List<String>): AttributeSource

/* 用上面的属性源处理方法，处理后将属性加到 AttributeData 目标上 */
fun addStaticAttributeSource(data: AttributeData, source: String, content: List<String>)

2. AttributeData 类

包名: org.serverct.ersha.api.data.AttributeData

计数器相关方法:

// 获取 Counter 主控对象
val counter: AttributeCounter = data.getCounter()

// 创建新的计数器
val counter = data.counter.getCounter("计数器名称", ItemCounterResetType.DEFUALT)

3. AttributeCounter 类

包名: org.serverct.ersha.api.data.AttributeCounter

计数器方法:

/** 更新计数器记录数值 */
fun updateValue(update: Double, default: Double): Double

/** 设置计数器记录数值 */
fun setValue(value: Double): Double

/** 设置计数器文本记录 */
fun updateContent(update: String): String

/** 获取计数器记录数值 */
fun getValue(default: Double): Double

/** 获取计数器记录文本 */
fun getContent(default: String): String

/** 重置计数器记录数值 */
fun resetValue()

/** 重置计数器记录文本 */
fun resetContent()

ItemCounterResetType 枚举:

DEFUALT: 该类型的计数器需要手动重置记录值
DEATH: 该类型的计数器在玩家死亡时会重置记录值

属性组件系统

1. SubAttribute 基类

包名: org.serverct.ersha.api.component.SubAttribute

继承方式:

public SubAttribute(Int priority, Double combatPower, String attributeName, AttributeType attributeType, String placeholder)

核心属性:

// 优先级
var priority: Int

// 属性战斗力
var combatPower: Double

// 属性默认名 (默认名 与 服务器内修改的属性名 不同)
val attributeName: String

// 属性类型
val attributeType: AttributeType

// 属性变量名 (请全部使用小写)
val placeholder: String

主要方法:

/* ATTACK 类属性时生效 */
fun runAttack(attacker: LivingEntity, entity: LivingEntity): Boolean

/* DEFENSE 类属性时生效 */
fun runDefense(entity: LivingEntity, killer: LivingEntity): Boolean

/* UPDATE RUNTIME 类属性时生效 */
fun run(entity: LivingEntity): Boolean

/* 属性加载时执行 */
fun onLoad(): SubAttribute

/* 注册属性 - 使用 @AutoRegister 注释 */
fun registerAttribute()

2. AttributeType 枚举

包名: org.serverct.ersha.api.enums.AttributeType

类型列表:

ATTACK: 攻击时触发，需要重写 runAttack 方法
DEFENSE: 被攻击者时触发，需要重写 runDefense 方法
UPDATE: 属性更新时触发，需要重写 run 方法
RUNTIME: 每隔多少秒触发一次，需重写 run 方法
KILLER: 击杀目标时触发，需要重写 runKiller 方法
CUSTOM: 自定义属性触发器，需要重写 runCustom 方法
OTHER: 该类型主要为其他类型的属性提供属性值

3. 实体扩展方法

LivingEntity 扩展方法:

/* 获得实体的属性数据 */
fun LivingEntity.getData(): AttributeData

/* 获得实体某一属性的属性值数据 */
fun LivingEntity.getAttributeValue(defaultAttributeName: String): Array<Number>

/* 获得实体当前属性的属性值数据 */
fun LivingEntity.getAttributeValue(): Array<Number>

/* 获取实体某一属性的随机值 */
fun LivingEntity.getRandomValue(defaultAttributeName: String): Number

/* 获取实体当前属性的随机值 */
fun LivingEntity.getRandomValue(): Number

/* 获取实体此次属性处理事件对对方所造成的伤害 */
fun LivingEntity.getDamage(): Number

/* 设置实体此次属性处理事件对对方所造成的伤害 */
fun LivingEntity.setDamage(value: Double)

/* 增加实体此次属性处理事件对对方所造成的伤害 */
fun LivingEntity.addDamage(value: Double)

/* 减少实体此次属性处理事件对对方所造成的伤害 */
fun LivingEntity.takeDamage(value: Double)

/* 增加实体此次属性处理事件对某个属性的属性值 */
fun LivingEntity.addAttribute(defaultAttributeName: String, value: Double)

/* 减少实体此次属性处理事件对某个属性的属性值 */
fun LivingEntity.takeAttribute(defaultAttributeName: String, value: Double)

/* 设置实体此次属性处理事件对某个属性的属性值 */
fun LivingEntity.setAttribute(defaultAttributeName: String, value: Double)

/* 取消实体此次属性处理事件对某个属性的触发 */
fun LivingEntity.cancelAttribute(defaultAttributeName: String)

4. 实用方法

属性值存储:

/* 将属性值储存至临时数据，用于 message 提示所显示的属性值 */
fun Pair<String, Double>.storageValue(init: Boolean)
fun Pair<String, Double>.storageValue()

/* Java 版本 */
fun Data<String, Double>.storageValue(init: Boolean)
fun Data<String, Double>.storageValue()

/* JavaScript 版本 */
fun storageValue(placeholder: String, value: Double, init: Boolean)
fun storageValue(placeholder: String, value: Double)

消息设置:

/* 设置属性触发时的提示消息 */
fun List<String>.setMessages(replaceAttack: Boolean)
fun List<String>.setMessages()

事件控制:

/* 取消此次属性处理事件的处理 */
fun Boolean.setCancelled()

/* 忽略此次属性处理事件取消状态 */
fun Boolean.setIgnoreCancelled()

/* 判断此次是否忽略取消 */
fun isIgnoreCancelled(): Boolean

/* 是否跳过过滤 */
fun Boolean.setSkipFilter()

几率触发:

/* 几率触发 */
fun Double.chance(): Boolean

公式设置:

/* 设置属性公式 */
fun String.setFormula()

/* 获取属性公式计算后的值 */
fun getFormulaValue(defaultFormula: () -> Double): Double

异步执行:

/* 属性是否异步执行 */
fun Boolean.setAsync()

/* 实时更新状态修改 */
fun Boolean.setSyncUpdateState()

属性名转换:

/* 通过属性默认名返回属性的变量 */
fun String.toPlaceholder(): String

/* 通过属性默认名获取服务器内修改后的属性名 */
fun String.toServerName(): String

自定义触发器组件

1. CustomTriggerComponent 接口

包名: org.serverct.ersha.api.component.CustomTriggerComponent

接口定义:

interface CustomTriggerComponent<E : Event> {
    // 触发器名称
    val name: String
    
    // 触发器事件
    val event: Class<E>
    
    // 触发器事件监听优先级
    val priority: EventPriority
    
    // 触发器事件是否忽略取消
    val ignoreCancelled: Boolean
    
    /* 触发器触发条件 */
    fun condition(event: E): Boolean
    
    /* 触发者对象传入 */
    fun caster(event: E): LivingEntity
    
    /* 目标对象传入 */
    fun target(event: E): LivingEntity?
    
    /* 触发事件相关参数传入 */
    fun params(event: E): Array<Any>
    
    /* 注册触发器 */
    fun register()
}

读取组件系统

1. ReadComponent 接口

包名: org.serverct.ersha.api.component.ReadComponent

接口定义:

interface ReadComponent {
    // 读取优先级
    val priority: DescriptionRead.ReadPriority
    
    // 读取类型
    val type: DescriptionRead.AttributeReadType
    
    // 是否过滤掉颜色代码
    val filterColor: Boolean
    
    /* 属性数据读取 */
    fun read(key: String, lore: String): Array<Number>
    fun read(key: String, lore: String, source: AttributeSource): Array<Number>
    
    /* 条件判断 */
    fun condition(entity: LivingEntity, lore: String): Boolean
    fun condition(entity: LivingEntity, lore: String, source: AttributeSource): Boolean
    
    /* 注册组件 */
    fun register()
    
    /* 注销组件 */
    fun unregister()
}

读取类型枚举:

enum class AttributeReadType {
    VALUE,      // 该类型会执行 read 与 condition 方法
    BOOLEAN,    // 该类型只执行 condition 方法
    RUNTIME     // 该类型与 VALUE 相同，但返回的值不会计入属性
}

读取优先级枚举:

enum class ReadPriority {
    BEFORE,     // 优先执行 BEFORE 的读取组件
    AFTER       // 所有组件是在 BEFORE 所有组件处理完后才执行
}

2. DescriptionLineCondition 接口

包名: org.serverct.ersha.api.component.DescriptionLineCondition

接口定义:

interface DescriptionLineCondition : DescriptionComponent {
    /* 单行描述条件 */
    fun condition(entity: LivingEntity?, text: String): Boolean
    fun condition(entity: LivingEntity?, text: String, slot: EquipmentSlot?): Boolean
    fun condition(entity: LivingEntity?, text: String, slot: EquipmentSlot?, item: ItemStack?): Boolean
}

属性名系统

1. AttributeName 说明

两种属性名:

属性默认名 (default): 属性类注册时内 attributeName 参数所设属性名
服务器属性名 (server): 属性注册后会在 attribute.yml 生成对应配置，在配置里面修改的属性名

重要说明:

getRandomValue(LivingEntity entity, String defaultAttributeName) 方法内的 defaultAttributeName 是属性默认名
一个属性类要调获取其他属性的值，需要通过属性默认名获取而不是使用服务器属性名获取

示例代码

1. 属性注册示例

@AutoRegister
class TestAttribute : SubAttribute(12, 5.0, "溟灭几率", AttributeType.ATTACK, "test") {
    override fun onLoad(): SubAttribute {
        arrayListOf(
            "溟灭! 你对对方造成 {test_damage} 点溟灭伤害",
            "溟灭! 对方对你造成 {test_defense} 点溟灭伤害"
        ).setMessages()
        "{entityA:溟灭伤害}+({entityB:生命力}*0.5)".setFormula()
        return this
    }
    
    override fun runAttack(attacker: LivingEntity, entity: LivingEntity): Boolean {
        val chance = attacker.getRandomValue().toDouble()
        return chance.chance().apply {
            if (this) {
                var damage = getFormulaValue {
                    val health = entity.getRandomValue(AttributeName.HEALTH.toDefaultName()).toDouble()
                    attacker.getRandomValue("溟灭伤害").toDouble() + (health * 0.5)
                }
                damage -= entity.getRandomValue("溟灭防御").toDouble()
                ("test_defense" to damage).storageValue(true)
                attacker.addDamage(damage)
            }
        }
    }
}

2. 计数器使用示例 (JavaScript)

function runKiller(attr, killer, entity, handle) {
    // 获取击杀者的 AttributeData 对象
    var data = attr.getData(killer, handle)
    
    // 获取创建一个名为 reaper_count 的计算，重置类型为 DEATH 死亡时重置
    var counter = data.counter.getCounter("reaper_count", "DEATH")
    
    // 更新计数器值 +1 默认值为 0
    var value = counter.updateValue(1, 0)
    
    // 判断计数器计数值是否大于等于 3 次
    if (value >= 3) {
        // 重置计数器值
        counter.resetValue()
        killer.sendMessage("§a§lKILLER_ATTRIBUTE 触发")
    } else {
        killer.sendMessage("§a§lKILLER_ATTRIBUTE §f§l" + value + "/3")
    }
}

3. 自定义触发器示例

class SkillCastAttributeTrigger : CustomTriggerComponent<PlayerCastSkillEvent> {
    override val name: String = "SKILL CAST"
    override val event: Class<PlayerCastSkillEvent> = PlayerCastSkillEvent::class.java
    override val priority: EventPriority = EventPriority.NORMAL
    override val ignoreCancelled: Boolean = false
    
    override fun caster(event: PlayerCastSkillEvent): LivingEntity {
        return event.player
    }
    
    override fun params(event: PlayerCastSkillEvent): Array<Any> {
        val skillName = event.skill.data.name
        return arrayOf(skillName)
    }
}

重要注意事项

属性注册: 使用 @AutoRegister 注释进行自动注册
插件依赖: 在 plugin.yml 依赖上加 AttributePlus
属性名使用: 获取其他属性值时使用属性默认名，而不是服务器属性名
计数器重置: 根据需求选择合适的 ItemCounterResetType
异步处理: 注意部分方法无法通过异步执行，需要将属性设为非异步执行

包名总结

主 API: org.serverct.ersha.api.AttributePlus
数据类: org.serverct.ersha.api.data.*
组件类: org.serverct.ersha.api.component.*
枚举类: org.serverct.ersha.api.enums.*
注解: org.serverct.ersha.api.annotations.*

此文档涵盖了 AttributePlus Pro 的主要 API 用法，适合开发者参考进行插件开发。

Overview

AttributePlus Pro API 文档

概述

核心 API

1. AttributeAPI 主类

2. AttributeData 类

3. AttributeCounter 类

属性组件系统

1. SubAttribute 基类

2. AttributeType 枚举

3. 实体扩展方法

4. 实用方法

自定义触发器组件

1. CustomTriggerComponent 接口

读取组件系统

1. ReadComponent 接口

2. DescriptionLineCondition 接口

属性名系统

1. AttributeName 说明

示例代码

1. 属性注册示例

2. 计数器使用示例 (JavaScript)

3. 自定义触发器示例

重要注意事项

包名总结