日历

日历模组

为 Minecraft 1.20.1 Forge / Fabric 和 26.2 Fabric 打造的可定制日历系统

简介

日历模组 是一个基于 HtmlCraft API 构建的全功能日历模组。它为 Minecraft 引入了可定制的日历系统，每个存档拥有独立的日历数据。玩家可以定义纪元名称、月份数量、每月天数、月份名称、星期名称，添加特殊日期事件，并通过现代 HTML/CSS 渲染界面进行交互。

---

功能特性

日历系统

功能	描述
每个存档独立	每个存档拥有独立的日历数据，互不影响
自定义纪元	可自定义纪元名称（例如：“星辰纪元”、“公元”）
自定义月份	可配置每年的月份数和每月的天数
自定义月份名称	每个月份可有独立的名称
自定义星期	可配置星期名称和每周天数
年份偏移	支持年份偏移以调整起始年份
独立时间追踪	不受 /time 命令影响，基于实际游戏时间，单调递增

事件系统

功能	描述
日期事件	可为任意日期添加事件（名称、描述、颜色）
年度重复	支持每年重复的事件（固定月/日）
颜色选择	列表选择器中的 12 种预设颜色，外加自定义颜色输入
事件标签	支持事件标签分类
特殊日期广播	特殊日期到来时通过 ActionBar 向所有玩家广播（无聊天刷屏）
HUD 显示	HUD 实时显示今日事件信息

界面系统

功能	描述
HTML/CSS 渲染	日历主界面通过 HtmlCraft API 渲染，具有现代化 UI 效果
多种内置样式	6 种内置 CSS 样式（浅灰 / 暗黑 / 海洋 / 森林 / 神秘 / 极简）
样式切换	可在客户端配置中切换界面样式，即时生效
资源包扩展	可通过资源包添加/替换样式，自动检测并合并
全屏自适应	根据屏幕分辨率动态计算布局
可拖动 HUD	HUD 支持鼠标拖动重新定位，位置自动保存
Cloth Config	通过 Cloth Config 提供配置界面；Forge 集成 Catalogue，Fabric 集成 ModMenu
本地化	支持中文和英文

网络同步

功能	描述
数据同步	服务器日历配置和事件数据自动同步到客户端
自动同步	事件修改自动同步到所有在线玩家
登录同步	玩家登录时接收最新的日历数据
客户端缓存	客户端缓存日历数据以减少网络开销

---

环境要求

该模组提供三个版本。请根据你的加载器和 Minecraft 版本选择匹配的版本。

Forge 版本 (1.20.1)

依赖	版本
Minecraft	1.20.1
Forge	47.x
Java	17
HtmlCraft API	1.0.0-1.20.1forge
Cloth Config	11.x（必需，用于配置界面）
Catalogue	（可选，用于模组列表配置按钮）

Fabric 版本 (1.20.1)

依赖	版本
Minecraft	1.20.1
Fabric Loader	>=0.19.3
Fabric API	0.92.11+1.20.1
Java	17
HtmlCraft API	1.0.0-1.20.1fabric
Cloth Config	11.x（必需，用于配置界面）
ModMenu	7.x（可选，用于模组列表配置按钮）

Fabric 版本 (26.2)

依赖	版本
Minecraft	26.2
Fabric Loader	>=0.19.3
Fabric API	0.157.0+26.2
Java	25
HtmlCraft API	1.0.0-26.2fabric（必需）
Cloth Config	26.2.155（必需，配置界面）
ModMenu	20.0.x（可选，模组列表配置按钮）

---

安装

Forge 版本 (1.20.1)

1. 将 htmlcraftapi-1.0.0-1.20.1forge.jar、calendarmod-1.0.0-1.20.1forge.jar 和 cloth-config-11.x-forge.jar 放入 mods 文件夹
2. （可选）添加 Catalogue 以在模组列表中显示配置按钮
3. 启动游戏

Fabric 版本 (1.20.1)

1. 安装 Fabric Loader 并确保存在 Fabric API
2. 将 htmlcraftapi-1.0.0-1.20.1fabric.jar、calendarmod-1.0.0-1.20.1fabric.jar 和 cloth-config-11.x-fabric.jar 放入 mods 文件夹
3. （可选）添加 ModMenu 以在模组列表中显示配置按钮
4. 启动游戏

Fabric 版本 (26.2)

1. 安装 Fabric Loader 并确保存在 Fabric API
2. 将 htmlcraftapi-1.0.0-26.2fabric.jar、calendarmod-1.0.0-26.2fabric.jar 和 cloth-config-26.2.155.jar 放入 mods 文件夹
3. （可选）添加 modmenu-20.0.x.jar 以在模组列表中显示配置按钮
4. 启动游戏

---

按键绑定

按键	功能	默认
打开日历	打开日历主界面	C
切换 HUD	显示/隐藏日历 HUD	H

按键可在 选项 → 控制 → 按键绑定 中自定义。

---

命令

所有命令均使用 /calendar 作为前缀。

命令	权限	描述
/calendar	所有玩家	显示命令帮助
/calendar today	所有玩家	查看今天的日期和事件
/calendar list	所有玩家	列出所有事件
/calendar add <year> <month> <day> <name>	OP(2)	添加事件
/calendar remove <index>	OP(2)	移除指定索引的事件
/calendar sync	OP(2)	手动将日历数据同步到所有玩家
/calendar set yearOffset <offset>	OP(2)	设置年份偏移
/calendar set eraName <name>	OP(2)	设置纪元名称

---

界面总览

日历主界面

按下 C 键打开。包含：

• 页眉：纪元名称、年份、月份导航
• 星期行：自定义星期名称
• 日期网格：CSS Grid 布局，今日高亮显示，有事件的日期带标记
• 事件面板：显示所选日期的事件列表
• 底部按钮：
  • 客户端设置：打开 Cloth Config（HUD、样式等）
  • 日历设置：打开日历配置（纪元、月份等）
  • 添加事件：打开事件管理界面

事件管理界面

• 日期输入（年/月/日）
• 事件名称和描述
• 颜色选择列表（12 种预设 + 自定义颜色输入）
• 年度重复开关
• 现有事件列表（支持删除）

HUD

• 显示当前日期和星期
• 显示今日事件（可配置）
• 浅灰色半透明现代 UI
• 可拖动重新定位
• 位置自动保存到配置文件

客户端配置 (Cloth Config)

配置选项	描述
HUD 启用	是否显示日历 HUD
HUD X/Y 位置	HUD 位置
HUD 右对齐	HUD 是否从右侧定位
显示今日事件	HUD 是否显示今日事件
显示事件描述	HUD 是否显示事件描述
界面样式	选择日历界面 CSS 样式
默认月份偏移	打开日历时所在的默认月份
登录时自动打开	登录时自动打开日历

---

样式系统

内置样式

样式	描述
浅灰（默认）	浅灰色半透明现代风格
暗黑	深色主题
海洋	蓝色科技风
森林	绿色自然风
神秘	紫色神秘风
极简	扁平极简风

通过资源包添加自定义样式

资源包只需提供自己的 styles.json（仅包含新样式）和相应的 CSS 文件。模组会自动合并并检测：

resource_pack/
├── pack.mcmeta
└── assets/calendarmod/templates/
    ├── styles.json              ← 仅包含新样式条目
    └── styles/
        └── my_style.css         ← 自定义 CSS 文件

styles.json 格式：

{
  "styles": [
    {
      "id": "my_style",
      "name": "My Custom",
      "description": "Resource pack custom style",
      "file": "styles/my_style.css",
      "builtin": false
    }
  ]
}

启用资源包后，打开 日历 → 客户端设置 → 界面样式 下拉菜单即可看到新样式。

CSS 文件可以使用 __ROOT_PADGAP__ 和其他双下划线变量，由 Java 动态替换为屏幕自适应的像素值。

关于详细的资源包创建指南，请参阅 资源包指南。

资源包生成器工具与教程

该模组提供了基于 GUI 的资源包生成器和详细教程，帮助你快速创建自定义样式：

资源	描述
📦 资源包生成器	PySide6 GUI 工具，用于可视化样式编辑、HUD 颜色配置、ZIP 导出
📖 资源包指南	详细文档，涵盖所有字段、CSS 属性、HTML 模板
🛠️ 工具使用指南	生成器工具的完整使用说明

👉 工具与教程：https://github.com/19136644525lxy/Calendar-Mod/tree/main/docs

快速开始：

cd docs
pip install -r requirements.txt
python resource_pack_generator.py

或在 Windows 上双击 docs/启动资源包生成器.bat。

---

时间系统

• 每个新存档从第一年开始
• 日历时间基于实际游戏时间，不受 /time 命令影响
• 即使其他模组重置时间，经过的日历时间也绝不会倒退
• 24000 tick = 1 天
• 特殊日期通过 ActionBar 广播给所有玩家，每天一次

---

项目结构

com.calendar.mod
├── CalendarMod.java              // 模组主类，按键绑定，网络注册
├── calendar/
│   ├── CalendarConfig.java       // 日历配置数据模型
│   ├── CalendarDate.java         // 日期数据模型
│   ├── CalendarSystem.java       // 日历系统接口
│   ├── ConfigurableCalendar.java // 可配置日历实现
│   └── DefaultCalendar.java      // 默认日历实现
├── client/
│   ├── CalendarClientConfig.java // 客户端配置（Cloth Config）
│   ├── CalendarConfigScreen.java // 日历配置界面
│   ├── CalendarEventScreen.java  // 事件管理界面
│   ├── CalendarHud.java          // HUD 渲染
│   ├── CalendarScreen.java       // 日历主界面（HTML/CSS）
│   ├── HudRenderSubscriber.java  // HUD 渲染事件订阅器
│   └── StyleManager.java         // 样式管理器
├── command/
│   └── CalendarCommand.java      // /calendar 命令
├── data/
│   ├── CalendarEvent.java        // 事件数据模型
│   └── CalendarSavedData.java    // 存档数据持久化
├── network/
│   ├── CalendarClientCache.java  // 客户端数据缓存
│   ├── CalendarConfigPacket.java // 日历配置同步数据包
│   ├── CalendarEventPacket.java  // 事件编辑数据包
│   └── CalendarSyncPacket.java   // 日历数据同步数据包
└── server/
    └── AutoSyncScheduler.java    // 自动同步调度器

---

资源文件

assets/calendarmod/
├── lang/
│   ├── zh_cn.json                // 简体中文语言文件
│   └── en_us.json                // 英文语言文件
├── templates/
│   ├── calendar_screen.html      // 日历界面 HTML 模板
│   ├── calendar_screen.css       // 默认 CSS 样式
│   ├── styles.json               // 样式元数据
│   └── styles/
│       ├── dark.css              // 暗黑
│       ├── ocean.css             // 海洋
│       ├── forest.css            // 森林
│       ├── mystic.css            // 神秘
│       └── minimal.css           // 极简
└── icon.png                      // 模组图标

---

附属模组开发

该模组提供了 CalendarSystem 接口和 CalendarSavedData API。附属模组可以：

• 实现自定义日历系统（实现 CalendarSystem 接口）
• 读取/修改存档日历数据（通过 CalendarSavedData.get(level)）
• 监听日期变更事件
• 注册自定义事件类型

---

许可证

LGPL-2.1

作者

Yifei

依赖

• HtmlCraft API — HTML/CSS 渲染引擎