Client-side water rendering for Minecraft 26.3 and 1.21.11
Reduce water-related rendering work while keeping the world, gameplay, and server unchanged.
Water Optimisation is a small, opt-in client mod for water-heavy Minecraft scenes. It focuses on client rendering and cosmetic water particles: oceans, flooded caves, waterfalls, and large pools can spend less work building or drawing water geometry. Version 1.0.0 supports Fabric 26.3 and Fabric 1.21.11; NeoForge 26.3 is planned as a later support update after its development tooling stabilises.
This mod only changes what is rendered on the client. It does not change fluid simulation, terrain, collision, movement, networking, gameplay, or server state.
- Download the latest release and choose the JAR matching both your Minecraft version and loader.
- Put the runtime JAR in the client’s
modsfolder. - Launch a supported Minecraft version with Fabric. NeoForge 26.3 will be added in a later support update once that target leaves development beta.
- Open the settings from Mod Menu on Fabric or the Mods screen on NeoForge, or press
Oin the client. - Enable the mod and start with the
Performancepreset.
The current public v1.0.0 release supports Fabric 26.3 and Fabric 1.21.11. The previous 0.0.10 release remains available as a historical release for Fabric 26.3, Fabric 26.2, Fabric 1.21.1, and NeoForge 26.2. The supplied water-block logo is used in this README and is also packaged as the mod icon.
| v1.0.0 target | Loader | Java | Status |
|---|---|---|---|
| 26.3 | Fabric | 25+ | Included in v1.0.0. |
| 1.21.11 | Fabric | 21+ | Included in v1.0.0. |
| 26.3 | NeoForge | 25+ | Planned after the NeoForge 26.3 development beta stabilises. |
The 26.2 Fabric, 1.21.1 Fabric, and 26.2 NeoForge artifacts remain available only as historical 0.0.10 releases. They will not receive the v1.0.0 settings redesign or new rendering features.
The 0.0.10 release supports Minecraft 26.3 Fabric with -Ptarget_minecraft=26.3, using Java 25, Fabric Loader 0.19.5, Fabric API 0.160.6+26.3 (metadata floor >=0.160.6+26.3 for 26.3 only), and optional Mod Menu 21.0.0-beta.1. Only the keyboard input adapter differs from the shared modern client code. The 0.0.10 release hardens configuration-log privacy, pins the Gradle distribution checksum, brackets fluid tessellation with try/finally cleanup, and corrects hidden-water skipping beneath solid ceilings. The newer historical local Fabric 26.3 result is 25 tests passed via test: 16 config-model tests, 4 context helper tests, and 5 mocked predicate tests. Earlier evidence separately records a forced test build verifyArtifact --rerun-tasks pass with 20 tests and clean repository/client-only audits and whitespace checks; it is not a 25-test full-build result. A separate NeoForge 26.2 build passed 20 tests before the new mocked predicate fixture was added. Current-SHA CI passed for builds and startup smoke per runs 35237266215 and 35237266249, and no project-run in-game tests were run for this hardening. Transformed-Mixin cancellation/exception validation remains an open nonvisual gate; helper tests and startup success do not prove transformed behavior or optional local-capture hook execution. A user-reported pass dated 2026-09-17 covered Apple M2 hardware, macOS 27, OpenGL, Sodium absent, and Mod Menu present on CI runtime water-optimisation-0.0.10-mc26.3-fabric.jar (SHA-256 d50d3074a14a0bd70daa7474e91f4f5d54a8751d6ceb5f4a8f84be6ab0db7d24); the full visual matrix and FPS remain unvalidated. A follow-up pass covered Mod Menu present and most settings with no failures observed. A further pass covered Sodium present and the Vulkan backend with no failures observed, with Sodium version and scenes unspecified. See the 26.3 build, test, and release guide and 26.3 release notes.
The preset selector gives the common choices clear names. Selecting a preset resets its advanced values.
| Preset | What it changes | Best for |
|---|---|---|
| Vanilla | Turns the mod off and restores vanilla behavior. | A reference comparison. |
| Balanced | Keeps vanilla fluid geometry and nearby particles. | A conservative starting point. |
| Performance | Skips only fully hidden source-water blocks and disables water particles by default. | Safer performance testing. |
| Maximum FPS | Includes the Performance path and, on supported vanilla renderers, removes optional inward water faces for ordinary full source water. | Testing the strongest available water-rendering reduction. |
Maximum FPS is intentionally opt-in. Hidden-water skipping leaves flowing water, waterlogged blocks, transparent boundaries, partial shapes, overlays, and ambiguous cases on vanilla tessellation. Experimental mode separately removes optional inward faces from ordinary source water and may affect underwater or transparent-boundary views.
Fully hidden water blocks
During section compilation, the modern renderer hook reuses the six neighbor states that Minecraft has already loaded to identify hidden ordinary source water. In the active 26.3 renderer path, ordinary source water is required above; source water or full solid-rendering blocks may hide the down/side faces. A solid ceiling alone is not sufficient because a water surface can remain visible beneath it. This correction does not retroactively change the historical 0.0.10 artifacts.
Open-surface water does not qualify, so visible top faces remain. Flowing water, waterlogged blocks, transparent boundaries, partial shapes, overlays, and ambiguous states fall back to vanilla tessellation.
The Maximum FPS preset keeps Minecraft’s normal outward water faces but removes the optional reverse copy for ordinary full source water. That can reduce translucent vertices, triangles, and overdraw in water-heavy views.
The trade-off is visual: reverse faces can matter when looking from inside a fluid volume or through unusual transparent arrangements. The normal water surface, fluid state, textures, tint, fog, and simulation are not replaced.
The client can reject water-only particles before they are created. Non-water particles and always-visible particles are preserved. When enabled, the filter uses a cached camera-relative distance bound and squared-distance math; an optional fog setting tightens that bound conservatively. The separate forced-particle switch controls the alwaysShow water subset; Minecraft's overrideLimiter flag controls particle-density limiting rather than distance admission and is intentionally left to vanilla.
Maximum FPS disables ordinary water particles by default. Particle settings continue to work when Sodium owns fluid rendering.
Sodium has its own fluid renderer. Water Optimisation keeps its vanilla fluid hooks disabled instead of competing with or replacing Sodium’s geometry. When Sodium is present, Sodium owns all water geometry and Water Optimisation applies only local particle controls. The reduced-inward-face option is available only on the vanilla renderer. No Sodium geometry bridge is planned; Sodium remains the geometry owner unless project scope is formally reconsidered. The effective path is shown in the main settings screen.
The mod is client-only. It declares no server entrypoint, custom packets, world updates, movement changes, collision changes, player-information features, telemetry, update checker, or outbound network service. Non-water rendering is outside its scope.
The optional diagnostics HUD reports fluid blocks, fully hidden skips, removed reverse faces, section compilation, translucent resorting, and particle admission. Its fast-path lines distinguish the saved setting, the effective active path, whether the target hook was observed, and actual skips. It is a cross-check, not a benchmark tool; disable it for final FPS measurements.
For a fair comparison, warm the same scene and compare Vanilla, Performance, and Maximum FPS from the same camera. Record average FPS, 1% lows, frame time, and visual correctness above water, underwater, around flowing water, in caves, and with Sodium present and absent. The mod is designed to reduce work, but no universal FPS gain is promised across hardware, shaders, resource packs, or backends.
| Component | Supported target |
|---|---|
| Minecraft | 26.3 or 1.21.11 for the v1.0.0 release line |
| Java | 25+ for 26.3; 21+ for 1.21.11 |
| Fabric Loader | 0.19.5+ for 26.3; 0.18.5+ for 1.21.11 |
| Fabric API | 0.160.6+26.3 for 26.3; 0.141.4+1.21.11 for 1.21.11 |
| Mod Menu | Optional: 21.0.0-beta.1 for 26.3; 17.0.1-beta.1 for 1.21.11 |
| NeoForge | Planned: matching stable 26.3 release line |
| Environment | Client only |
- Configuration guide — every preset and advanced option.
- Compatibility — Sodium, Mod Menu, backends, and fallback behavior.
- Testing matrix — visual and performance checks.
- Benchmark template — repeatable measurements.
- Architecture — renderer and client-boundary details.
- Privacy and security policy.
Useful changes should be measurable, client-side, and conservative around fluid shapes and transparency. See CONTRIBUTING.md, open an issue with the exact scene and versions, or use the repository’s issue templates.
Water Optimisation is released under the MIT License. Created by Cinq.