> For the complete documentation index, see [llms.txt](https://alexdev-s-organization.gitbook.io/unlimitednametags/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alexdev-s-organization.gitbook.io/unlimitednametags/features/show-while-looking.md).

# Show while looking & through-wall

These features provide advanced visibility control for player name tags based on a viewer's line of sight and crosshair target direction.

***

## 🎯 Show While Looking

When `showWhileLooking` is enabled, player name tags are only rendered to a viewer if they aim their crosshair directly at the target player. The name tag despawns the moment the viewer looks away. All standard visibility filters (permissions, vanish integrations, world list constraints) still apply.

![Visual demonstration of the name tag appearing only when the player's crosshair is aimed directly at the target player](https://1998043917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXFajS60IVNJP9RE0gA9h%2Fuploads%2Fgit-blob-f293f76a1b9dbb3964dcef4ef32e57983af8010e%2Fshow-while-looking.gif?alt=media)

### Enabling Show While Looking

```yaml
visibility:
  showWhileLooking: true
```

***

## 🔍 How Visibility Checks Work

The plugin performs synchronous raycast calculations on the main server thread at intervals defined by `taskInterval` for every active viewer/player pair within tracking distance.

> \[!WARNING] Because raycasting is performed on the primary server thread, enabling `showWhileLooking` on high-population servers increases CPU load. If server TPS decreases after enabling this option, refer to the [Performance Tuning Guide](/unlimitednametags/performance.md) — raising the global `taskInterval` value is the primary method to mitigate load.

***

## Companion Feature: Through-Wall Occlusion (`throughWallMode`)

The `throughWallMode` setting provides advanced visibility check options when the line of sight between the viewer and target is blocked by solid blocks.

* **`SEE_THROUGH`** (Default): Vanilla behavior; name tags remain fully visible through walls.
* **`OBSCURED`**: Dims the name tag to a specified opacity when behind walls.
* **`HIDE`**: Completely hides the name tag display when behind walls (acts as a built-in anti-wallhack).

> \[!NOTE] `throughWallMode: SEE_THROUGH` controls whole-tag visibility behind walls. It is **not** the same as per-row `background.seeThrough`. See [Limitations](/unlimitednametags/limitations.md#background-see-through).

### `throughWallMode` vs. `background.seeThrough`

These two options are often confused, but they control different layers:

| Option                           | Scope                    | What it does                                                                                                                                   |
| -------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **`visibility.throughWallMode`** | Global visibility system | Decides whether the whole name tag stays visible, is dimmed, or is hidden when the viewer's line of sight is blocked.                          |
| **`background.seeThrough`**      | Per `TEXT` display group | Enables Minecraft's text-display see-through flag for that row, so the text can render through opaque block geometry while the row is visible. |

Interaction rules:

* `background.seeThrough: true` is honored only when `throughWallMode: SEE_THROUGH` and the owner is not sneaking.
* `throughWallMode: OBSCURED` manages see-through internally: clear line of sight uses normal rendering; blocked line of sight enables see-through and applies `throughWallSettings.opacity`.
* `throughWallMode: HIDE` despawns/hides the tag when blocked, so `background.seeThrough` cannot make it visible through walls.
* `ITEM` and `BLOCK` display groups are not affected by `background.seeThrough`; through-wall opacity/see-through presentation applies to `TEXT` rows.

### Interaction Matrix

| Configuration State                                               | Rendering Behavior                                                                                                     |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **`showWhileLooking: true` + `throughWallMode: SEE_THROUGH`**     | The tag is only visible when the viewer aims their crosshair directly at the target player.                            |
| **`showWhileLooking: false` + `throughWallMode: OBSCURED`**       | The tag remains visible continuously, but dims in opacity when line of sight is blocked by solid geometry.             |
| **`showWhileLooking: false` + `throughWallMode: HIDE`**           | The tag remains visible when there is clear line of sight, but is completely despawned when behind walls.              |
| **Both features enabled (`showWhileLooking: true` + `OBSCURED`)** | The tag only renders when targeted, and will render with reduced opacity if the sightline passes through solid blocks. |
| **Both features enabled (`showWhileLooking: true` + `HIDE`)**     | The tag only renders when targeted and if there is a clear, unobstructed line of sight.                                |

***

## Through-Wall Settings

```yaml
visibility:
  throughWallMode: OBSCURED        # Options: SEE_THROUGH, OBSCURED, HIDE
  throughWallSettings:
    opacity: 55                    # Alpha value (0–127) when sightline is blocked
    maxDistance: 48.0              # Maximum block radius for evaluation
    checkInterval: 5               # Check frequency in ticks
```

| Option                                  | Default       | Description                                                                                                          |
| --------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| **`throughWallMode`**                   | `SEE_THROUGH` | Direct line-of-sight mode. Set to `OBSCURED` to dim tags, or `HIDE` to completely remove them behind solid geometry. |
| **`throughWallSettings.opacity`**       | `55`          | The opacity value (from `0` to `127`) applied to the display when the sightline is obstructed in `OBSCURED` mode.    |
| **`throughWallSettings.maxDistance`**   | `48.0`        | The maximum distance (in blocks) for the check. Beyond this distance, through-wall calculations are skipped.         |
| **`throughWallSettings.checkInterval`** | `5`           | Ticks between raycast updates. This runs synchronously on the main thread.                                           |

> \[!WARNING] Both `showWhileLooking` and through-wall checks execute raycast calculations on the **primary server thread**. Through-wall occlusion settings are applied to `TEXT` display groups only. On high-population servers, it is highly recommended to increase `throughWallSettings.checkInterval` to `10` or `20` ticks to prevent performance degradation.

***

## Performance Best Practices

* **Adjust Intervals**: Raise `behavior.taskInterval` (e.g., to `40` ticks) to reduce the computation frequency of `showWhileLooking`.
* **Settle Check Timings**: Set `throughWallSettings.checkInterval` between `10` and `20` ticks. This change is virtually unnoticeable to players but significantly reduces CPU overhead.
* **Disable Unused Toggles**: Keep `showWhileLooking` set to `false` and `throughWallMode` set to `SEE_THROUGH` if they are not actively utilized; they consume no resources.

For detailed performance steps, refer to the [Performance Tuning Guide](/unlimitednametags/performance.md).

***

## Common Use Cases

* **Minigames & Competitive Maps**: Displays team names only when targeted, minimizing UI clutter on screen.
* **Roleplay & Immersive Servers**: Hides name tags at long distances to protect immersion, revealing them only when focusing on a player.
* **Tactical & PvP Servers**: Through-wall dimming prevents players from tracking opponents through solid walls using floating name tags, without completely disabling name tag visibility.