# Avatar item data — what was changed, and how to revert

Everything here is data only. No code change is needed to undo any of it: restore the
named backup over `avatar_items.json`, restart the server, done.

## Backups, newest last

| file | state it holds |
|---|---|
| `avatar_items.json.bak-malformed-desc` | original. 1108 descriptors had fewer than 4 fields |
| `avatar_items.json.bak-dupid` | descriptors padded to 4 fields; 3 items still shared id 9503 |
| `avatar_items.json.bak-before-realids` | duplicate ids fixed; ids still renumbered 1..9505 |
| `avatar_items.json.bak-shortguids` | real ids restored; descriptors still mixed UUID / short guid |
| `avatar_items.json` | current: every id written as a full UUID |

## Change 1 — descriptors padded to 4 fields

`AvatarItemDesc` must be `guid,combination,combination,combination`. The client parses
exactly 4 comma-separated fields; a 2-field entry never lands live and only appears after
a relog. 1108 entries were short and are now padded. The 2023 server documents this in
`Campus-2023/Classes/DBs/PlayerDB.cs` (see `NormalizeItemDesc`).

Revert: `cp avatar_items.json.bak-malformed-desc avatar_items.json`

## Change 2 — duplicate AvatarItemId removed

Three hand-added items (Green Cheer Sash, Helmet Hair, Hacker Suit) all carried id 9503
and were the only three missing `TagList` / `CreatedAt` / `ThumbnailImage`. Given unique
ids and the same key set as the other 3058.

NOTE: this turned out NOT to be why items fail to load — the 2023 catalog has 153
duplicate ids and works fine. Kept because it is still correct, not because it fixed
anything.

Revert: `cp avatar_items.json.bak-dupid avatar_items.json`

## Change 3 — REAL AvatarItemIds restored  ← the one to revert first if things get worse

The 2025 catalog had been renumbered 1..9505. Of 2815 items present in both this catalog
and the known-good 2023 catalog, only **2** had a matching `AvatarItemId`. The 2023
catalog carries the real Rec Room ids (range -1 .. 1995874561).

Ids are now taken from the 2023 catalog, matched on the normalised `AvatarItemDesc`
(trailing empty colour slots dropped, so `guid,,,` and `guid,` match):

- 2815 items restored to their real id — e.g. White Hat 1462 -> **1604**
- 246 items have no 2023 counterpart and were given ids above the real id space so they
  cannot collide
- 0 duplicate ids

Why: if the client keys its item database or asset lookup on `AvatarItemId`, renumbered
ids break items in exactly the partial way seen — some hats and shirts load, others do
not, while the GET response contains everything.

Revert: `cp avatar_items.json.bak-before-realids avatar_items.json`
Then also regenerate `../AlgorithmicLists/customizeitems_5.json`, which lists these ids.

## Change 4 — every id expanded to a full UUID  ← revert this one first

Rec Room writes ids two ways: a full UUID, or a 22-char base64 "short guid". This catalog
mixed both, sometimes inside the same descriptor:

```
Hacker Suit  4308da04-af84-40bb-845a-7a9e1a2726ec,5aa7be74-19a9-4dd8-b525-46c5aef34866,,   LOADS
White Hat    76369aef-aeda-46d2-996a-cd00594d0543,8XajS2adOEOqzqnLy6-zcQ,P12CUkIg8EuFihGQsvPlxg,   DID NOT LOAD
```

Kyle reports the same pattern on the 2023 build: items written with full UUIDs loaded,
items with short guids did not. Every short guid is now expanded:

- 1664 items rewritten — 369 base guids, 2289 combinations
- 0 short tokens left, all descriptors still 4 fields
- White Hat is now
  `76369aef-aeda-46d2-996a-cd00594d0543,4ba376f1-9d66-4338-aace-a9cbcbafb371,52825d3f-2042-4bf0-858a-1190b2f3e5c6,`

Byte order: `.NET new Guid(byte[])` reads the first three fields little-endian, i.e. Python's
`uuid.UUID(bytes_le=...)`. Same conversion as the 2023 server's `ItemGuids.NormalizeGuid`.

Verified after the rewrite: 157/157 starter items still resolve, all 3061 descriptors
written in the OLD spelling still match the new catalog, 3061 keys still unique.

`PlayerDB.NormalizeAvatarItemDesc` now expands short guids too, so ownership rows,
`DefaultAvatarItems.json` and the storefronts keep matching whichever spelling they hold.
That code change is safe to leave in place even if this data change is reverted.

Revert: `cp avatar_items.json.bak-shortguids avatar_items.json`

## Related file — AlgorithmicLists/customizeitems_5.json

`GET /lists/algorithmiclists/customizeitems?type=5` was returning
`{"Type":5,"Entities":[]}` because the file did not exist. Generated from this catalog,
one `{Id, Context}` entry per item, same shape as `new_1.json`.

The meaning of `Id` here is INFERRED (the rooms list uses room ids, so this uses avatar
item ids). If it causes trouble, just delete the file — a missing file makes the endpoint
return the empty list it returned before.

**It must be regenerated whenever `avatar_items.json` ids change**, or it points at ids
that no longer exist.

## Ruled out — do not spend time re-checking these

Each was checked against the 2023 catalog, which works:

- `AvatarItemType: 0` on every item — 2023 is identical, and so is real captured store
  data in `GiftDropStores/*.json`. The client takes the type from the item's ASSET.
- Missing thumbnails — the 2023 server ships 3 image files total and 404s everything else.
- Mixed UUID / 22-char short-guid combination fields — both catalogs mix them the same way.
- Response truncation — the full 1.03 MB reaches the client, White Hat included.