Quick answer: Set no_depth_test = false to respect geometry depth. For nameplates that should always be visible but sort correctly relative to each other, use render_priority. For a constant on-screen size, enable fixed_size. Billboard mode determines which axes the label rotates on.

Here is how to fix Godot Label3D render depth wrong. You place a Label3D over an enemy’s head to show its name. The enemy walks behind a wall and the name is still visible, floating through the wall. Or you have dozens of nameplates and they flicker against each other. Godot’s Label3D ships with a set of defaults optimized for “always visible” UI-style labels, which is wrong for most in-world labeling.

The Symptom

A Label3D renders on top of everything regardless of world position. A text label placed at (0,0,0) shows over a wall at z = -10. Multiple Label3Ds at similar positions z-fight or blink. Adding a Camera3D at different angles shows labels popping in and out unexpectedly.

Variant: the label occludes correctly against some meshes but not others; or it respects depth in the editor but ignores it at runtime.

What Causes This

no_depth_test defaults to true. Label3D sets no_depth_test = true out of the box, which disables the depth buffer test for this object. It paints over anything regardless of Z. This is fine for UI overlays but wrong for world labels.

Transparent rendering bin. Text uses alpha blending, so Label3D lands in the transparent render bin. Transparent objects sort by distance to camera, not by z-buffer. Two close labels can z-fight unless one has a higher render_priority.

Billboard mode misalignment. With billboard = BILLBOARD_ENABLED, the label rotates each frame to face the camera. The bounding box changes shape, and cached culling info may be stale, producing pop-in.

fixed_size rescales after world scale. With fixed_size = true, the label is projected to screen and scaled so it is always N pixels tall. A label at z = -100 and z = -1 render at the same apparent size. Without depth test, both show at full alpha.

Outline rendering. Label3D outlines use a separate material. If you set no_depth_test on the text but not the outline (or vice versa), you get half-occluded labels where the outline clips but the text does not.

The Fix

Step 1: Turn off no_depth_test for world labels.

extends Label3D

func _ready():
    no_depth_test = false
    fixed_size = true
    billboard = BaseMaterial3D.BILLBOARD_FIXED_Y
    text = "Goblin (HP 24)"

With no_depth_test = false, the label respects the depth buffer. Walls in front of it occlude it. Behind it, other geometry is drawn correctly.

Step 2: Use render_priority for sorting. Even with depth test on, transparent objects at the same position sort by render_priority. Higher priority draws last (on top). For nameplates that should always be on top of trees but behind UI:

name_label.render_priority = 1      # above world
damage_number.render_priority = 2   # above names

Range is typically -128 to 127. Use small integers; large jumps are not necessary.

Step 3: Pick the right billboard mode. Three options:

For character nameplates, BILLBOARD_FIXED_Y is usually correct. Full billboard looks unnatural when you tilt the camera.

Step 4: Keep fixed_size on for readability. Without fixed_size, distant labels shrink to illegibility. With it on, the label occupies a constant pixel height and remains readable regardless of camera distance. Combine with pixel_size to tune the apparent text size:

label.pixel_size = 0.005   # smaller number = smaller label

Visibility Through Walls (On Purpose)

Sometimes you want labels visible through walls — for example, marking quest NPCs through fog of war. Use two Label3Ds on the same node: one opaque with no_depth_test = false for the normal case, one translucent with no_depth_test = true and lower alpha for the see-through case:

func _ready():
    $NameNormal.no_depth_test = false
    $NameNormal.modulate.a = 1.0

    $NameGhost.no_depth_test = true
    $NameGhost.modulate.a = 0.35
    $NameGhost.render_priority = -1

The ghost pass draws behind, so when the normal pass is occluded the ghost bleeds through faintly.

Outline Sync

Label3D’s outline_size renders the text with an outline. The outline respects the same depth-test flag as the main text, so they will occlude together. If you customize via StandardMaterial3D on the generated mesh, make sure depth settings are matched on both passes.

Understanding the issue

Render pipelines have ordering: which pass runs when, what state is bound, which targets are written. Bugs at this layer are often invisible in code review and only manifest at runtime.

The specific bug described above is the kind that surfaces during integration rather than unit testing. It depends on a combination of factors: the asset configuration, the runtime state, the platform's specific behavior. In isolation, each piece looks correct; in combination, the bug emerges. This is why thorough integration testing - playing the actual game in realistic conditions - catches things that automated tests miss.

Why this happens

Bugs of this class are particularly easy to ship past internal QA because they often depend on specific runtime conditions - hardware combinations, network states, or asset configurations that QA didn't reproduce. Players hit them in the wild, file reports that are hard to repro, and the bug accumulates negative reviews while engineering tries to recreate the failure mode.

At the engine level, the behavior comes from a deliberate design decision in Godot. The engine team chose a particular trade-off - usually performance versus convenience, or generality versus specificity - and that trade-off has consequences when you push against it. Understanding the trade-off is what turns 'this bug is mysterious' into 'this bug is the expected consequence of this design'.

Verifying the fix

Verifying this fix in isolation is straightforward: reproduce the bug, apply the change, confirm the bug no longer reproduces. The harder verification is regression - did this fix introduce a new bug elsewhere? Run your standard regression suite, plus any tests that exercise the same code path with different inputs.

Reproducibility is the prerequisite for verification. If you can't reliably reproduce the bug pre-fix, you can't reliably verify it post-fix. Spend time getting a clean reproduction before you write any fix code. The fix is fast once you understand the reproduction; the reproduction is the slow part.

Variations to watch for

There's almost always a less obvious case where the same problem applies. The reported case is the one a player hit; the related cases hide because they're rarer or affect fewer players. After fixing the reported case, search the codebase for the pattern - one fix often unlocks several.

Adjacent bugs often share a root cause. After fixing the case you've found, spend an hour searching the codebase for similar patterns. What's the same call with different arguments? The same data flow with a different entity type? The same lifecycle issue in a sibling system? Each match is a candidate for the same fix, or a related fix that prevents future bugs of the same class.

In production

Live games surface this bug class at scale. What's a rare edge case in development becomes a daily occurrence once you have a few thousand concurrent players. The class isn't 'this player has a unique setup'; it's 'one in N thousand sessions will trigger this exact combination'.

When triaging a similar issue in production, prioritize gathering data over hypothesizing causes. A player report describes a symptom; what you need is a build SHA, a session timestamp, and ideally a screen recording or session replay. With those, the bug becomes tractable. Without them, you're guessing at hypothetical reproductions that may not match what the player actually hit.

Performance considerations

If this issue manifests under high load (many actors, many particles, many network connections), profile the post-fix code path with realistic counts. The original cost was a bug; the new cost is real work, and real work has a budget.

Diagnostic approach

Before applying any fix, gather enough context to be confident you're addressing the actual cause and not a similar-looking symptom. The cheapest diagnostic step is reproducing the bug deterministically - if you can't get the same failure twice in a row, your fix attempts will be hard to evaluate. Lock down the reproduction first.

For Godot-specific diagnostics, the editor's profiler is the canonical starting point. Capture a representative frame with the symptom present; compare against a frame without the symptom; the diff often points directly at the cause. If the symptom is non-deterministic, capture multiple frames and look for the pattern - the cause is usually a state transition or a specific input value rather than a continuous effect.

Tooling and ecosystem

Third-party plugins often provide better diagnostics for their own behavior than the engine does. If the affected code is in a plugin, check the plugin's documentation for debug modes, verbose logging, or inspector tools - these can save hours of investigation when they exist.

Within Godot, the relevant diagnostic surfaces include the standard frame debugger, memory profiler, and engine-specific debug overlays. Each one shows a different facet of what's happening. The frame debugger reveals draw call ordering and state transitions; the memory profiler shows allocation patterns; the debug overlay reveals per-system state. Bugs that resist one tool usually surrender to another - the trick is knowing which tool to reach for first.

Edge cases and pitfalls

Boundary conditions deserve specific testing attention. What happens when the input is zero, maximum, negative, or NaN? What happens at the start of a session vs hours in? What happens at the boundary between two systems handling the same data? These are where bugs hide and where regression tests are most valuable.

When writing a regression test for this fix, focus on the boundary conditions that surfaced the original bug. Tests that exercise the happy path catch obvious regressions; tests that exercise the boundary catch the subtler regressions that look like new bugs but are really the original returning. The latter are the tests that earn their keep over the long life of the project.

Team communication

When this bug class affects multiple teams (often the case for cross-system issues), early communication prevents duplicate work. The team that owns the symptom may not own the cause. A 15-minute conversation at the start of triage often saves hours of independent investigation.

If this fix touches a system several engineers work in, a short writeup in the team's engineering channel helps. Not a full design doc - a paragraph explaining what was wrong, what's fixed, and what to watch for. Future engineers encountering similar symptoms will search for the fix; making it findable is a small investment that pays back later.

“no_depth_test = true is UI mode. For world labels, you almost always want it off.”

Related Issues

For 3D scene setup generally, see CharacterBody3D Wall Slide Jitter. For broader rendering questions, Viewport Mouse Position Offset covers related display topics.

no_depth_test off, fixed_size on, billboard fixed Y, render_priority for sorting. Labels occlude right.