RP沉浸

RpImmersion

RpImmersion 是 RpEssentials 的配套服务端模组，专为在 NeoForge 上运行 Minecraft 1.21.1 的角色扮演服务器设计。它为服务器管理员提供对玩家所体验氛围的控制：雾效、镜头效果、天气沉浸感以及自定义 RP 日历，所有配置均无需重启服务器即可生效。

当前版本：1.0.0

注意： 当客户端启用光影包时，服务器控制的雾效将不会生效。这是 NeoForge 雾效事件系统的已知限制，目前无法绕过。

---

前置要求

依赖	版本	端	必需
Minecraft	1.21.1	双端	✅
NeoForge	21.1.219+	双端	✅
RpEssentials	4.1.7+	双端	✅
ImmersiveMessages	neoforge-1.21.1:1.0.18	客户端	⬜ 可选
TxniLib	neoforge-1.21.1-1.0.24	客户端	⬜ 可选

仅当使用 weatherMessageMode = IMMERSIVE 时，客户端才需要 ImmersiveMessages 和 TxniLib。服务器无需它们即可运行，未安装这些模组的客户端将回退至行动栏显示。

---

功能特性

雾效系统

由服务器控制玩家的雾效覆盖，配置位于 rpimmersion-fog.toml 中。

• 命名预设： 定义雾效颜色（RGB）、起始/结束距离以及淡入淡出过渡时长。
• 圆形区域： 将预设分配至由中心坐标和半径定义的区域。重叠时，优先级更高的区域优先生效。
• 基于生物群系的雾效： 当玩家进入特定生物群系时应用预设。支持通配符模式（minecraft:*、*:dark_*）。
• RpEssentials 区域覆盖： 将雾效应用于 RpEssentials 中已定义的区域，无需重新定义坐标。
• 昼夜变体： 区域、生物群系和全局预设各自支持独立的 dayPreset 和 nightPreset，并可在两者之间进行动态过渡。
• 全局雾效： 当没有区域或生物群系规则匹配时应用的默认预设。
• 世界边界雾效： 当玩家踏出世界边界时激活的专属预设。
• 单玩家覆盖： 管理员可通过命令为单个玩家指定特定雾效，优先级高于所有其他规则。
• 平滑过渡： 雾效变化会在可配置的时长内进行插值。
• 优化同步： 服务器每隔 N 个游戏刻（可配置）检查每位玩家的雾效状态，仅在解析后的状态发生变化时才发送数据包。

---

天气沉浸感

额外的天气行为，配置位于 rpimmersion-weather.toml 中。

• 天气雾效集成： CLEAR、RAIN 和 THUNDER 分别映射至一个雾效预设，并在没有区域或生物群系雾效激活时作为低优先级回退应用。
• 闪电频率控制： 在雷暴期间增加或减少闪电击落的频率。额外的闪电会出现在在线玩家附近的配置半径内。
• 闪电镜头震动： 附近的玩家会收到与其距闪电距离成比例的镜头震动效果。该效果会在可配置的时长内逐渐消退。
• 镜头震动兼容性： 震动效果以叠加方式添加到现有镜头角度上，因此不会与修改镜头行为的其他模组冲突。
• 客户端震动覆盖： 可选允许客户端通过自己的客户端配置减少或禁用镜头震动。服务器也可以对所有玩家强制固定震动强度。
• 自动天气循环： 定义一系列以现实分钟为单位的天气步骤和持续时间。服务器会自动循环切换它们。
• 叙事消息： 天气变化时广播可配置的消息。支持 CHAT、ACTION_BAR 和 IMMERSIVE（需要 ImmersiveMessages）显示模式。
• 降雨效果： 对淋雨或身处雷暴中的玩家施加药水效果，并可选检查是否暴露在天空下。

---

RP 日历

一个持久的、由服务器驱动的角色扮演日历，配置位于 rpimmersion-calendar.toml 中。

• 自定义结构： 定义自己的月份名称、月份数量、每月天数（统一或每月不同），以及可选的星期名称。
• 可配置时间比例： 控制 RP 时间相对服务器刻的推进速度。ticksPerRpMinute、rpMinutesPerHour 和 rpHoursPerDay 均可独立设置。还提供 Minecraft 日同步模式，每个 Minecraft 昼夜循环将日历推进一个 RP 日。
• 持久化： 当前日期和暂停状态保存至 world/data/rpimmersion/calendar.json，并在服务器重启后保留。
• 可暂停： 管理员可冻结日历。日期仍会显示（带有可配置的后缀），但时间停止累积。
• 灵活显示： 以 HUD 叠加层、行动栏、两者兼有或均不显示的方式展示日期。格式字符串支持 {day}、{dayName}、{month}、{monthName}、{year}、{hour} 和 {minute} 占位符。
• RpEssentials 日程集成： 当 RpEssentials 服务器日程关闭时，日历可自动暂停，并在日程开启时自动恢复。
• 实时命令： 无需重启即可设置日期、按 N 个 RP 分钟推进、暂停/恢复或强制向所有玩家同步。

---

命令

所有命令需要由 RpEssentials 定义的管理员权限。

雾效

命令	描述
/rpimmersion fog set global <预设|clear>	对所有玩家应用雾效预设，或清除全局覆盖。
/rpimmersion fog set player <玩家> <预设|clear>	对特定玩家应用雾效预设。
/rpimmersion fog clear global	移除全局雾效覆盖。
/rpimmersion fog clear player <玩家>	移除单玩家雾效覆盖。
/rpimmersion fog list	列出所有已加载的雾效预设及其参数。
/rpimmersion fog status	显示当前雾效状态：全局覆盖、世界边界状态、区域和生物群系数量。
/rpimmersion fog reload	从磁盘重新加载雾效配置并重新同步所有玩家。

天气

命令	描述
/rpimmersion weather set <CLEAR|RAIN|THUNDER>	强制服务器进入特定天气状态。
/rpimmersion weather status	显示当前天气和激活的雾效预设。
/rpimmersion weather reload	从磁盘重新加载天气配置。

日历

命令	描述
/rpimmersion calendar status	显示当前 RP 日期、时间和暂停状态。
/rpimmersion calendar pause <true|false>	暂停或恢复日历。
/rpimmersion calendar set <年> <月> <日> [小时] [分钟]	将日历设置为特定日期和时间。
/rpimmersion calendar advance <分钟>	按 N 个 RP 分钟推进或回退日历。
/rpimmersion calendar reload	强制向所有已连接玩家同步当前日期。

---

配置

首次启动时，将在 config/rpimmersion/ 下生成三个服务端配置文件。一个客户端配置文件生成在标准 NeoForge 客户端配置位置。

文件	内容
rpimmersion-fog.toml	预设、区域、生物群系、RpEssentials 覆盖、世界边界雾效、昼夜设置、优化
rpimmersion-weather.toml	天气雾效映射、闪电频率和震动、自动循环、叙事消息、降雨效果
rpimmersion-calendar.toml	月份/日期结构、时间比例、开始日期、显示格式
rpimmersion-client.toml	客户端震动强度覆盖、雾效禁用开关

所有服务器配置均支持通过相应的 /rpimmersion ... reload 命令进行热重载。无需重启服务器。

雾效预设格式

# 名称;红;绿;蓝;起始距离;结束距离;过渡秒数[;覆盖项]
# 覆盖项：TERRAIN、SKY、WATER、LAVA、POWDER_SNOW、ALL（默认：TERRAIN）
presets = [
    "night_fog;0.05;0.05;0.1;5.0;30.0;3.0",
    "morning_mist;0.7;0.75;0.8;2.0;20.0;5.0",
    "border_void;0.0;0.0;0.0;1.0;8.0;2.0;ALL"
]

雾效区域格式

# 区域名称;中心X;中心Z;半径;预设;优先级[;白天预设;夜晚预设]
zones = [
    "dark_woods;100;-200;80;cursed_forest;10;morning_mist;night_fog"
]

天气雾效格式

# 天气类型;雾效预设
weatherFogPresets = [
    "RAIN;morning_mist",
    "THUNDER;purge"
]

日历结构示例

monthNames    = ["Janvier", "Février", "Mars", "Avril", "Mai", "Juin",
                 "Juillet", "Août", "Septembre", "Octobre", "Novembre", "Décembre"]
daysPerMonth  = [30]
dayNames      = ["Lundi", "Mardi", "Mercredi", "Jeudi", "Vendredi", "Samedi", "Dimanche"]
dateFormat    = "§7{dayName} {day} {monthName}, An {year} — {hour}h{minute}"

---

数据存储

文件	内容
world/data/rpimmersion/calendar.json	当前 RP 日期和暂停状态

---

技术说明

• 雾效过渡使用固定的起始/目标插值模型。“起始”值在应用新雾效的瞬间被捕获，确保无论重叠的过渡如何，都能获得一致的缓入/缓出效果。
• 镜头震动是在现有镜头角度上添加增量值而非替换，使其与同样修改镜头行为的模组兼容。
• 雾效状态每隔 N 个游戏刻（可配置，默认 3 秒）对每位玩家重新计算。仅在解析后的状态与上次发送的值不同时才发送数据包。
• RpEssentials 集成在运行时使用 Java 反射读取命名区域。依赖关系在模组元数据中声明为必需，但在编译时除 isStaff() 权限检查外从未硬链接。