What's new

These docs track PlayerState V1 for the Creator Store model. Install or update the model there; this site documents behaviour and API surface.

Notable capabilities and recent additions. For how data is scoped and replicated, start with Concepts and the data visibility model.

Docs layout: The API reference is split into topic pages under Server, Client, and Types—bookmark deep links that used #sections may need updating.

• Shared session and server-only data
• Session (per-player, non-persistent) and migration
• Other API highlights

Shared session and server-only data

• Shared session — Server-wide non-persistent state for the current server, replicated to every client in that server. Configure via Server.SharedSession in PlayerStateConfig. Server APIs include SetShared, GetShared, SetSharedPath, GetSharedPath, SetSharedValues, OnSharedChanged, GetSharedReplica, GetSharedAll, and IsSharedReady. Client APIs include GetShared, GetSharedPath, OnSharedChanged, GetSharedReplica, GetSharedAll, and IsSharedReady (reads wait until the shared Replica is ready, similar to profile data). Shared session guide · Server API · Client API

• Server-only player data — ServerOnlyRoots (for example a top-level "Server" root) persist in profile.Data but are stripped before the player Replica, so they never replicate to clients. SetOfflineData can target those paths where appropriate. Server-only data · Data visibility

Session (per-player, non-persistent) and migration

• Session data — Runtime-only roots such as session replicate during play but do not persist. RuntimeNonPersistentRoots in config lists top-level keys stripped before save.

• Legacy data migration — Opt-in import from an old DataStore during profile load (strategies include Auto, Overwrite, KeepNew, Manual, and related options). MigrationResult reports when migration finishes (applied, legacy data, strategy, metadata). Migration guide

Other API highlights

Server and client references cover the full surface area; these are commonly called out:

• Server OnChanged — Replica-backed listeners per player. Change subscription
• BatchUpdateValues — Batch numeric increment/decrement-style updates. BatchUpdateValues
• IsPlayerDataReady — Non-blocking profile + Replica readiness check. Details
• BatchSetValues / FlushBatch — Bulk updates with optional flush. Server API
• Leaderstats — Automatic integration when configured in DefaultData / config.
• ClearPathCache (server) / ClearCache() (client) — Debugging and tuning.
• Array & dictionary helpers — AddToArray, SetInDict, and related operations.
• GetOfflineData (client) — Saved profile snapshot for another user via RemoteFunction. Client API
• Client OnChanged — Action-aware change info (Set, TableInsert, etc.), global "." listener, IsReady() for gated reads.

Lifecycle events: BeforeRelease, BeforeSave, ProfileLoaded, ProfileUnloaded, MigrationResult. Events

• BeforeRelease — Fires before a player's profile session is released on leave or server shutdown. Intended for leave-only final data writes (e.g. persisting world state into the profile). Does not fire on SaveData(). On leave, runs before BeforeSave. BeforeRelease()