📷 Camera Culling

Active Version Policy: I build 1 JAR for 1 Version. I support active Minecraft version anchors: 1.20.1, 1.21.1, 1.21.11, and Modern Sovereign 26.1.2, 26.2, and 26.3+. Each version is compiled natively with zero compromises.

Unrender the unseen. Lightweight, zero-allocation camera occlusion culling, 2-sided sign text culling & distance entity detail LOD.

The Vanilla Problem

In vanilla Minecraft, the game's renderer extracts render states and draws thousands of entities, block entities, particle quads, and sign text glyphs even when they are hidden behind solid walls, underground in caves, or obscured from your field of view. Furthermore, rendering fully-resolved secondary model layers on distant mobs consumes precious GPU fillrate and memory bandwidth.

What Camera Culling Does

Camera Culling solves this at the rendering root. It performs lightning-fast client-side raycasting and frustum occlusion checks against block collisions to dynamically unrender occluded entities, block entities, particles, and sign text faces. Combined with a smart crowd overdraw defense, distance-based entity detail & shadow LOD, dynamic boss/mini-boss protections, zero per-frame heap allocations, and an anti-flicker temporal hysteresis buffer, Camera Culling drastically increases frame rates without altering world simulation or network packets.

Part of the Vanilla Outsider Collection — mods that refine the vanilla experience with modern standards.

🔗 Official GitHub Wiki: https://github.com/Rifaditya/Vanilla-Outsider-Camera-Culling/wiki

✨ Key Optimization Features

🧱 Entity Occlusion Culling (Zero-Allocation Raycast Engine)

Never waste GPU cycles rendering mobs you cannot see. Fast multi-point raytracing against solid block collision geometry unrenders entities hidden behind walls, cave ceilings, and terrain.

• Zero-Allocation Hot-Path Engine: Passing primitive coordinates directly eliminates intermediate Vec3 heap allocations during continuous frame rendering, removing JVM Young-Gen garbage collection stutter spikes when panning across dense herds.
• Multi-Point Precision: Evaluates key entity sightlines (head top, anatomical eye height, upper torso, center of mass, and elevated flanks) to guarantee mobs are never culled prematurely when partially visible around corners.
• Directional Floor Filtering: Ignores upward block normal collisions (Direction.UP) at entity base level, preventing ground-grazing false culling on slopes and hills.
• Proximity Safety Margin: Mobs within your close proximity safety bubble are always rendered smoothly without delay.

Zero Simulation Impact: Culling operates strictly on client-side render submission. Entity ticks, server synchronization, sound events, and physics remain 100% active.

🛡️ Anti-Flicker Temporal Hysteresis

• Distance-Scaled Grace Buffer: Implements an adaptive frame debounce decay (4 frames near ≤ 32m, 8 frames medium 32–64m, 12 frames far > 64m) that absorbs camera rotation and walking view-bobbing jitter without sudden pop-in.
• Instant Unculling: Mobs becoming visible are rendered immediately with 0-frame latency as soon as a single sightline sample connects.

🪧 2-Sided Sign & Hanging Sign Back-Face Text Culling

Signs with text on both sides render font glyphs, kerning tables, and glow outlines on both faces simultaneously — even when looking at only one side.

• Normal Vector Dot-Product Math: Calculates the sign face normal vector across Wall Signs, Standing Signs, Ceiling Hanging Signs, and Wall Hanging Signs to automatically skip font rendering passes for whichever side faces away from the camera.
• Empty-Side Fast-Pass: Automatically detects blank/unwritten sign faces and skips text layout immediately with zero math overhead.
• 50% to 100% Draw Call Reduction on signs in storage warehouses and multiplayer towns.

✨ Particle & Animation Occlusion Culling

• Particle Occlusion: Raycasts particle sightlines against visual collision shapes with a 4.0-meter proximity safety bubble around the player's camera.
• TextureAtlas Animation Freezing: Freezes 3D block animations and skips off-screen texture atlas frame cycling when the game is paused or modal menus are open.

👥 Entity-Behind-Entity Culling (Crowd Overdraw Defense)

Dense mob farms and crowded pens are major FPS killers. Camera Culling detects when mobs are completely obscured behind closer, opaque mobs in front of them.

• Cluster Density Cap: Automatically caps rendered entities in tight 1.5-block clusters (default: 8 mobs per cluster), preventing rendering lag in cramming farms.
• 16-Meter Distance Fast-Fail: Completely bypasses crowd queries beyond 16 meters, ensuring zero CPU overhead in large open-field herds.
• Decorative & Small Mob Bypass: Transparent or small entities (Slimes, Magma Cubes, Vexes, Armor Stands, Item Frames) never block sightlines or occlude other mobs.

🎨 Entity Detail & Shadow LOD

Distant mobs don't need fully articulated outer model layers or heavy drop-shadows. Camera Culling features a decoupled distance detail engine:

• Secondary Render Layer Culling: Automatically skips secondary model layers (armor overlays, accessories, micro-attachments) on living entities beyond the configured LOD distance (default: 32.0m).
• Distance-Scaled Shadow Fade: Smoothly scales and fades entity shadow radii between start distance (32m) and far distance (48m), completely culling shadows on distant entities to reduce shadow quad draw overhead.
• Exemptions: Players, glowing entities, bosses, mini-bosses, and blacklisted mobs are completely exempt from detail LOD downscaling.

🛡️ Two-Tier Entity Immunity Blacklist

Want specific entities to never be culled under any circumstances? Camera Culling provides a robust two-tier blacklist system:

• Client Personal Blacklist: Stored locally in config/camera-culling.json. You can blacklist your favorite companions (e.g. minecraft:wolf, minecraft:allay, minecraft:cat).
• Server Admin Blacklist: Configured in config/camera-culling-server.json. Server operators can enforce server-wide entity immunity across all connected clients.
• Full Immunity: Blacklisted entities are 100% exempt from block occlusion culling, crowd overdraw culling, and detail LOD downscaling.

👑 Dynamic Boss & Mini-Boss Immunity

Never lose sight of dangerous foes. Camera Culling automatically identifies both vanilla and modded bosses & mini-bosses:

• Automatic Recognition: Protects Ender Dragons, Withers, Wardens, Elder Guardians, Ravagers, Iron Golems, Piglin Brutes, Evokers, Breezes, and modded champions/titans.
• Configurable Health Thresholds:
  • Major Boss Threshold: bossHealthThreshold (Default: 150.0 HP / 75 hearts).
  • Mini-Boss Threshold: miniBossHealthThreshold (Default: 50.0 HP / 25 hearts).
• Absolute Sightline Protection: Bosses and mini-bosses are never culled behind solid blocks, never culled by crowd caps, and never downscaled by detail LOD.

📦 Block Entity Occlusion Culling

• Enclosure Check: Automatically unrenders chests, signs, banners, skulls, and decorated pots that are fully surrounded on all 6 faces by solid opaque blocks.
• Line-of-Sight Check: Skips rendering when blocked from camera view on aggressive culling profiles.

⚙️ 4 Culling Intensity Profiles

• LOW (Conservative): 5.0m buffer, 7-point sampling, padded hitboxes.
• MEDIUM (Balanced): 3.5m buffer, 5-point sampling, culls all block entities.
• HIGH (Aggressive): 3.0m buffer, 3-point sampling, aggressive block entity culling, decorative entity culling.
• SUPER (Extreme — Default): 2.0m buffer, ultra-fast 2-point check for maximum FPS on modern systems.

📋 Quick Command Reference

All settings can be inspected and adjusted in-game via the /cameraculling command suite:

/cameraculling status                               → View live statistics, active level, and thresholds
/cameraculling toggle                               → Toggle culling on or off
/cameraculling set <low|medium|high|super>          → Change culling intensity preset
/cameraculling particles [true|false]               → Toggle particle occlusion culling
/cameraculling animations [true|false]              → Toggle block & texture atlas animation culling
/cameraculling crowdculling <true|false>            → Toggle crowd overdraw / entity-behind-entity culling
/cameraculling cluster <1-128>                      → Set cluster density cap for packed mob pens (default: 8)
/cameraculling entitylod [true|false]               → Toggle entity detail & secondary layer LOD
/cameraculling entitylod distance <4.0-256.0>       → Set entity detail LOD distance threshold (default: 32.0m)
/cameraculling texturlod <true|false>               → Alias for entity detail LOD toggle
/cameraculling bossimmunity <true|false>            → Toggle boss & mini-boss immunity
/cameraculling bosshealth <boss_hp> [miniboss_hp]   → Set major boss health threshold (default: 150.0 HP)
/cameraculling minibosshealth <miniboss_hp>         → Set mini-boss health threshold (default: 50.0 HP)
/cameraculling blacklist add <entity_id>            → Add mob to personal client immunity list (e.g. minecraft:wolf)
/cameraculling blacklist remove <entity_id>         → Remove mob from personal immunity list
/cameraculling blacklist list                       → List all personal blacklisted entities
/cameraculling blacklist clear                      → Clear personal immunity blacklist
/cameraculling serverblacklist add <entity_id>      → Add mob to server admin immunity list
/cameraculling serverblacklist remove <entity_id>   → Remove mob from server admin immunity list
/cameraculling serverblacklist list                 → List all server blacklisted entities
/cameraculling serverblacklist clear                → Clear server admin blacklist
/cameraculling debug [true|false]                   → Toggle real-time diagnostic tracing in chat & logs
/cameraculling reload                               → Reload configuration from disk

⚙️ Configuration File

Settings are saved directly to config/camera-culling.json:

{
  "enabled": true,
  "level": "SUPER",
  "cullEntitiesBehindEntities": false,
  "maxEntitiesPerCluster": 8,
  "entityDetailLod": true,
  "entityLodDistance": 32.0,
  "bossImmunity": true,
  "bossHealthThreshold": 150.0,
  "miniBossHealthThreshold": 50.0,
  "cullParticles": true,
  "cullAnimations": true,
  "cullSignText": true,
  "clientBlacklist": [],
  "debugMode": false
}

📦 Installation & Environment

⚛️ Environment Support

• ✅ Client-side only: All functionality is done client-side and is compatible with vanilla servers.
  • ✅ Works in singleplayer too
  • ✅ Compatible with any multiplayer server
• ❌ Server-side only: Server-only installation.
• ❌ Client and server: Requires installation on both sides.

📥 Install Instructions

1. Install Fabric API.
2. (Optional) Install ModMenu and YetAnotherConfigLib (YACL) for graphical settings.
3. Download the latest Camera Culling JAR for your Minecraft version and place it in your .minecraft/mods folder.
4. Launch Minecraft and enjoy smooth, optimized frame rates!

☕ Support

If you enjoy Camera Culling and the Vanilla Outsider philosophy, consider fueling the next update!

📜 Credits

📦 Modpack Permissions & Distribution: You are free to include this mod in any modpack on any platform. However, the mod itself must be downloaded from its official distribution pages on Modrinth or CurseForge. Re-uploading or redistributing official JAR files to third-party sites is strictly prohibited.

License & Forks: Since the source code is licensed under GNU GPLv3, you are fully permitted to fork the repository, make modifications, build your own versions, and distribute them under the terms of the GPLv3 as distinct projects.

Made with ❤️ for the Minecraft community
Part of the Vanilla Outsider Collection