> 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="https://611779084-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyIhlDMEOMB6JOWTfU9zr%2Fuploads%2FOnEm4IvABZhjDGeQWRzk%2Fpositions-move-identity-stays%20(1).svg?alt=media&amp;token=26ccf99d-956a-4862-9ba4-43e669893cbe" 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 by asking a question.

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

```
GET https://guide.cronuszen.com/gpcscripting/gpc-script-guide/advanced-architecture/keep-settings-with-the-right-object.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.
