> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/scripting/script-aliases.md).

# Script Aliases

{% hint style="warning" %}
Script Aliases are currently an **Experimental Feature** and must be enabled under **File → Preferences → Advanced → Experimental Features**.
{% endhint %}

### Why Use Script Aliases?

Objects in Grid Studio can be accessed through their unique scripting ID.

For example:

```python
sp.Camera1.coordinates.position.value
```

This reference points directly to a specific Object in the project.

When a script should be reusable with different Objects, an Alias can be used instead:

```python
sp.alias.camera.coordinates.position.value
```

The script now references the Alias `camera` instead of the unique Object ID.

The Object assigned to this Alias can be changed in the Alias Manager without changing the script itself.

This is useful when building reusable scripts or when the same script logic should be used with different Objects.

### Alias Manager

Before Aliases can be configured, the **Alias Manager** View needs to be opened and added to the Grid Studio workspace.

Go to:

**View → Aliases**

This opens the Alias Manager as a separate View. The View can then be docked into the Grid Studio window like other Views.

<div align="left"><figure><img src="/files/uhZyKPbDiQaPaNLKtaKD" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="warning" %}
If **Aliases** is not available in the **View** menu, make sure **Experimental Features** are enabled under **File → Preferences → Advanced → Experimental Features**.

After enabling Experimental Features, Grid Studio may need to be restarted once before the Alias Manager becomes available.
{% endhint %}

Once the View is open and docked, Aliases can be configured directly in the Alias Manager.

An Alias links a custom Alias name to an Object or Parameter in the project.

Aliases are available project-wide, and both complete Objects and individual Parameters can be linked to an Alias.

### Creating and Assigning Aliases

The Alias Manager is a list of Alias entries. You can add as many Aliases as required for the project.

Each entry contains two main parts:

* **Alias** — the custom name used to access the target from a script
* **Target** — the Object or Parameter linked to the Alias

A newly created Alias does not have a Target assigned yet.

{% hint style="info" %}
Each Alias must be linked to an Object or Parameter before it can be used to access project data from a script.
{% endhint %}

#### Adding Alias Entries

New Alias entries can be added directly in the Alias Manager.

Each new entry is added to the list and can then be assigned its own Alias name and Target.

The Alias Manager can contain any number of entries, allowing all scripting references required by the project to be managed from one place.

<div align="left"><figure><img src="/files/PkedD1ZqRPVtRtvoGElx" alt="" width="423"><figcaption></figcaption></figure></div>

#### Naming an Alias

To assign or change an Alias name, double-click the current name in the **Alias** column.

<div align="left"><figure><img src="/files/lCEyMugHjZNoj4hf9fwP" alt="" width="440"><figcaption></figcaption></figure></div>

The name can then be edited directly in the Alias Manager.

For example, an Alias could be named:

```
camera
tracker
position
```

The assigned name is the name used when accessing the Alias from a script:

```python
sp.alias.camera
```

#### Adding Objects by Drag and Drop

Objects can be added directly from the **Project Tree** by dragging them into the Alias Manager.

This provides a quick way to create an Alias and assign an Object as its Target without using the Target selection menu.

<div align="left"><figure><img src="/files/Nll94ecCRXdpcCPViWNz" alt="" width="563"><figcaption></figcaption></figure></div>

#### Adding Parameters by Drag and Drop

Individual Parameters can also be dragged directly from the **Inspector** into the Alias Manager.

This creates an Alias that targets the Parameter itself rather than the complete Object.

This is useful when a script only needs access to a specific Parameter.

<div align="left"><figure><img src="/files/PWJ31wDhAAZuFXCBqgLz" alt="" width="563"><figcaption></figcaption></figure></div>

#### Selecting a Target

A Target can also be assigned after an Alias has already been created.

Click **Select an Object** in the Target field of the Alias to open the Target selection menu.

From here, navigate to **Project** to access the Objects in the Project Tree.

When an Object is shown in the selection menu, there are two ways to continue:

* Click the **Target** icon on the right side of the Object entry to link the complete Object directly.
* Click the Object entry itself to navigate further into its Containers and Parameters.

This makes it possible to select either an entire Object or a specific Parameter below that Object as the Alias Target.

<div align="left"><figure><img src="/files/Zw9AUelVgZdtjU43GLCC" alt="" width="563"><figcaption></figcaption></figure></div>

#### Assigning a Parameter Directly to an Existing Alias

A Parameter from the Inspector can also be dragged directly onto the **Target** field of an existing Alias.

This immediately assigns the Parameter as the Target without opening the Target selection menu.

<div align="left"><figure><img src="/files/rBSfejrcPw8BM7tQ87N2" alt="" width="563"><figcaption></figcaption></figure></div>

The connection can also be made in the opposite direction by dragging from the Alias **Target** field onto a Parameter in the Inspector.

Both methods allow an existing Alias to be linked quickly while working directly with the relevant Parameter.

<div align="left"><figure><img src="/files/tozr0z7Xa9esZKZxgjRp" alt="" width="563"><figcaption></figcaption></figure></div>

### Accessing Objects by Alias

If an Object has been assigned the Alias `tracker`, it can be accessed using:

```python
sp.alias.tracker
```

This returns the Object handle.

Parameters below the Object can then be accessed normally:

```python
sp.alias.tracker.coordinates.position.value
```

For example, the Position Parameter can be changed directly:

```python
sp.alias.tracker.coordinates.position.value = [0, 1, 2]
```

### Accessing Parameters by Alias

An Alias can also point directly to an individual Parameter.

For example, if a Position Parameter has been assigned the Alias `posi`:

```python
sp.alias.posi
```

The Parameter value can then be accessed through `.value`:

```python
print(sp.alias.posi.value)
```

or changed directly:

```python
sp.alias.posi.value = [99, 88, 77]
```

Using a Parameter Alias avoids having to reference the complete Object and Parameter path.

### Multiple Aliases with the Same Name

Multiple Objects or Parameters can use the same Alias name.

When an Alias is accessed directly, Grid Studio returns the **first matching Alias**:

```python
sp.alias.tracker
```

The same behavior can be requested explicitly using:

```python
sp.alias.first.tracker
```

To access all targets using the same Alias name, use `all`:

```python
for tracker in sp.alias.all.tracker:
    print(tracker)
```

The returned targets can then be processed individually:

```python
for tracker in sp.alias.all.tracker:
    print(tracker.coordinates.position.value)
```

The same approach can be used with Parameter Aliases:

```python
for pos in sp.alias.all.pos:
    print(pos.value)
```

This allows matching targets to be added or changed in the Alias Manager without modifying the script.

### Wildcard Matching

Aliases can also be matched using `*` as a wildcard.

For example:

```python
for tracker in sp.alias["tracker*"]:
    print(tracker)
```

This returns an array containing all matching Aliases whose names match the given pattern.

For example, `tracker*` could match Alias names such as:

```
trackerLeft
trackerRight
trackerCenter
```

{% hint style="info" %}
Alias wildcard matching currently supports `*`.
{% endhint %}

### Alias Names with Special Characters

Bracket notation can be used for Alias names containing spaces or special characters.

For example:

```python
sp.alias["tracker with special chars & $"]
```

This can be used whenever an Alias name cannot be accessed using regular dot notation.

### Random Matching Alias

If multiple targets use the same Alias name, one random matching target can be accessed using:

```python
sp.alias.random.tracker
```

### Missing Aliases

If a directly requested Alias does not exist, the result is `None`.

For example:

```python
sp.alias.doesNotExist
```

Trying to continue accessing properties on that result will cause a script error, which is shown in the Grid Studio Log.

For example:

```python
sp.alias.doesNotExist.value
```

### Building Reusable Scripts

The main purpose of Script Aliases is to separate script logic from project-specific Object IDs.

A script using a direct Object reference:

```python
sp.Camera1.coordinates.position.value = [0, 1, 2]
```

is tied directly to `Camera1`.

The same logic using an Alias:

```python
sp.alias.camera.coordinates.position.value = [0, 1, 2]
```

only depends on an Alias called `camera`.

The target assigned to `camera` can be changed in the Alias Manager without modifying the script itself.

This makes it possible to create a script once and reuse it with different Objects or Parameters by changing only the Alias target.

When several targets use the same Alias, they can also be processed together:

```python
for tracker in sp.alias.all.tracker:
    print(tracker)
```