# UI Creator Runtime (com.uigenx.runtime)

Runtime and editor support for UI built with the UI Creator studio.

- `Runtime/Core`: screen lifecycle (`UgxScreen`, `UgxDocument`, `UgxScreenManager`, `UgxScreenRegistry`).
- `Runtime/Binding`: data sources and the binding connector over Unity 6 runtime binding.
- `Runtime/Actions`: the action bus that carries UI events into game code.
- `Runtime/Animation`: keyframe clips for anything USS transitions cannot express.
- `Runtime/Effects`: material parameter binding, filters and RenderTexture sources for UI shaders.
- `Runtime/Bridge`: WebSocket client that talks to the local UI Creator daemon (development builds only).
- `Runtime/Protocol`: hand written DTOs for the daemon protocol. `Runtime/Protocol/Generated/` is
  reserved for a future TypeScript generator; the files in the folder root stay hand written.
- `Editor`: bundle importer with stable GUIDs, compile reporter, data schema reflector, settings.

Requires Unity 6000.0 or newer, .NET Standard 2.1 and `com.unity.nuget.newtonsoft-json`.

## Install

Add to `Packages/manifest.json`:

```json
"com.uigenx.runtime": "file:../../ui-creator/unity/com.uigenx.runtime"
```

The studio's `ugx init` offers to do this for you.

## Scripting define symbols

| Symbol | Effect |
| --- | --- |
| `UGX_BRIDGE` | Compiles `Runtime/Bridge` into a player build. |

Everything under `Runtime/Bridge` is wrapped in `#if UGX_BRIDGE || UNITY_EDITOR`, so a release build
contains no WebSocket client, no token handling and no preview renderer unless you ask for it. Add
`UGX_BRIDGE` under **Project Settings > Player > Scripting Define Symbols** for the build targets
where you want live preview in a development build, and leave it off for ship builds.

The bridge also refuses to start in a non development build: `UgxBridgeBehaviour` bootstraps only
when `Debug.isDebugBuild` or `Application.isEditor` is true, and only when `UgxSettings.bridgeEnabled`
is set.

## Configuration

| Where | What | Committed |
| --- | --- | --- |
| `Assets/<UiFolder>/Generated/Resources/UgxSettings.asset` | bridge on/off, daemon url, stream Hz, default `PanelSettings`, screen registry | yes |
| `ProjectSettings/UgxSettings.json` | relative path to the UI Creator project, UI folder, bridge on/off, stream Hz | yes, holds no secret |
| `<ugxProject>/.uigenx/daemon.json` | daemon url and pairing token, written by the studio | no |
| `Resources/UgxBridgeConfig.asset` | url, token and project id for a development build | no |

The token can also come from the command line with `-ugx-token <value>`, which is what CI uses so a
token is never committed. `-ugx-url <value>` overrides the daemon address the same way.

## Generated code

**[CONTRACT.md](CONTRACT.md) is the source of truth for what the compiler must emit.** Read it
before changing anything the generator produces or anything the runtime loads.

The compiler writes into `Assets/<UiFolder>/Generated/`:

```
Screens/Hud/Hud.uxml
Screens/Hud/Hud.uss
Screens/Hud/HudScreen.g.cs        partial class HudScreen : UgxScreen
Screens/Hud/HudActions.g.cs       action constants and typed subscribe helpers
UgxScreenFactory.g.cs             key to class switch, installs itself on load
Resources/UgxScreenRegistry.asset key, uxml, styles, class name, layer, panel
```

Import the **Minimal HUD** sample for a complete worked example of that contract.

## Editor menu

`Tools > UI Creator >` Connect, Disconnect, Sync now, Pull data schema, Rebuild screen registry,
Open studio, Dump theme, Open project settings.