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

# Social and Communication

> Connect user search, friends, mail, messages, guilds, and notifications.

Social features let players find each other, build relationships, and exchange messages or rewards. Operators can inspect users, mail, messages, and guilds in Console.

## User Search and Random Lookup

```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
);
```

Search returns public users by nickname or user ID. Random lookup returns candidates that registered into the same bucket.

## Friends

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

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

Friends support request, accept, reject, remove, and block. Blocked relationships cannot send friend requests or messages.

## Mail

```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);
```

Mail attachments are returned as JSON payloads. Apply rewards according to your game policy and rely on server claim state to prevent duplicate claims.

## Messages

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

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

Messages are user-to-user text messages. Operators can hide inappropriate messages in Console.

## Guilds

```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);
```

For `joinPolicy`, use `HyperX.GuildJoinPolicy.Open`, `HyperX.GuildJoinPolicy.Approval`, or `HyperX.GuildJoinPolicy.InviteOnly`. You can still pass a string for custom values. Joining an approval or invite-only guild creates a member with `requested` status, and the guild owner or an officer can approve or reject the request.

Guild owners and officers can create and revoke invite codes. Joining by invite either adds the player immediately or creates a pending request depending on the guild policy.

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

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

Guild goods are server-managed guild balances with ledger history. Contributions, grants, and spends take a positive amount and can include an 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");
```

Operators can inspect invite links, goods balances, and ledger entries from Console Social, then apply reasoned adjustments when needed.

## Notifications

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

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

Use the subscription wrapper to receive new notifications periodically from Unity.

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