> For the complete documentation index, see [llms.txt](https://doc.realvirtual.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.realvirtual.io/components-and-scripts/scene-interaction/runtime-metadata.md).

# Runtime Metadata (Pro)

Attach part information to 3D objects and search, highlight and inspect it at runtime

## Overview

Runtime Metadata attaches information to the parts of your 3D model: article numbers, technical data, live PLC signal values and links to documents. At runtime the operator searches this information in a toolbar at the bottom of the screen. Matching parts are highlighted in the 3D scene and show their data in a small window.

The system consists of three building blocks:

* **Runtime Metadata** – the component on each part. It holds the information as a short tagged text.
* **Metadata Manager** – one per scene. It provides the search toolbar and controls which parts are highlighted and which windows are shown.
* **Excel Metadata Setup** – optional. It creates the Runtime Metadata components for a whole CAD assembly from a part list.

The same content is exported with the GLB and used by realvirtual WEB for hover tooltips and for linking parts to their documents. See [Building a 3D-HMI](/extensions/realvirtual-web/3d-hmi.md).

{% hint style="warning" %}
The runtime windows and the search toolbar are built with the Unity **App UI** package. Import its **UI Kit** sample once per project (**Window → Package Manager → App UI → Samples → UI Kit → Import**). Without it the windows appear as empty dark boxes and the Console shows *"No Theme Style Sheet set to PanelSettings"*.
{% endhint %}

## Quick Start

1. Drag the **MetadataManager** prefab from *Packages/realvirtual Professional/RuntimeUISystem* into your scene. It already contains the **UIManager** that renders the windows.
2. Select a part and add the **Runtime Metadata** component. **Runtime UI Window** and **Runtime Interactable** are added automatically.
3. Write the part information into the **Content** field (see [Content Syntax](#content-syntax)).
4. On **Runtime Interactable**, assign a highlighter to **Base Highlight** and **Hover Highlight**, for example *realvirtual/Highlighter/Highlight 1* and *realvirtual/Highlighter/Outline*.
5. Start play mode, type a search term into the toolbar at the bottom and press **Enter**.

## Runtime Metadata

### Properties

**Content** (text) The information shown for this part, written with the tags described below. The first `<name>` entry is also the name the search uses for this part.

**Window** (Runtime UI Window) The window that displays the content. It is assigned automatically when you add the component.

**Interactable** (Runtime Interactable) The component that highlights the part and makes it react to the mouse. It is assigned automatically when you add the component.

On **Runtime Interactable**:

**Base Highlight** (selection manager) The highlighter applied while the part matches the current search.

**Hover Highlight** (selection manager) The highlighter applied additionally while the mouse is over the part in Hover mode.

**On Highlight Activated / Deactivated, On Hover Start / End** (events) Optional Unity events to trigger your own reactions, for example to play a sound or show an additional object.

### Content Syntax

Each line of information is one tag. The entries are shown in the window from top to bottom in the order you write them.

| Tag                                                                    | Result in the window                                                                                                          |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `<name>Entry Conveyor Motor</name>`                                    | Bold title. Also used as the display name in the search.                                                                      |
| `<bold>Live Signals</bold>`                                            | Bold section header.                                                                                                          |
| `<text>Geared motor driving the belt.</text>`                          | A line of plain text.                                                                                                         |
| `<value label="Article No.">GM-0370-B14</value>`                       | A labeled value.                                                                                                              |
| `<signal>EntryConveyorStart</signal>`                                  | A labeled value that shows the live value of the PLC signal with this name.                                                   |
| `<link url="https://example.com/datasheet.pdf">Open data sheet</link>` | A button that opens the URL. A path without `http://` or `https://` opens the matching page of the realvirtual documentation. |

Example:

```xml
<name>Entry Conveyor Motor</name>

<text>Geared motor driving the entry conveyor belt.</text>

<value label="Article No.">GM-0370-B14</value>
<value label="Manufacturer">Demo Drives GmbH</value>
<value label="Power">0.37 kW</value>

<bold>Live Signals</bold>

<signal>EntryConveyorStart</signal>

<link url="https://example.com/datasheet.pdf">Open data sheet</link>
```

{% hint style="info" %}
Signals are found by their signal name, which is case-sensitive. Bool signals show *True* / *False*, float signals show two decimals. If no signal with this name exists, the window shows *Signal not found*. Tags cannot be nested, and the text inside a tag must not contain the `<` character.
{% endhint %}

## Metadata Manager

The Metadata Manager adds a toolbar to the bottom of the screen. It collects all Runtime Metadata components when the scene starts.

### Using the Toolbar

* **Search field** – Type to get suggestions. Parts whose name starts with your text come first, then parts whose name contains it, then parts where it appears anywhere in the content. Press **Enter** or click a suggestion to apply the search. All matching parts are highlighted. The search is not case-sensitive and accepts regular expressions.
* **Clear** (x) – Removes all highlights and windows and empties the search field.
* **Show all** (pointer) – Makes every part with metadata react to the mouse without highlighting it. This overrides the search.
* **Always / Hover** (info) – Switches the display mode. In **Hover** mode a window appears when you move the mouse over a highlighted part. In **Always** mode every highlighted part that is visible on screen shows its window permanently.
* **Camera follow** (camera) – Moves the camera so that all highlighted parts stay in view.

### Properties

**Mode** (Always / Hover) The display mode the scene starts with. The operator can switch it in the toolbar.

**Pattern** (string) The search text the scene starts with. Leave it empty to start without an active search.

**Max Active Interactables** (integer) The largest number of parts one search may highlight. If a search matches more parts, nothing is highlighted and a message asks the operator to refine the search. Use this to keep large CAD models responsive. 0 means no limit.

**View Margin** (float) The free space around the highlighted parts when camera follow is active. 1 is a tight fit, larger values zoom out further.

**Max Suggestions** (integer) The largest number of suggestions shown below the search field.

**Enable Suggestion Preview** (boolean) If set to true, moving the mouse or the arrow keys over a suggestion highlights that part immediately, before the search is applied.

{% hint style="info" %}
Parts are only picked by the mouse on the layer **rvSelection**. This layer is part of the realvirtual project settings. The colliders needed for picking are created automatically for highlighted parts, so you do not need to add colliders to your CAD data.
{% endhint %}

## Excel Metadata Setup

For a real machine you do not write the content by hand. **Excel Metadata Setup** reads a part list (*.xlsx*) and creates a Runtime Metadata component on every matching part of the imported CAD model.

### Workflow

1. Add **Excel Metadata Setup** to an empty GameObject in the scene.
2. Select the file with the **...** button next to **Excel File Path** and enter the **Sheet Name**. If the sheet name is empty or not found, the first sheet is used. The first row of the sheet must contain the column names.
3. Assign **Base Highlight** and **Hover Highlight**. They are applied to every created part.
4. Click **Read Header**. The columns of the sheet appear in the **Columns** list.
5. Set a mode for each column:
   * **Key** – the part number used to find the matching part in the scene. At least one column must be a Key. Its value is shown with the label *ID*.
   * **Display Name** – becomes the title of the window and the name used in the search.
   * **Include** – shown as a labeled value, with the column name as label.
   * **Exclude** – ignored.
6. Click **Setup Components**. The Console reports how many components were created.

{% hint style="danger" %}
**Setup Components** first removes **all** existing Runtime Metadata components in the scene, including the ones you created by hand, and then creates them again from the sheet. The step can be reverted with Undo.
{% endhint %}

### How Parts Are Matched

**Match By Cad Part Number** (boolean) If set to true, each part is matched by the part number stored in its imported CAD properties. This is the reliable choice, because GameObject names in CAD imports are often inconsistent. Parts without a CAD part number are matched by their GameObject name instead.

**Cad Metadata Type Name** (string) The component that holds the imported CAD properties. The default is the metadata component created by a Pixyz import.

**Cad Part Number Property** (string) The CAD property that contains the part number.

**Cad Part Number Property Fallback** (string) A second CAD property that is used if the first one is empty.

The comparison ignores upper and lower case, a CAD file extension such as *.ipt* or *.sldprt*, and an instance suffix such as *:2*. A part *ENG-033927:2* therefore matches the row *ENG-033927.ipt*. If the same part number appears in several rows, the first row is used.

## Common Use Cases

* **Spare part lookup** – The operator types an article number and sees where the part is installed.
* **Maintenance support** – Each part shows its service data and a button that opens the data sheet or manual.
* **Live diagnostics** – Signal values are shown directly at the sensor or drive they belong to.
* **Browser 3D-HMI** – The same content drives tooltips and document links in realvirtual WEB.

## See Also

* [Building a 3D-HMI](/extensions/realvirtual-web/3d-hmi.md) – how realvirtual WEB uses Runtime Metadata for tooltips and documents
* [Supported Components](/extensions/realvirtual-web/supported-components.md) – all components read by realvirtual WEB
* [Scene Selectables (Pro)](/components-and-scripts/scene-interaction/scene-selectables-pro.md) – highlighting and selecting objects at runtime
* [Tooltip (Pro)](/components-and-scripts/scene-interaction/tooltip-pro.md) – simple tooltips for single objects


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.realvirtual.io/components-and-scripts/scene-interaction/runtime-metadata.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.