DUATAR: Optimization

# DUATAR: Optimization

A lightweight, client-side performance mod.

Instead of replacing the renderer, it fixes two specific bottlenecks that were found by profiling the vanilla game, and leaves everything else exactly as Mojang wrote it. The game looks the same, it just renders less work and does that work faster.

---

## Features

### Asynchronous occlusion culling

Vanilla already skips objects outside your field of view and whole chunk sections it can prove are hidden. But inside every visible section it still renders **all** entities and block entities, even the ones behind a wall: mobs on the other side of a hill, chests inside a house, signs in the next room.

This mod checks on a background thread whether entities and block entities (chests, signs, banners and more) are hidden behind solid blocks, and skips rendering the ones you cannot see.

- **Never blocks the game.** The check runs on its own thread; rendering only reads the latest result.
- **When in doubt, it renders.** Players, entities with visible name tags, glowing entities, leashed mobs, vehicles and passengers, the Ender Dragon and very large objects are never culled. Nothing is culled in spectator mode.
- **Low background cost.** Objects that did not move, seen from a camera that did not move, are not re-tested every cycle.

### Faster vertex writes

On Java 25, LWJGL writes vertex data in a way that the JIT compiler fails to optimize inside Minecraft's large vertex-building methods. With many entities on screen, this single issue took about **45% of the render thread's time** in profiling. The mod writes exactly the same bytes through one shared memory segment instead.

- Speeds up everything built with Minecraft's `BufferBuilder`: entities, block entities, text, GUI and chunk meshes.
- A self-test runs at startup. If anything does not match, the mod automatically falls back to the vanilla code path.

---

## Benchmarks

Measured with the mod's built-in benchmark on AMD Radeon integrated graphics, 16 CPU threads, Java 25, 854×480, render distance 12. Each value is the average of several measurement phases.

**Stone wall in front of 427 mobs and 250 block entities**
- Vanilla: 48.7 FPS average, 23.8 FPS 1% low
- With the mod: **238 FPS average, 87 FPS 1% low**

**Open view with 382 mobs visible**
- Vanilla: 63.9 FPS average, 31.4 FPS 1% low
- With the mod: **91 FPS average, 50.8 FPS 1% low**

The first scene is a best case for culling. Real gains depend on your world and your hardware: if your GPU is the limiting factor (for example at high resolutions), the improvement will be smaller.

Screenshots taken with each optimization turned on and off were compared pixel by pixel and showed no rendering differences.

---

## Configuration

File: `config/duatar_forge_optimization-client.toml`

- `entityCulling` (default `true`): skip entities hidden behind opaque blocks.
- `blockEntityCulling` (default `true`): skip block entities hidden behind opaque blocks.
- `fastVertexWrites` (default `true`): use the faster vertex write path. Requires a restart.

Every optimization can be turned off on its own if it ever conflicts with another mod.

---

## FAQ

**Does it change how the game looks?**
No. It only skips objects you cannot see and writes the same vertex data faster.

**Is it a replacement for Sodium or Embeddium?**
No. It keeps the vanilla renderer and removes specific bottlenecks, which keeps it small and compatible.

**My log shows "WARNING: A restricted method in java.lang.foreign.MemorySegment has been called".**
This is expected and harmless. Java prints it once when the faster vertex writes set up their memory segment.

**How can I check that it is active?**
Your log should contain the line `Fast vertex writes active`.

---

## For testers: built-in benchmark

Add the JVM argument `-Dduatar.benchmark=12` to your launcher profile. The game will then:

1. Create a superflat world named `duatar_benchmark` (deleted and recreated on every run).
2. Measure frame times, 1% lows and memory allocation with culling off and on.
3. Save a report to the `duatar_benchmark` folder and screenshots to `screenshots`, then close the game.

While it runs, the benchmark changes some options (VSync off, unlimited FPS, render distance 12, no pause when the window loses focus), so check your settings afterwards. Remove the argument again for normal play.

---

Part of the **DUATAR** mod series. Bug reports and feedback are welcome in the co