RpImmersion

RpImmersion is a server-side companion mod for RpEssentials, designed for Roleplay servers running Minecraft 1.21.1 on NeoForge. It gives server administrators control over the atmosphere experienced by players: fog, camera effects, weather immersion, and a custom RP calendar, all configurable without server restarts.

Current version: 1.0.0

Note: Server-controlled fog is not applied when a shader pack is active on the client. This is a known limitation of the NeoForge fog event system and cannot be worked around at this time.

---

Requirements

Dependency	Version	Side	Required
Minecraft	1.21.1	Both	✅
NeoForge	21.1.219+	Both	✅
RpEssentials	4.1.7+	Both	✅
ImmersiveMessages	neoforge-1.21.1:1.0.18	Client	⬜ Optional
TxniLib	neoforge-1.21.1-1.0.24	Client	⬜ Optional

ImmersiveMessages and TxniLib are only required on the client if you use weatherMessageMode = IMMERSIVE. The server runs without them, and clients without them fall back to action bar display.

---

Features

Fog System

Server-controlled fog override for players, configured in rpimmersion-fog.toml.

• Named presets: define fog color (RGB), start/end distances, and fade transition duration.
• Circular zones: assign a preset to a zone defined by center coordinates and radius. Higher-priority zones take precedence when overlapping.
• Biome-based fog: apply a preset when a player enters a specific biome. Wildcard patterns are supported (minecraft:*, *:dark_*).
• RpEssentials zone overrides: apply fog to zones already defined in RpEssentials, without redefining coordinates.
• Day/Night variants: zones, biomes, and the global preset each support separate dayPreset and nightPreset, with animated transitions between them.
• Global fog: a fallback preset applied when no zone or biome rule matches.
• World border fog: a dedicated preset that activates when a player steps outside the world border.
• Per-player override: staff can assign a specific fog to one player via command, taking precedence over all other rules.
• Smooth transitions: fog changes interpolate over a configurable duration.
• Optimized sync: the server checks each player's fog state every N ticks (configurable) and only sends a packet when the resolved state has changed.

---

Weather Immersion

Additional weather behavior, configured in rpimmersion-weather.toml.

• Weather fog integration: CLEAR, RAIN, and THUNDER each map to a fog preset, applied as a low-priority fallback when no zone or biome fog is active.
• Lightning frequency control: increase or decrease the rate of lightning strikes during thunderstorms. Extra bolts are placed near online players within a configurable radius.
• Camera shake on lightning: nearby players receive a camera shake proportional to their distance from a lightning strike. The effect fades over a configurable duration.
• Camera shake compatibility: the shake is applied additively to existing camera angles, so it does not conflict with other mods that modify camera behavior.
• Client shake override: optionally allow clients to reduce or disable camera shake via their own client config. The server can also enforce a fixed intensity for all players.
• Automatic weather cycle: define a sequence of weather steps with durations in real-time minutes. The server cycles through them automatically.
• Narrative messages: broadcast a configurable message when weather changes. Supports CHAT, ACTION_BAR, and IMMERSIVE (requires ImmersiveMessages) display modes.
• Rain effects: apply potion effects to players caught in rain or thunderstorms, with optional sky-exposure checks.

---

RP Calendar

A persistent, server-driven roleplay calendar, configured in rpimmersion-calendar.toml.

• Custom structure: define your own month names, number of months, days per month (uniform or per-month), and optionally day-of-week names.
• Configurable time ratio: control how fast RP time advances relative to server ticks. ticksPerRpMinute, rpMinutesPerHour, and rpHoursPerDay can each be set independently. A Minecraft-day-sync mode is also available, advancing the calendar by one RP day per Minecraft day cycle.
• Persistent: the current date and pause state are saved to world/data/rpimmersion/calendar.json and survive server restarts.
• Pauseable: staff can freeze the calendar. The date continues to be displayed (with a configurable suffix) but time stops accumulating.
• Flexible display: show the date as a HUD overlay, in the action bar, both, or nowhere. The format string supports {day}, {dayName}, {month}, {monthName}, {year}, {hour}, and {minute} placeholders.
• RpEssentials schedule integration: the calendar can automatically pause when the RpEssentials server schedule is closed, and resume when it opens.
• Live commands: set the date, advance it by N RP minutes, pause/resume, or force a sync to all players, without restarting.

---

Commands

All commands require staff permission as defined by RpEssentials.

Fog

Command	Description
/rpimmersion fog set global <preset|clear>	Apply a fog preset to all players, or clear the global override.
/rpimmersion fog set player <player> <preset|clear>	Apply a fog preset to one specific player.
/rpimmersion fog clear global	Remove the global fog override.
/rpimmersion fog clear player <player>	Remove the per-player fog override.
/rpimmersion fog list	List all loaded fog presets with their parameters.
/rpimmersion fog status	Display the current fog state: global override, world border status, zone and biome counts.
/rpimmersion fog reload	Reload fog config from disk and re-sync all players.

Weather

Command	Description
/rpimmersion weather set <CLEAR|RAIN|THUNDER>	Force a specific weather state on the server.
/rpimmersion weather status	Show the current weather and active fog preset.
/rpimmersion weather reload	Reload weather config from disk.

Calendar

Command	Description
/rpimmersion calendar status	Display the current RP date, time, and pause state.
/rpimmersion calendar pause <true|false>	Pause or resume the calendar.
/rpimmersion calendar set <year> <month> <day> [hour] [minute]	Set the calendar to a specific date and time.
/rpimmersion calendar advance <minutes>	Advance or rewind the calendar by N RP minutes.
/rpimmersion calendar reload	Force a sync of the current date to all connected players.

---

Configuration

Three server-side config files are generated under config/rpimmersion/ on first launch. One client-side config is generated in the standard NeoForge client config location.

File	Contents
rpimmersion-fog.toml	Presets, zones, biomes, RpEssentials overrides, world border fog, day/night settings, optimization
rpimmersion-weather.toml	Weather fog mapping, lightning frequency and shake, auto cycle, narrative messages, rain effects
rpimmersion-calendar.toml	Month/day structure, time ratio, start date, display format
rpimmersion-client.toml	Client-side shake intensity override, fog disable toggle

All server configs support live reload via the corresponding /rpimmersion ... reload command. No server restart required.

Fog Preset Format

# name;red;green;blue;start;end;transitionSeconds[;overrides]
# overrides: TERRAIN, SKY, WATER, LAVA, POWDER_SNOW, ALL (default: 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"
]

Fog Zone Format

# zoneName;centerX;centerZ;radius;preset;priority[;dayPreset;nightPreset]
zones = [
    "dark_woods;100;-200;80;cursed_forest;10;morning_mist;night_fog"
]

Weather Fog Format

# weatherType;fogPreset
weatherFogPresets = [
    "RAIN;morning_mist",
    "THUNDER;purge"
]

Calendar Structure Example

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}"

---

Data Storage

File	Contents
world/data/rpimmersion/calendar.json	Current RP date and pause state

---

Technical Notes

• Fog transitions use a fixed start/target interpolation model. The "from" value is captured at the moment a new fog is applied, ensuring a consistent ease-in/out regardless of overlapping transitions.
• Camera shake adds delta values to existing camera angles rather than replacing them, making it compatible with mods that also modify camera behavior.
• Fog state is recalculated every N ticks per player (configurable, default 3 seconds). A packet is only sent when the resolved state differs from the last sent value.
• RpEssentials integration uses Java reflection at runtime to read named zones. The dependency is declared as required in the mod metadata but is never hard-linked at compile time beyond the isStaff() permission check.