任何使用 1.2.0 或 1.2.1 版本的用户,请更新至 1.2.2!!
Timed Modifiers API
这是一个允许你添加在设定时间后自动移除的临时属性修饰符的 API。
如果你是玩家,只需下载此文件并将其放入你的模组文件夹中即可。
如果你是开发者,请阅读以下内容以了解如何使用此 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) -> {
//你的逻辑
});
AFTER_REMOVE
在修饰符成功且完全从属性实例中移除之后触发。
AttributeModifierEvents.AFTER_REMOVE.register((entity, modifier) -> {
//你的逻辑
});
Anyone using version 1.2.0 or 1.2.1, please update to 1.2.2!!
Timed Modifiers API
This is an API that allows you to add temporary attribute modifiers that gets removed after a set amount of time.
If you are a player, simply download and add this to your mod folder.
If you are a developer, please read the following to learn how to use this API.
This is an API and does not add new gameplay features. This is just used as a dependency.
Set up
Add this to the build.gradle to depend on this API.
repositories {
maven {
url = "https://api.modrinth.com/maven"
}
}
dependencies {
modImplementation "maven.modrinth:timed_modifiers_api:{the_version}"
}
The version number will be in the form x.y.z+[mc_version], e.g. 1.0.0+1.21.7.
How to use
Example Modifier
EntityAttributeModifier modifier = new EntityAttributeModifier(
Identifier.of("example", "speed"),
0.6,
EntityAttributeModifier.Operation.ADD_MULTIPLIED_TOTAL
);
Add modifier
This adds a temporary modifier that expires after a duration (in ticks)
TimedModifierAPI.addModifier(living_entity, attribute_type, attribute_modifier, int duration);
Example:
TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 60);
//Adds a modifier that increases speed by 60% for 60 ticks (3 seconds)
You can make a modifier's value increase/decrease over its lifetime. To do this, call .grow() or .decay().
You need to provide a limit for .grow(), but this is optional for .decay().
If you want this to happen in a specific amount of time instead of over the whole lifetime, provide a duration in ticks.
Example:
TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 100).decay();
//Gradually decreases from +60% to 0% over 100 ticks (5 seconds)
TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 60).grow(1.2, 30);
//Lasts 60 ticks (3 seconds), value increases from +60% to +120% in 30 ticks (1.5 seconds)
You can even select an easing type and ease the over time change. There are: Sine, Quadratic, Cubic, Quartic, Quintic and Circle.
Call ease() and provide the type of easing.
Example:
TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 100).decay().ease(EaseHelper.EasingTypes.SINE_OUT);
//Gradually decreases from +60% to 0% over 100 ticks (5 seconds) with sine ease out
Remove modifier
This manually removes a temporary modifier before it expires.
TimedModifierAPI.removeModifier(living_entity, attribute_type, identifier);
Example:
TimedModifierAPI.addModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier.id());
Clear modifier
This removes all temporary modifiers added via this API.
TimedModifierAPI.clearModifier(living_entity, attribute_type);
Example:
TimedModifierAPI.clearModifier(player, EntityAttributes.MOVEMENT_SPEED);
Override Modifier
This will override the current modifier, preventing the error when the same modifier is added.
TimedModifierAPI.overrideModifier(living_entity, attribute_type, modifier, duration);
Example:
TimedModifierAPI.overrideModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier, 40).decay();
Update Modifier Value
This can update the value of an existing modifier.
TimedModifierAPI.updateModifier(living_entity, attribute_type, identifier, double);
Example:
TimedModifierAPI.updateModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier.id(), 0.4);
If you want to renew the duration as well, call renew() after that. You can technically call it after you add it too, but that wouldn't do anything meaningful.
Example:
TimedModifierAPI.updateModifier(player, EntityAttributes.MOVEMENT_SPEED, modifier.id(), 0.3).renew();
Get duration
This retrieves the remaining duration (in ticks) of a specific temporary modifier.
TimedModifierAPI.getDuration(living_entity, attribute_type, identifier);
Example:
TimedModifierAPI.getDuration(player, EntityAttributes.MOVEMENT_SPEED, modifier.id());
Set/Unset value
This directly sets the value of an attribute instance, ignoring any modifiers and its base value.
TimedModifierAPI.setValue(living_entity, attribute_type, double);
Example:
TimedModifierAPI.setValue(player, EntityAttributes.MOVEMENT_SPEED, 0.088);
This makes the attribute instance return back to its original value.
TimedModifierAPI.unsetValue(living_entity, attribute_type);
Check if value is set/obtain the value
This returns whether or not the attribute instance value is set.
TimedModifierAPI.isValueSet(living_entity, attribute_type);
This returns the value that is set, or -1 if the value isn't set.
TimedModifierAPI.getValueSet(living_entity, attribute_type);
Alternative 1
Instead of calling TimedModifierAPI over and over again, you can simply cast the entity to ITimedModifier and access the methods, or just ask TimedModifierAPI to cast it.
Example:
ITimedModifier api = (ITimedModifier) player;
//or
ITimedModifier api = TimedModifierAPI.asApi(player);
//add modifier
api.addModifier(EntityAttributes.MOVEMENT_SPEED, modifier, 60);
//remove modifier
api.removeModifier(EntityAttributes.MOVEMENT_SPEED, modifier.id());
//clear modifiers
api.clearModifier(EntityAttributes.MOVEMENT_SPEED);
//get duration
api.getDuration(EntityAttributes.MOVEMENT_SPEED, modifier.id());
//set Value
api.setValue(EntityAttributes.MOVEMENT_SPEED, 0.088);
//unset value
api.unsetValue(EntityAttributes.MOVEMENT_SPEED);
Alternative 2
If you find writing EntityAttributes.XYZ too repetitive, you can even retrieve the TimedModifierContainer of that attribute directly.
Example:
var container = TimedModifierAPI.getContainer(player, EntityAttributes.MOVEMENT_SPEED);
//or
ITimedModifier api = TimedModifierAPI.asApi(player);
var container = api.getContainer(EntityAttributes.MOVEMENT_SPEED);
//and then do whatever you need
container.addModifier(...);
Please note that you cannot call setValue(), unsetValue(), isValueSet() and getValueSet() from a container. In order to call these methods, call asApi() first.
Example
container.asApi().setValue(25);
Events
AttributeModifierEvents
This is the class that includes the 4 events.
BEFORE_ADD
This is invoked before a modifier is actually added to the attribute instance.
AttributeModifierEvents.BEFORE_ADD.register((entity, modifier, isPersistent) -> {
//your logic
});
AFTER_ADD
This is invoked after a modifier is fully added to the attribute instance.
AttributeModifierEvents.AFTER_ADD.register((entity, modifier, isPersistent) -> {
//your logic
});
BEFORE_REMOVE
This is invoked before a modifier is actually removed from the attribute instance.
AttributeModifierEvents.BEFORE_REMOVE.register((entity, identifier) -> {
//your logic
});
BEFORE_ADD
This is invoked after a modifier is successfully and fully removed from the attribute instance.
AttributeModifierEvents.AFTER_REMOVE.register((entity, modifier) -> {
//your logic
});
评论 0
登录后参与评分
还没有评论,来抢沙发吧