> For the complete documentation index, see [llms.txt](https://guide.cronuszen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.cronuszen.com/gpcscripting/gpc-script-guide/advanced-architecture/keep-settings-with-the-right-object.md).

# Keep settings with the right object

<figure><img src="/files/VuUL0kVP1FNbj6bK4bO4" alt=""><figcaption><p>Stable identity follows the object when its UI position changes</p></figcaption></figure>

### The idea in one sentence

A UI position tells you **where an object is right now**. A stable ID tells you **which object it is**.

Think of a weapon rack: moving a labeled weapon from the first hook to the second hook does not change which weapon it is. Settings should follow the weapon's label, not remain attached to the hook.

***

### A concrete weapon example

Suppose an R-301 can appear in either loadout slot:

| Moment      | Primary slot     | Secondary slot   | Where the R-301 settings belong |
| ----------- | ---------------- | ---------------- | ------------------------------- |
| Before swap | R-301, ID `17`   | Flatline, ID `8` | Weapon record `17`              |
| After swap  | Flatline, ID `8` | R-301, ID `17`   | Still weapon record `17`        |

If you save by `primary` or `secondary`, an edit stays attached to that position after the swap and can affect the wrong weapon. If you save by weapon ID, the edit follows the R-301 wherever the UI displays it.

***

### Resolve the position into an identity

Use the selected UI slot only to discover the stable ID. Then calculate storage from that ID:

```
selected UI slot → stable weapon ID → BVAR record base → field
```

{% code title="save-by-weapon-id.gpc" lineNumbers="true" %}

```cpp
define SLOT_PRIMARY          = 0;
define SLOT_SECONDARY        = 1;
define WEAPON_R301           = 17;
define WEAPON_FLATLINE       = 8;
define BVAR_WEAPON_BASE      = 100;
define WEAPON_RECORD_STRIDE  = 4;
define FIELD_STRENGTH        = 0;

int primary_weapon = WEAPON_R301;
int secondary_weapon = WEAPON_FLATLINE;
int selected_slot;
int selected_weapon;
int record_index;
int edited_strength = 25;

main {
    selected_weapon = primary_weapon;
    if(selected_slot == SLOT_SECONDARY) {
        selected_weapon = secondary_weapon;
    }

    record_index = BVAR_WEAPON_BASE
                 + (selected_weapon * WEAPON_RECORD_STRIDE)
                 + FIELD_STRENGTH;

    if(event_press(PS5_CROSS)) {
        set_bvar(record_index, edited_strength);
    }
}
```

{% endcode %}

After a weapon swap, update `primary_weapon` and `secondary_weapon`. Do not move or rewrite the saved weapon records merely because their screen positions changed.

***

### Use this pattern beyond weapons

The same rule applies whenever something can move:

| Moving UI position                | Stable identity |
| --------------------------------- | --------------- |
| Primary, secondary, or sling slot | Weapon ID       |
| Menu row after sorting            | Item ID         |
| Player position in a lobby list   | Player ID       |
| Preset button                     | Preset ID       |

The test is simple: **if two objects trade positions, do their saved settings stay with the correct objects?** If not, the code is probably using position as identity.


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guide.cronuszen.com/gpcscripting/gpc-script-guide/advanced-architecture/keep-settings-with-the-right-object.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.