---
title: "Screens, values, events, and actions"
description: "Quartz UI 0.57.0-dev: Screens, values, events, and actions. Source-reviewed guidance, usage and limitations."
status: approved
visibility: public
sourceRevision: fe5b709ec900e282b50e58b819a25041945005f9
reviewedAt: 2026-09-24
---

# Screens, values, events, and actions

> **0.57.0-dev · beta source documentation.** Native, Blueprint, Editor and rendering examples are source-reviewed, not executed in Unreal during this scan. See [validation and limits](https://betterbuilt.games/docs/quartz-ui/evidence).

Prerequisite: the [first UI](https://betterbuilt.games/docs/quartz-ui/first-ui) is configured, and you have the exact `ULocalPlayer` or local PlayerController. `FQuartzUI` and `UQuartzUIBlueprintLibrary` are the high-level gameplay facade. They handle the shell and bridge; gameplay does not construct Chromium objects.

## Change screen and input together

```cpp
FQuartzUIInputConfig Input;
Input.InputMode = EQuartzUIInputMode::UIOnly;
Input.MouseCaptureMode = EMouseCaptureMode::NoCapture;
const bool bShown = FQuartzUI::ShowScreen(Player, TEXT("menu.pause"), Input);
```

The native call publishes screen intent; your frontend must render the intended screen. It does not navigate to another HTML file, mount a React route automatically, or author the menu for you. Subscribe to `quartzui.shell`, whose `screen` field contains that intent. Call `ApplyInputPolicy` when only input ownership changes. Handle false results and use the failure nodes instead of assuming a call created a shell.

## State is a snapshot; an event is a moment

`SetBoolValue`, `SetIntegerValue`, `SetFloatValue`, `SetTextValue`, and `SetNameValue` publish a named object with a `value` member. `PublishStruct` copies a data-only Unreal struct; `PublishJsonState` accepts bounded object JSON. Latest state survives packaged navigation and is coalesced by name. `EmitStructEvent`, `EmitJsonEvent`, and `ShowNotification` are transient.

```cpp
FQuartzUI::SetTextValue(Player, TEXT("hud.location"), NSLOCTEXT("Game", "Garage", "Garage"));
FQuartzUI::EmitJsonEvent(Player, TEXT("race.started"), TEXT("{}"));
FQuartzUI::ShowNotification(Player, NSLOCTEXT("Game", "Saved", "Saved"), TEXT("save.complete"));
```

On the page:

```js
const stopLocation = client.subscribeState('hud.location', value => {
  if (typeof value.value === 'string') locationElement.textContent = value.value;
});
const stopRace = client.subscribeEvent('race.started', () => showStartAnimation());
// When this screen/component leaves:
stopLocation();
stopRace();
```

`locationElement` and `showStartAnimation` are project UI objects. Strictly validate domain payloads; the transport validates envelopes, not your game's semantics. State subscriptions replay retained data immediately; event subscriptions do not. Do not use an event for health that a newly mounted component must display.

After shell creation but before Ready, state coalesces and events queue within the existing bounds: 128 state names, 64 queued events, 256 KiB UTF-8 envelopes. Suspension pauses delivery; it does not make buffers unbounded. Check publication results and avoid frame-by-frame unchanged data.

## Let a button request an allowed action

Register a native handler for an explicit project name:

```cpp
FQuartzUI::RegisterNativeAction(Player, TEXT("menu.continue"),
    FQuartzUINativeNamedActionHandler::CreateLambda([](FName ActionName)
    {
        // Invoke your authoritative resume operation here.
    }));
// On owner teardown:
FQuartzUI::UnregisterAction(Player, TEXT("menu.continue"));
```

Use weak UObject delegate bindings for real gameplay owners; do not capture an actor raw pointer in a long-lived lambda. Registration authorizes a handler. `SetActions` separately supplies the visible action-bar catalog (`FQuartzUIBoundAction`: name, localized label, priority, enabled/display flags, hold duration). A visible label alone does not register gameplay authority.

```js
try {
  await client.request('quartzui.action', { action: 'menu.continue' });
} catch (error) {
  showActionError(error.code ?? error.message);
}
```

This generic request exists in the shipped transport. Convenience methods such as `client.invokeAction()` are not exported here. Both named-action registrations and catalogs are capped at 64. `quartzui.*` is reserved for middleware; game names use bounded lowercase names such as `inventory.drop`.

## React components

The app supplies React 18+ and React DOM, a lockfile, and a production bundle. Copy/bundle `react.mjs` and `react-store.mjs` beside the transport. Create one client and one React root per document, outside component renders.

```jsx
import { useQuartzUIState } from './quartzui/react.mjs';
function Ammo({ client }) {
  const state = useQuartzUIState(client, 'hud.ammo');
  return <output>{Number.isInteger(state?.value) ? state.value : '—'}</output>;
}
```

The hook uses a stable immutable retained snapshot. `createStateStore(client, name)` is available for advanced external-store integration. Effects that subscribe to transient events must return their unsubscribe function. Unmount the root and subscriptions before disposing the document client. Keep drafts and focus stable during unrelated snapshots, and verify Strict Mode setup/cleanup/setup in the host frontend.

Do not ship bare `react` imports, JSX, or a dev-server dependency in the game. CSS/DOM markup, roving focus, action-bar rendering, and domain decoders remain project work.

## Smooth an authoritative timer

`PresentationClock` from `presentation-clock.mjs` interpolates between native samples. Call `sample(seconds, phase, finished, nowMs)` on each update, and `read(nowMs)` in the timer's animation loop. Only `Running` interpolates; pause/reset/finish snap. It holds at the latest sample when updates stop and introduces up to one sample interval of presentation delay. Cancel the animation loop on unmount; never send its display estimate back as simulation time.

All native fragments are unexecuted during this scan. Facade source (source: `Source/QuartzUIRuntime/Public/QuartzUIBlueprintLibrary.h`), original gameplay guide (source: `Documentation/SimpleGameUI.md`), React adapter (source: `Resources/Client/react.mjs`).

Canonical HTML: https://betterbuilt.games/docs/quartz-ui/gameplay