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

# Summer.client.friends

> The player's Summer friends as this Game may see them.

**Class:** `SummerClientFriends` · **Inherits:** RefCounted · **Access:** `Summer.client.friends`

The player's Summer friends as this Game may see them.

With the player's consent, this view lists the player's Summer friends and whether each is offline, online, or playing this Game. A Game never learns which other Game a friend is playing. The trusted Summer app owns friendship, friend requests, blocking and chat; [`show_friends()`](/api-reference/gdscript/client/friends#show_friends), [`show_profile()`](/api-reference/gdscript/client/friends#show_profile) and [`show_chat()`](/api-reference/gdscript/client/friends#show_chat) ask the app to present those screens over the game, and need no consent.
Reading friends needs the `social.friends.read` permission: the Build declares it, and the player grants it in the Summer app's consent sheet, which [`request_access()`](/api-reference/gdscript/client/friends#request_access) asks the app to show. [`get_access()`](/api-reference/gdscript/client/friends#get_access) reports the player's current decision. The Engine re-reads the friends when they change, when the event stream starts or resyncs, after a consent decision, on [`refresh()`](/api-reference/gdscript/client/friends#refresh), and about every 60 seconds while a handler is connected to [`changed`](/api-reference/gdscript/client/friends#changed) and the game is in front; friend status changes are not pushed. Every signal is emitted after the view is updated, once per change.

```gdscript theme={null}
var friends := Summer.client.friends
friends.changed.connect(_show_friends)

func _on_friends_button_pressed() -> void:
    if not friends.is_available():
        return
    if friends.get_access() != &"granted":
        var decision: SummerResult = await friends.request_access().completed
        if not decision.is_ok():
            return # The player kept their friends private.
    _show_friends()

func _show_friends() -> void:
    for friend in friends.get_friends():
        add_row(friend.display_name, friend.status == &"in_this_game")
```

**Host capabilities named here:** `player.friends@1`

## Methods

### get\_access

```gdscript theme={null}
func get_access() -> StringName const
```

Returns the player's current decision for `social.friends.read` in this Game: `granted`, `declined`, `revoked`, `not_requested`, or `undeclared` when this Build does not declare the permission. It is `not_requested` until the first read after [`Summer.initialize()`](/api-reference/gdscript/overview#initialize) completes; [`access_changed`](/api-reference/gdscript/client/friends#access_changed) reports every change.

**Returns:** StringName

### get\_friends

```gdscript theme={null}
func get_friends() -> SummerFriend[] const
```

Returns the player's friends from the latest read, in the order the platform returns them. Empty until the player grants access, and when [`is_available()`](/api-reference/gdscript/client/friends#is_available) is `false`. Each entry is an immutable [`SummerFriend`](/api-reference/gdscript/types/friend); an unchanged friend keeps its object across reads, so key UI by [`SummerFriend.user_id`](/api-reference/gdscript/types/friend#user_id).

**Returns:** [`SummerFriend`](/api-reference/gdscript/types/friend)\[]

### is\_available

```gdscript theme={null}
func is_available() -> bool const
```

Returns `true` when the Summer app offers friends (`player.friends@1`) to this signed-in player and this Build declares `social.friends.read`. Always `false` in local play, for guests, and for accounts the platform does not allow social features (`age_restricted`).

**Returns:** bool

### refresh

```gdscript theme={null}
func refresh() -> SummerOperation
```

Reads the player's permissions and, while access is granted, their friends again. Normally unnecessary. One read is in flight at a time; a second call while pending returns the same operation. Succeeds when the friends were read. Fails with `permission_not_requested`, `permission_declined`, `permission_revoked` or `permission_undeclared` when the player has not granted access (the view is then empty), `capability_unavailable` when [`is_available()`](/api-reference/gdscript/client/friends#is_available) is `false` for lack of the capability, `age_restricted`, `unavailable` (retryable) when the Player Host cannot be reached, or `protocol_error` for a malformed read, which changes nothing.

**Returns:** [`SummerOperation`](/api-reference/gdscript/types/operation)

Returns at once. Wait for the result with `var result: SummerResult = await op.get_result_or_completed_signal()`; see [SummerOperation](/api-reference/gdscript/types/operation).

### request\_access

```gdscript theme={null}
func request_access() -> SummerOperation
```

Asks the Summer app to show its consent sheet for `social.friends.read`. Only the trusted app records the player's decision; the Engine then reads it, and the operation completes with it: success once the player granted access, after [`access_changed`](/api-reference/gdscript/client/friends#access_changed) and [`changed`](/api-reference/gdscript/client/friends#changed) have fired, or `permission_declined` or `permission_not_requested` (the player closed the sheet without deciding). It succeeds at once when access is already granted, fails at once with `permission_undeclared` when this Build does not declare the permission, and fails with `ui_unavailable` when the app cannot show the sheet now. One consent sheet is requested at a time; while it is pending, a second call returns the same operation.

**Returns:** [`SummerOperation`](/api-reference/gdscript/types/operation)

Returns at once. Wait for the result with `var result: SummerResult = await op.get_result_or_completed_signal()`; see [SummerOperation](/api-reference/gdscript/types/operation).

### show\_chat

```gdscript theme={null}
func show_chat(user_id: String) -> SummerOperation
```

Asks the Summer app to open its direct-message thread with the friend `user_id` over the game. Completes when the app's presenter answers, as soon as the screen is shown; fails with `ui_unavailable` when the app cannot show it now, `invalid_argument` for a malformed ID or this player's own, and `capability_unavailable` when the Summer app offers no friends or parties. The overlays share the party sheets' presenter: one request is in flight at a time, the same request while pending returns the same operation, and any other fails with retryable `operation_in_progress`.

| Parameter | Type | Default |
| - | - | - |
| `user_id` | String | required |

**Returns:** [`SummerOperation`](/api-reference/gdscript/types/operation)

Returns at once. Wait for the result with `var result: SummerResult = await op.get_result_or_completed_signal()`; see [SummerOperation](/api-reference/gdscript/types/operation).

### show\_friends

```gdscript theme={null}
func show_friends() -> SummerOperation
```

Asks the Summer app to show its friends list over the game. Needs no consent. Completion and failures match [`show_chat()`](/api-reference/gdscript/client/friends#show_chat).

**Returns:** [`SummerOperation`](/api-reference/gdscript/types/operation)

Returns at once. Wait for the result with `var result: SummerResult = await op.get_result_or_completed_signal()`; see [SummerOperation](/api-reference/gdscript/types/operation).

### show\_profile

```gdscript theme={null}
func show_profile(user_id: String) -> SummerOperation
```

Asks the Summer app to show the profile of the player `user_id` over the game, with its add-friend, message, invite-to-party and report actions. `user_id` can be any other player this Game knows, such as a [`SummerParticipant`](/api-reference/gdscript/types/participant) in the current match. Completion and failures match [`show_chat()`](/api-reference/gdscript/client/friends#show_chat).

| Parameter | Type | Default |
| - | - | - |
| `user_id` | String | required |

**Returns:** [`SummerOperation`](/api-reference/gdscript/types/operation)

Returns at once. Wait for the result with `var result: SummerResult = await op.get_result_or_completed_signal()`; see [SummerOperation](/api-reference/gdscript/types/operation).

## Signals

### access\_changed

```gdscript theme={null}
signal access_changed(state: StringName)
```

The player's decision for `social.friends.read` changed to `state`; see [`get_access()`](/api-reference/gdscript/client/friends#get_access). When access ends, [`changed`](/api-reference/gdscript/client/friends#changed) follows with an empty list.

### changed

```gdscript theme={null}
signal changed()
```

The friends list, or any friend's name, handle or status, changed. Emitted once per read that changed something visible.

***

What is live on the platform today: [platform capability status](/knowledge-base/source-status). Check availability at runtime before you offer a feature.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.