Java Tip API

本篇会带你用 Java API 写一个小贴士（Tip），并把它“注册、触发、显示”完整走一遍。

如果你是整合包作者，通常更推荐先看数据包文档 / KJS 文档；但只要你愿意写点 Java，这套 API 会更自由：你可以在任何事件、任何逻辑里决定 什么时候给谁弹什么 Tip。

你需要先理解的 3 个概念

1) TipData：最终的数据

Tip 的“真身”是 cc.sighs.auratip.data.TipData，它包含：

id：全局唯一的 id（ResourceLocation）
trigger：触发类型、触发模式（一次/可重复）、冷却
visual_settings：尺寸、位置、背景、动画、主题色等
behavior：持续时间、关闭方式、是否允许翻页
pages：页面列表（每页可以有标题/副标题/正文/图片）

你可以通过两种来源提供 TipData：

数据包：data/auratip/tips/*.json（见数据包文档）
运行时（Java/KubeJS）：用 TipBuilder 组装，再放进 TipRegistry

注意：Tip 的 id 必须全局唯一。

2) TipRegistry：运行时 Tip 的“仓库”

cc.sighs.auratip.api.tip.TipRegistry 用来管理“运行时注册的 Tip”。

一个 owner（填你的 modid）对应一组 tips
kubejs 这个是用 Kubejs 添加的 tips 自带的 id，非必要不要用，除非你的模组叫 kubejs
如果是数据包添加的，那 modid 就默认为 auratip

3) TipServer：在服务器端触发 / 直接显示

cc.sighs.auratip.api.tip.TipServer 是 服务器侧入口：

trigger(type, player, vars)：按 trigger.type 匹配并触发（会走 ONCE/冷却规则）
triggerById(tipId, player, vars)：点名触发某个 tip id（也会走 ONCE/冷却规则）
show(player, tips, vars)：直接推送，不走触发过滤/冷却（“立刻显示”）

快速上手：写一个最小可用 Tip

下面这段是最常见的写法：

用 TipBuilder 构建出 TipData
用 TipRegistry.setTips(owner, ...) 注册
在某个事件里 TipServer.trigger(...)

import cc.sighs.auratip.api.tip.TipBuilder;
import cc.sighs.auratip.api.tip.TipRegistry;
import cc.sighs.auratip.api.tip.TipServer;
import cc.sighs.auratip.data.TipData;
import net.minecraft.network.chat.Component;
import net.minecraft.resources.ResourceLocation;
import net.minecraft.server.level.ServerPlayer;

import java.util.List;
import java.util.Map;

public final class MyTips {
    public static final String OWNER = "mymod";

    public static final ResourceLocation TIP_ID = new ResourceLocation("mymod", "intro");
    public static final ResourceLocation TRIGGER_ID = new ResourceLocation("mymod", "player_login");

    public static void registerRuntimeTips() {
        TipData tip = new TipBuilder(TIP_ID)
                .triggerOnce(TRIGGER_ID)
                .visual(v -> v
                        .size(220, 55)
                        .positionPreset("TOP_LEFT")
                        .animationStyle(new ResourceLocation("auratip", "fade_and_slide"))
                        .hoverAnimationStyle(new ResourceLocation("auratip", "none"))
                )
                .behavior(b -> b
                        .duration(160)
                        .pauseOnHover(true)
                )
                .page(0, p -> p
                        .title(Component.literal("欢迎！"), 0.8f, 0)
                        .content(Component.literal("你好，${player}"), 0.65f, 1)
                )
                .build();

        TipRegistry.setTips(OWNER, List.of(tip));
    }

    public static void triggerLoginTip(ServerPlayer player) {
        TipServer.trigger(TRIGGER_ID, player, Map.of(
                "player", player.getDisplayName()
        ));
    }
}

你看到的 ${player} 不是魔法：AuraTip 会在渲染时用 variables map 做字符串占位替换。

TipBuilder：把 TipData “拼出来”

核心类：cc.sighs.auratip.api.tip.TipBuilder

1) 构造器与 id 规则

new TipBuilder(ResourceLocation id)
这个 id 用来做 “ONCE 是否展示过 / REPEATABLE 冷却” 的记录，所以建议是 不要轻易改变

2) trigger：触发信息

trigger(type, mode, cooldownTicks)
triggerOnce(type)：等价于 mode=ONCE
triggerRepeatable(type, cooldownTicks)：等价于 mode=REPEATABLE

如果你写了两个 trigger type 相同的 Tip，那么触发这个 type 的效果就是依次展示这两个 Tip。

触发规则在服务端执行，记录存放在玩家 persistentData 下的 auratip_shown_tips 里。

AuraTip 自带两个示例：

auratip:first_join_world：玩家登录时触发（见 CommonEventHandler）

auratip:showtip_command：/showtip 指令触发（见 ShowTipCommand）

3) page：页面内容

page(index, builder -> ...) 用于创建/更新某个页面。

要求与注意点：

至少要有 1 页
page_index 不能重复
一页必须至少有一个内容（title/subtitle/content/image 任意一个）

PageBuilder 常用方法：

title(Component text, float scale, int lineSpacing)
subtitle(Component text, float scale, int lineSpacing)
content(Component text, float scale, int lineSpacing)
titleDivider(...)：在标题下方加一条分割线
image(path, preset, w, h) / image(path, x, y, w, h)
imageScaled(...)：同上，但带 scale

图片 path 的常见写法：minecraft:textures/item/apple.png

4) visual：外观与动画

visual(v -> { ... }) 对应 TipData.VisualSettings。

尺寸与位置

size(w, h)：宽高必须 > 0
positionPreset(preset)：预设位置（不区分大小写，内部会转大写）
- TOP_LEFT / TOP_CENTER / TOP_RIGHT
- LEFT_CENTER / RIGHT_CENTER
- BOTTOM_LEFT / BOTTOM_CENTER / BOTTOM_RIGHT
- 其他值会按 CENTER 处理
positionAbsolute(x, y)：以屏幕 GUI 像素为单位（要求 x/y >= 0）

背景

background(type, colors, radius)：
- type=GRADIENT：建议给 2+ 个颜色
- type=SOLID：建议给 1 个颜色
- type=IMAGE：颜色不一定使用，配合 backgroundImage(path)
backgroundRounded(true/false)：是否圆角
backgroundImage(path)：图片背景路径（仅 IMAGE 类型使用）

颜色建议用：#AARRGGBB 或 #RRGGBB（例如 #CC101010）。

动画（开/关场）

animationStyle(id)：动画类型 id
animationSpeed(speed)：速度倍率（建议 > 0）
animParam(key, value) / animParams(map)：传递动画参数（会转为 Dynamic）

内置 transition 动画（auratip:*）：

auratip:fade_and_slide（默认，参数：offset）
auratip:fade
auratip:slide（参数：extra_padding）
auratip:slide_in_left（参数：extra_padding）
auratip:slide_in_right（参数：extra_padding）
auratip:slide_in_top（参数：extra_padding）
auratip:slide_in_bottom（参数：extra_padding）

悬停动画（hover）

hoverAnimationStyle(id)
hoverAnimationSpeed(speed)
hoverOnlyOnHover(true/false)：只在鼠标悬停面板时播放
hoverParam(...) / hoverParams(...)

内置 hover 动画：

auratip:none（默认）
auratip:hover_float（参数：amplitude、ramp_duration）
auratip:hover_shake（参数：amplitude_x、amplitude_y、frequency_x、frequency_y、phase、ramp_duration）

主题色与边条

themeColor("#55FFFF")：主题色（影响边条、分割线默认色等）
stripeWidth(px)：左侧竖条宽度
stripeLengthFactor(0~1)：竖条长度比例

5) behavior：交互与持续时间

behavior(b -> { ... }) 对应 TipData.Behavior。

duration(ticks)：默认 200 ticks；-1 表示一直显示直到关闭
pauseOnHover(true/false)：鼠标悬停时暂停倒计时
closeKey("key.keyboard.delete")：按某个按键关闭（会解析为 InputConstants.Key）
allowPaging(true/false)：多页时是否允许左右键翻页

提示：Tip 面板默认也支持：

点击右上角 X 关闭
按 DEL 关闭

变量占位：`${key}` 怎么生效？

AuraTip 只做一件事：在渲染前，把 Component 扁平化后，对文字里的 ${...} 做替换。

你需要：

在 tip 的文字里写 ${key}
在触发/显示时传入 Map<String, ?> variables

变量值可以是：

Component：保留样式
任何对象：会走 toString() 变成纯文字 Component.literal(...)

示例：

TipServer.trigger(myTrigger, player, Map.of(
        "player", player.getDisplayName(),
        "x", player.getBlockX(),
        "z", player.getBlockZ()
));

服务器触发 vs 客户端直接入队

服务器触发（推荐）

适用于绝大多数场景：服务器决定“该不该显示”，并负责同步给客户端。

TipServer.trigger(type, player, vars)
TipServer.triggerById(tipId, player, vars)
TipServer.show(player, tips, vars)

客户端直接入队（绕开触发规则）

适用于“纯客户端教程/GUI 引导”一类：

cc.sighs.auratip.api.client.TipClientApi.enqueue(tips, vars)（@OnlyIn(Dist.CLIENT)）

注意：TipClientApi.enqueue 不会走 ONCE/冷却，也不会做 trigger.type 匹配。

自定义动画（Java）

如果内置动画不够用，你可以注册自己的动画 id：

cc.sighs.auratip.api.animation.TipAnimations.register(id, factory)：transition
cc.sighs.auratip.api.animation.TipAnimations.registerHover(id, factory)：hover

注册后就可以在 visual().animationStyle(...) / visual().hoverAnimationStyle(...) 中使用你的 id。

你需要先理解的 3 个概念​

1) TipData：最终的数据​

2) TipRegistry：运行时 Tip 的“仓库”​

3) TipServer：在服务器端触发 / 直接显示​

快速上手：写一个最小可用 Tip​

TipBuilder：把 TipData “拼出来”​

1) 构造器与 id 规则​

2) trigger：触发信息​

3) page：页面内容​

4) visual：外观与动画​

尺寸与位置​

背景​

动画（开/关场）​

悬停动画（hover）​

主题色与边条​

5) behavior：交互与持续时间​

变量占位：${key} 怎么生效？​

服务器触发 vs 客户端直接入队​

服务器触发（推荐）​

客户端直接入队（绕开触发规则）​

自定义动画（Java）​