⚡ Relay
行业标准的响应式服务注册中心、插件间发布/订阅通信及 Folia 多线程生态系统框架
Endüstri Standardı Reaktif Servis Kaydı, Eklentiler Arası İletişim (Pub/Sub) ve Çok Çekirdekli Folia Ekosistem Çatısı
?? English Documentation
•
?? Türkçe Dokümantasyon
?? English
? What is Relay?
Relay is an enterprise-grade, high-performance reactive service backbone, inter-plugin communication framework, and multi-threaded infrastructure engine designed for modern Minecraft servers running on Paper, Purpur, and multi-threaded Folia.
For years, Minecraft plugin architecture has remained shackled to single-threaded Bukkit conventions from 2012: synchronous main-thread stalls, fragile depend load-order chains in plugin.yml, incompatible Folia scheduler crashes, hacky ArmorStand holograms that destroy client FPS, and notorious memory leaks whenever a plugin reloads.
Relay completely redesigns server internals around 5 modern architectural pillars:
- ⚡ 100% Non-Blocking & Asynchronous Architecture: Built on Java 21
CompletableFuture promises, concurrent lock-free primitives, and nanosecond telemetry. Long database lookups, economy calculations, and permission queries never stall server ticks.
- ? Unified Multi-Thread Scheduler (
SchedulerService): Write your task logic once. Relay transparently routes entity, region, global, and async tasks to Folia's EntityScheduler, RegionScheduler, GlobalRegionScheduler, and AsyncScheduler, while seamlessly degrading to BukkitScheduler on Paper/Spigot.
- ? Microservice-Style Pub/Sub & RPC Event Bus: Decouple your plugins completely. Publish events across topics, subscribe typed payload consumers, or invoke time-bounded asynchronous request-response queries (
request) without direct .jar dependencies.
- ?️ Zero-Memory Leak Lifecycles: Automatic cleanup hooks unregister listeners, remove display entities, close active virtual menus, dismiss active bossbars, cancel running scheduled tasks, and evict stale cooldowns upon plugin disable (
setPersistent(false)).
- ? Ultra-Lightweight API (~80 KB): Zero transitive runtime dependencies. Your consumer plugins stay clean, fast, and featherweight.
? Built-in Services (Overview)
Relay unifies 13 essential server subsystems into a clean, lightweight API:
| 服务 / 子系统 |
描述 |
关键特性 |
| ServiceRegistry |
响应式服务发现与提供者注册表 |
优先级层级 (HIGHEST ➔ FALLBACK)、与加载顺序无关的 onServiceReady Promise 回调。 |
| RelayMessenger |
解耦的 Pub/Sub 事件总线及异步 RPC |
无需 jar 依赖即可实现插件间通信;发布主题、订阅监听器并等待异步响应。 |
| EconomyService |
多币种财务账本引擎 |
符合 IEEE 754 浮点数安全的 BigDecimal 算术运算、任意货币注册、原子化转账。 |
| CooldownService |
通用基于时间的冷却管理器 |
适用于技能、法术和命令的线程安全冷却;动作栏完成百分比显示 (getProgress())、自动 TTL 过期清理。 |
| SharedDataService |
类型安全的共享响应式数据存储 |
强类型 DataKey<T> 验证、临时 TTL 键过期、实时变更观察者 (observe)。 |
| PermissionService |
异步权限与群组检查 |
非阻塞式的群组和权限查询以保护服务器 Tick 性能,LuckPerms/Vault 桥接,权重排名。 |
| PartyService |
团队、小队及友伤管理 |
零分配、无锁的 isFriendlySync 验证,用于战斗引擎、副本小队及共享掉落物。 |
| MetricsService |
性能遥测与卡顿尖峰警报 |
纳秒级分辨率计时器、P50/P95/P99 延迟百分位数、Tick 下降时自动派发 LagSpikeEvent。 |
| HologramService |
基于显示实体的全息广告牌引擎 |
Minecraft 1.20+ 原生 TextDisplay 实体、零 ArmorStand 卡顿、Folia 区域安全的 spawnAsync、MiniMessage 文本及阴影效果。 |
| MenuService |
虚拟箱子库存与 GUI 引擎 |
Folia 线程安全打开、严格的防重复取消机制、150ms 防宏去抖、分页菜单 (PaginatedMenu<T>)。 |
| NotificationService |
多渠道玩家反馈与显示引擎 |
基于优先级的队列 ActionBars、动画倒计时 BossBars、虚拟右上角 Toasts 以及平滑的 Title 序列。 |
| SchedulerService |
统一的 Folia 与 Paper 多线程调度器 |
支持实体、位置/区域、全局及异步调度;runAsyncPromise、线程验证、零泄漏任务自动取消。 |
| ScoreboardService |
通用无闪烁计分板与 Tablist 引擎 |
按玩家隔离的计分板、1-15 行动态内容、Lambda 供给器、动画标题帧、Tablist 页眉/页脚。 |
?️ Folia 多线程与零泄漏架构
Relay 从底层开始即为多线程服务器而设计:
- 区域安全调度: 世界实体变更(如
TextDisplay 全息图)、计划任务、计分板视图和库存视图均通过 Folia 的 RegionScheduler 或 EntityScheduler 进行分发。
- 无锁并发: 所有内部注册表均使用
ConcurrentHashMap、CopyOnWriteArrayList 和 AtomicReference 结构,以确保确定性执行,避免线程竞争或死锁。
- 持久化自动清理: 所有生成的实体均启用
setPersistent(false)。当消费插件卸载时,Relay 会自动清除其关联的订阅者、全息图、BossBar、计划任务、侧边栏和 GUI 会话。
? 添加到你的项目(依赖)
插件开发者只需针对轻量级的 relay-api (~80 KB,无传递性运行时膨胀) 进行编译:
Gradle (Kotlin DSL)
repositories {
mavenCentral()
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.Kriscra.Relay:relay-api:v1.6.0")
}
Gradle (Groovy DSL)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.Kriscra.Relay:relay-api:v1.6.0'
}
Maven (pom.xml)
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.Kriscra.Relay</groupId>
<artifactId>relay-api</artifactId>
<version>v1.6.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
?️ 快速代码示例
1. 响应式服务发现 (onServiceReady)
再也不用担心 loadbefore 或 depend 的顺序问题。在服务注册的瞬间即可获取其实例:
RelayAPI.getServiceRegistry().onServiceReady(EconomyService.class, economy -> {
getLogger().info("Economy hooked! Default currency: " + economy.getDefaultCurrency().displayName());
});
2. 插件间 Pub/Sub 与 RPC 消息传递
实现无缝的跨插件通信,无需直接的 .jar 依赖:
// 发布者插件:
RelayAPI.getMessenger().publish("guild:levelup", new GuildLevelPayload("Valkyrie", 10), this);
// 订阅者插件:
RelayAPI.getMessenger().subscribe("guild:levelup", GuildLevelPayload.class, this, ctx -> {
getLogger().info(ctx.getPayload().guildName() + " has reached level " + ctx.getPayload().level());
});
// 非阻塞 RPC 请求/响应:
RelayAPI.getMessenger().request("guild:get_balance", guildId, BigDecimal.class, Duration.ofSeconds(2))
.thenAccept(balance -> player.sendMessage("Guild Balance: " + balance));
3. TextDisplay 全息图 (Minecraft 1.20+ 原生)
使用 Minecraft 1.20+ Display Entities 创建无卡顿的文本显示:
Hologram hologram = RelayAPI.getHolograms().createBuilder(plugin, location)
.appendLine("<gradient:#4facfe:#00f2fe><bold>✦ RELAY NETWORK ✦</bold></gradient>")
.appendLine("<gray>Powered by TextDisplay & Folia</gray>")
.setBillboard(Billboard.CENTER)
.setTextShadow(true)
.build();
hologram.spawnAsync();
4. Folia 安全型箱子 GUI(防刷与去抖)
Menu menu = RelayAPI.getMenus().createBuilder(plugin)
.titleMiniMessage("<green>传送门</green>")
.pattern(
"#########",
"# W #",
"#########"
)
.bindKey('#', MenuButton.of(new ItemStack(Material.BLACK_STAINED_GLASS_PANE)))
.bindKey('W', MenuButton.builder()
.item(new ItemStack(Material.COMPASS))
.sound(Sound.ENTITY_ENDERMAN_TELEPORT)
.debounce(250L) // 250毫秒防宏去抖
.onClick(ctx -> ctx.getPlayer().teleportAsync(spawnLocation))
.build())
.build();
menu.open(player);
5. 多通道通知(优先级动作栏、BossBar 和 Toast)
// 支持抢占式优先级的动作栏队列:
RelayAPI.getNotifications().actionBar(player)
.messageMiniMessage("<gradient:#f12711:#f5af19><bold>警告:</bold>已进入战斗区域!</gradient>")
.priority(NotificationPriority.HIGH)
.duration(Duration.ofSeconds(3))
.send(plugin);
// 带占位符 %time% 和 %progress% 的倒计时 BossBar:
ActiveBossBar bar = RelayAPI.getNotifications().bossBar(player)
.titleMiniMessage("<aqua>副本清理中</aqua> <gray>(剩余 %time%s)</gray>")
.countdown(Duration.ofSeconds(30))
.color(BossBar.Color.BLUE)
.onComplete(() -> player.sendMessage("副本已封印!"))
.send(plugin);
// 虚拟右上角 Toast 弹窗:
RelayAPI.getNotifications().toast(player)
.titleMiniMessage("<gold>神话任务完成!</gold>")
.descriptionMiniMessage("<gray>击败末影龙</gray>")
.icon(Material.DRAGON_HEAD)
.frame(ToastFrame.CHALLENGE)
.send(plugin);
6. 统一多线程调度器(兼容 Folia 和 Paper)
在实体区域线程、全局刻或异步池中运行任务,Paper 和 Folia 使用完全相同的代码:
SchedulerService scheduler = RelayAPI.getScheduler();
// 在玩家所在区域线程上安全运行:
scheduler.runFor(plugin, player, () -> {
player.giveExp(100);
});
// 在世界坐标处运行重复粒子任务:
RelayTask task = scheduler.runAtRepeating(plugin, targetLoc, t -> {
targetLoc.getWorld().spawnParticle(Particle.FLAME, targetLoc, 5);
}, 20L, 10L);
// 随时取消(或在插件禁用时由 Relay 自动取消):
task.cancel();
// 非阻塞异步 Promise 执行:
scheduler.supplyAsyncPromise(() -> database.loadPlayerData(uuid))
.thenAccept(data -> scheduler.runFor(plugin, player, () -> player.sendMessage("加载完成!")));
7. 无闪烁计分板与列表引擎
创建隔离的每玩家侧边栏,支持动态行供应器和动画标题:
Sidebar sidebar = RelayAPI.getScoreboard().sidebarBuilder(plugin)
.titleMiniMessage("<gradient:#ff0844:#ffb199><bold>✦ RELAY RPG ✦</bold></gradient>")
.lineMiniMessage(1, "<gray>玩家:<white>" + player.getName())
.line(2, () -> Component.text("金币:" + economy.getBalance(player.getUniqueId())))
.lineMiniMessage(3, "<aqua>延迟:<green>" + player.getPing() + "ms")
.updateInterval(20L) // 每秒自动刷新动态行
.buildAndShow(player);
// 每玩家的动画 Tablist 页眉和页脚:
RelayAPI.getScoreboard().setTablistMiniMessage(
player,
"<gradient:#4facfe:#00f2fe><bold>RELAY 服务器网络</bold></gradient>\n<gray>在线玩家:150</gray>",
"<gray>商店:store.example.com • Discord:/discord</gray>"
);
⚙️ 管理与诊断
实时监控活跃服务、主题、遥测数据、打开会话、计划任务和测试通知:
/relay status:查看已加载服务、主题、活跃全息图、菜单、任务、侧边栏及服务器运行环境的概览。
/relay services:列出所有注册的服务、提供程序插件及优先级层级。
/relay topics:检查活跃的发布/订阅主题及订阅者数量。
/relay metrics:实时执行平均值、P95 延迟及事务计数器。
/relay metrics reset:重置所有活跃的遥测样本和指标计数器。
/relay holograms:检查当前跟踪的 TextDisplay 全息图及其世界位置。
/relay menus:列出活跃的虚拟库存会话及观看玩家。
/relay scoreboards:列出所有活跃的侧边栏及其观看玩家。
/relay notify <player> <actionbar|bossbar|toast|title> [message]:向在线玩家发送实时测试通知。
权限: relay.admin (默认:OP)
?? 土耳其语
? Relay 是什么?
Relay 是一个企业级开源基础设施引擎,旨在将现代 Minecraft 服务器(Paper、Purpur 以及特别是多核 Folia)中的插件集成、数据通信和服务器服务提升至行业标准水平。
多年来,Minecraft 插件架构一直受困于源自 2012 年的单核 Bukkit 习惯:在主线程(Main Thread)上锁定的同步数据库/经济查询、plugin.yml 中脆弱的 depend: 加载顺序冲突、在 Folia 上崩溃的经典计时器、耗尽服务器性能的 ArmorStand 全息图,以及插件重新加载后遗留僵尸对象的内存泄漏。
Relay 通过以下 5 个核心支柱重构服务器架构:
- ⚡ %100 非阻塞与异步架构: 采用 Java 21
CompletableFuture 承诺链、无锁并发数据结构以及纳秒级精度的遥测技术。数据库查询和经济交易绝不会降低服务器的 TPS。
- ? 通用多核调度器 (
SchedulerService): 任务代码只需编写一次。Relay 将实体、坐标/区域、全局 tick 和异步任务自动路由至 Folia 的 EntityScheduler、RegionScheduler、GlobalRegionScheduler 和 AsyncScheduler 引擎;在 Paper 上则透明地回退至 BukkitScheduler。
- ? 微服务式 Pub/Sub & RPC 通信数据总线: 让您的插件完全独立。无需依赖彼此的
.jar 文件,即可订阅频道、发布消息或进行带超时保护的异步请求-响应(request)交互。
- ?️ 零内存泄漏保证: 当插件卸载或服务器重新加载时;打开的 hologram(全息显示)、虚拟箱子菜单、活跃的 BossBar、定时任务和冷却时间会自动从服务器中清理(
setPersistent(false))。
- ? 轻量级 API(约 80 KB): 不包含外部依赖或臃肿代码。添加到项目中后,仅提供轻量且类型安全的接口。
? 内部服务概览
Relay 在一个统一的框架下,完整提供了服务器及插件所需的 13 个核心子系统:
| 模块 / 服务 |
描述 |
主要特性 |
| ServiceRegistry |
响应式服务发现与注册表 |
HIGHEST ➔ FALLBACK 优先级阶梯,与加载顺序无关的 onServiceReady Promise 架构。 |
| RelayMessenger |
独立的 Pub/Sub 和 RPC 通信数据总线 |
插件无需依赖彼此的 .jar 文件即可订阅频道或进行异步请求-响应(request)。 |
| EconomyService |
多货币与经济引擎 |
使用 BigDecimal 算术运算防止 IEEE 754 浮点数错误,支持无限货币种类和原子化交易。 |
| CooldownService |
通用冷却管理器 |
为技能、法术和命令提供线程安全的冷却时间,支持 ActionBar 填充百分比(getProgress())和自动 TTL 清理。 |
| SharedDataService |
类型安全的共享数据池 |
通过 DataKey<T> 进行数据验证,支持临时数据(setTemporary)和响应式实时观察者(observe)。 |
| PermissionService |
异步权限与等级检查 |
异步权限查询避免 TPS 下降,兼容 LuckPerms/Vault,支持前缀和等级权重。 |
| PartyService |
队伍与友军伤害管理 |
战斗时无需冻结线程的零内存分配 isFriendlySync 检查,支持副本组队。 |
| MetricsService |
性能遥测与延迟警报 |
纳秒级精度计时,P50/P95/P99 百分位数,TPS 下降时自动触发 LagSpikeEvent 警报。 |
| HologramService |
基于 Display Entity 的全息引擎 |
采用 Minecraft 1.20+ TextDisplay 原生架构,零 ArmorStand 延迟,Folia region-safe spawnAsync,支持 MiniMessage 和阴影效果。 |
| MenuService |
Folia 安全的虚拟箱子 GUI 引擎 |
锁定顶部物品栏点击和拖拽以反作弊防复制,150ms 防宏去抖处理,支持分页功能。 |
| NotificationService |
多渠道玩家通知与反馈引擎 |
优先级排序的 ActionBar 队列,带动画倒计时的 BossBar,右上角虚拟 Toast 窗口和 Title 流式通知。 |
| SchedulerService |
通用 Folia & Paper 多核调度器 |
执行 Folia 实体、坐标/区域、全局和异步任务;支持 runAsyncPromise、线程验证和零泄漏的任务取消。 |
| ScoreboardService |
通用无抖动记分板与 Tab 列表引擎 |
每个玩家隔离的记分板,支持 1-15 行动态内容、Lambda 提供者、动画标题以及 Tab 列表页眉页脚。 |
?️ Folia 并行核心安全性与零泄漏架构
Relay 专为多线程 Minecraft 服务器软件 Folia 从零设计:
- 区域安全调度(Region-Safe Scheduling): 全息显示、定时任务、菜单、记分板和通知操作会自动分发到目标坐标或所属玩家的独立线程上。
- 无锁数据结构: 所有内部缓存均配备
ConcurrentHashMap、CopyOnWrite 和原子计数器;杜绝死锁现象。
- 零泄漏生命周期: 当插件卸载或服务器重新加载时,该插件关联的所有监听器、全息显示、定时任务、侧边栏、菜单、BossBar 和冷却时间都会自动从服务器中清理(
setPersistent(false))。
? 集成到您的项目(依赖项)
插件开发者仅需拉取轻量且无外部库依赖的 relay-api 模块(约 80 KB):
Gradle (Kotlin DSL)
repositories {
mavenCentral()
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.Kriscra.Relay:relay-api:v1.6.0")
}
Gradle (Groovy DSL)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.Kriscra.Relay:relay-api:v1.6.0'
}
Maven (pom.xml)
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.Kriscra.Relay</groupId>
<artifactId>relay-api</artifactId>
<version>v1.6.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
?️ 快速代码示例
1. 响应式服务发现 (onServiceReady)
无需担心加载顺序。即使相关插件在您之后加载,一旦服务被注册,回调函数就会立即触发:
RelayAPI.getServiceRegistry().onServiceReady(EconomyService.class, economy -> {
getLogger().info("经济系统已连接!货币单位: " + economy.getDefaultCurrency().displayName());
});
2. 插件间 Pub/Sub 与 RPC 通信
插件之间可以在不相互依赖 .jar 文件的情况下安全地进行通信:
// 消息发布插件:
RelayAPI.getMessenger().publish("klan:seviye_atlama", new KlanSeviyeVerisi("Valkyrie", 10), this);
// 消息订阅插件:
RelayAPI.getMessenger().subscribe("klan:seviye_atlama", KlanSeviyeVerisi.class, this, ctx -> {
getLogger().info(ctx.getPayload().klanAdi() + " 达到了新等级: " + ctx.getPayload().seviye());
});
// 非阻塞异步 RPC 请求-响应:
RelayAPI.getMessenger().request("klan:bakiye_sor", klanId, BigDecimal.class, Duration.ofSeconds(2))
.thenAccept(bakiye -> player.sendMessage("公会余额: " + bakiye));
3. TextDisplay 全息投影引擎 (Minecraft 1.20+ 原生)
无需使用 ArmorStand,即可在 Folia 区域线程中安全地创建零 FPS 损耗的全息投影:
Hologram hologram = RelayAPI.getHolograms().createBuilder(plugin, location)
.appendLine("<gradient:#4facfe:#00f2fe><bold>✦ RELAY NETWORK ✦</bold></gradient>")
.appendLine("<gray>TextDisplay & Folia 支持</gray>")
.setBillboard(Billboard.CENTER)
.setTextShadow(true)
.build();
hologram.spawnAsync();
4. Folia 安全虚拟储物柜 GUI (防刷 & 防宏)
Menu menu = RelayAPI.getMenus().createBuilder(plugin)
.titleMiniMessage("<green>传送门</green>")
.pattern(
"#########",
"# W #",
"#########"
)
.bindKey('#', MenuButton.of(new ItemStack(Material.BLACK_STAINED_GLASS_PANE)))
.bindKey('W', MenuButton.builder()
.item(new ItemStack(Material.COMPASS))
.sound(Sound.ENTITY_ENDERMAN_TELEPORT)
.debounce(250L) // 250ms 防宏延迟保护
.onClick(ctx -> ctx.getPlayer().teleportAsync(spawnLocation))
.build())
.build();
menu.open(player);
5. 多通道玩家通知(优先 ActionBar、BossBar 和 Toast)
// 优先级排序、不会覆盖其他消息的 ActionBar 队列:
RelayAPI.getNotifications().actionBar(player)
.messageMiniMessage("<gradient:#f12711:#f5af19><bold>警告:</bold> 已进入战斗区域!</gradient>")
.priority(NotificationPriority.HIGH)
.duration(Duration.ofSeconds(3))
.send(plugin);
// 带倒计时动画及 %time% / %progress% 标签的 BossBar:
ActiveBossBar bar = RelayAPI.getNotifications().bossBar(player)
.titleMiniMessage("<aqua>副本清理</aqua> <gray>(剩余: %time%s)</gray>")
.countdown(Duration.ofSeconds(30))
.color(BossBar.Color.BLUE)
.onComplete(() -> player.sendMessage("副本大门已封印!"))
.send(plugin);
// 右上角虚拟 Toast (成就) 通知:
RelayAPI.getNotifications().toast(player)
.titleMiniMessage("<gold>传奇任务!</gold>")
.descriptionMiniMessage("<gray>击败末影龙</gray>")
.icon(Material.DRAGON_HEAD)
.frame(ToastFrame.CHALLENGE)
.send(plugin);
6. 通用多线程调度器 (Folia & Paper)
在 Folia 区域线程 (Region)、全局 Tick 或异步线程池中,使用相同的代码安全地执行任务:
SchedulerService scheduler = RelayAPI.getScheduler();
// 在玩家所在的区域 (region) 线程中安全运行:
scheduler.runFor(plugin, player, () -> {
player.giveExp(100);
});
// 在特定世界坐标处周期性粒子效果任务:
RelayTask task = scheduler.runAtRepeating(plugin, targetLoc, t -> {
targetLoc.getWorld().spawnParticle(Particle.FLAME, targetLoc, 5);
}, 20L, 10L);
// 随时取消(或在插件关闭时交由 Relay 自动取消):
task.cancel();
// 非阻塞异步 Promise 流程:
scheduler.supplyAsyncPromise(() -> database.loadPlayerData(uuid))
.thenAccept(data -> scheduler.runFor(plugin, player, () -> player.sendMessage("已加载!")));
7. 无闪烁 Scoreboard & Tablist 引擎
包含动态标题、定期刷新和动态 Lambda 提供者的隔离计分板:
Sidebar sidebar = RelayAPI.getScoreboard().sidebarBuilder(plugin)
.titleMiniMessage("<gradient:#ff0844:#ffb199><bold>✦ RELAY RPG ✦</bold></gradient>")
.lineMiniMessage(1, "<gray>玩家: <white>" + player.getName())
.line(2, () -> Component.text("余额: " + economy.getBalance(player.getUniqueId())))
.lineMiniMessage(3, "<aqua>延迟: <green>" + player.getPing() + "ms")
.updateInterval(20L) // 每秒自动刷新动态行
.buildAndShow(player);
// 玩家 Tablist 顶部和底部信息:
RelayAPI.getScoreboard().setTablistMiniMessage(
player,
"<gradient:#4facfe:#00f2fe><bold>RELAY SERVER NETWORK</bold></gradient>\n<gray>在线玩家: 150</gray>",
"<gray>网站: www.example.com • Discord: /discord</gray>"
);
⚙️ 管理命令
实时监控服务器上的活跃服务、遥测数据、计划任务、计分板和会话状态:
/relay status: 显示活跃服务、主题、全息图、菜单、任务、记分板和工作区信息。
/relay services: 列出服务器上注册的所有服务及其优先级。
/relay topics: 列出活跃的 Pub/Sub 通信频道及监听器数量。
/relay metrics: 显示平均处理时间、P95 延迟和计数器。
/relay metrics reset: 重置所有遥测和性能计数器。
/relay holograms: 列出活跃的 TextDisplay 全息图及其位置。
/relay menus: 列出活跃的虚拟菜单会话及查看玩家数量。
/relay scoreboards: 列出活跃的虚拟记分板及观看玩家。
/relay notify <player> <actionbar|bossbar|toast|title> [message]: 向玩家发送测试通知。
权限: relay.admin (默认: OP)
? Links & Resources / 链接与资源
- ? Live Documentation / 在线文档:
- ? GitHub Repository:
- ? JitPack SDK:
- ? License / 许可证: MIT License
⚡ Relay
Industry-Standard Reactive Service Registry, Inter-Plugin Pub/Sub & Folia Multi-Thread Ecosystem Framework
Endüstri Standardı Reaktif Servis Kaydı, Eklentiler Arası İletişim (Pub/Sub) ve Çok Çekirdekli Folia Ekosistem Çatısı
?? English Documentation
•
?? Türkçe Dokümantasyon
?? English
? What is Relay?
Relay is an enterprise-grade, high-performance reactive service backbone, inter-plugin communication framework, and multi-threaded infrastructure engine designed for modern Minecraft servers running on Paper, Purpur, and multi-threaded Folia.
For years, Minecraft plugin architecture has remained shackled to single-threaded Bukkit conventions from 2012: synchronous main-thread stalls, fragile depend load-order chains in plugin.yml, incompatible Folia scheduler crashes, hacky ArmorStand holograms that destroy client FPS, and notorious memory leaks whenever a plugin reloads.
Relay completely redesigns server internals around 5 modern architectural pillars:
- ⚡ 100% Non-Blocking & Asynchronous Architecture: Built on Java 21
CompletableFuture promises, concurrent lock-free primitives, and nanosecond telemetry. Long database lookups, economy calculations, and permission queries never stall server ticks.
- ? Unified Multi-Thread Scheduler (
SchedulerService): Write your task logic once. Relay transparently routes entity, region, global, and async tasks to Folia's EntityScheduler, RegionScheduler, GlobalRegionScheduler, and AsyncScheduler, while seamlessly degrading to BukkitScheduler on Paper/Spigot.
- ? Microservice-Style Pub/Sub & RPC Event Bus: Decouple your plugins completely. Publish events across topics, subscribe typed payload consumers, or invoke time-bounded asynchronous request-response queries (
request) without direct .jar dependencies.
- ?️ Zero-Memory Leak Lifecycles: Automatic cleanup hooks unregister listeners, remove display entities, close active virtual menus, dismiss active bossbars, cancel running scheduled tasks, and evict stale cooldowns upon plugin disable (
setPersistent(false)).
- ? Ultra-Lightweight API (~80 KB): Zero transitive runtime dependencies. Your consumer plugins stay clean, fast, and featherweight.
? Built-in Services (Overview)
Relay unifies 13 essential server subsystems into a clean, lightweight API:
| Service / Subsystem |
Description |
Key Features |
| ServiceRegistry |
Reactive service discovery & provider registry |
Priority tiers (HIGHEST ➔ FALLBACK), load-order independent onServiceReady Promise callbacks. |
| RelayMessenger |
Decoupled Pub/Sub event bus & async RPC |
Inter-plugin messaging without jar dependencies; publish topics, subscribe listeners, and await async responses. |
| EconomyService |
Multi-currency financial ledger engine |
IEEE 754 float-safe BigDecimal arithmetic, arbitrary currency registration, atomic transfers. |
| CooldownService |
Universal time-to-live cooldown manager |
Thread-safe cooldowns for spells, skills, and commands; action bar completion percentage (getProgress()), auto-TTL eviction. |
| SharedDataService |
Type-safe shared reactive data store |
Strongly-typed DataKey<T> validation, temporary TTL key expiration, live change observers (observe). |
| PermissionService |
Asynchronous permission & group checking |
Non-blocking group and permission queries to safeguard server tick performance, LuckPerms/Vault bridge, weight ranking. |
| PartyService |
Team, party & friendly-fire manager |
Allocation-free, lockless isFriendlySync verification for combat engines, dungeon parties, and shared loot. |
| MetricsService |
Performance telemetry & lag spike alerts |
Nanosecond-resolution timers, P50/P95/P99 latency percentiles, automatic LagSpikeEvent dispatch upon tick drops. |
| HologramService |
Display Entity based holographic billboard engine |
Minecraft 1.20+ native TextDisplay entities, zero ArmorStand lag, Folia region-safe spawnAsync, MiniMessage text and shadows. |
| MenuService |
Virtual chest inventory & GUI engine |
Folia thread-safe opening, strict anti-duplication cancellation, 150ms anti-macro debounce, paginated menus (PaginatedMenu<T>). |
| NotificationService |
Multi-channel player feedback & display engine |
Priority-based queued ActionBars, animated countdown BossBars, virtual top-right Toasts, and smooth Title sequences. |
| SchedulerService |
Unified Folia & Paper multi-thread scheduler |
Universal entity, location/region, global, and async scheduling; runAsyncPromise, thread verification, zero-leak task auto-cancel. |
| ScoreboardService |
Universal flicker-free scoreboard & tablist engine |
Per-player isolated scoreboards, 1-15 dynamic lines, lambda suppliers, animated title frames, tablist header/footers. |
?️ Folia Multi-Threading & Zero-Leak Architecture
Relay was architected from the ground up for multi-threaded servers:
- Region-Safe Scheduling: World entity mutations (such as
TextDisplay holograms), scheduled tasks, scoreboard views, and inventory views are dispatched via Folia's RegionScheduler or EntityScheduler.
- Lock-Free Concurrency: All internal registries utilize
ConcurrentHashMap, CopyOnWriteArrayList, and AtomicReference constructs to guarantee deterministic execution without thread contention or deadlocks.
- Persistent Auto-Cleanup: All spawned entities have
setPersistent(false) enabled. When a consumer plugin unloads, Relay automatically purges its associated subscribers, holograms, bossbars, scheduled tasks, sidebars, and GUI sessions.
? Adding to Your Project (Dependency)
Plugin developers only need to compile against the featherweight relay-api (~80 KB, zero transitive runtime bloat):
Gradle (Kotlin DSL)
repositories {
mavenCentral()
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.Kriscra.Relay:relay-api:v1.6.0")
}
Gradle (Groovy DSL)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.Kriscra.Relay:relay-api:v1.6.0'
}
Maven (pom.xml)
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.Kriscra.Relay</groupId>
<artifactId>relay-api</artifactId>
<version>v1.6.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
?️ Quick Code Examples
1. Reactive Service Discovery (onServiceReady)
Never worry about loadbefore or depend ordering again. Receive the service instance the moment it gets registered:
RelayAPI.getServiceRegistry().onServiceReady(EconomyService.class, economy -> {
getLogger().info("Economy hooked! Default currency: " + economy.getDefaultCurrency().displayName());
});
2. Inter-Plugin Pub/Sub & RPC Messaging
Enable seamless cross-plugin communication without direct .jar dependencies:
// Publisher Plugin:
RelayAPI.getMessenger().publish("guild:levelup", new GuildLevelPayload("Valkyrie", 10), this);
// Subscriber Plugin:
RelayAPI.getMessenger().subscribe("guild:levelup", GuildLevelPayload.class, this, ctx -> {
getLogger().info(ctx.getPayload().guildName() + " has reached level " + ctx.getPayload().level());
});
// Non-blocking RPC Request/Response:
RelayAPI.getMessenger().request("guild:get_balance", guildId, BigDecimal.class, Duration.ofSeconds(2))
.thenAccept(balance -> player.sendMessage("Guild Balance: " + balance));
3. TextDisplay Holograms (Minecraft 1.20+ Native)
Create lag-free text displays using Minecraft 1.20+ Display Entities:
Hologram hologram = RelayAPI.getHolograms().createBuilder(plugin, location)
.appendLine("<gradient:#4facfe:#00f2fe><bold>✦ RELAY NETWORK ✦</bold></gradient>")
.appendLine("<gray>Powered by TextDisplay & Folia</gray>")
.setBillboard(Billboard.CENTER)
.setTextShadow(true)
.build();
hologram.spawnAsync();
4. Folia-Safe Chest GUI (Anti-Dupe & Debounce)
Menu menu = RelayAPI.getMenus().createBuilder(plugin)
.titleMiniMessage("<green>Teleportation Portal</green>")
.pattern(
"#########",
"# W #",
"#########"
)
.bindKey('#', MenuButton.of(new ItemStack(Material.BLACK_STAINED_GLASS_PANE)))
.bindKey('W', MenuButton.builder()
.item(new ItemStack(Material.COMPASS))
.sound(Sound.ENTITY_ENDERMAN_TELEPORT)
.debounce(250L) // 250ms anti-macro debounce
.onClick(ctx -> ctx.getPlayer().teleportAsync(spawnLocation))
.build())
.build();
menu.open(player);
5. Multi-Channel Notifications (Priority ActionBar, BossBar & Toast)
// Priority-queued ActionBar with preemption:
RelayAPI.getNotifications().actionBar(player)
.messageMiniMessage("<gradient:#f12711:#f5af19><bold>WARNING:</bold> Combat Zone Entered!</gradient>")
.priority(NotificationPriority.HIGH)
.duration(Duration.ofSeconds(3))
.send(plugin);
// Animated Countdown BossBar with placeholders %time% and %progress%:
ActiveBossBar bar = RelayAPI.getNotifications().bossBar(player)
.titleMiniMessage("<aqua>Dungeon Cleansing</aqua> <gray>(%time%s left)</gray>")
.countdown(Duration.ofSeconds(30))
.color(BossBar.Color.BLUE)
.onComplete(() -> player.sendMessage("Dungeon sealed!"))
.send(plugin);
// Virtual Top-Right Toast Popup:
RelayAPI.getNotifications().toast(player)
.titleMiniMessage("<gold>Mythic Quest Complete!</gold>")
.descriptionMiniMessage("<gray>Defeat the Ender Dragon</gray>")
.icon(Material.DRAGON_HEAD)
.frame(ToastFrame.CHALLENGE)
.send(plugin);
6. Unified Multi-Thread Scheduler (Folia & Paper)
Run tasks on entity region threads, global ticks, or async pools with identical code across Paper and Folia:
SchedulerService scheduler = RelayAPI.getScheduler();
// Run safely on player's regional thread:
scheduler.runFor(plugin, player, () -> {
player.giveExp(100);
});
// Run repeating particle task at world coordinates:
RelayTask task = scheduler.runAtRepeating(plugin, targetLoc, t -> {
targetLoc.getWorld().spawnParticle(Particle.FLAME, targetLoc, 5);
}, 20L, 10L);
// Cancel anytime (or let Relay auto-cancel upon plugin disable):
task.cancel();
// Non-blocking async promise execution:
scheduler.supplyAsyncPromise(() -> database.loadPlayerData(uuid))
.thenAccept(data -> scheduler.runFor(plugin, player, () -> player.sendMessage("Loaded!")));
7. Flicker-Free Scoreboard & Tablist Engine
Create per-player isolated sidebars with dynamic line suppliers and animated titles:
Sidebar sidebar = RelayAPI.getScoreboard().sidebarBuilder(plugin)
.titleMiniMessage("<gradient:#ff0844:#ffb199><bold>✦ RELAY RPG ✦</bold></gradient>")
.lineMiniMessage(1, "<gray>Player: <white>" + player.getName())
.line(2, () -> Component.text("Coins: " + economy.getBalance(player.getUniqueId())))
.lineMiniMessage(3, "<aqua>Ping: <green>" + player.getPing() + "ms")
.updateInterval(20L) // Auto-refresh dynamic lines every second
.buildAndShow(player);
// Per-player animated tablist header and footer:
RelayAPI.getScoreboard().setTablistMiniMessage(
player,
"<gradient:#4facfe:#00f2fe><bold>RELAY SERVER NETWORK</bold></gradient>\n<gray>Online Players: 150</gray>",
"<gray>Store: store.example.com • Discord: /discord</gray>"
);
⚙️ Administration & Diagnostics
Monitor active services, topics, telemetry, open sessions, scheduled tasks, and test notifications in real time:
/relay status: Overview of loaded services, topics, active holograms, menus, tasks, sidebars, and server runtime environment.
/relay services: Lists all registered services, provider plugins, and priority tiers.
/relay topics: Inspects active pub/sub topics and subscriber counts.
/relay metrics: Live execution averages, P95 latencies, and transaction counters.
/relay metrics reset: Resets all active telemetry samples and metrics counters.
/relay holograms: Inspects currently tracked TextDisplay holograms and their world locations.
/relay menus: Lists active virtual inventory sessions and viewing players.
/relay scoreboards: Lists all active sidebars and their viewing players.
/relay notify <player> <actionbar|bossbar|toast|title> [message]: Dispatches real-time test notifications to an online player.
Permission: relay.admin (Default: OP)
?? Türkçe
? Relay Nedir?
Relay, modern Minecraft sunucularında (Paper, Purpur ve özellikle çok çekirdekli Folia) eklentiler arası entegrasyonu, veri iletişimini ve sunucu servislerini endüstri standartlarına taşıyan kurumsal düzeyde açık kaynaklı bir altyapı motorudur.
Yıllardır Minecraft eklenti mimarisi 2012'den kalma tek çekirdekli Bukkit alışkanlıklarına takılı kalmıştır: Ana iş parçacığını (Main Thread) kilitleyen senkron veritabanı/ekonomi sorguları, plugin.yml içerisindeki kırılgan depend: yüklenme sırası çakışmaları, Folia üzerinde çöken klasik zamanlayıcılar, sunucu performansını yok eden ArmorStand hologramları ve eklenti yeniden yüklendiğinde arkasında zombi nesneler bırakan bellek sızıntıları.
Relay, sunucu mimarisini 5 temel sütun üzerinde yeniden inşa eder:
- ⚡ %100 Non-Blocking & Asenkron Mimari: Java 21
CompletableFuture promise zincirleri, kilit-içermeyen (lock-free) eşzamanlı veri yapıları ve nanosaniye hassasiyetli telemetri. Veritabanı sorguları ve ekonomi transferleri sunucu TPS'ini asla düşürmez.
- ? Evrensel Çok Çekirdekli Zamanlayıcı (
SchedulerService): Görev kodunuzu tek sefer yazın. Relay; varlık, koordinat/bölge, küresel tick ve asenkron görevleri Folia'nın EntityScheduler, RegionScheduler, GlobalRegionScheduler ve AsyncScheduler motorlarına yönlendirirken, Paper üzerinde otomatik olarak BukkitScheduler'a şeffaf düşer.
- ? Mikroservis Tipi Pub/Sub & RPC İletişim Veri Yolu: Eklentilerinizi birbirinden tamamen bağımsız hale getirin. Birbirlerinin
.jar dosyasına ihtiyaç duymadan kanallara abone olun, mesaj yayınlayın veya zaman aşımı korumalı asenkron soru-cevap (request) yapın.
- ?️ Sıfır Bellek Sızıntısı (Zero-Leak) Garantisi: Bir eklenti kapandığında veya sunucu yeniden yüklendiğinde; açılan hologramlar, sanal sandık menüleri, aktif BossBar'lar, zamanlanmış görevler ve bekleme süreleri sunucudan otomatik olarak tahliye edilir (
setPersistent(false)).
- ? Tüy Siklet API (~80 KB): Harici bağımlılık veya şişkinlik içermez. Projenize eklediğinizde sadece hafif ve tip-güvenli arayüzler sunar.
? Dahili Servisler (Genel Bakış)
Relay, bir sunucunun ve eklentilerin ihtiyaç duyduğu 13 temel alt sistemi tek bir çatı altında eksiksiz sunar:
| Modül / Servis |
Açıklama |
Öne Çıkan Özellikler |
| ServiceRegistry |
Reaktif servis keşfi ve kayıt defteri |
HIGHEST ➔ FALLBACK öncelik basamakları, yüklenme sırasından bağımsız onServiceReady Promise mimarisi. |
| RelayMessenger |
Bağımsız Pub/Sub ve RPC iletişim veri yolu |
Eklentiler birbirinin .jar dosyasına bağımlı olmadan kanallara abone olabilir veya asenkron istek-cevap (request) yapabilir. |
| EconomyService |
Çoklu para birimi ve finans motoru |
IEEE 754 kayan noktalı sayı hatalarını önleyen BigDecimal aritmetiği, sınırsız para birimi, atomik transferler. |
| CooldownService |
Evrensel bekleme süresi yöneticisi |
Yetenek, büyü ve komutlar için thread-safe bekleme süreleri, ActionBar dolum yüzdesi (getProgress()), otomatik TTL tahliyesi. |
| SharedDataService |
Tip güvenli paylaşımlı veri havuzu |
DataKey<T> ile veri doğrulama, süreli geçici veriler (setTemporary), reaktif canlı gözlemciler (observe). |
| PermissionService |
Asenkron yetki ve rütbe kontrolü |
TPS düşüşlerini engelleyen asenkron yetki sorgulama, LuckPerms/Vault uyumluluğu, ön ek ve rütbe ağırlığı. |
| PartyService |
Takım ve dost ateşi yöneticisi |
Combat anında thread dondurmayan sıfır-bellek tahsisli isFriendlySync kontrolleri, zindan grupları. |
| MetricsService |
Performans telemetrisi & lag alarmı |
Nanosaniye hassasiyetinde süre ölçümü, P50/P95/P99 yüzdelikleri, TPS düşüşlerinde otomatik LagSpikeEvent alarmı. |
| HologramService |
Display Entity tabanlı hologram motoru |
Minecraft 1.20+ TextDisplay native mimarisi, sıfır ArmorStand lag, Folia region-safe spawnAsync, MiniMessage ve gölge. |
| MenuService |
Folia güvenli sanal sandık GUI motoru |
Üst envanter tıklamalarını ve sürüklemelerini kilitleyen anti-dupe koruması, 150ms anti-macro debounce, sayfalama (pagination). |
| NotificationService |
Çok kanallı oyuncu bildirim & geri bildirim motoru |
Öncelik sıralı ActionBar kuyruğu, animasyonlu geri sayımlı BossBar, sağ üst sanal Toast kutucukları ve Title akışları. |
| SchedulerService |
Evrensel Folia & Paper çok çekirdekli zamanlayıcı |
Folia varlık, koordinat/bölge, global ve asenkron görev çalıştırma; runAsyncPromise, thread doğrulama, sıfır sızıntılı görev iptali. |
| ScoreboardService |
Evrensel titreşimsiz scoreboard & tablist motoru |
Oyuncu başına izole scoreboard, 1-15 dinamik satır, lambda sağlayıcıları, animasyonlu başlık, tablist üst/alt bilgi. |
?️ Folia Paralel Çekirdek Güvenliği & Sıfır Sızıntı Mimarisi
Relay, çok çekirdekli Minecraft sunucu yazılımı Folia için sıfırdan tasarlanmıştır:
- Region-Safe Scheduling: Hologram, zamanlanmış görevler, menü, scoreboard ve bildirim işlemleri, hedef koordinatın veya oyuncunun ait olduğu bağımsız iş parçacığına otomatik iletilir.
- Lock-Free Veri Yapıları: Tüm dahili önbellekler
ConcurrentHashMap, CopyOnWrite ve atomik sayaçlar ile donatılmıştır; kilitlenme (deadlock) yaşanmaz.
- Zero-Leak Yaşam Döngüsü: Bir eklenti kapandığında veya sunucu yeniden yüklendiğinde, o eklentiye ait tüm dinleyiciler, hologramlar, zamanlanmış görevler, sidebarlar, menüler, BossBar'lar ve bekleme süreleri sunucudan otomatik tahliye edilir (
setPersistent(false)).
? Projenize Dahil Edin (Bağımlılık)
Eklenti geliştiricileri yalnızca hafif, harici kütüphane içermeyen relay-api modülünü çeker (~80 KB):
Gradle (Kotlin DSL)
repositories {
mavenCentral()
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.Kriscra.Relay:relay-api:v1.6.0")
}
Gradle (Groovy DSL)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.Kriscra.Relay:relay-api:v1.6.0'
}
Maven (pom.xml)
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.Kriscra.Relay</groupId>
<artifactId>relay-api</artifactId>
<version>v1.6.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
?️ Hızlı Kod Örnekleri
1. Reaktif Servis Keşfi (onServiceReady)
Yüklenme sırasını dert etmeyin. İlgili eklenti sizden sonra yüklense bile servis kaydedildiği anda geri çağrılır:
RelayAPI.getServiceRegistry().onServiceReady(EconomyService.class, economy -> {
getLogger().info("Ekonomi sistemi bağlandı! Para birimi: " + economy.getDefaultCurrency().displayName());
});
2. Eklentiler Arası Pub/Sub ve RPC İletişimi
Eklentiler birbirinin .jar dosyasına bağımlı olmadan güvenle haberleşir:
// Mesaj Yayınlayan Eklenti:
RelayAPI.getMessenger().publish("klan:seviye_atlama", new KlanSeviyeVerisi("Valkyrie", 10), this);
// Dinleyen Eklenti:
RelayAPI.getMessenger().subscribe("klan:seviye_atlama", KlanSeviyeVerisi.class, this, ctx -> {
getLogger().info(ctx.getPayload().klanAdi() + " yeni seviyeye ulaştı: " + ctx.getPayload().seviye());
});
// Non-blocking Asenkron RPC İstek-Cevap:
RelayAPI.getMessenger().request("klan:bakiye_sor", klanId, BigDecimal.class, Duration.ofSeconds(2))
.thenAccept(bakiye -> player.sendMessage("Klan Bakiyesi: " + bakiye));
3. TextDisplay Hologram Motoru (Minecraft 1.20+ Native)
ArmorStand kullanmadan, sıfır FPS kaybı ile Folia bölgesel iş parçacığında güvenli hologramlar oluşturun:
Hologram hologram = RelayAPI.getHolograms().createBuilder(plugin, location)
.appendLine("<gradient:#4facfe:#00f2fe><bold>✦ RELAY NETWORK ✦</bold></gradient>")
.appendLine("<gray>TextDisplay & Folia Destekli</gray>")
.setBillboard(Billboard.CENTER)
.setTextShadow(true)
.build();
hologram.spawnAsync();
4. Folia Güvenli Sanal Sandık GUI (Anti-Dupe & Anti-Macro)
Menu menu = RelayAPI.getMenus().createBuilder(plugin)
.titleMiniMessage("<green>Işınlanma Kapısı</green>")
.pattern(
"#########",
"# W #",
"#########"
)
.bindKey('#', MenuButton.of(new ItemStack(Material.BLACK_STAINED_GLASS_PANE)))
.bindKey('W', MenuButton.builder()
.item(new ItemStack(Material.COMPASS))
.sound(Sound.ENTITY_ENDERMAN_TELEPORT)
.debounce(250L) // 250ms anti-macro debounce koruması
.onClick(ctx -> ctx.getPlayer().teleportAsync(spawnLocation))
.build())
.build();
menu.open(player);
5. Çok Kanallı Oyuncu Bildirimleri (Öncelikli ActionBar, BossBar & Toast)
// Öncelik sıralı, diğer mesajları ezmeyen ActionBar kuyruğu:
RelayAPI.getNotifications().actionBar(player)
.messageMiniMessage("<gradient:#f12711:#f5af19><bold>UYARI:</bold> Savaş Bölgesine Girildi!</gradient>")
.priority(NotificationPriority.HIGH)
.duration(Duration.ofSeconds(3))
.send(plugin);
// Animasyonlu geri sayımlı ve %time% / %progress% etiketli BossBar:
ActiveBossBar bar = RelayAPI.getNotifications().bossBar(player)
.titleMiniMessage("<aqua>Zindan Temizliği</aqua> <gray>(Kalan: %time%s)</gray>")
.countdown(Duration.ofSeconds(30))
.color(BossBar.Color.BLUE)
.onComplete(() -> player.sendMessage("Zindan kapıları mühürlendi!"))
.send(plugin);
// Sağ Üst Sanal Toast (Advancement) Bildirimi:
RelayAPI.getNotifications().toast(player)
.titleMiniMessage("<gold>Efsanevi Görev!</gold>")
.descriptionMiniMessage("<gray>Ender Ejderhasını alt et</gray>")
.icon(Material.DRAGON_HEAD)
.frame(ToastFrame.CHALLENGE)
.send(plugin);
6. Evrensel Çok Çekirdekli Zamanlayıcı (Folia & Paper)
Folia bölgesel iş parçacıkları (Region), global tick veya asenkron havuzlarda aynı kodla güvenle görev çalıştırın:
SchedulerService scheduler = RelayAPI.getScheduler();
// Oyuncunun bulunduğu bölgesel (region) iş parçacığında güvenle çalıştır:
scheduler.runFor(plugin, player, () -> {
player.giveExp(100);
});
// Belirli bir dünya koordinatında periyodik parçacık efekti görevi:
RelayTask task = scheduler.runAtRepeating(plugin, targetLoc, t -> {
targetLoc.getWorld().spawnParticle(Particle.FLAME, targetLoc, 5);
}, 20L, 10L);
// İstediğiniz an iptal edin (veya eklenti kapandığında Relay'in otomatik iptal etmesine bırakın):
task.cancel();
// Non-blocking asenkron promise akışı:
scheduler.supplyAsyncPromise(() -> database.loadPlayerData(uuid))
.thenAccept(data -> scheduler.runFor(plugin, player, () -> player.sendMessage("Yüklendi!")));
7. Titreşimsiz Scoreboard & Tablist Motoru
Animasyonlu başlıklar, periyodik yenileme ve dinamik lambda sağlayıcıları içeren izole scoreboard:
Sidebar sidebar = RelayAPI.getScoreboard().sidebarBuilder(plugin)
.titleMiniMessage("<gradient:#ff0844:#ffb199><bold>✦ RELAY RPG ✦</bold></gradient>")
.lineMiniMessage(1, "<gray>Oyuncu: <white>" + player.getName())
.line(2, () -> Component.text("Bakiye: " + economy.getBalance(player.getUniqueId())))
.lineMiniMessage(3, "<aqua>Gecikme: <green>" + player.getPing() + "ms")
.updateInterval(20L) // Dinamik satırları saniyede bir otomatik yenile
.buildAndShow(player);
// Oyuncu tablist üst ve alt bilgi mesajları:
RelayAPI.getScoreboard().setTablistMiniMessage(
player,
"<gradient:#4facfe:#00f2fe><bold>RELAY SERVER NETWORK</bold></gradient>\n<gray>Aktif Oyuncular: 150</gray>",
"<gray>Web: www.example.com • Discord: /discord</gray>"
);
⚙️ Yönetici Komutları
Sunucudaki aktif servisleri, telemetriyi, zamanlanmış görevleri, scoreboard'ları ve oturumları anlık izleyin:
/relay status: Aktif servis, konu, hologram, menü, görev, scoreboard ve çalışma ortamı bilgilerini gösterir.
/relay services: Sunucuda kayıtlı tüm servisleri ve öncelik derecelerini listeler.
/relay topics: Aktif Pub/Sub iletişim kanallarını ve dinleyici sayılarını listeler.
/relay metrics: Ortalama işlem sürelerini, P95 gecikmelerini ve sayaçları gösterir.
/relay metrics reset: Tüm telemetri ve performans sayaçlarını sıfırlar.
/relay holograms: Aktif TextDisplay hologramlarını ve konumlarını listeler.
/relay menus: Aktif sanal menü oturumlarını ve görüntüleyen oyuncu sayılarını listeler.
/relay scoreboards: Aktif sanal scoreboard'ları ve izleyen oyuncuları listeler.
/relay notify <oyuncu> <actionbar|bossbar|toast|title> [mesaj]: Oyuncuya test bildirimi gönderir.
Yetki: relay.admin (Varsayılan: OP)
? Links & Resources / Bağlantılar
- ? Live Documentation / Canlı Dokümantasyon:
- ? GitHub Repository:
- ? JitPack SDK:
- ? License / Lisans: MIT License
评论 0
登录后参与评分
还没有评论,来抢沙发吧