Data Visibility Model

This page is part of the Concepts trail. PlayerState separates who can read data, whether it persists, and how widely it replicates. Use what follows to pick the right bucket before you structure your DefaultData or config.

• Mental model
• Choosing SharedSession vs Server

Mental model

Kind	Scope	Saved	Replicated to clients
Normal player data (top-level fields and nested paths)	Per player	Yes	Yes — only to that player’s client
session (and other RuntimeNonPersistentRoots)	Per player	No	Yes — only to that player’s client
SharedSession	Current server	No	Yes — every client in this server
Server root (and other ServerOnlyRoots)	Per player	Yes	Never — server APIs only

• Normal data — Default replicated profile fields. Existing games keep using top-level keys as today; you do not need a Public / Private split for compatibility.
• session — Temporary per-player state that resets each join and never touches the DataStore. See Session Data.
• SharedSession — Temporary server-wide state for this running server only (round phase, votes, timers all clients should see). Not universe-wide or cross-server. See Shared Session.
• Server — Persistent per-player fields stripped out before the player Replica is built, so no client receives them—even the owner. See Server-only data.

Choosing SharedSession vs Server

Common confusion

Server is per-player saved data, not “whole server state.”
SharedSession is current-server shared state visible to all clients, not saved.

• Use SharedSession when every client in this server needs the same read-only (on the client) UI or gameplay snapshot: match phase, round timer end timestamp, vote counts, etc.
• Use Server under a player profile when something must persist but must never replicate to any client: internal versioning, anti-tamper caches, moderation flags, etc.

Do not put secrets in normal replicated fields if the owning client must never see them—move those roots under Server or add them to ServerOnlyRoots.

Implementation notes (accuracy)

Internally:

• Shared session uses a dedicated SharedSession Replica token and syncs to all clients in the current server.
• Player data Replicas are built from a filtered clone of profile data with ServerOnlyRoots removed.
• profile.Data remains the server-side source of truth. Normal writes update both profile.Data and the client-visible Replica. Server-only writes update only profile.Data.

Migration

Existing projects do not need to reorganize into new top-level wrappers. Normal top-level data behaves as before.

To hide saved internal fields from clients, move them under a Server root (or another root you list in ServerOnlyRoots) instead of leaving them in replicated paths.

See also: Legacy Data Migration for importing old DataStores (separate topic).