玩家计时器

玩家计时器

这个项目添加了一个计时器，玩家或命令方块都可以启动它。计时器对每个玩家来说是独立的，每个玩家可以运行各自的计时器。这是仅服务器端安装的，用于运行小游戏和限时挑战。

游戏机制

玩家计时器 Fabric 版

一个 Fabric 模组，为 Minecraft 服务器和单人世界提供独立的逐玩家计时器。

当前 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> 的计时器（操作员等级2+）
/playertimer admin clearall 清除所有玩家的计时器（操作员等级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

支持：

  • 小时 (h)
  • 分钟 (m)
  • 秒 (s)

可以使用任意组合。

规则：

  • 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，无论其之前是否在运行——因为服务器没有在运行，所以计时器没有前进。如果计时器是由玩家直接启动的，则玩家负责恢复它。如果计时器是由小游戏或冒险地图启动的，则游戏负责恢复它。

故障行为

加载时： 如果某个计时器条目包含损坏的 UUID，则会跳过该条目并记录警告。如果文件完全无法读取，则会抛出 RuntimeException，阻止模组初始化。

保存时： 如果文件无法写入，则会记录错误并抛出 RuntimeException。由于计时器被视为关键基础设施（例如对于小游戏），这会导致服务器崩溃，而不是在状态未保存的情况下继续运行。

构建

要求

  • Java 25
  • Gradle
  • Fabric Loader 0.19.3 或更新版本
  • Fabric API 0.153.0+26.2

构建

./gradlew build

编译后的 jar 文件将出现在：

build/libs/

版本号

PlayerTimer 使用以下版本方案：

[模组版本]

示例：

1.4.0

Minecraft 兼容性信息记录在 fabric.mod.json、gradle.properties 以及每个版本的更新日志条目中。

计划中的更改

  • 配置选项：
    • 默认倒计时时长
    • 倒计时结束时声音警报的开关
    • 倒计时结束前每秒提示音的开关
    • 倒计时结束前提示音的持续时长
    • 保存时的故障行为（关键 → 服务器崩溃，非关键 → 记录并继续）
  • 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

  • 计时器现在在服务器重启和崩溃后保持持久化
  • 添加了管理员命令（clear, clearall），需要操作员等级2+
  • 将计时器逻辑移动到 PlayerTimer 领域模型中
  • 用领域操作（启动、暂停、继续、停止、重置）替换贫血的设置器
  • 引入 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 许可证