VirtualStore

VirtualStore.players is the convenient player lifecycle layer. VirtualStore.new is the lower-level key-based Store.

The player facade opens Player_<UserId>, associates GDPR IDs, tracks players, releases sessions and exposes short mutation helpers over a normal Store.

Use players for ordinary player profiles. Use the core Store for guilds, auctions, global records, custom keys or infrastructure code.

The facade is not a second persistence system. Advanced work remains available through Data.Store.

Every key stores gameplay Data beside internal Meta, a schema version and a VirtualStore format marker.

The template supplies missing defaults. Metadata holds the lease, revisions, user IDs, tags, write receipts and operation ledgers without mixing them into gameplay data.

Put persistent gameplay state in the template: currency, inventory, settings and progression. Treat metadata as framework-owned.

A template is not a fallback for a failed load. VirtualStore fails closed instead of replacing unknown stored data with defaults.

A lease is an expiring ownership token stored with one key. It identifies the only server allowed to save that active profile.

Open claims a token inside UpdateAsync. Every later write verifies the same stored token. Another server may claim only after release or expiry.

Leases automatically protect player joins, teleports, reconnects and any record that must have one active writer.

A lease is not a gameplay resource lock and should not be force-released casually; another server may still have unsaved RAM changes.

A Session is the server-memory view of one opened record, with safe mutation, save, operation and release methods.

It moves through explicit states such as Active, Releasing, Released and LeaseLost. Only an Active owner may mutate or commit.

Use the active session for gameplay involving an online player or an opened custom record.

Memory is not durable by itself. A full server-process crash can lose changes that were never checkpointed or represented as durable operations.

StrictData makes public profile data read-only. Changes go through Set, Patch, Increment, Insert, Remove or a transaction.

Safe helpers copy and validate the change, mark the session dirty, record changed paths and notify replication and audit listeners.

Use path helpers for small focused changes such as adding coins, changing a setting or inserting an item.

Direct writes to non-strict session.Data cannot immediately emit paths and can bypass validation, audit and replication behavior.

A transaction is an isolated working copy for several related changes inside one profile.

The callback edits the copy. Callback failure, cancellation or invalid data discards it; success validates and swaps the completed copy into live session memory.

Use it for shop purchases, crafting, equipping, reward claims and any action where all profile changes must succeed or none should.

A local transaction is not a DataStore write and cannot atomically commit several different keys.

A named lock prevents two systems in the same server process from editing the same logical resource simultaneously.

WithLockTransaction holds the name, edits an isolated copy and commits only after the callback succeeds. Multi-session helpers acquire locks in deterministic key order.

Use it when inventory, crafting and trade code could race over one active session or several locally open participants.

Local locks do not protect another server and do not make later writes to separate DataStore keys atomic.

Dirty state means gameplay data changed since the last confirmed commit. Autosave persists it later; checkpoint persists it now; release performs the final save and clears the lease.

Autosaves are staggered and concurrency-limited. Clean sessions skip unnecessary data writes until lease renewal is due. Release saves final data and unlocks in one write.

Rely on autosave for routine progress. Checkpoint before teleport or a risky external flow. Release when ownership must end.

A manual save is not needed after every mutation. Revision counts commits; DataRevision counts persisted gameplay-data changes.

A write receipt is a bounded record of a unique commit token and whether that commit changed gameplay data.

If DataStore commits a write but the response is lost, retrying with the same token recognizes the completed commit instead of applying its transform twice.

VirtualStore uses this automatically for saves, releases and updates where a network failure can make the result uncertain.

Receipts are intentionally bounded. They prevent short-term retry ambiguity, not permanent business-request idempotency.

A durable operation is uniquely identified pending work stored inside the target profile.

A deterministic non-yielding handler mutates profile data. The result receipt is committed with the same single-profile write, so retries can see whether it already applied.

Use it for developer products, crate outcomes, matchmaking rewards, offline grants and work that must survive disconnects, teleports or temporary outages.

Do not perform external side effects or random selection inside a retryable handler. Decide random outcomes before queueing and include them in the payload.

A receipt records terminal operation status. Dedupe tombstones remember completed IDs longer. TTL expires stale work. Dead letters retain bounded failed-operation details.

Attempts, timestamps and errors update during retries. The attempt limit or TTL produces a Failed receipt and dead letter. Reusing a retained ID returns its receipt instead of applying again.

Use status and dead letters to drive purchase retry, compensation, incident investigation and admin repair.

All ledgers are bounded. Never reuse operation IDs. Replay a failed operation under a new globally unique ID.

Replication is a read-only client mirror containing only server-approved public paths or transformed output.

The owner receives a revisioned initial snapshot, then path patches from safe mutations. A missed revision requests a fresh snapshot.

Use it for HUD currency, settings, level, XP, inventory views and quest progress that the owning client must display.

Publishing a parent can expose every child. Prefer narrow nested paths and never expose receipts, escrow, anti-cheat flags or admin data.

Validation rejects values Roblox cannot safely store. Migrations convert an older known schema into the current schema one destination version at a time.

Open and offline update run required migrations, reconcile template defaults and validate before allowing the new record to commit.

Use migrations when renaming fields, changing inventory formats, splitting values or introducing a new persistent model.

Migration is not automatic corruption repair. Each migration must be deterministic and tested against real older shapes.

An adapter implements storage requests. The production adapter talks to Roblox DataStore; the memory adapter provides deterministic local storage for tests.

Core lifecycle and correctness code call the adapter contract instead of directly depending on live DataStore behavior.

Use the memory adapter for automated tests, retry simulation, lease conflicts, operation failure cases and scheduler benchmarks.

A memory benchmark does not measure Roblox network speed. Published-server comparisons need identical real conditions.

Budget waiting controls request timing, the scheduler spreads autosaves, diagnostics count system behavior and critical state summarizes repeated recent issues.

Requests wait for their correct Roblox budget. Autosaves use capped concurrency. Metrics record requests, retries, waits, latency, failures, restores, deletes and lease loss.

Use diagnostics for dashboards, alerting, load testing and deciding whether trading or purchases should temporarily degrade during an incident.

Higher concurrency is not automatically faster. Measure diagnostics before changing safety-oriented defaults.

MessagingService sends hints that a waiting server wants a lease or that new operation work exists.

A message can encourage faster save, release or processing, while DataStore records, polling, autosave and lease timeout remain the correctness path.

Enable it to reduce reconnect, teleport handoff and offline-delivery latency across servers.

Messaging delivery is not guaranteed. Code must remain correct when every message is dropped.

Version APIs inspect historical DataStore versions, restore one as a new latest version or create a deletion tombstone after exclusive ownership.

Restore and delete reject active foreign leases. Restore creates another version, preserving the state that existed before restoration.

Use it for administrator rollback, investigating lost progress and deliberate privacy/deletion workflows.

Restore is not safe while another server actively owns the profile, and Roblox controls how long old versions remain available.

Admin repair is a server-only, key-based set of inspection and recovery methods protected by an explicit AdminAuthorize callback.

Authorized tooling can inspect metadata, list pending work and dead letters, cancel or fail work, requeue with a new ID, compact ledgers or force-release an exact inspected lease token.

Use it from trusted incident tooling when normal retry and lease timeout are not enough.

Never expose a generic repair remote to clients. Dead-letter payloads and lease tokens contain sensitive operational data.

Patterns are removable gameplay modules for cooldowns, daily rewards, purchase receipts, offline rewards and timed effects.

They prepare template fields and deterministic handlers, then call the same public transactions and durable operations as custom game code.

Use them to ship common systems quickly without designing their retry and idempotency behavior from scratch.

Patterns are not correctness-critical core. They can be deleted, and they never replace leases, persistence or operation receipts.

An optional OrderedDataStore extension that stores integer projections and reads sorted pages without using VirtualStore's profile envelope.

Writes use OrderedDataStore budgets and bounded retries. Top queries page through sorted results; rank lookup scans only up to a configured maximum.

Use it for persistent scoreboards, fastest times, season points and other sortable integer read models.

The projection is not atomic with the source profile and may lag. Never use it as the authoritative source for currency, purchases or trades.

A saga is a persistent multi-step workflow used because Roblox cannot atomically commit several DataStore keys. A journal records progress; escrow reserves assets before settlement.

The coordinator writes pending state, queues unique idempotent operations for each profile, observes receipts and retries, compensates or marks NeedsRepair when settlement cannot finish.

Use it for player trades, auctions, guild banks, ownership transfers and any valuable cross-profile economy action.

withLockTransactions only protects local memory. It is not a substitute for a persistent coordinator across DataStore keys.