Chronos 奖励

⏱️ 技术规格与架构：ChronosRewards

Fabric 平台 100% 服务端游戏时间与连续登录奖励引擎 🚀

---

1. 🎯 引言与核心理念

ChronosRewards 是一款高性能、以进度为导向的 100% 服务端 Fabric 模组，专为解决多人环境下的玩家留存问题而设计。通过标准网络和数据包处理所有逻辑，原版客户端可以无缝连接并与完全彩色编码的自定义菜单交互，无需下载任何客户端修改！🌟

该模组引入了一个平衡且高度令人满意的系统，可同时追踪和奖励玩家的每日连续性和长期游戏时间积累，即使在数百名玩家同时在线的高负载压力测试环境下也能稳定运行。⚡

---

2. 🎛️ 系统架构与核心机制

2.1 动态虚拟背包界面（GUI 引擎）📦

该界面使用配置文件中提供的行参数，基于原版的 GenericContainerScreenHandler 结构将原始数据直接映射到容器屏幕中。

• 最大容量布局： 系统分配完整的 6 行箱子界面（共 54 个槽位），如配置中所指定（"rows": 6），以最大化物品种类密度，提供全面的进度路径！📊
• 槽位分配矩阵： 物品根据 JSON 映射中指定的明确槽位直接放置。
• 占位符标准化： 背包引擎会即时扫描物品元数据，将诸如 {streak}、{playtime} 和 {status}（例如 §a可领取、§c已锁定、§7已领取）的原始字符串节点，使用格式化标记（§）转换为完全渲染的客户端组件。✨

2.2 精确的时间连续登录验证 ⏳

每日登录追踪避免了有缺陷的本地系统日历依赖，而是通过计算当前登录与玩家上次记录的每日领取时间之间的精确纪元时间戳差值（以毫秒为单位）：

• minimum_window_millis（20 小时）： 防止玩家过早领取奖励的门槛。🛑
• maximum_window_millis（48 小时）： 如果时间差超过此窗口，当前连续登录天数将重置为 1。如果时间差恰好介于两个限制之间，则连续天数增加 1。📈

2.3 即时加入物品递送矩阵 🎁

为了欢迎玩家，该模组会拦截玩家进入处理程序。当连接初始化时，模组会评估玩家的即时资格状态。如果玩家符合每日或里程碑奖励的条件，引擎会直接使用 player.getInventory().insertStack() 将具体的基础物品放入玩家的背包中。📥

• 溢出保护： 如果玩家的背包容器已满，引擎会以物理 ItemEntity 的形式将物品丢弃在玩家确切的 BlockPos 坐标环境中，保证零数据丢失！💎

---

3. 🛠️ 按目标系列划分的模组执行规范

3.1 📂 MINECRAFT 26.2.x 执行规范

• 目标架构： 使用最新 Mojang 和 Fabric Loader 参数的 Minecraft 26.2.x。
• 运行时环境： Java 25。
• 依赖约束： 严格零外部依赖；不依赖 Fabric API 框架。

底层数据包拦截 🛰️

该模组通过针对 ServerPlayNetworkHandler.onPlayerJoin() 的核心 Mixin 进行注入。执行时，它会触发 JSON 缓存的异步读取，运行连续登录天数计算差值，并将任何待处理的条目物品块直接放入用户的数据容器中。

线程性能优化 🏎️

游戏时间计算使用通过直接注入 MinecraftServer.tick() 管理的全局计时映射。为了最大限度地发挥处理核心的性能，运行时值使用 Java 25 作用域值和轻量级虚拟线程进行映射，从而减少在紧密打包的专用架构上的执行帧下降。

---

3.2 📂 MINECRAFT 26.1.x 执行规范

• 目标架构： 使用初始 26 系列 Mojang 映射的 Minecraft 26.1.x。
• 运行时环境： Java 25。
• 依赖约束： 严格零外部依赖；纯 Fabric Loader Mixin。

注册表评估 🔍

由于 26.1.x 引入了精炼的数据序列化协议，物品堆栈通过查询服务器执行线程内的 Registries.ITEM 注册表动态构建。游戏时间状态通过 CommandRegistrationCallback 与 Brigadier 命令执行节点原生同步。

---

3.3 📂 MINECRAFT 1.21.x 通用规范

• 目标架构： Minecraft 1.21、1.21.1、1.21.2、1.21.3、1.21.4、1.21.11。
• 运行时环境： Java 21。
• 依赖约束： 零 Fabric API 要求。

数据组件注册表集成 🧩

Minecraft 1.21.x 完全缺少菜单项的传统 NBT 堆栈，转而依赖于类型安全的数据组件系统。物品生成将配置中的字符串组件映射到使用活动注册表数据库的类型安全实例中。文本修改通过 DataComponentTypes.LORE 和 DataComponentTypes.CUSTOM_NAME 参数附加。

线程隔离存储架构 💾

为了防止自动保存循环（autosave_interval_ticks）期间的服务器卡顿，运行时指标会将数据配置文件克隆到异步存储线程池中。此后台引擎使用标准 GSON 配置，将玩家游戏时间映射和时间戳直接序列化到目录中。

---

4. ⚙️ 生产主配置 (config/chronos_rewards.json)

(为简洁代码生成，优化后的较短配置最多包含 3 个参考示例) 📄

{
  "command": "rewards",
  "autosave_interval_ticks": 1200,
  "menu": {
    "title": "Chronos 最大容量压力测试",
    "rows": 6
  },
  "streak": {
    "minimum_window_millis": 72000000,
    "maximum_window_millis": 172800000
  },
  "rewards": [
    {
      "id": "daily_1",
      "type": "daily",
      "slot": 0,
      "required_streak": 1,
      "title": "§a第 1 天欢迎",
      "item": "minecraft:emerald",
      "lore": ["连续登录天数：{streak}", "{status}"],
      "commands": ["give {player} emerald 1"]
    },
    {
      "id": "playtime_1m",
      "type": "playtime",
      "slot": 27,
      "required_ticks": 1200,
      "title": "§e游戏时间：1 分钟入门",
      "item": "minecraft:bread",
      "lore": ["时间：{playtime}", "{status}"],
      "commands": ["give {player} bread 2"]
    },
    {
      "id": "playtime_100h",
      "type": "playtime",
      "slot": 53,
      "required_ticks": 7200000,
      "title": "§4游戏时间：100 小时传奇",
      "item": "minecraft:elytra",
      "lore": ["时间：{playtime}", "{status}"],
      "commands": ["give {player} elytra 1"]
    }
  ]
}

---

5. ⚡ 硬件性能与内存管理

• 目标硬件环境： 高性能多核处理器（例如，24/7 服务器架构上的 Ryzen 7 处理器）。

通过 FastUtil 减少内存占用 🧠

为了避免因装箱原始类型而造成内存浪费，所有玩家的运行时映射（UUID 到游戏时间刻度和领取时间戳）都通过使用 FastUtil 库中的高性能原始映射（如 Object2LongOpenHashMap）来严格维护。这确保了最小的开销，即使在最大容量压力测试下高并发玩家数量时，也能保持极低的内存垃圾回收周期指标！📈

---

🛠️ 如何使用 JSON 配置

• 步骤 1：找到你的 config 文件夹 📂

• 打开你的 Minecraft 服务器框架目录。

• 导航到根目录下的 config 文件夹，并查找奖励模组指定的文件夹（名为 chronos_rewards）。

• 步骤 2：打开或创建文件 📄

• 在该文件夹中，查找名为 chronos_rewards.json 的配置文件。

• 如果文件尚不存在，请启动一次服务器实例，让后端框架自动生成它，或手动创建一个名为 chronos_rewards.json 的新文件。

• 步骤 3：粘贴代码 📋

• 使用高级文本编辑器（如 VS Code 或 Notepad++）打开 JSON 文件。

• 选中文件中的所有内容，将其删除，然后粘贴上面提供的整个生产配置块。

• 确保没有多余的逗号或损坏的右括号，以便 GSON 解析层能够成功验证语法。

• 步骤 4：保存更改 💾

• 保存文件并安全关闭文本编辑器。

• 步骤 5：在游戏中应用 🔄

• 如果服务器正在运行，请通过服务器控制台执行模组的原生热加载命令，或完全重启引擎以刷新配置流。

• 玩家现在可以在聊天网络中输入 /[command]（默认为 /rewards）来打开完全填充的 6 行奖励菜单网格，并查看其实时统计数据！🎮