snap-spectacles-sync

# 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>