Generative UI and OSC Control for Unity.
This plugin allows you to simply create a UI for your application, exposing script sliders, input fields and methods. This UI is also fully controllable via OSC, and accessible locally via a web browser.
| Requirement | Notes |
|---|---|
| Unity 2022.3 or later | Set by the Input System dependency below. |
| com.unity.inputsystem | No fallback to the legacy input backend, so set Project Settings > Player > Active Input Handling to Input System Package or Both. |
| com.theoriz.ocf 3.0.0 or later | GenUI is the UI layer on top of OCF; the control model, OSC addressing and presets all live there. |
| com.theoriz.unityosc 1.3.0 or later | OCF's transport. Earlier versions still work but declare Unity 2019.4. |
The packages declare no UPM dependencies, so nothing installs them for you and nothing warns you when a version is too old — install all three, in the order below.
Add the following line to your project's Packages/manifest.json:
{
"dependencies": {
"com.theoriz.unityosc": "https://github.com/Theoriz/UnityOSC.git",
"com.theoriz.ocf": "https://github.com/Theoriz/OCF.git",
"com.theoriz.genui": "https://github.com/Theoriz/GenUI.git"
}
}Or in the Unity Editor, go to Window > Package Manager > + > Add package from git URL and enter:
https://github.com/Theoriz/UnityOSC.git
then
https://github.com/Theoriz/OCF.git
then
https://github.com/Theoriz/GenUI.git
- F1 : Toggle the UI.
- PageUp / PageDown, or Ctrl + Plus/Minus (numpad included) : Scale up/down the UI, only when the UI is visible.
- Ctrl + Left/Right/Up/Down arrow : Move the UI, only when the UI is visible.
- F2 : Reset the UI, only when the UI is visible.
- Tab / Shift + Tab : Move to the next/previous input field, selecting its text so you can type over it.
- Ctrl + Z : Undo the last value you changed in the UI. A whole slider drag, label scrub or colour pick undoes in one press. Values arriving over OSC, and members restored by loading a preset, are not undone.
- Drag a numeric member's label left/right : Scrub its value, one label per vector axis, with Shift for coarse steps and Ctrl for fine ones.
- Drag the panel's right edge, or its scrollbar left/right : Resize the panel. Dragging the scrollbar up/down scrolls.
Scaling is ignored while you are typing in an input field.
- In the toolbar go to Theoriz -> GenUI -> Add GenUI to Scene. It adds the GenUI prefab, plus an EventSystem if the scene has none.
Note
The UI needs an EventSystem to receive input, but GenUI does not provide one itself. If you add the GenUI prefab from the Samples folder manually instead, add an EventSystem yourself via GameObject -> UI -> Event System.
- Generate controllables for the scripts you want to control using the controllable generation described below.
- Run the scene, press F1 to toggle the UI.
The UI draws as a Screen Space - Overlay canvas by default. To put it in the world or in front of a camera, change the Render Mode on the GenUI prefab's Canvas as for any Unity canvas: in World Space, give its RectTransform a size and a scale (e.g. 1920x1080 at 0.002) and place it in the scene, leaving Event Camera empty to use the main camera. The scaling shortcuts then scale that transform and F2 puts it back.
- In your MonoBehaviour script, add the [OCFExposed] attribute to the fields, properties and methods you want to expose to the UI and OSC.
Tip
You can set some fields or properties as read only by using [OCFExposed(readOnly = true)].
- On the script component of your script in your scene, click on the three dots on the top right and choose Add Controllable. It will prompt you to generate a Controllable script, click Generate. Once compilation finishes, the Controllable component is added automatically.
Tip
You can also generate a controllable directly from the project window by right-clicking on a script and choosing Generate Controllable Script.
On the GenUI object, the UI Master component holds the settings that apply to the whole interface.
| Field | Default | Effect |
|---|---|---|
Auto Hide Cursor |
on | Hides the mouse cursor while the UI is hidden. Ignored in the Editor, where the cursor always stays visible. |
Hide UI At Start |
on | Tick to start with the UI hidden; F1 still brings it up. |
Enable UI Movement |
on | Uncheck to pin the UI in place, disabling the Ctrl + arrow shortcuts. Scaling and F2 keep working. |
To control the look of a Controllable's panel in GenUI, add a GenUI Panel Settings component next to the Controllable. You can do this by clicking the three dots on the Controllable and choose Add GenUI Panel Settings.
| Field | Default | Effect |
|---|---|---|
barColor |
a color derived from the controllable's ID | Color of the panel's title bar. |
usePanel |
on | Uncheck to give this controllable no panel at all. It stays controllable over OSC. |
closePanelAtStart |
on | Uncheck to have the panel start open. |
panelOrder |
0 | Lower values sit higher in the stack. |
The component is optional: a Controllable without one draws its panel with the defaults above, already colored from its ID.
Panels are ordered by panelOrder, lowest first, then alphabetically by ID; the GenUI panel always stays on top. Its ID, GenUI, is reserved: a Controllable of your own asking for it is refused and left unregistered, so give it another ID and a low panelOrder if you want it near the top.
You can expose the following types :
- bool
- int
- float
- string
- Vector2
- Vector2Int
- Vector3
- Vector3Int
- Vector4
- Color
- any enum
An enum renders as a dropdown of its members — see Exposing an enum in the OCF documentation. A [Flags] enum is the one exception: it logs a warning and draws no widget, because one dropdown cannot represent a combination of members. It is controllable over OSC.
The Header, Range, and Tooltip attributes are also supported in Controllables. A Tooltip shows when the pointer rests on the member's name, as in the Inspector.
A member is labelled with its name split into words (fadeDuration → "Fade Duration"), or with its displayName when [OCFExposed] sets one — see the OCF options.
A Color member is drawn as a swatch; left-clicking the swatch opens the picker. It holds a saturation/value square, a hue bar, an alpha bar, an R/G/B/A row and a hex field.
The channel boxes and the hex field are both 0–255. The hex field accepts #RGB, #RRGGBB and #RRGGBBAA, with or without the leading #.
A member marked [OCFExposed(readOnly = true)] is drawn as a display: its value with no box around it, nothing to click or type into. Read-only members are also left out of presets, and have no Copy OSC Control Address menu, since that address cannot control them.
A method without parameters shows as a button in the UI. A method with parameters gets no button, but is still callable over OSC.
To pick a value from a list of strings, keep the List<string> on your script and point a string member at it by name with [OCFExposed(targetList = "myList")]. It renders as a dropdown that writes the selected entry into that member.
The entries are re-read each time the dropdown opens, so a list that changed while the app runs is up to date. If the member holds a value the list does not offer — your script assigned it, or the entry has since gone — the dropdown shows that value as a trailing entry.
See Exposing a list in the OCF documentation for a full example.
To access a property or launch a method, use its address.
For example : "/OCF/id/method" or "/OCF/id/floatProperty 1.5". By default the id corresponds to the script type name, but this can be changed by setting the public variable controllableId on your script extending "Controllable".
Tip
You can copy the OSC Control Address of any exposed parameter by right clicking anywhere on its row.
GenUI listens on port 6001. If another application already holds it, the Controllable Master component on the GenUI object retries on the next port up:
| Field | Default | Effect |
|---|---|---|
Incremental Connect |
on | If the input port is busy, increment it and retry. Uncheck to fail on 6001 instead. |
Max Connect Attempts |
60 | How many ports to try before giving up with a warning in the Console. |
The port actually opened is printed in the Console at start, and advertised over Zeroconf/Bonjour, so send your OSC there rather than assuming 6001 if you use Incremental Connect.
This plugin comes with a preset system, you can save the state of a "Controllable" script. It saves each property to a file that can be loaded later so that you can create different settings for your script. To use it, click "Save", then simply select a preset in the dropdown menu — selecting it loads it immediately.
Each panel has "Save", "Save As", "Load" and "Show" buttons plus the preset dropdown, at the bottom of the panel. "Show" reveals the selected preset in your file browser, or its folder when no preset is selected. The GenUI panel has "Save All", "Save As All" and "Load All" to apply the same action to every controllable at once.
It is also possible to load a specific file via the OSC method "ControllableLoadWithName", giving it the case-sensitive file name as its argument :
/OCF/id/ControllableLoadWithName "myPreset.pst"
Presets go under the Documents directory by default. The Controllable Master component on the GenUI object has two fields to change that:
| Field | Default | Effect |
|---|---|---|
Use Documents Directory |
on | Presets live in Documents/<product name>/Presets. Untick to keep them next to the application instead. |
Custom Preset Directory |
empty | An absolute path to keep presets in, overriding the above. A relative path is rejected with an error and the default is used. |
The -presetsPath "<absolute path>" command-line argument wins over both. See Where presets are stored in the OCF documentation for the full folder layout.
The panel can also be served to a browser, so a phone or a laptop on the same network drives the same values. On the GenUI object, tick Enable Web Server on the GenUI Web Server component, press Play, and open http://<the machine's IP>:6080 — the port is printed in the Console at start. The page needs no internet connection. Ticking the option during Play starts and stops the server there and then, and editing the port restarts it on the new one — connected browsers have to be reloaded.
The same two options sit in the GenUI panel and answer to OSC as /OCF/GenUI/enableWebServer and /OCF/GenUI/webServerPort, so the server can be switched on while the app runs.
Panel, browsers and the target script stay in sync in all directions: whatever changes anywhere shows everywhere.
Dragging a numeric member's label sideways scrubs its value there too, with the same Shift and Ctrl modifiers. On a phone, dragging a label up or down still scrolls the page.
Warning
There is no password and no HTTPS. Anyone who can reach that port can change every exposed value and press every button, so leave the option off unless you are on a network you trust.
The browser is a mirror, not a copy. It draws the same rows from the same style values, with these differences:
- No Ctrl + Z.
- Right-clicking a row shows its OSC control address ready to copy, rather than copying it.
- Tooltips are the browser's own rather than drawn by GenUI; both show on the member's name.
The interface is built from code, not from prefabs. Every size and colour comes from GenUIStyle, and the sprites and fonts come from the GenUIAssets asset in Resources. Changing a row height, a tint or the font in one of those two places applies to every widget at once, and to the web mirror with it.
Do not reuse a name that "Controllable" already declares. The generated Controllable inherits from "Controllable", so a member of the same name shadows the real one and breaks it. The generator refuses these and tells you which member to rename. See Reserved names in the OCF documentation.
GenUI is GPL-3.0; see LICENSE. The fonts it ships are third-party — see THIRD-PARTY-NOTICES.md.