PlayerTimer Fabric
一个为 Minecraft 服务器和单人世界提供独立玩家计时器的 Fabric 模组。
当前 Fabric 构建版本:
- Minecraft
26.2
- Fabric Loader
0.19.3 或更高版本
- Fabric API
0.153.0+26.2
- Java 25 或更高版本
每位玩家拥有独立的计时器,支持以下功能:
- 正数计数
- 倒序计数
- 暂停/恢复
- 独立隐藏或显示
- 通过命令或命令方块触发
适用场景:
- 小游戏
- 密室逃脱
- 限时挑战
- 跑酷
- 速通
- 多人活动
- 冒险地图
功能特性
- 每位玩家独立的计时器
- 正数和倒数模式
- Brigadier 命令支持
- 暂停和恢复支持
- 计时器可见性控制
- 倒计时完成通知
- 完成时音效反馈
- 多种时长输入格式
- 兼容使用
/execute as 的命令方块
- 用于管理计时器的管理员命令
- 重启和崩溃后计时器数据持久化
- 专为 Fabric 打造
- 支持 Java 25
命令
| 命令 |
描述 |
/playertimer startcountup |
使用配置的默认颜色开始正数计时 |
/playertimer startcountup <color> |
开始彩色正数计时 |
/playertimer startcountdown |
使用配置的默认颜色开始 5 分钟倒计时 |
/playertimer startcountdown <duration> |
使用配置的默认颜色开始自定义时长的倒计时 |
/playertimer startcountdown <duration> <color> |
开始彩色倒计时 |
/playertimer pause |
暂停计时器 |
/playertimer resume |
恢复已暂停的计时器 |
/playertimer stop |
停止计时器并将其重置为 00:00 |
/playertimer reset |
将计时器重置为 00:00 |
/playertimer hide |
隐藏计时器显示 |
/playertimer show |
显示计时器显示 |
/playertimer admin clear <player> |
清除玩家 <player> 的计时器(需要 op 等级 2+) |
/playertimer admin clearall |
清除所有玩家的计时器(需要 op 等级 2+) |
时长格式
倒计时命令接受多种输入格式。
1. 秒数
/playertimer startcountdown 300
开始 300 秒倒计时。
2. 分:秒 (mm:ss)
/playertimer startcountdown 05:30
开始 5 分 30 秒倒计时。
规则:
mm 必须在 0 到 59 之间
ss 必须在 0 到 59 之间
示例:
05:30 ✓ 有效
59:59 ✓ 有效
60:00 ✗ 无效
05:60 ✗ 无效
99:99 ✗ 无效
3. 时:分:秒 (hh:mm:ss)
/playertimer startcountdown 01:40:05
开始 1 小时 40 分 5 秒倒计时。
规则:
mm 必须在 0 到 59 之间
ss 必须在 0 到 59 之间
示例:
01:40:05 ✓ 有效
10:59:59 ✓ 有效
01:60:05 ✗ 无效
01:40:60 ✗ 无效
4. 文本格式
/playertimer startcountdown 1h40m5s
/playertimer startcountdown 10m
/playertimer startcountdown 45s
/playertimer startcountdown 2h
/playertimer startcountdown 1h5s
支持:
可以任意组合使用。
规则:
m 必须在 0 到 59 之间
s 必须在 0 到 59 之间
示例:
1h40m5s ✓ 有效
10m30s ✓ 有效
59m59s ✓ 有效
1h60m ✗ 无效
10m90s ✗ 无效
10s49m ✗ 无效
最大时长
允许的最大时长为:
2147483647 秒
约为:
68 年
此限制存在是因为计时器内部使用 Java int 值。
计时器颜色
计时器可以选择性地附带颜色参数启动。
支持的颜色
| 颜色 |
| black (黑色) |
| dark_blue (深蓝色) |
| dark_green (深绿色) |
| dark_aqua (深青色) |
| dark_red (深红色) |
| dark_purple (深紫色) |
| gold (金色) |
| gray (灰色) |
| dark_gray (深灰色) |
| blue (蓝色) |
| green (绿色) |
| aqua (青色) |
| red (红色) |
| light_purple (浅紫色) |
| yellow (黄色) |
| white (白色) |
示例:
/playertimer startcountup red
/playertimer startcountdown 5m gold
/playertimer startcountdown 01:30 dark_blue
计时器状态
模组内部使用有限状态机跟踪计时器状态。
| 状态 |
含义 |
READY |
计时器存在但尚未开始 |
RUNNING |
计时器正在运行 |
PAUSED |
计时器暂时中止 |
STOPPED |
计时器被手动停止 |
FINISHED |
倒计时归零 |
这防止了无效操作,例如:
- 恢复已完成的计时器
- 同时启动多个计时器
- 恢复已被停止的计时器
可见性行为
计时器可见性与计时器状态无关。
| 操作 |
结果 |
| 启动计时器 |
计时器变为可见 |
| 暂停计时器 |
计时器保持可见 |
| 恢复计时器 |
计时器变为可见 |
| 停止计时器 |
计时器状态不变 |
| 重置计时器 |
计时器保持可见 |
| 隐藏命令 |
计时器变为隐藏 |
| 显示命令 |
计时器变为可见 |
倒计时完成
当倒计时归零时:
- 计时器自动停止
- 计时器进入
FINISHED 状态
- 玩家收到通知
- 播放钟声效果
命令方块支持
可以通过 Minecraft 的 execute 命令利用命令方块触发命令。
示例:
execute as @p run playertimer startcountdown 5m
这允许:
持久化
所有计时器都会保存到磁盘,并在服务器重启或崩溃恢复时还原。计时器数据存储于:
config/playertimer/timers.json
配置文件存储于:
config/playertimer/config.toml
当前配置支持:
defaultColor = "WHITE"
保存时机包括:
- 每次计时器状态更改时(启动、暂停、恢复、停止、重置、隐藏、显示、完成)
- 每 30 秒自动保存
- 玩家断开连接时
- 服务器关闭时
重启后恢复计时器时,无论其之前是否正在运行,状态都会设置为 PAUSED——因为服务器未进行 tick 更新,计时器不会推进。如果计时器由玩家直接启动,则由玩家负责恢复它。如果计时器由小游戏或冒险地图启动,则由游戏负责恢复它。
失败行为
加载时: 如果计时器条目包含损坏的 UUID,则跳过该条目并记录警告。如果文件完全无法读取,将抛出 RuntimeException,导致模组无法初始化。
保存时: 如果文件无法写入,将记录错误并抛出 RuntimeException。由于计时器被视为关键基础设施(例如用于小游戏),这将导致服务器崩溃,而不是以未保存的状态继续运行。
构建
要求
- Java 25
- Gradle
- Fabric Loader 0.19.3 或更高版本
- Fabric API 0.153.0+26.2
构建
./gradlew build
编译后的 jar 包将出现在以下目录:
build/libs/
版本控制
PlayerTimer 使用以下版本方案:
[mod-version]
示例:
1.4.0
Minecraft 兼容性在 fabric.mod.json、gradle.properties 以及每个版本的更新日志中跟踪。
计划变更
- 配置选项:
- 默认倒计时时长
- 倒计时结束时 audible alarm(声音警报)的开关
- 倒计时结束前每秒蜂鸣提示的开关
- 倒计时结束前蜂鸣提示的持续时间
- 保存时的失败行为(关键 → 服务器崩溃,非关键 → 记录日志并继续)
- API —— 提供一个接口,允许游戏和冒险地图的开发者直接从代码中访问计时器功能
更新日志
1.4.0 - Minecraft 26.2
- 更新 Fabric 目标至 Minecraft 26.2
- 更新 Fabric Loader 要求至 0.19.3 或更高版本
- 更新 Fabric API 依赖至 0.153.0+26.2
- 确认 Fabric 模块可针对 Minecraft 26.2 依赖集成功构建
26.1.x-1.2
- 计时器现在可在服务器重启和崩溃后保持持久化
- 添加了需要 op 等级 2 权限的管理员命令(clear, clearall)
- 将计时器逻辑移至
PlayerTimer 领域模型
- 用领域操作(start, pause, resume, stop, reset)替换了贫血 setter
- 引入
TimerOperationResult 枚举,替代基于异常的流程控制
- 从
PlayerTimerMod 中提取出 PlayerTimerCommand 类
- 添加通过 Gson 实现 JSON 持久化的
TimerStore
- 添加定期自动保存和状态变更时保存
- 通过
TimerCommandContext 统一命令来源的消息传递
- 玩家断开连接时现在会从内存中移除计时器并触发保存
26.1.x-1.1
- 添加彩色计时器支持
- 为计时器启动命令添加可选的颜色参数
26.1.x-1.0
- 首次 Fabric 发布
- 将 PlayerTimer 从 Paper 移植到 Fabric
- 添加独立于玩家的计时器
- 添加倒计时和正计时模式
- 添加计时器状态系统
- 添加可见性系统
- 添加 Brigadier 命令支持
- 添加命令方块兼容性
- 添加支持多种格式的持续时间解析
- 添加动作栏计时器显示
- 添加倒计时完成音效
- 添加 Java 25 支持
- 将计时器逻辑重构至
PlayerTimerService
许可证
MIT License
PlayerTimer Fabric
A Fabric mod providing independent per-player timers for Minecraft servers and singleplayer worlds.
Current Fabric build:
- Minecraft
26.2
- Fabric Loader
0.19.3 or newer
- Fabric API
0.153.0+26.2
- Java 25 or newer
Each player has their own timer which can:
- count up
- count down
- be paused/resumed
- be hidden or shown independently
- be triggered by commands or command blocks
Designed for:
- minigames
- escape rooms
- timed challenges
- parkour
- speedrunning
- multiplayer events
- adventure maps
Features
- Independent timer per player
- Countup and countdown modes
- Brigadier command support
- Pause and resume support
- Timer visibility control
- Countdown completion notification
- Sound effects on completion
- Multiple duration input formats
- Command block compatible using
/execute as
- Admin commands for timer management
- Persistent timers across restarts and crashes
- Built for Fabric
- Java 25 support
Commands
| Command |
Description |
/playertimer startcountup |
Start a countup timer using the configured default colour |
/playertimer startcountup <color> |
Start a coloured countup timer |
/playertimer startcountdown |
Start a 5 minute countdown using the configured default colour |
/playertimer startcountdown <duration> |
Start a countdown with custom duration using the configured default colour |
/playertimer startcountdown <duration> <color> |
Start a coloured countdown |
/playertimer pause |
Pause the timer |
/playertimer resume |
Resume a paused timer |
/playertimer stop |
Stop the timer and reset it to 00:00 |
/playertimer reset |
Reset timer to 00:00 |
/playertimer hide |
Hide the timer display |
/playertimer show |
Show the timer display |
/playertimer admin clear <player> |
Clear the timer for player <player> (op level 2+) |
/playertimer admin clearall |
Clear the timer for all players (op level 2+) |
Duration Formats
The countdown command accepts multiple input formats.
1. Seconds
/playertimer startcountdown 300
Starts a 300 second countdown.
2. mm:ss
/playertimer startcountdown 05:30
Starts a 5 minute 30 second countdown.
Rules:
mm must be between 0 and 59
ss must be between 0 and 59
Examples:
05:30 ✓ valid
59:59 ✓ valid
60:00 ✗ invalid
05:60 ✗ invalid
99:99 ✗ invalid
3. hh:mm:ss
/playertimer startcountdown 01:40:05
Starts a 1 hour 40 minute 5 second countdown.
Rules:
mm must be between 0 and 59
ss must be between 0 and 59
Examples:
01:40:05 ✓ valid
10:59:59 ✓ valid
01:60:05 ✗ invalid
01:40:60 ✗ invalid
4. Text format
/playertimer startcountdown 1h40m5s
/playertimer startcountdown 10m
/playertimer startcountdown 45s
/playertimer startcountdown 2h
/playertimer startcountdown 1h5s
Supports:
- hours (
h)
- minutes (
m)
- seconds (
s)
Any combination may be used.
Rules:
m must be between 0 and 59
s must be between 0 and 59
Examples:
1h40m5s ✓ valid
10m30s ✓ valid
59m59s ✓ valid
1h60m ✗ invalid
10m90s ✗ invalid
10s49m ✗ invalid
Maximum Duration
The maximum allowed duration is:
2147483647 seconds
which is approximately:
68 years
This limit exists because the timer internally uses Java int values.
Timer Colours
Timers may optionally be started with a colour argument.
Supported colours
| Colour |
| black |
| dark_blue |
| dark_green |
| dark_aqua |
| dark_red |
| dark_purple |
| gold |
| gray |
| dark_gray |
| blue |
| green |
| aqua |
| red |
| light_purple |
| yellow |
| white |
Examples:
/playertimer startcountup red
/playertimer startcountdown 5m gold
/playertimer startcountdown 01:30 dark_blue
Timer States
Internally the mod tracks timer state using a finite state model.
| State |
Meaning |
READY |
Timer exists but has not started |
RUNNING |
Timer is actively counting |
PAUSED |
Timer is temporarily halted |
STOPPED |
Timer was manually stopped |
FINISHED |
Countdown reached zero |
This prevents invalid operations such as:
- resuming finished timers
- starting multiple timers simultaneously
- resuming timers that were stopped
Visibility Behaviour
Timer visibility is independent of timer state.
| Action |
Result |
| Start timer |
Timer becomes visible |
| Pause timer |
Timer remains visible |
| Resume timer |
Timer becomes visible |
| Stop timer |
Timer remains unchanged |
| Reset timer |
Timer remains visible |
| Hide command |
Timer becomes hidden |
| Show command |
Timer becomes visible |
Countdown Completion
When a countdown reaches zero:
- the timer stops automatically
- the timer enters the
FINISHED state
- the player receives a notification
- a bell sound is played
Command Block Support
Commands can be triggered via command blocks using Minecraft's execute command.
Example:
execute as @p run playertimer startcountdown 5m
This allows:
- buttons
- pressure plates
- redstone systems
- region triggers
- adventure map integration
Persistence
All timers are saved to disk and restored on server restart or crash recovery. Timer data is stored in:
config/playertimer/timers.json
Configuration is stored in:
config/playertimer/config.toml
The current configuration supports:
defaultColor = "WHITE"
Saves occur:
- on every timer state change (start, pause, resume, stop, reset, hide, show, finish)
- every 30 seconds automatically
- when a player disconnects
- when the server stops
When a timer is restored after a restart, its state is set to PAUSED regardless of whether it was running before — the server was not ticking so the timer was not advancing. If the timer was started by the player directly, they are responsible for resuming it. If the timer was started by a minigame or adventure map, the game is responsible for resuming it.
Failure Behaviour
On load: if a timer entry has a corrupt UUID it is skipped and a warning is logged. If the file cannot be read at all, a RuntimeException is thrown which prevents the mod from initialising.
On save: if the file cannot be written, an error is logged and a RuntimeException is thrown. Because the timer is considered critical infrastructure (e.g. for minigames), this will cause the server to crash rather than continue with unsaved state.
Building
Requirements
- Java 25
- Gradle
- Fabric Loader 0.19.3 or newer
- Fabric API 0.153.0+26.2
Build
./gradlew build
Compiled jars will appear in:
build/libs/
Versioning
PlayerTimer uses the following versioning scheme:
[mod-version]
Example:
1.4.0
Minecraft compatibility is tracked in fabric.mod.json, gradle.properties, and the changelog entry for each release.
Planned Changes
- Configuration options for:
- default countdown duration
- audible alarm on/off at end of countdown timer
- pre countdown finish beep per second on/off
- duration of pre countdown finish beeps
- failure behaviour on save (critical → server crash, non-critical → log and continue)
- API — an interface to allow developers of games and adventure maps to access timer functions directly from their code
Changelog
1.4.0 - Minecraft 26.2
- Updated Fabric target to Minecraft 26.2
- Updated Fabric Loader requirement to 0.19.3 or newer
- Updated Fabric API dependency to 0.153.0+26.2
- Confirmed the Fabric module builds against the Minecraft 26.2 dependency set
26.1.x-1.2
- Timers are now persistent across server restarts and crashes
- Added admin commands (clear, clearall) gated behind op level 2
- Moved timer logic into
PlayerTimer domain model
- Replaced anemic setters with domain operations (start, pause, resume, stop, reset)
- Introduced
TimerOperationResult enum replacing exception-based control flow
- Extracted
PlayerTimerCommand class from PlayerTimerMod
- Added
TimerStore for JSON persistence via Gson
- Added periodic auto-save and save-on-state-change
- Consistent command source messaging via
TimerCommandContext
- Player disconnect now removes timer from memory and triggers a save
26.1.x-1.1
- Added coloured timer support
- Added optional colour arguments to timer start commands
26.1.x-1.0
- Initial Fabric release
- Ported PlayerTimer from Paper to Fabric
- Added per-player timers
- Added countdown and countup modes
- Added timer state system
- Added visibility system
- Added Brigadier command support
- Added command block compatibility
- Added duration parsing with multiple formats
- Added action bar timer display
- Added countdown completion sounds
- Added Java 25 support
- Refactored timer logic into
PlayerTimerService
License
MIT License
评论 0
登录后参与评分
还没有评论,来抢沙发吧