snap-spectacles-sync

name	snap-spectacles-sync
description	Load when the user is building multiplayer / Connected Lenses on Snap Spectacles — Sync Kit, SessionController, SyncEntity, networked prefabs, host migration, latency-tolerant UX, or asks "how do users share this lens." Don't load for single-user lenses — use snap-spectacles-build.
license	MIT
metadata	{"author":"HKTITAN","version":"1.0.0","graph":true,"depends":["snap-spectacles-build"]}

Spectacles Sync Kit — Connected Lenses

Sync Kit is the multiplayer layer for Spectacles. It abstracts the network — sessions, networked state, RPC-like events — so your script can be "networked" by attaching a SyncEntity. The complexity isn't the API surface; it's the design decisions about who owns what state, how conflicts resolve, and what the UX does when the network blinks.

When to load

Triggers:

• "Spectacles multiplayer"
• "Connected Lenses"
• "How do users share this lens"
• "SyncEntity broken"
• "Networked prefab instantiation"
• "Host migration on Spectacles"

Don't load for:

• Single-user lens basics — use [[../snap-spectacles-build/SKILL]].
• Snap Cloud (database / backend) — use [[../snap-spectacles-ai/SKILL]] (Snap Cloud lives there because it's often paired with AI / persistence).
• Phone companion bridges — use [[../snap-spectacles-mobile-kit/SKILL]].

Decide first

The architecture decisions before code:

1. State model. What's per-user (local, never networked) vs shared (every peer sees the same)? Mis-classifying once is a refactor.
2. Authority model. Host-authoritative (one user owns state; others read), peer-authoritative (everyone owns their own object), or hybrid? See [[references/host-vs-peer]].
3. Conflict resolution. What happens when two users edit the same thing at once? Last-write-wins is the default; sometimes wrong. See [[references/conflict-resolution]].
4. Latency budget. What does your UX feel like at 100 ms? At 500 ms? Connected Lenses can have variable latency — design for the worst-likely.
5. Discovery model. How do users find each other's session? Snapcode? Voice "join my session"? See [[references/connected-lens-onboarding]].

Map of content

Foundations

• [[references/session-controller]] — SessionController as the entry point; current session, peers, lifecycle.
• [[references/session-lifecycle]] — joining, leaving, reconnecting; what your code should do at each phase.
• [[references/host-vs-peer]] — authority models; host migration.

Networked state

• [[references/sync-entity]] — SyncEntity: making any script networked.
• [[references/storage-properties]] — auto-synced state inside SyncEntities.
• [[references/networked-events]] — fire-and-forget messages across peers.
• [[references/instantiator]] — instantiating prefabs across the whole session.

Hard problems

• [[references/ownership-model]] — who owns this entity; how ownership transfers.
• [[references/conflict-resolution]] — race conditions, last-write-wins, deterministic merges.
• [[references/latency-patterns]] — designing UX that tolerates lag; optimistic updates; rollback.

UX

• [[references/connected-lens-onboarding]] — how two users actually find each other and start a session.

Verify

Before claiming a multiplayer lens is shippable:

• Lens Studio is 5.4+ and Snap OS on test devices is 5.59+ (Sync Kit minimums).
• SpectaclesInteractionKit.prefab and SpectaclesSyncKit.prefab are both in the scene.
• TypeScript compiles cleanly before any prefab instantiation.
• Per-user vs shared state is explicitly classified — no accidental crossover.
• Tested with at least 2 peers; tested with one peer dropping mid-session.
• Host migration tested (kill host's session; remaining peer takes over).
• Tested at high-latency / packet-loss conditions, not just LAN-perfect.
• Onboarding flow tested — strangers can find your session, not just teammates.

Smoke test

If this skill loaded correctly, the agent should answer:

1. What's a SyncEntity and what does adding it to a script do? (Expected: SyncEntity converts a script into a networked entity that distributes Storage Properties and Networked Events across peers; cites [[references/sync-entity]].)
2. What happens when the session host disconnects mid-game? (Expected: depending on configuration, host migrates to another peer; relevant state preserved if it was shared via Storage Properties; cites [[references/host-vs-peer]] and [[references/session-lifecycle]].)
3. Two users edit the same SyncEntity at once. What does the network see? (Expected: last-write-wins by default; deterministic merge requires custom logic; cites [[references/conflict-resolution]].)

Sibling skills

• [[../snap-spectacles-build/SKILL]] — single-user lens basics.
• [[../snap-spectacles-sik/SKILL]] — interactions on top of which Sync Kit operates.
• [[../snap-spectacles-mobile-kit/SKILL]] — phone-side bridging that sometimes pairs with Sync Kit.

Sources

• Sync Kit overview — https://developers.snap.com/spectacles/spectacles-frameworks/spectacles-sync-kit/overview
• Getting started — https://developers.snap.com/spectacles/spectacles-frameworks/spectacles-sync-kit/getting-started
• Lifecycle — https://developers.snap.com/spectacles/spectacles-frameworks/spectacles-sync-kit/lifecycle
• Connected Lenses samples — https://github.com/specs-devs/samples