Entities

Entities provide a structured way to store and organize data within objects.

Every object in Grid Studio contains an Entity structure, which can store multiple related values describing the object's internal state, generated data, or information received from external systems.

Entities behave like a tree-based data structure, similar to formats such as JSON. This allows objects to store complex datasets in an organized hierarchy rather than relying on individual parameters.

Entities are commonly used to represent device states, system information, or structured datasets.

High-frequency spatial data such as tracking positions is typically handled through Maps, which are designed for real-time data pipelines.

---

Viewing Entities

Entities are hidden by default in the interface.

To display them, the Entities view can be enabled in the editor. Once visible, the entity structure of the selected object can be inspected and monitored in real time.

This allows users to observe internal data generated by devices, sensors, or other systems.

---

Entity Structure

Entities are organized in a tree structure made up of keys and values.

This hierarchical structure allows objects to expose complex datasets in an organized and readable format.

A simplified example for a device status readout might look like this:

Entity
│
├ connection
│   ├ connected
│   ├ ip
│   └ port
│
├ device
│   ├ model
│   ├ firmware
│   └ serial
│
├ status
│   ├ temperature
│   ├ fanSpeed
│   └ power
│
└ system
    ├ uptime
    └ lastUpdate

Unlike fixed parameter structures, entity trees can also be dynamic, meaning that keys and values may appear or change depending on the data provided by a device or system.

---

Working with Entity Values

Entity values can be accessed and used throughout the system.

They can be:

• read by Workflows

• written by Workflows

• used inside Modifier nodes

• accessed through Scripting

• connected to Widgets

This allows entities to act as a shared data layer used by multiple systems in the project.

---

Entity Events

Entity values can generate events when their value changes.

These onChange events can be used by Workflows to trigger logic whenever a value updates.

For example, a workflow might react when:

• a device connection state changes

• a sensor reports a new measurement

• a system status value updates

Workflows can also write values back into entities, allowing logic systems to update the object state.

---

Entity History

Individual entity values can optionally be converted into History parameters.

History parameters store value changes over time and allow the system to generate graphs or analyze trends.

This feature is commonly used when monitoring values such as:

• temperature

• signal levels

• device performance metrics

---

Using Entities in Systems

Entities integrate with several systems inside Grid Studio.

Entity values can be used by:

• Workflows to read, write, and react to data

• Modifiers to process values

• Widgets to display system information

• Scripts to access structured data programmatically

Because entities act as a shared data layer, multiple systems can access and react to the same dataset.

---

Example Use Cases

Entities are commonly used for:

• storing device status information

• representing system health data

• exposing protocol data

• sharing state information between objects

Entities can also store custom project data created by the user.

For example, data retrieved from an external API—such as game statistics or player information—can be stored in entities. Instead of keeping a large flat dataset, individual entities can represent structured elements such as players or objects.

This makes it easier for workflows, widgets, and scripts to interact with the data.