Summer world chat skill for AI agents

​

When your agent uses it

• Adding in-game text chat, match chat or a chat box to a multiplayer Summer game
• Chat messages fail with text_not_allowed, rate_limited or unavailable, or chat history looks incomplete
• Deciding where player chat should live instead of sending it through Commands or State

​

Install

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

​

The skill

​

Overview

• who may read it;
• the text filter;
• rate limits;
• 24-hour retention;
• blocks between players.

​

Steps

​

1. Publish player names

	var players: Dictionary = match_doc.get("players", {})
	players[session.player.user_id] = session.player.display_name
	match_doc["players"] = players
	match_group.reset(Game.pack(match_doc))

​

2. Add the chat node

extends Node
## Match chat: one World channel that every player in this match shares.

signal lines_changed(lines: PackedStringArray)
signal status(text: String)

var chat: SummerWorldChannel
var names := {}   # player user id -> display name, from your match state

## Call after the player has entered the match.
func open() -> void:
	var channels := Summer.client.channels
	var ready := channels.check_open_readiness()
	if not ready.ok:
		status.emit("Chat is not available here.")   # hide the chat box
		return
	var opened := channels.open_world_channel("match")
	var result: SummerResult = await opened.get_result_or_completed_signal()
	if not result.ok:
		status.emit("Chat is not available here.")
		return
	chat = opened.get_channel()
	if chat == null:
		return   # the player already left this World
	chat.history_changed.connect(_render)
	chat.history_failed.connect(func(_failure: SummerResult) -> void: status.emit("Chat history is unavailable. Tap to retry."))
	chat.closed.connect(func(_reason: String) -> void:
		chat = null
		_render())
	_render()   # the first history may already be here

## The Retry tap after history_failed.
func retry_history() -> void:
	if chat != null:
		chat.refresh()

func send(text: String) -> void:
	if chat == null or text.strip_edges().is_empty():
		return
	var sent := chat.send_message(text)
	var result: SummerResult = await sent.get_result_or_completed_signal()
	if not result.ok and result.retryable and result.code != &"rate_limited":
		# An ambiguous failure may have been accepted. Retry the same send,
		# never send_message again: that would be a second message.
		sent = sent.retry()
		result = await sent.get_result_or_completed_signal()
	if result.ok:
		return
	match result.code:
		&"text_not_allowed":
			status.emit("That message was not sent.")
		&"rate_limited":
			status.emit("You are sending messages too fast.")
		_:
			status.emit("Message not sent.")

## The visible window always comes from get_messages(), never from appending.
func _render() -> void:
	var lines := PackedStringArray()
	if chat != null and chat.is_history_current():
		for message in chat.get_messages():
			var author := "Game" if message.author_kind == &"creator_system" else String(names.get(message.player_id, "Player"))
			lines.append("%s: %s" % [author, message.text])
	lines_changed.emit(lines)

• Messages: a Label or RichTextLabel with bbcode_enabled = false, refilled from lines_changed.
• Input: a LineEdit whose text_submitted calls $Chat.send(text) and clears itself.
• Status: status feeds a status line; hide the whole box when chat is unavailable.

​

3. Rules the code above follows

• Render, don’t append. history_changed means “replace the view from get_messages()”. It also fires when a block or expiry removes messages, which must disappear from the screen.
• message_received is for sounds and badges only. It fires for newly seen messages, not for the initial or older history. Display still comes from get_messages().
• One send_message call is one message. For an ambiguous retryable failure, call retry() on the same operation; it reuses the original idempotency key. A second send_message would post twice.
• text_not_allowed stored nothing. The filter refused it, and resending the same text fails again.
• rate_limited. About 120 messages a minute per player; tell them to slow down, don’t loop.
• Sequence gaps are normal. Blocks, other recipients and expiry hide messages; never treat a gap as an error.
• creator_system messages are from the game, never from a player or from Summer staff.

​

4. Test

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

​

Checklist

• Local Play: open() reports chat unavailable, the chat box is hidden, and there are no script errors.
• The channel opens only after the player entered the World.
• Hosted: a message from one player appears for the other, with the right name.
• A filtered message shows “not sent” and never appears.
• After leaving and joining another match, chat reopens on a new handle.
• Text is shown as plain text: [b]hi[/b] appears literally.

​

Common mistakes

​

See also

• multiplayer-state: the match document that carries player names
• summer-friends: direct messages with friends
• summer-parties: party chat lives in the Summer app
• 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-state: Authority-owned state in Summer multiplayer: shared and private State groups, Commands, Events.
• multiplayer-testing: Test a Summer multiplayer game with Local Play: several players, bad network, bots, a passing run.
• summer-friends: Summer friends in a game: a consented friends list, profile and chat screens, direct messages. Hosted only.
• summer-parties: Let a Summer party play together: the leader presses Play, members follow into the same match. Hosted only.