> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D text

> Floating overhead text for /me-style channels, with per-channel duration and distance overrides.

Awoken Chat renders message bodies as 3D floating text above the sender's head when a category has `threeD = true`. The implementation is a faithful port of qbox's `qbx.drawText3d` with one addition: a per-player queue that stacks multiple concurrent lines in screen-space instead of overwriting via a single state-bag value.

## Global defaults

```lua config.lua theme={"dark"}
threeD = {
    renderDistance = 25.0,    -- metres
    durationMs     = 5000,    -- 5 seconds per line
    maxConcurrent  = 6,       -- per-player FPS guard
    verticalOffset = 0.0,     -- metres above ped origin
},
```

| Key              | Default | Effect                                                                                                                      |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `renderDistance` | `25.0`  | Camera-relative distance (metres) at which the 3D text appears. Beyond this it's culled.                                    |
| `durationMs`     | `5000`  | How long (ms) each line stays on screen before fading out. Per-payload overrides are clamped client-side to `[250, 60000]`. |
| `maxConcurrent`  | `6`     | Max stacked lines per player. If a player spams `/me` fast, the queue drops the oldest line when it overflows.              |
| `verticalOffset` | `0.0`   | Metres above the ped origin to anchor the text. Bump positive if your peds have low transforms.                             |

<Tip>
  `renderDistance` is the **global** default. Per-fun-command override lives in `funCommands.renderDistance`; per-message override travels on the payload itself (set by the server when a fun-command-style send is made).
</Tip>

## Per-channel overrides

Categories can opt out of the global defaults. Available in the Category Manager → **3D Text** section, or directly in the `awoken_chat_categories` JSON.

| Field               | Type       | Effect                                                                                                                                                              |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `threeD`            | `boolean?` | Master switch for that channel. If `true`, every message in the channel renders as 3D text in addition to the chat row.                                             |
| `threeDOnly`        | `boolean?` | With `threeD = true`, **suppress the chat row** - the 3D text is the only visible surface. Server still persists + webhooks the message; the audit trail is intact. |
| `threeDDurationSec` | `number?`  | Seconds the 3D text stays on screen for this channel. Clamped client-side to `[0.25, 60]`. `nil` = use `cfg.threeD.durationMs`.                                     |