LISeasons
LISeasons 的使用、配置、维护和扩展指南。
当前发布：2.1.2。Paper / Folia 26.3 适配、测试范围和升级限制见 26.3 兼容说明。
LISeasons 的使用、配置、维护和扩展指南。
本文档对应
LISeasons 1.0.81，包含 13 种持续灾害、25 种季节事件，以及十五种可选 MM/ME 模型资产。大型移动龙卷风、雷暴、火流星、蘑菇云使用无需资源包的原生粒子，并增加阶段变化、次级细节和定向音景，不叠加对应旧模型。免疫玩家可手动安全预览。季节染色通过 PacketEvents 生成玩家独立的客户端群系视图，不修改世界真实群系。
本次更新新增有预警、移动漏斗风柱、卷吸抬升和范围伤害的龙卷风，不破坏建筑；保留持续自然灾害和温度生存，详见更新日志。
1.0.81 新增流星奖励箱：沿用原奖励池，箱子与物品随世界保存；不安全落点回退散落，空箱自动清理。
从这里开始
玩家请阅读玩家文档，了解日期、节气、体温、日历菜单、季节事件和常用指令。
服主与运维人员请阅读管理员文档，了解安装、世界启用、配置文件、客户端染色、性能预算和故障排查。
需要立即使用时：
- 普通玩家从玩家文档 · 总览开始；
- 新服务器从安装与升级开始；
- 不变色先检查PacketEvents 客户端季节染色；
- 发生异步线程错误、卡顿或 Watchdog 时进入性能优化与故障排查。
核心系统
LISeasons 把一个服务器世界拆成六个相互连接、但可以分别配置的系统：
| 系统 | 负责内容 | 典型入口 |
|---|---|---|
| 世界日历 | 日期来源、季节、二十四节气和自动轮转 | config.yml -> time、/seasons info |
| 世界气候 | 季节色调、天气、作物、冬冻春融和生物规则 | config.yml、season-color.yml |
| 玩家体感 | 体温、潮湿、时段、海拔、室内、水、装备、热源和季节 Buff BossBar | temperature.yml、season-buff-boss-bar |
| 季节内容 | 16 个季节事件、真实感流星雨和陨石奖励 | season-events.yml |
| 现实节日 | 按服务器现实日期显示节日记录与到来提醒 | festivals.yml |
| 信息界面 | 六页日历 GUI、命令、消息和 PlaceholderAPI | gui/*.yml、messages.yml |
这种拆分意味着“冬天不结冰”“群系没有变色”和“体温没有变化”属于三条不同的处理路径。排查前先确认问题属于日历状态、世界规则、玩家体感、事件还是显示层，可以避免在错误的配置文件中反复修改。
选择你的任务
| 想完成的事情 | 阅读页面 |
|---|---|
| 看懂当前日期、季节与节气 | 玩家：看懂四季与节气 |
| 查看体温为什么升高或降低 | 玩家：体温生存指南 |
| 了解随机事件和流星奖励 | 玩家：季节事件与流星雨 |
| 打开日历、查看现实节日 | 玩家：日历与节日 |
| 查询玩家可用指令 | 玩家：常用指令 |
| 安装插件并确认成功加载 | 管理员：安装与升级 |
| 了解所有玩法和管理模块 | 管理员：功能清单 |
| 设置作物、天气、冰雪与生物 | 管理员：季节效果与世界规则 |
| 调整群系颜色或排查不变色 | 管理员：PacketEvents 客户端季节染色 |
| 查询所有配置文件 | 管理员：配置文件参考 |
| 查询管理指令、权限和 PAPI | 管理员：指令、权限与占位符 |
| 处理高在线卡顿或异步错误 | 管理员：性能优化与故障排查 |
| 从其他插件读取季节状态 | 开发者：附属插件 API |
兼容范围
| 项目 | 1.0.71 状态 |
|---|---|
| Paper/Leaves/Lophine 1.21.1-1.21.8 | Paper 1.21.1 API 最低编译基线；Paper 1.21.1 stable 真实加载验证 |
| Paper/Leaves/Lophine 1.21.9 | PacketEvents 运行验证；Paper 官方仅提供 Alpha 构建 |
| Paper/Leaves/Lophine 1.21.10 | PacketEvents 运行验证 |
| Paper/Leaves/Lophine 1.21.11 | PacketEvents 协议支持 |
| Paper/Leaves/Lophine 26.1.2 | PacketEvents 协议支持 |
| Paper/Leaves/Lophine 26.2 | PacketEvents 协议支持与 Paper 26.2 API 编译 |
| Folia 1.21.8 及以上稳定构建 | Folia 1.21.11 build 14 真实加载、重载与控制台区域查询验证 |
| Java | 插件字节码为 Java 21 |
| PacketEvents | 强制前置，最低 2.13.0，负责构造并发送区块群系数据包 |
| PlaceholderAPI | 可选，用于 TAB、聊天和其他界面显示 |
| CustomCrops | 可选，自定义作物季节联动 |
| Dominion | 可选，领地环境联动 |
| Residence | 可选，通过 Bukkit 事件遵守 iceform、icemelt；Residence 自身需要匹配的 CMILib |
重要的安全边界
季节群系染色不会修改或保存服务端区块群系，关闭后无需恢复群系。注意：冬冻春融和秋季真实叶块替换仍属于世界方块变化，生产世界仍建议保留常规备份。
calendar-state.yml 保存服内日历的运行状态，由插件维护。服务器运行时不要手工改写，也不要把其他世界或旧服务器中的状态文件直接覆盖到生产服。
管理员或 OP 账号可能绕过普通权限限制。测试玩家指令、菜单和 PlaceholderAPI 显示时，应使用没有 liseasons.admin 的普通账号再次验证。
获取帮助
提交问题时请同时提供：
- 服务端核心与完整版本号；
- Java、LISeasons 和 PacketEvents 版本；
- 启动阶段与问题发生阶段的完整日志；
- 可以稳定复现问题的步骤；
- 涉及的配置片段，并隐藏密码、令牌和服务器地址；
- 视觉问题附客户端录像，并说明粒子、光影与资源包设置。