定时修饰符 API

定时修饰符 API

允许你添加属性修饰符,这些修饰符会在特定时间后过期并被移除。

基础库

使用 1.2.0 或 1.2.1 版本的用户,请更新到 1.2.2!!

限时修饰符 API

这是一个 API,允许你添加临时的属性修饰符,这些修饰符会在设定的时间后自动移除。

如果你是玩家,只需下载并将其添加到你的 mods 文件夹中。 如果你是开发者,请阅读以下内容以了解如何使用此 API。

这是一个 API,不会添加新的游戏玩法功能。它仅用作依赖项。

设置

将此内容添加到 build.gradle 中以依赖此 API。

repositories {
    maven {
        url = "https://api.modrinth.com/maven"
    }
}

dependencies {
    modImplementation "maven.modrinth:timed_modifiers_api:{the_version}"
}

版本号的格式为 x.y.z+[mc_version],例如 1.0.0+1.21.7。

如何使用

示例修饰符

EntityAttributeModifier modifier = new EntityAttributeModifier(
  Identifier.of("example", "speed"),
  0.6,
  EntityAttributeModifier.Operation.ADD_MULTIPLIED_TOTAL
);

添加修饰符

这会添加一个临时修饰符,在持续时间(以刻为单位)后过期

TimedModifierAPI.addModifier(living_entity, attribute_type, attribute_modifier, int duration);

示例:

TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 60);
//添加一个修饰符,在 60 刻(3 秒)内将速度提高 60%

你可以让修饰符的值在其生命周期内增加/减少。要执行此操作,请调用 .grow() 或 .decay()。

你需要为 .grow() 提供一个限制值,但对于 .decay() 这是可选的。

如果你希望此变化在特定时间内发生而不是在整个生命周期内发生,请提供一个以刻为单位的持续时间。

示例:

TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 100).decay();
//在 100 刻(5 秒)内从 +60% 逐渐减少到 0%

TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 60).grow(1.2, 30);
//持续 60 刻(3 秒),值在 30 刻(1.5 秒)内从 +60% 增加到 +120%

你甚至可以选择一种缓动类型来对随时间的变化进行缓动。可用的类型有:Sine、Quadratic、Cubic、Quartic、Quintic 和 Circle。

调用 ease() 并提供缓动类型。

示例:

TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 100).decay().ease(EaseHelper.EasingTypes.SINE_OUT);
//在 100 刻(5 秒)内从 +60% 逐渐减少到 0%,使用正弦缓出

移除修饰符

这会手动在临时修饰符过期前将其移除。

TimedModifierAPI.removeModifier(living_entity, attribute_type, identifier);

示例:

TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier.id());

清除修饰符

这会移除通过此 API 添加的所有临时修饰符。

TimedModifierAPI.clearModifier(living_entity, attribute_type);

示例:

TimedModifierAPI.clearModifier(player, EntityAttributes.MOVEMENT_SPEED);

覆盖修饰符

这会覆盖当前的修饰符,防止在添加相同修饰符时出现错误。

TimedModifierAPI.overrideModifier(living_entity, attribute_type, modifier, duration);

示例:

TimedModifierAPI.overrideModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 40).decay();

更新修饰符值

这可以更新现有修饰符的值。

TimedModifierAPI.updateModifier(living_entity, attribute_type, identifier, double);

示例:

TimedModifierAPI.updateModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier.id(), 0.4);

如果你还想续期持续时间,请在此之后调用 renew()。理论上你也可以在添加之后调用它,但那样不会产生任何有意义的效果。

示例:

TimedModifierAPI.updateModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier.id(), 0.3).renew();

获取持续时间

这会检索特定临时修饰符的剩余持续时间(以刻为单位)。

TimedModifierAPI.getDuration(living_entity, attribute_type, identifier);

示例:

TimedModifierAPI.getDuration(player, EntityAttributes.MOVEMENT_SPEED, modifier.id());

设置/取消设置值

这会直接设置属性实例的值,忽略任何修饰符及其基础值。

TimedModifierAPI.setValue(living_entity, attribute_type, double);

示例:

TimedModifierAPI.setValue(player, EntityAttributes.MOVEMENT_SPEED, 0.088);

这会使属性实例返回其原始值。

TimedModifierAPI.unsetValue(living_entity, attribute_type);

检查值是否已设置/获取该值

这会返回属性实例的值是否已设置。

TimedModifierAPI.isValueSet(living_entity, attribute_type);

这会返回已设置的值,如果未设置则返回 -1。

TimedModifierAPI.getValueSet(living_entity, attribute_type);

替代方案 1

与其反复调用 TimedModifierAPI,你可以简单地将实体强制转换为 ITimedModifier 并访问方法,或者直接让 TimedModifierAPI 进行转换。

示例:

ITimedModifier api = (ITimedModifier) player;
//或者
ITimedModifier api = TimedModifierAPI.asApi(player);

//添加修饰符
api.addModifier(EntityAttributes.MOVEMENT_SPEED, modifier, 60);

//移除修饰符
api.removeModifier(EntityAttributes.MOVEMENT_SPEED, modifier.id());

//清除修饰符
api.clearModifier(EntityAttributes.MOVEMENT_SPEED);

//获取持续时间
api.getDuration(EntityAttributes.MOVEMENT_SPEED, modifier.id());

//设置值
api.setValue(EntityAttributes.MOVEMENT_SPEED, 0.088);

//取消设置值
api.unsetValue(EntityAttributes.MOVEMENT_SPEED);

替代方案 2

如果你觉得写 EntityAttributes.XYZ 太重复,你甚至可以直接检索该属性的 TimedModifierContainer。

示例:

var container = TimedModifierAPI.getContainer(player, EntityAttributes.MOVEMENT_SPEED);
//或者
ITimedModifier api = TimedModifierAPI.asApi(player);
var container = api.getContainer(EntityAttributes.MOVEMENT_SPEED);

//然后做你需要做的任何事
container.addModifier(...);

请注意,你不能从容器调用 setValue()、unsetValue()、isValueSet() 和 getValueSet()。要调用这些方法,请先调用 asApi()。

示例

container.asApi().setValue(25);

事件

AttributeModifierEvents

这是包含 4 个事件的类。

BEFORE_ADD

这在修饰符实际添加到属性实例之前调用。

AttributeModifierEvents.BEFORE_ADD.register((entity, modifier, isPersistent) -> {
    //你的逻辑
});

AFTER_ADD

这在修饰符完全添加到属性实例之后调用。

AttributeModifierEvents.AFTER_ADD.register((entity, modifier, isPersistent) -> {
    //你的逻辑
});

BEFORE_REMOVE

这在修饰符实际从属性实例中移除之前调用。

AttributeModifierEvents.BEFORE_REMOVE.register((entity, identifier) -> {
    //你的逻辑
});

BEFORE_ADD

这在修饰符成功且完全地从属性实例中移除之后调用。

AttributeModifierEvents.AFTER_REMOVE.register((entity, modifier) -> {
    //你的逻辑
});