TickBudget
为 Paper 和 Folia 插件共享的刻时预算。插件将耗时任务拆分为小片段执行,TickBudget 会在它们之间分配可用的毫秒数。
TickBudget 是一个库插件。在没有其他插件调用它之前,它自身不会执行任何操作,但它为管理员提供了一个命令,用于显示各插件消耗的刻时间比例。
服务器所有者须知
如果您运行的某个插件将 TickBudget 列为依赖项,请将 jar 文件放入 plugins/ 目录并重启服务器。无需进行额外配置。默认设置适用于大多数服务器。
- 单插件刻时使用情况 -
/tickbudget status 显示每个插件在过去 60 秒内的 CPU 时间,以及自启动以来完成的步骤、延迟的刻数和线程违规情况。
- 顶级任务 -
/tickbudget top 按总 CPU 时间列出正在运行的任务。
- 公平共享 - 每个插件在每个刻中都获得保证的最小时间配额。剩余的可用时间则根据任务优先级进行分配,因此单个插件无法占用整个刻的时间。
- Paper 和 Folia - 插件在启动时检测平台,并使用相应的调度器。
需要 Java 21。已在 Paper 1.21 至 26.3 以及从 1.21.4 到 26.2 的所有 Folia 构建版本上测试通过。
命令
所有命令均使用权限 tickbudget.admin,默认情况下操作员拥有此权限。
/tickbudget status 平台、活动任务计数及单插件使用情况
/tickbudget top 按 CPU 时间排序的运行中任务
/tickbudget debug <on|off> 当任务触及错误线程时记录详细信息
/tickbudget reload 重载 config.yml
配置文件
# 每个刻中留给服务器自身的未使用剩余时间(毫秒)
safety-margin-ms: 5.0
# 每个活跃插件在每个刻中获得的最小时间配额(毫秒)
floor-budget-ms: 0.5
# 未自行设置预算的任务的预算(毫秒)
default-task-budget-ms: 1.0
# 任何任务在每个刻中可使用的最大预算,包括 CRITICAL(毫秒)
max-task-budget-ms: 20.0
# 按任务优先级的自由时间分配比例
priority-weights:
low: 1
normal: 2
high: 4
critical: 8
debug: false
# 通过 bStats 进行的匿名使用统计
metrics: true
插件开发者指南
一个任务被拆分为多个步骤。TickBudget 在每个刻中运行尽可能多的步骤以符合预算,并在下一个刻继续执行。
TickBudget tb = TickBudget.of(plugin);
tb.run(Target.region(location), BudgetedTask.iterate(blocks, block -> block.setType(Material.AIR)))
.name("clear-ruins")
.budget(Budget.millisPerTick(1.5))
.priority(Priority.NORMAL)
.onComplete(() -> plugin.getLogger().info("Done"))
.onError(error -> plugin.getLogger().severe(error.getMessage()))
.start();
一个步骤返回 MORE(如果预算允许则继续)、YIELD(本刻不再执行更多操作,稍后继续)或 DONE。对于长期存在且偶尔队列为空的消费者工作线程,应在空闲时返回 YIELD,这样它们每个刻只消耗一个廉价步骤的成本,而不是耗尽整个预算。
- 目标范围 -
Target.global()、Target.region(location)、Target.entity(entity) 和 Target.async()。在 Folia 上,每种类型都映射到相应的调度器。在 Paper 上,global、region 和 entity 在主线程上运行,而 async 则在非主线程上运行。
- 线程检查 - 如果当前线程不拥有该目标,
tb.assertOn(target) 将抛出异常。
- 异步区块加载 -
tb.chunks().loadAsync(world, x, z) 在不阻塞的情况下加载区块。
通过 JitPack 添加 API,请勿对其进行阴影打包(shade):
repositories { maven("https://jitpack.io") }
dependencies { compileOnly("com.github.denfry:tickbudget:v0.3.0") }
然后在您的 plugin.yml 中添加 depend: [TickBudget],或者如果您的插件应在没有它也能运行时,添加 softdepend: [TickBudget] 并提供备用计时器。README 中有一个现成的备用类。API jar 文件也附带在每一个 GitHub Release 中。
统计数据
TickBudget 向 bStats 报告匿名统计数据(服务器平台、使用该插件的插件数量、活动任务数量)。在 config.yml 中设置 metrics: false 即可关闭此功能。
链接
依据 MIT 许可证发布。
TickBudget
A shared tick-time budget for Paper and Folia plugins. Plugins run long jobs in small slices, and TickBudget divides the available milliseconds between them.
TickBudget is a library plugin. It does nothing on its own until another plugin uses it, but it gives admins a command that shows which plugin spends how much tick time.
For server owners
If a plugin you run lists TickBudget as a dependency, drop the jar into plugins/ and restart. There is nothing to set up. The defaults work for most servers.
- Per-plugin tick usage -
/tickbudget status shows each plugin's CPU time over the last 60 seconds, plus completed steps, deferred ticks and thread violations since startup.
- Top tasks -
/tickbudget top lists running tasks by total CPU time.
- Fair sharing - each plugin gets a guaranteed minimum per tick. The rest of the free time is split by task priority, so one plugin cannot use up the whole tick.
- Paper and Folia - the plugin detects the platform at startup and uses the matching scheduler.
Requires Java 21. Tested on Paper 1.21 to 26.3 and on every Folia build from 1.21.4 to 26.2.
Commands
Everything uses the permission tickbudget.admin, which operators have by default.
/tickbudget status Platform, active task count and per-plugin usage
/tickbudget top Running tasks sorted by CPU time
/tickbudget debug <on|off> Log details when a task touches the wrong thread
/tickbudget reload Reload config.yml
Configuration
# Time left unused in each tick for the server itself (ms)
safety-margin-ms: 5.0
# Minimum time each active plugin gets per tick (ms)
floor-budget-ms: 0.5
# Budget for tasks that do not set their own (ms)
default-task-budget-ms: 1.0
# Largest budget any task may use per tick, CRITICAL included (ms)
max-task-budget-ms: 20.0
# Share of the free time by task priority
priority-weights:
low: 1
normal: 2
high: 4
critical: 8
debug: false
# Anonymous usage statistics through bStats
metrics: true
For plugin developers
A task is split into steps. TickBudget runs as many steps as fit into the budget each tick and continues on the next tick.
TickBudget tb = TickBudget.of(plugin);
tb.run(Target.region(location), BudgetedTask.iterate(blocks, block -> block.setType(Material.AIR)))
.name("clear-ruins")
.budget(Budget.millisPerTick(1.5))
.priority(Priority.NORMAL)
.onComplete(() -> plugin.getLogger().info("Done"))
.onError(error -> plugin.getLogger().severe(error.getMessage()))
.start();
A step returns MORE (keep going if the budget allows), YIELD (nothing more this tick, continue later) or DONE. Long-lived workers that drain a sometimes-empty queue should return YIELD when idle, so they cost one cheap step per tick instead of their whole budget.
- Targets -
Target.global(), Target.region(location), Target.entity(entity) and Target.async(). On Folia each one maps to the matching scheduler. On Paper, global, region and entity run on the main thread and async runs off it.
- Thread checks -
tb.assertOn(target) throws if the current thread does not own the target.
- Async chunks -
tb.chunks().loadAsync(world, x, z) loads a chunk without blocking.
Add the API through JitPack and do not shade it:
repositories { maven("https://jitpack.io") }
dependencies { compileOnly("com.github.denfry:tickbudget:v0.3.0") }
Then add depend: [TickBudget] to your plugin.yml, or softdepend: [TickBudget] with a fallback timer if your plugin should also run without it. The README has a ready-made fallback class. The API jar is also attached to every GitHub release.
Metrics
TickBudget reports anonymous statistics (server platform, number of plugins using it, number of active tasks) to bStats. Set metrics: false in config.yml to turn it off.
Links
Released under the MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧