Multiplayer testing skill for AI agents

​

When your agent uses it

• Running or testing a Summer multiplayer game locally with several players (Local Play)
• Testing multiplayer under latency, jitter or packet loss, or with bots
• A multiplayer run says ok but nothing networked works, or deciding whether a multiplayer change is done

​

Install

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

​

The skill

​

1. Start Local Play

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

<summer> --headless --path . --import
<summer> --path . --summer-local-play 2 --summer-local-play-timeout 30

​

2. Make the network bad

summer_project_setting key="summer/local_play/network/round_trip_msec" value=100
summer_project_setting key="summer/local_play/network/jitter_msec" value=10
summer_project_setting key="summer/local_play/network/loss_percent" value=1

[summer]

local_play/network/round_trip_msec=100
local_play/network/jitter_msec=10
local_play/network/loss_percent=1

​

3. Read the run

SUMMER_LOCAL_PLAY_RESULT {"ok":true,"players":2,"network":{...},"processes":[{"label":"authority","script_errors":0,...},{"label":"player-1","joined":true,"script_errors":0,...}],...}

• "ok":true, and every process has "script_errors":0.
• The game’s own ready lines appear: the authority’s, and one per client after its join Command (COURTYARD_AUTHORITY_READY, COURTYARD_CLIENT_JOINED in the Courtyard example). Print one in your game too.
• No [SummerNetworkSpawner] cannot attach warning on any process.
• No SCRIPT ERROR lines.

​

4. Drive the game with bots

<summer> --path . --summer-local-play 2 --summer-local-play-headless --summer-local-play-timeout 20 -- --bot={client}

extends Node
## Test bot for Local Play, enabled with `-- --bot={client}`. It presses the
## real input actions. Bot 1 walks to the first coin and collects it; every
## bot prints what it sees, for the test run to check.

const COIN := "0"

var number := 0
var main: Node
var elapsed := 0.0
var step := 0

func _process(delta: float) -> void:
	elapsed += delta
	var me := _own_player()
	if me == null:
		return
	if number == 1 and step == 0:
		var at: Array = main.match_doc.get("coins", {}).get(COIN, [])
		if at.is_empty():
			return
		var to_coin := Vector2(at[0] - me.global_position.x, at[2] - me.global_position.z)
		if to_coin.length() > 0.5:
			_steer(to_coin.normalized())
			return
		_steer(Vector2.ZERO)
		step = 1
		print("BOT_MOVED %s" % me.global_position)
		var collected: Dictionary = await main.collect(COIN)
		print("BOT_COLLECT %s" % JSON.stringify(collected))
	if elapsed > 6.0 and step < 2:
		step = 2
		for node in main.get_node("Entities").get_children():
			if node != me:
				print("BOT_SAW %s" % node.global_position)
		print("BOT_SCORES %s" % JSON.stringify(main.match_doc.get("scores", {})))

func _own_player() -> Node3D:
	for node in main.get_node("Entities").get_children():
		if node.get_script() == preload("res://client/player_owner.gd"):
			return node
	return null

func _steer(direction: Vector2) -> void:
	for action in [&"ui_left", &"ui_right", &"ui_up", &"ui_down"]:
		Input.action_release(action)
	if direction.x > 0.0: Input.action_press(&"ui_right", direction.x)
	if direction.x < 0.0: Input.action_press(&"ui_left", -direction.x)
	if direction.y > 0.0: Input.action_press(&"ui_down", direction.y)
	if direction.y < 0.0: Input.action_press(&"ui_up", -direction.y)

	# Local Play test bot: `-- --bot={client}` (see multiplayer-testing).
	for arg in OS.get_cmdline_user_args():
		if arg.begins_with("--bot="):
			var bot := preload("res://client/bot.gd").new()
			bot.number = int(arg.trim_prefix("--bot="))
			bot.main = self
			add_child(bot)

• [player-1] BOT_MOVED and [player-2] BOT_SAW report the same position (the observer is up to 100 ms behind while moving, then equal).
• [player-1] BOT_COLLECT {"ok":true...} and both players print the new score.

​

5. What Local Play cannot show

• Hosted-only services answer with an error code locally: parties, friends, World chat, the store, client leaderboards and analytics. Their skills list the codes. Make the UI hide or explain them; never crash on them.
• Matchmaking’s accept prompt. Local Play seats players directly: no proposal, one World per queue.
• A player leaving for good. A client that quits or calls Summer.client.leave() only disconnects. session_disconnected fires and their seat is held. session_left arrives when the World ends; hosted, it arrives when Summer ends the Session.
• Which scene the hosted server starts. Local Play starts the authority scene by name. Summer starts the exported server.pck with no scene, so a server preset without the summer_authority feature still passes here and then runs the title screen hosted, where every join fails with world_start_timeout. Run the bundle’s server.pck with no scene (multiplayer-publish, step 4d).
• A wrong Game ID. Local Play has no hosted identity, so Summer.initialize("some-id") passes here and fails hosted with game_identity_mismatch. Call Summer.initialize() with no ID; only a real online join after publishing proves it.
• Real devices, real accounts, real distances. Publish to staging for that (multiplayer-publish).

​

Checklist for any multiplayer change

• Ran Local Play with at least 2 players, and once with 100 ms / 10 ms / 1 %.
• Every process: no SCRIPT ERROR, no cannot attach, script_errors 0.
• The game’s own ready lines appear for the authority and every client.
• Your own player responds instantly and never snaps while moving normally.
• Other players move smoothly and end where their owners are.
• Shared state matches on every client; private state reaches only its owner.
• A refused Command changes nothing and shows its reason.

​

Common mistakes

​

Next

​

From a shell

​

Related skills

• multiplayer: Start here for Summer multiplayer: how authority, clients, Worlds and Sessions fit, and what comes next.
• multiplayer-project: Set up a Summer multiplayer project: entry scenes, World and queue files, joining, a first Local Play.
• multiplayer-movement: Movement in Summer multiplayer: owners move instantly, others glide, the authority checks each pose.
• multiplayer-state: Authority-owned state in Summer multiplayer: shared and private State groups, Commands, Events.
• multiplayer-publish: Ship a hosted Summer multiplayer game: the bundle, server preset, pre-upload checks, a new Build.
• release-readiness: Before releasing a Summer game version, prove players can play it: server, online join, progress, files.
• summer-friends: Summer friends in a game: a consented friends list, profile and chat screens, direct messages. Hosted only.
• summer-match-results: End a Summer match: report each player’s win, loss or draw, show results on clients, then close the World.
• summer-matchmaking: Get players into matches with Summer matchmaking: queues, teams, accept prompts, join progress and failures.
• summer-parties: Let a Summer party play together: the leader presses Play, members follow into the same match. Hosted only.
• summer-player-data: Save a player’s progress so it follows them to every match: authority load and commit, autosave, safe retries.
• summer-store: Sell Summer items for Sparks in a multiplayer game: shop, checkout, owned items, authority entitlement checks.
• summer-world-chat: Add match chat to a Summer game: one World channel shared by everyone in the match. Hosted only.