> ## 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.

# 소셜과 커뮤니케이션

> 유저 검색, 친구, 우편, 쪽지, 길드, 알림 기능을 연결합니다.

소셜 기능은 유저가 서로 찾고, 관계를 맺고, 메시지와 보상을 주고받는 흐름을 제공합니다. 운영자는 Console에서 유저, 우편, 메시지, 길드 상태를 확인할 수 있습니다.

## 유저 검색과 랜덤 조회

```cs theme={null}
var users = await HyperX.Core.Social.Search.Users(query: "hero", limit: 20);

await player.RegisterRandom(
    "arena",
    new { power = 1200 }
);

var candidates = await player.LookupRandom(
    bucket: "arena",
    limit: 5
);
```

검색은 닉네임 또는 유저 ID 기준으로 공개 유저 정보를 반환합니다. 랜덤 조회는 같은 bucket에 등록한 유저 중 후보를 반환합니다.

## 친구

```cs theme={null}
var request = await player.SendFriendRequest(targetUserId);

await otherPlayer.AcceptFriendRequest(request.Id);
var friends = await player.Friends();
```

친구는 요청, 수락, 거절, 삭제, 차단을 지원합니다. 차단된 관계에서는 친구 요청과 쪽지 전송이 거부됩니다.

## 우편

```cs theme={null}
var mail = await player.SendMail(
    recipientUserId,
    "gift",
    "welcome",
    new { gold = 100 }
);

var inbox = await player.Mail();
var claimed = await player.ClaimMail(mail.Id);
```

우편 첨부는 JSON payload로 반환됩니다. 보상 지급은 게임 정책에 맞게 처리하고, 중복 수령은 서버의 수령 상태를 기준으로 막습니다.

## 쪽지

```cs theme={null}
var sent = await player.SendMessage(recipientUserId, "hello");

var thread = await player.Messages(peerUserId: recipientUserId);
```

쪽지는 유저 간 텍스트 메시지입니다. 운영자는 Console에서 부적절한 메시지를 숨김 처리할 수 있습니다.

## 길드

```cs theme={null}
var guild = await player.CreateGuild(
    "knights",
    "Knights",
    joinPolicy: HyperX.GuildJoinPolicy.Approval
);

var requested = await otherPlayer.JoinGuild(guild.Id);
await player.ApproveGuildMember(guild.Id, requested.UserId);
var members = await player.GuildMembers(guild.Id);
```

`joinPolicy`는 `HyperX.GuildJoinPolicy.Open`, `HyperX.GuildJoinPolicy.Approval`, `HyperX.GuildJoinPolicy.InviteOnly` 중 하나를 사용할 수 있습니다. 커스텀 값이 필요하면 기존 string 값을 전달할 수 있습니다. 승인형 또는 초대형 길드에 가입하면 멤버 상태가 `requested`가 되고, 길드 owner 또는 officer가 승인하거나 거절합니다.

길드 owner 또는 officer는 초대 코드를 만들고 폐기할 수 있습니다. 초대 코드로 가입하면 길드 정책에 따라 즉시 가입되거나 승인 대기 상태가 됩니다.

```cs theme={null}
var invite = await player.CreateGuildInvite(
    guild.Id,
    maxUses: 10
);

await otherPlayer.JoinGuildByInvite(invite.Code);
await player.RevokeGuildInvite(guild.Id, invite.Id);
```

길드 goods는 서버가 balance와 ledger를 관리하는 길드 단위 값입니다. 기여, 지급, 사용은 양수 금액과 선택적 idempotency key를 받습니다.

```cs theme={null}
await player.ContributeGuildGoods(
    guild.Id,
    "guild_gold",
    amount: 100,
    reason: "raid"
);

var balances = await player.GuildGoods(guild.Id);
var ledger = await player.GuildGoodsLedger(guild.Id, goodsKey: "guild_gold");
```

운영자는 Console Social 화면에서 초대 링크, goods balance, ledger를 확인하고 필요한 경우 사유를 남겨 조정할 수 있습니다.

## 알림

```cs theme={null}
var notifications = await player.Notifications(unreadOnly: true);

await player.MarkNotificationRead(notifications[0].Id);
```

Unity에서 새 알림을 주기적으로 받고 싶으면 구독 래퍼를 사용합니다.

```cs theme={null}
using var subscription = player.SubscribeNotifications(
    notification => Debug.Log(notification.EventType),
    error => Debug.LogWarning(error.Message),
    pollIntervalMilliseconds: 2000
);
```