Summer world saves skill for AI agents

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

{
  "lifetime": "persistent",
  "settlement": { "mode": "none" },
  "persistence": {
    "mode": "checkpoint",
    "recovery_point_seconds": 60,
    "snapshot_schemas": ["courtyard.v1"],
    "migration_ids": []
  },
  "lifecycle": {
    "reconnect_seconds": 30,
    "drain_seconds": 120,
    "transfer": "disabled",
    "completion_owner": "world"
  }
}

const SAVE_SCHEMA := "courtyard.v1"      # the WorldDefinition's snapshot_schemas entry
const CHECKPOINT_SECONDS := 30.0         # at most the WorldDefinition's recovery_point_seconds
var saves: SummerAuthorityWorld          # Summer.authority.world: this World's save slot
var save_revision := "0"
var save_sequence := 0
var save_op: SummerWorldSaveOperation    # the commit in flight, if any
var restored := false
var world_dirty := false
var acknowledged: Array[String] = []

	# Restore before waiting for binding_ready: players are admitted only
	# after the World confirms its restore.
	if not await _restore_world():
		push_error("could not restore this World; not starting")
		return
	var checkpoints := Timer.new()
	checkpoints.wait_time = CHECKPOINT_SECONDS
	checkpoints.timeout.connect(_on_checkpoint_timer)
	add_child(checkpoints)
	checkpoints.start()
	if not world.is_ready():
		await world.binding_ready

## Loads the World's last checkpoint, or starts fresh when it has none.
func _restore_world() -> bool:
	saves = Summer.authority.world
	saves.save_requested.connect(_on_save_requested)
	# Local Play binds the World on the frame after initialize; let that
	# frame pass before loading.
	await get_tree().process_frame
	var loading := saves.load_save()
	var result: SummerResult = await loading.get_result_or_completed_signal()
	if not result.ok:
		return false   # never treat a failed load as an empty World
	var saved := loading.get_save()
	if saved.has_save():
		var doc: Variant = JSON.parse_string(saved.get_data().get_string_from_utf8())
		if not doc is Dictionary or not doc.has_all(["coins", "scores"]):
			return false
		match_doc = doc
	save_revision = saved.get_revision()
	save_sequence = int(saved.get_state_sequence())
	result = await saves.finish_restore(saved).get_result_or_completed_signal()
	if not result.ok:
		return false
	restored = true
	# A save request may have arrived before this point.
	var pending := saves.get_snapshot_request_id()
	if not pending.is_empty():
		_on_save_requested(pending, saves.get_snapshot_deadline_unix_msec())
	return true

	world_dirty = true

func _on_checkpoint_timer() -> void:
	if world_dirty:
		_checkpoint()

## Commits one consistent copy of the World. One save at a time; a retry
## resends exactly the same five arguments.
func _checkpoint() -> SummerWorldSaveReceipt:
	while save_op != null:
		await save_op.get_result_or_completed_signal()
	world_dirty = false
	save_sequence += 1
	var sequence := str(save_sequence)
	var save_id := "cut-" + sequence
	var bytes := JSON.stringify(match_doc).to_utf8_buffer()
	var expected := save_revision
	for attempt in 3:
		save_op = saves.commit_save(expected, save_id, SAVE_SCHEMA, bytes, sequence)
		var result: SummerResult = await save_op.get_result_or_completed_signal()
		var receipt := save_op.get_receipt()
		save_op = null
		if result.ok:
			save_revision = receipt.get_revision()
			return receipt
		if not result.retryable:
			# Conflict, corrupt, incompatible or fenced: stop, never overwrite.
			push_error("world save failed: %s" % result.code)
			break
	world_dirty = true
	return null

## The platform asks for a final save before it stops or moves this World.
## Commit a fresh cut, then acknowledge it. Never wait for timers or frames
## here: gameplay is frozen while the final save runs.
func _on_save_requested(request_id: String, _deadline_unix_msec: int) -> void:
	if not restored or request_id in acknowledged:
		return
	acknowledged.append(request_id)
	var receipt := await _checkpoint()
	if receipt == null:
		return   # never acknowledge a save that did not commit
	await saves.finish_snapshot(request_id, receipt).get_result_or_completed_signal()
	# This runtime may stop right here. Put nothing important after it.

var join := Summer.client.join(SummerJoinTarget.world(world_id))
var joined: SummerResult = await join.get_result_or_completed_signal()

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