About Liubai

Liubai is a client-side graphics optimization mod. It watches how smoothly the game is running and carefully reduces the graphics work caused by objects behind walls, distant details, particles, shadows, and name tags. When the game starts to struggle, Liubai gradually reduces the work spent drawing distant or less important objects. Once the game is smooth again, it waits for performance to remain stable before restoring detail step by step, which prevents settings from constantly switching near the target frame rate.

Liubai only changes client-side graphics. It does not stop mob or entity AI, redstone, recipes, or machines, and it does not reduce server-side game processing or improve server TPS (server speed).

Liubai can work alongside mods such as Entity Culling and Create / Flywheel.

Features

Automatic adjustment based on game performance

Uses the target FPS and recent game smoothness to switch automatically between NORMAL / HIGH / CRITICAL pressure levels;
Waits for performance to remain stable before lowering the pressure level, reducing frequent switching;
If the game's own frame-rate limit is lower than Liubai's target, Liubai uses the lower value so it does not incorrectly remain in a high-pressure state.

Careful checks for objects behind walls

When no other occlusion optimization mod is installed, Liubai can use its own checks for objects hidden behind walls;
Uses the real visible area recorded by the game for each object instead of treating every object as the same size;
Only complete solid blocks count as reliable cover; objects are still drawn when chunks are not loaded, their visible area is unusual, or the result is uncertain;
By default, an object must be confirmed as hidden twice before Liubai temporarily stops drawing it;
Only a limited number of checks can run for a limited amount of time each frame; checks that are too complex to finish continue next frame without discarding an earlier reliable result;
After the player moves, Liubai checks whether the old wall still blocks the view and gives these objects priority, reducing stutter caused when all old results suddenly become invalid.

Distant details and large groups of similar objects

When the game is under pressure, Liubai looks at how large a distant object appears on screen and handles objects that are barely visible;
Uses a stable per-area limit for distant dropped items and experience orbs, reducing flicker caused by changes in processing order;
Protects important objects such as players, bosses, projectiles, vehicles, glowing or burning entities, and whatever the crosshair is pointing at;
Inside the nearby safety range, objects are not skipped because they appear too small or because too many similar objects are present.

Particles, shadows, and name tags

Decides whether a distant particle needs to be shown before creating it, reducing unnecessary creation work;
Uses a suggested limit for existing particles and limits how many distant particles can be added each frame;
Reduces the display distance of ordinary entity shadows and name tags when the game is under pressure;
Protects important particles such as explosions, Totems of Undying, and sonic booms, as well as the shadows and name tags of important entities.

Settings and performance information

Provides configuration screens in Simplified Chinese and English;
Opens directly from the “Liubai Settings” button in the upper-right corner of the ESC pause menu;
An optional on-screen performance panel (HUD) shows the current pressure level, active working mode, number of objects not drawn per second, time spent checking hidden objects and timed-out checks, particle status, and P95/P99 frame times, which help show the slowest 5% and 1% of frames;
The performance panel is disabled by default and can be enabled in the settings when needed.

Mod compatibility

Entity Culling

The default occlusion mode is AUTO:

With Entity Culling installed, Entity Culling decides whether ordinary objects are completely hidden, and Liubai does not repeat the same wall-visibility checks;
Without Entity Culling, Liubai uses its own careful visibility checks;
In either case, Liubai can continue handling tiny distant objects, particles, shadows, name tags, and how often distant objects from supported mods update on screen.

Entity Culling 1.10.5 has been tested. Objects skipped by Entity Culling are not included in Liubai's performance information, so Liubai's “hidden objects skipped” number may be 0 when both mods are used together. This is normal.

Create and Flywheel

The following versions have dedicated support and testing:

Create 6.0.10
Flywheel 1.0.6

When the game is under pressure, Liubai works with Flywheel's own rules so distant machines update on screen less often. Nearby machines keep their original update rate. Liubai does not remove or rebuild the objects Flywheel uses to draw machines, and it does not stop machine logic.

Other Create / Flywheel versions are not automatically considered supported. If they work differently from what Liubai expects, Liubai disables this extra optimization and leaves Flywheel's original behavior unchanged so the game can still start safely.

Sable and Create Aeronautics

The current safe compatibility mode was made for the following combination, and these versions have been confirmed to start together and enter a world:

Sable 2.0.3
Create Aeronautics 1.3.0
Create 6.0.10
Flywheel 1.0.6

Iris

Liubai uses information made publicly available by Iris to tell when the game is drawing shadows. While shadows are being generated, Liubai avoids applying the normal-view rules that hide objects, reducing the risk that mobs, other entities, specially rendered blocks, or vanilla entity shadows will be missing.

Iris has been confirmed to start with Liubai and enter a world. Actual shadow results still need separate testing with different shader packs, so this does not mean that every shader pack is fully supported.

Recommended settings

After entering a world, open “Liubai Settings” from the upper-right corner of the ESC pause menu.
Keep the occlusion mode on the default AUTO setting.
When using Entity Culling, do not force both mods to check whether ordinary objects are hidden at the same time.
To check whether the optimization is active, temporarily enable the on-screen performance panel (HUD).
Liubai does not need to be installed on a standard dedicated server. For multiplayer, install it only on the client to use its graphics optimizations.

Configuration file:

config/liubai-client.toml

Frequently asked questions

Can I use Liubai with Entity Culling?

Yes. The default AUTO mode lets Entity Culling decide whether ordinary objects are completely hidden, avoiding duplicate checks. Liubai continues controlling the graphics work spent on the remaining visible objects.

Does it affect machines, redstone, or entity logic?

No. Liubai only adjusts client-side graphics and how often supported rendered objects update on screen. It does not stop game logic.

Why does Liubai show 0 hidden objects skipped in the performance panel?

When Liubai is working with Entity Culling, Entity Culling performs the visibility checks, and the objects it skips are not included in Liubai's performance information. Other optimization counters may also remain at 0 when the pressure level is still NORMAL or when there are no qualifying distant objects nearby.

Why is there little change in average FPS after installing Liubai?

The result depends on each player's world and modpack. Liubai may provide a noticeable FPS improvement in some situations and little or no noticeable change in others.