> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 데이터 관리

> 공유 데이터, 유저 데이터, 캐릭터 데이터를 구분하고 저장합니다.

HyperX는 게임 데이터의 소유자와 운영 방식에 따라 저장소를 나눕니다. 먼저 어떤 데이터인지 결정한 뒤 Console에서 필요한 테이블을 만들고 SDK로 읽거나 저장합니다.

## 어떤 기능을 써야 하나요?

| 기능      | 소유자   | 주 용도                                         |
| ------- | ----- | -------------------------------------------- |
| 공유 데이터  | 프로젝트  | 아이템 목록, 상점 카탈로그, 공개 밸런스 값처럼 모든 클라이언트가 읽는 데이터 |
| 유저 데이터  | 유저 계정 | 재화, 업적, 튜토리얼 진행도, 설정, 세이브처럼 계정에 붙는 데이터       |
| 캐릭터 데이터 | 캐릭터   | 캐릭터 레벨, 장비, 스탯처럼 플레이 캐릭터에 붙는 데이터             |

계정 전체에 붙는 설정이나 세이브도 유저 데이터로 저장합니다. 자유로운 JSON 묶음이 필요하면 유저 데이터 테이블에 `object` 필드를 두고 그 안에 payload를 저장하세요.

## 공유 데이터 읽기

공유 데이터는 Console에서 테이블과 레코드를 만들고 게시합니다. SDK는 읽기만 합니다. 레코드 ID를 지정하지 않으면 테이블의 첫 레코드를 읽습니다.

```cs theme={null}
var sword = await HyperX.Core.Data.Shared.Get("catalog");
var itemRecordIds = await HyperX.Core.Data.Shared.ListRecordIds("catalog");
var specificItem = await HyperX.Core.Data.Shared.GetRecord("catalog", itemRecordIds[0]);

int price = (int)sword.Data["price"];
```

## 유저 데이터 저장

유저 데이터는 로그인한 유저 계정에 저장됩니다.

```cs theme={null}
await player.PutUserData(
    "inventory",
    new { gold = 1200, gem = 30 }
);

var inventory = await player.GetUserData("inventory");
int gold = (int)inventory.Data["gold"];
```

`PutUserData`는 POCO, anonymous object, dictionary를 `JsonMapper`로 JSON object로 변환합니다. 정확한 JSON 문자열이나 Unity AOT 제어가 필요하면 `PutUserDataJson` 또는 `JsonData` overload를 사용할 수 있습니다.

레코드 ID를 지정하지 않으면 테이블의 첫 레코드를 읽고 저장합니다. 필요 없어진 기본 레코드는 삭제할 수 있습니다.

```cs theme={null}
await player.DeleteUserData("inventory");
```

## 여러 레코드 저장

테이블에 여러 레코드가 필요하면 서버가 레코드 ID를 자동으로 생성합니다. 클라이언트는 반환된 `RecordId`를 저장해 특정 레코드를 다시 읽거나, 테이블의 레코드 ID 목록을 조회할 수 있습니다.

```cs theme={null}
var save = await player.CreateUserData(
    "save_state",
    new { payload = new { chapter = 3, checkpoint = "forest" } }
);

var recordIds = await player.ListUserDataRecordIds("save_state");

var loaded = await player.GetUserDataRecord(
    "save_state",
    save.RecordId
);
```