> For the complete documentation index, see [llms.txt](https://docs.sonoransoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonoransoftware.com/store/sonoran-station-displays/performance.md).

# Performance

## Shared data design

Sonoran Station Displays does not poll SonoranCADFiveM once per television.

```
SonoranCADFiveM exports/events
→ one normalized server cache
→ full sync or shared incremental deltas
→ one client cache
→ per-display filtering
→ nearby DUI renderers
```

Unit and call polls are centralized. Display count does not multiply server export calls.

## DUI lifecycle

Every client checks display distance twice per second.

When a display enters range:

1. The object model loads.
2. A frozen display object is created.
3. One 1280×720 DUI and runtime texture are created.
4. The current filtered state is sent.
5. The surface is drawn while active.

When it leaves range, the client waits three seconds, then deletes the object and DUI. The internally managed delay prevents repeated create/destroy cycles near the boundary and is canceled if the display becomes relevant again.

Object and DUI cleanup also runs when the resource stops.

## Pool limit

`Config.MaximumActiveDuis = 8` is a hard per-client limit. If the limit is reached, additional in-range displays cannot create a DUI until capacity becomes available.

Keep no more than eight displays inside one client's render range with the default configuration. For low-end clients or large 3D interiors, use fewer. This is a resource limit, not a tested player-count claim.

## Render distance

Default:

```lua
Config.RenderDistance = 75.0
```

Per-display range:

```
5–250 meters
```

Use the shortest distance that allows the intended viewing area. A longer distance:

* Creates objects and DUIs earlier
* Keeps them alive longer
* Makes dense placements more likely to reach the pool limit
* Increases the number of surfaces drawn each frame

## Incremental updates

The server compares normalized cache records by ID.

* Added, changed, and removed records become incremental client deltas.
* Identical record content does not receive another delta.
* The DUI receives a full display-state payload only when state changes, on explicit refresh, or on a page change.
* Rotation progress state is checked at most once per second; the browser animates smoothly between messages.

Coordinates use the same unit delta stream. There is no per-screen coordinate loop.

## Recommended intervals

| Setting                      | Default    | Guidance                                                               |
| ---------------------------- | ---------- | ---------------------------------------------------------------------- |
| `UnitRefreshInterval`        | 2000 ms    | Keep at 2 seconds unless a measured integration issue requires change. |
| `CallRefreshInterval`        | 3000 ms    | Keep at 3 seconds for normal call volumes.                             |
| `DefaultRotationInterval`    | 30 seconds | Page presentation only; does not affect cache freshness.               |
| `Bodycams.refreshIntervalMs` | 1000 ms    | Runtime polling fallback; bodycam events can update sooner.            |

Push events already request early refreshes. Lower polling intervals increase export calls and delta processing without making every upstream CAD change arrive sooner.

## Interface resolution and row limits

The internally managed interface resolution is 1280×720. Customers should control resource use with render distance, active-DUI capacity, and row limits rather than editing protected resolution or lifecycle values.

Higher unit/call limits increase the number of DOM rows and cards. Automatic 10-second list pagination provides a better layout than very large page limits.

## Live Map cost

The map redraws its canvas when state changes and projects every visible marker. To reduce cost or clutter:

* Disable call markers on displays that do not need them.
* Reduce the number of displays simultaneously showing the map.
* Keep the default DUI resolution.
* Reduce render distance in dense stations.

`MapRefreshInterval` is not active in version 1.0.0, so changing it does not affect cost.

## Bodycam cost

Bodycam tiles are materially more expensive than unit/call pages because they decode periodic JPEGs. One active subscribed officer captures at most once every 4 seconds, and all eligible displays reuse that same latest frame.

Frames are capped at 300 KB. At the hard limit, one feed averages about 75 KB/s and four feeds about 300 KB/s per viewer before overhead. In busy areas:

* Prefer `SINGLE` or a lower per-page feed limit.
* Keep bodycam displays behind short, intentional render distances.
* Avoid several overlapping displays when one screen serves the audience.
* Place bodycam displays only where the intended audience can approach them.
* Increase bodycam pagination time rather than raising the four-feed ceiling.
* Use diagnostics to measure average/max frame size and upload duration.

## Routing buckets and interiors

A display with a saved routing bucket is created only when the client's local bucket matches. A display with an interior ID is created only when the player's current interior matches.

These checks prevent irrelevant objects and DUIs in other world contexts. New displays automatically capture a nonzero interior ID.

## Diagnose high client usage

1. Open `/stationdisplay`.
2. Select **Mounted Displays → View Diagnostics**.
3. Check **Active DUIs** and **Nearby Displays**.
4. Compare active DUI count with `MaximumActiveDuis`.
5. Move outside render distance and verify the count drops after the destroy delay.
6. Check whether several displays overlap at high render distances.
7. Temporarily reduce render distances or call markers and retest.
8. Check the client F8 console for repeated DUI/model errors.

Do not use page rotation speed as a data-refresh control.

## Release testing

Before deployment, test:

* One and several identical model instances with different content
* Pool limit and out-of-range cleanup
* Resource restart and player join
* CAD present, stopped, restarted, and incompatible
* Routing buckets and interiors
* Long labels and maximum row counts
* Auto-fit, fixed-region, and follow-units maps
* Bodycam single/grid/focused layouts, activation, subscription limits, connecting/live/delayed/failed/offline states, and cleanup
* One/four bodycams, two displays sharing a feed, two viewers, missing `screenshot-basic`, malformed/oversized frames, restarts, and bandwidth
* The server's representative client hardware and map assets

The source repository's static checks cannot verify native DUI orientation, model offsets, OneSync contexts, or client performance inside FiveM.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonoransoftware.com/store/sonoran-station-displays/performance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.