26.3 Debug Logging and Diagnostics

🔍 Debug Logging & Diagnostic Tracing (Minecraft 26.3)

Camera Culling includes an in-game diagnostic logging and real-time state transition tracing engine to enable players and modpack developers to monitor exactly when and why entities are rendered or culled.

---

📋 Diagnostics Infobox

Property	Value
Command Toggle	`/cameraculling debug [true
GUI Toggle	"Real-Time Debug Logging" in Engine & Diagnostics category
Default State	false (Zero string allocations on hot render paths)
Chat Output	Color-coded §6[CC-Debug] state transition notifications
Log Output	SLF4J logger output under [CameraCulling Debug] tag

---

🔬 State Transition Logging Architecture

When debug mode is enabled, CullingDiagnosticsHelper captures every state transition (Visible $\leftrightarrow$ Culled) as entities cross sightlines:

[CC-Debug] §c[CULLED] §eminecraft:cow #412§7 (dist: §f18.4m§7) -> §bBlock Occlusion
[CC-Debug] §a[VISIBLE] §eminecraft:zombie #891§7 (dist: §f12.1m§7) -> §bSightline (Eyes)
[CC-Debug] §a[VISIBLE] §eminecraft:wolf #204§7 (dist: §f6.2m§7) -> §bBlacklist Immunity
[CC-Debug] §a[VISIBLE] §eminecraft:warden #102§7 (dist: §f34.8m§7) -> §bBoss Immunity

Transition Reasons Documented

1. Sightline (Head Top) — Visible via head top raycast sample.
2. Sightline (Eyes) — Visible via anatomical eye sample.
3. Sightline (Upper Torso) — Visible via upper chest sample.
4. Sightline (Center) — Visible via midpoint sample.
5. Sightline (Flank) — Visible via perimeter flank sample.
6. Proximity Safety Bubble — Within min distance margin.
7. Boss Immunity — Protected by boss HP threshold or keyword.
8. Blacklist Immunity — Whitelisted in client or server blacklist.
9. Player / Vehicle Immunity — Local player, passenger, or mount.
10. Glowing Immunity — Entity has active glowing effect.
11. Crowd / Mob Overdraw Occlusion — Exceeded local cluster density cap.
12. Block Occlusion — All sightline samples occluded by solid blocks.

---

⚡ Zero-Allocation Hot-Path Guard

To maintain maximum FPS, debug string formatting and message generation are completely bypassed when debugMode is false:

public static boolean isDebugEnabled() {
    return CameraCullingConfig.isDebugMode() || LOGGER.isDebugEnabled();
}

public static void logStateTransition(Entity entity, Vec3 camPos, boolean nowOccluded, String reason) {
    if (!isDebugEnabled()) {
        return; // Zero string formatting or object creation when disabled
    }
    ...
}

---

🔗 Related Pages

• Commands & Configuration
• Temporal Hysteresis & Math
• Return to MC 26.3 Overview