Summer friends skill for AI agents

​

When your agent uses it

• Showing a friends list, who is online or which friends are playing this Summer game
• Opening a player’s Summer profile, friends list or chat screen from inside a game
• Reading or writing a player’s direct messages, or a friends call fails with permission_undeclared or permission_declined

​

Install

npx -y summer-engine@latest skills install summer-friends --agent claude-code

​

The skill

​

Overview

• friend requests;
• blocking;
• the friends list screen;
• profiles;
• chat.

• Two screens need no consent: show_friends() and show_chat(user_id). They ask the Summer app to show its own screen over the game.
• show_profile(user_id) is the same. The profile includes add friend, message, invite to party and report, so it is the social feature most games need.
• With consent, it reads the list: each friend’s name, handle and whether they are offline, online, in_this_game or in_other_game. Another game is never named.

• Reads and sends the player’s direct messages, with a separate consent for each kind of access.
• Prefer show_chat(user_id) unless chat is central to your game.

1. The Build declares the permission in summer.build.json.
2. The player grants it in the Summer app’s consent sheet, which your game asks for with request_access.

• Engine release. This needs an engine release that includes SummerClientFriends. On older engines, Summer.client.friends does not exist and scripts that use it fail to parse. Check the class reference for SummerClientFriends before using this skill.
• Hosted only. is_available() is false in Local Play and editor runs, for guests, for accounts the platform keeps out of social features (age_restricted, under 13), and in Summer apps without player.friends@1 (friends) or player.messaging@1 (messages).
• Overlays. The screens need the Summer app to offer friends and parties; otherwise they fail with capability_unavailable or ui_unavailable.

​

Steps

​

1. Declare the permissions you use

  "permissions": ["social.friends.read"],

​

2. The friends node

extends Node
## The player's Summer friends, with their consent, and the Summer app's
## friend screens over the game.

signal friends_changed(rows: Array)   # [{user_id, name, status}]
signal status(text: String)

var friends: SummerClientFriends

## Main calls this right after Summer.initialize succeeds: a child's _ready
## runs before that, while Summer.client is still null.
func start() -> void:
	friends = Summer.client.friends
	friends.changed.connect(_render)
	friends.access_changed.connect(func(_state: StringName) -> void: _render())
	_render()

## The Friends button: asks for consent once, then shows the list.
func open() -> void:
	if not friends.is_available():
		status.emit("Friends are not available here.")
		return
	if friends.get_access() != &"granted":
		var decision: SummerResult = await friends.request_access().get_result_or_completed_signal()
		if not decision.ok:
			status.emit("Your friends list stays private.")
			return
	_render()

func _render() -> void:
	var rows := []
	for friend in friends.get_friends():
		rows.append({"user_id": friend.user_id, "name": friend.display_name, "status": friend.status})
	friends_changed.emit(rows)

## The Summer app's profile for any other player this game knows. No consent needed.
func show_profile(user_id: String) -> void:
	var shown: SummerResult = await friends.show_profile(user_id).get_result_or_completed_signal()
	if not shown.ok:
		status.emit("That screen is not available right now.")

## The Summer app's direct-message thread with a friend, over the game.
func show_chat(user_id: String) -> void:
	var shown: SummerResult = await friends.show_chat(user_id).get_result_or_completed_signal()
	if not shown.ok:
		status.emit("That screen is not available right now.")

• When the list is read again. With a handler on changed, the engine re-reads the list on every change hint, after a consent decision, on refresh(), and about every 60 seconds while the game is in front. Never poll yourself.
• Statuses. Show in_this_game friends first. unknown means presence couldn’t be read; it is not offline.
• Rows. Key them by user_id; each read replaces the SummerFriend objects.
• Profiles of other players. For the people in the current match, use the user ids your authority publishes (the players map in summer-world-chat, step 1) and call show_profile(user_id). Your own id fails with invalid_argument.
• Inviting a friend into a match. Use the party invite sheet (summer-parties).

​

3. Direct messages (only if chat is central)

## Sends one direct message, asking for the send permission once.
func send_message(user_id: String, text: String) -> void:
	var messages := Summer.client.messages
	if not messages.is_available():
		return
	if messages.get_access(&"social.messages.send") != &"granted":
		var decision: SummerResult = await messages.request_access(PackedStringArray(["social.messages.send"])).get_result_or_completed_signal()
		if not decision.ok:
			return
	var sent := messages.send(user_id, text)
	var result: SummerResult = await sent.get_result_or_completed_signal()
	if result.ok:
		print("sent #%d" % sent.message.sequence)
	elif result.code == &"text_not_allowed":
		status.emit("That message was not sent.")
	elif result.code == &"target_unavailable":
		status.emit("You can't message this player.")

• Read a page. Ask for social.messages.read, then messages.list_messages(user_id). Read op.messages, newest page first; pass op.next_cursor for older pages.
• Catch up. After messages_changed, call list_messages_after(user_id, last_sequence). Today messages_changed fires only after a stream resync, so also reload when the chat screen opens.
• Mark read. mark_read(user_id, sequence) needs social.messages.read_state.write. It marks the thread read on every device.
• Send rules. send takes 1–4000 characters and no control characters except newline and tab. Each call is one message; the engine never sends it twice.

​

4. Failure codes

​

5. Test

• is_available() is false;
• buttons are hidden;
• there are no script errors.

summer_project_setting key="summer/local_play/players" value=2
summer_play
summer_get_diagnostics
summer_stop

​

Checklist

• The engine’s class reference lists SummerClientFriends.
• summer.build.json declares exactly the permissions the code asks for.
• Local Play: friends features are hidden, with no script errors.
• Declining consent leaves the game fully playable, and the button can ask again later.
• Hosted: a friend playing the game shows in_this_game; show_profile opens for another player in the match.
• No polling timer: updates come from changed.

​

Common mistakes

​

See also

• summer-parties: playing together, the invite sheet
• summer-world-chat: chat inside a match
• multiplayer-publish: summer.build.json and publishing a Build
• multiplayer-testing: what Local Play can and can’t test

​

From a shell

​

Related skills

• multiplayer: Start here for Summer multiplayer: how authority, clients, Worlds and Sessions fit, and what comes next.
• multiplayer-testing: Test a Summer multiplayer game with Local Play: several players, bad network, bots, a passing run.
• summer-parties: Let a Summer party play together: the leader presses Play, members follow into the same match. Hosted only.
• summer-world-chat: Add match chat to a Summer game: one World channel shared by everyone in the match. Hosted only.