API 参考 / 打击特效样式（render 包）

HitEffectStyles

想先跑起来？

这一页是签名与行为参考。预置样式工厂：文字、图片序列、精灵图切帧。直接做一遍：教程 · 自定义打击特效。

用途：打击特效样式工厂。静态方法构造常用样式，本类不可实例化（私有构造）。

方法速览

方法	用途
`text(...)` ×3	固定文字，全强度显示同一串
`textByIntensity(...)` ×3	文字随强度切换（由高到低）
`imageSequence(...)` ×2	显式帧列表 + 显式每帧时长
`imageSequenceByDuration(...)` ×4	显式帧列表 + 按总时长自动均分每帧时长
`imageSheet(...)` ×4	精灵图网格拆帧，每帧时长自动均分

完整签名

java

public final class HitEffectStyles {

    public static HitEffectStyle text(String text, long durationMs);

    public static HitEffectStyle text(String text, long durationMs, float scale);

    public static HitEffectStyle text(String text, long durationMs, float scale,
                                      boolean followLaneRotation);

    public static HitEffectStyle textByIntensity(String[] texts, long durationMs);

    public static HitEffectStyle textByIntensity(String[] texts, long durationMs, float scale);

    public static HitEffectStyle textByIntensity(String[] texts, long durationMs, float scale,
                                                 boolean followLaneRotation);

    public static HitEffectStyle imageSequence(
            List<RenderImage> frames, long frameDurationMs, boolean loop, long durationMs);

    public static HitEffectStyle imageSequence(
            List<RenderImage> frames, long frameDurationMs, boolean loop,
            long durationMs, float scale);

    public static HitEffectStyle imageSequenceByDuration(List<RenderImage> frames, long durationMs);

    public static HitEffectStyle imageSequenceByDuration(
            List<RenderImage> frames, long durationMs, boolean loop);

    public static HitEffectStyle imageSequenceByDuration(
            List<RenderImage> frames, long durationMs, boolean loop, float scale);

    public static HitEffectStyle imageSequenceByDuration(
            List<RenderImage> frames, long durationMs, boolean loop, float scale,
            boolean followLaneRotation);

    public static HitEffectStyle imageSheet(
            RenderImage sheet, int cellWidth, int cellHeight, long durationMs);

    public static HitEffectStyle imageSheet(
            RenderImage sheet, int cellWidth, int cellHeight, long durationMs, boolean loop);

    public static HitEffectStyle imageSheet(
            RenderImage sheet, int cellWidth, int cellHeight,
            long durationMs, boolean loop, float scale);

    public static HitEffectStyle imageSheet(
            RenderImage sheet, int cellWidth, int cellHeight,
            long durationMs, boolean loop, float scale, boolean followLaneRotation);
}

text(text, durationMs) / text(text, durationMs, scale) / text(text, durationMs, scale, followLaneRotation)

签名：

java

static HitEffectStyle text(String text, long durationMs);

static HitEffectStyle text(String text, long durationMs, float scale);

static HitEffectStyle text(String text, long durationMs, float scale, boolean followLaneRotation);

行为：构造固定文字样式，textForIntensity 在任何强度下都返回同一串。text 为 null 抛 NullPointerException。scale 在文字路径不生效（见 HitEffectStyle#scale()）。

textByIntensity(texts, durationMs) / (texts, durationMs, scale) / (texts, durationMs, scale, followLaneRotation)

签名：

java

static HitEffectStyle textByIntensity(String[] texts, long durationMs);

static HitEffectStyle textByIntensity(String[] texts, long durationMs, float scale);

static HitEffectStyle textByIntensity(String[] texts, long durationMs, float scale,
                                      boolean followLaneRotation);

行为：构造随强度切换文字的样式。索引映射：强度 1 → texts[0]，强度 0 → texts[length-1]，中间线性取整。

texts 为 null 抛 NullPointerException；长度为 0 抛 IllegalArgumentException；
数组在构造时克隆，之后修改原数组不影响已创建的样式。

imageSequence(frames, frameDurationMs, loop, durationMs) / (..., scale)

签名：

java

static HitEffectStyle imageSequence(
        List<RenderImage> frames, long frameDurationMs, boolean loop, long durationMs);

static HitEffectStyle imageSequence(
        List<RenderImage> frames, long frameDurationMs, boolean loop,
        long durationMs, float scale);

行为：显式帧列表 + 显式每帧时长，帧按列表顺序播放，播完按 loop 决定循环或停在最后一帧。

frames 为 null 抛 NullPointerException；为空、frameDurationMs <= 0、durationMs <= 0、scale <= 0 抛 IllegalArgumentException；
列表在构造时复制为不可变副本（List.copyOf），之后修改原列表不影响样式。

imageSequenceByDuration(...)

签名：

java

static HitEffectStyle imageSequenceByDuration(List<RenderImage> frames, long durationMs);

static HitEffectStyle imageSequenceByDuration(
        List<RenderImage> frames, long durationMs, boolean loop);

static HitEffectStyle imageSequenceByDuration(
        List<RenderImage> frames, long durationMs, boolean loop, float scale);

static HitEffectStyle imageSequenceByDuration(
        List<RenderImage> frames, long durationMs, boolean loop, float scale,
        boolean followLaneRotation);

行为：与 imageSequence 相同，但不指定每帧时长：宿主按 durationMs / 帧数 自动均分（至少 1ms）。默认 scale = 1.0f、loop = false、followLaneRotation = false。校验规则同 imageSequence（此时不校验 frameDurationMs）。

imageSheet(...)

签名：

java

static HitEffectStyle imageSheet(
        RenderImage sheet, int cellWidth, int cellHeight, long durationMs);

static HitEffectStyle imageSheet(
        RenderImage sheet, int cellWidth, int cellHeight, long durationMs, boolean loop);

static HitEffectStyle imageSheet(
        RenderImage sheet, int cellWidth, int cellHeight,
        long durationMs, boolean loop, float scale);

static HitEffectStyle imageSheet(
        RenderImage sheet, int cellWidth, int cellHeight,
        long durationMs, boolean loop, float scale, boolean followLaneRotation);

行为：用一张精灵图按网格拆帧，每帧时长自动均分（同 imageSequenceByDuration），绘制尺寸 = 单格尺寸 × scale。

sheet 为 null 抛 NullPointerException；cellWidth <= 0、cellHeight <= 0、durationMs <= 0、scale <= 0 抛 IllegalArgumentException；
网格列数 = sheet.width() / cellWidth、行数 = sheet.height() / cellHeight，均至少为 1，多余的边角像素不参与播放。

示例：注册一个按判定等级区分的打击特效

java

import com.seecmd.mod.api.ModContext;
import com.seecmd.mod.api.registry.RegistryKey;
import com.seecmd.mod.api.render.HitEffectStyleProvider;
import com.seecmd.mod.api.render.HitEffectStyles;

// 在 onPreInit 内注册
void registerHitEffects(ModContext ctx) {
    RegistryKey<HitEffectStyleProvider> key =
            RegistryKey.of("mymod", "hit_effects", HitEffectStyleProvider.class);

    ctx.registries().hitEffectStyles().register(key, c -> {
        if (!"PERFECT".equals(c.grade().displayName())) {
            return null;   // 不是 PERFECT 就不接管，交回默认表现
        }
        return HitEffectStyles.textByIntensity(
                new String[] { "PERFECT!", "Perfect", "good" }, 500L, 1.0f);
    });
}

上一页HitEffectStyle 下一页HitEffectStyleProvider