# Roblox Data

> Use for Roblox persistent data and cross-server state design: choosing between DataStoreService, OrderedDataStore, MemoryStoreService, and MessagingService; designing save and load flows, schema shape, versioning, metadata, retries, quotas, observability, and concurrency-safe coordination across servers.

- Skill: `luumenlabs/roblox-data` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add luumenlabs/roblox-data`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luumenlabs/roblox-data/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: luumenlabs (https://skillmd.com/u/luumenlabs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/luumenlabs/roblox-data

---


# roblox-data

## When to Use

Use this skill when the task is mainly about Roblox data durability, shared cross-server state, or quota-aware coordination:

- Designing persistent player saves, global config-like records, or other `DataStoreService` usage.
- Choosing between standard data stores and ordered data stores.
- Structuring save payloads, schema versions, migrations, and metadata.
- Deciding when to use `SetAsync()`, `UpdateAsync()`, `IncrementAsync()`, or version APIs.
- Designing ephemeral cross-server systems with `MemoryStoreService`.
- Choosing between memory store queues, sorted maps, and hash maps.
- Coordinating multiple servers with `MessagingService`.
- Handling throttling, request budgets, retries, backoff, contention, and observability.
- Reasoning about stale reads, cache behavior, idempotency, and multi-server correctness.

Do not use this skill when the task is mainly about:

- Remote-event security, client-to-server validation, or general gameplay networking.
- OAuth flows, API key setup, or general Open Cloud authentication.
- Broad engine API lookup outside data services.

## Decision Rules

- Use standard data stores for durable cross-session data that can be represented as numbers, strings, booleans, tables, or buffers.
- Use ordered data stores only when the stored value is numeric and the main requirement is persistent ranking or sorted retrieval.
- Prefer storing one related object per durable key instead of scattering related fields across many durable keys.
- Prefer `UpdateAsync()` when multiple servers might write the same key or when the new value depends on the current value.
- Use memory stores for shared data that is frequent, temporary, or coordination-oriented and can expire.
- Use a memory store hash map for keyed lookups and high fan-out across many keys.
- Use a memory store sorted map when ordering matters or when you need range reads by sort key.
- Use a memory store queue for ordered work processing, matchmaking queues, or claim-and-remove workflows.
- Use `MessagingService` for short-lived broadcast signals, fan-out notifications, or wake-up coordination, not as the durable system of record.
- If the task is mostly about remotes, replication to clients, or trust boundaries, hand off to `roblox-networking`.
- If the task is mostly about general runtime structure or script placement, hand off to `roblox-core`.
- If the task is mostly about member lookup, signatures, or class discovery, hand off to `roblox-api`.
- If a request mixes in out-of-scope material, answer only the data-service portion and exclude the rest.

## Instructions

1. Classify the state before choosing a service:
   - Durable across sessions.
   - Temporary but cross-server.
   - Broadcast-only coordination.
   - Numeric ranking versus arbitrary structured data.
2. Choose the narrowest primitive that fits:
   - Standard data store for durable objects.
   - Ordered data store for durable numeric rankings.
   - Hash map for keyed ephemeral state.
   - Sorted map for ordered ephemeral state.
   - Queue for claim-and-process work items.
   - Messaging for notifications that can be regenerated from other state.
3. For persistent saves, define a stable schema:
   - Keep one self-contained object per key when possible.
   - Include a schema version field inside the value.
   - Reserve migrations for load time or first write after load.
   - Keep keys, scopes, and store names short and predictable.
4. Design writes for concurrency:
   - Prefer `UpdateAsync()` for contested keys.
   - Make callbacks deterministic and non-yielding.
   - Return `nil` to abort invalid updates.
   - Preserve existing metadata and user IDs when you do not intend to clear them.
5. Design reads with cache behavior in mind:
   - Treat `GetAsync()` as locally cached for a short window.
   - Use uncached reads only when freshness matters enough to justify extra budget use.
   - Avoid reading immediately after writing from a different server unless the design accounts for staleness.
6. Treat quotas as part of the design:
   - Check request budgets before bursty durable writes.
   - Batch related durable data into one object where it improves atomicity and budget use.
   - Keep memory-store TTLs as short as the use case allows.
   - Remove queue and sorted-map items promptly after processing.
7. Design for retries and failure:
   - Wrap network calls in `pcall()`.
   - Retry transient failures with exponential backoff.
   - Add jitter or spreading when many servers may retry together.
   - Make retryable operations idempotent whenever possible.
8. Use observability to close the loop:
   - Watch request counts, throttles, and quota usage for data stores.
   - Watch memory usage, request-unit usage, and throttle statuses for memory stores.
   - Use dashboards to confirm whether the bottleneck is global quota, per-key contention, or hot partitions.
9. Use messaging as a coordination layer, not storage:
   - Publish compact events.
   - Re-read or update authoritative state in data or memory stores as needed.
   - Assume messages can be delayed or duplicated and make handlers safe.
10. Keep guidance inside scope:
   - Focus on persistence, ephemeral shared state, quotas, and concurrency.
   - Do not drift into remote security, gameplay networking, or auth flows.

## Using References

- Open `references/data-stores-guides.md` for standard versus ordered data stores, core CRUD patterns, metadata, serialization, and save-shape decisions.
- Open `references/data-store-best-practices.md` for durable schema layout, key organization, storage hygiene, and cleanup strategy.
- Open `references/versioning-listing-caching-limits-and-observability.md` for version history, prefix listing, cache behavior, limits, request budgets, throttling, and dashboards.
- Open `references/memory-stores-guides.md` for choosing between queues, sorted maps, and hash maps and for the core API patterns of each.
- Open `references/memory-store-best-practices-limits-and-observability.md` for TTL strategy, sharding, partition pressure, request-unit budgeting, contention handling, and dashboards.
- Open `references/cross-server-messaging.md` for topic design, publish-subscribe flow, and coordination patterns that pair messaging with durable or ephemeral state.
- Open `references/data-stores-vs-memory-stores-comparison.md` when the first decision is which service class should own the data.

## Checklist

- The state is classified as durable, ephemeral cross-server, or broadcast-only.
- The chosen service matches the durability and ordering requirements.
- Persistent keys use a stable schema with an explicit version field.
- Durable writes use `UpdateAsync()` when contention is possible.
- Ordered data stores are only used for numeric ranking data.
- Cache behavior and stale-read risk are accounted for.
- Request budgets, quotas, and throttling behavior are part of the design.
- Memory-store TTLs are intentionally short and cleanup paths are explicit.
- Queue items are removed after processing and sorted-map or hash-map items are pruned when stale.
- Messaging is used for coordination, not as the system of record.
- Retry logic uses `pcall()` plus backoff rather than tight loops.
- No remote security, OAuth, or general API-lookup material is included.

## Common Mistakes

- Using `SetAsync()` on hot keys that multiple servers can write concurrently.
- Splitting one durable player profile across many unrelated keys without a strong reason.
- Using ordered data stores for structured blobs or metadata-heavy records.
- Forgetting that `GetAsync()` can return a cached value for a few seconds.
- Treating memory stores as durable storage.
- Using a queue when random keyed access or scans would fit a hash map better.
- Putting all hash-map traffic on one hot key and then hitting partition throttles.
- Keeping long TTLs on temporary memory-store items and filling quota with stale data.
- Using `MessagingService` as the only source of truth for recoverable state.
- Retrying immediately on throttles or conflicts and causing coordinated retry storms.

## Examples

### Choose the right service

- Player profile save: standard data store with one object per player key.
- All-time coins leaderboard: ordered data store keyed by player identifier with numeric values.
- Matchmaking pool: memory store queue.
- Cross-server auction board with ranking: memory store sorted map.
- Shared ephemeral room registry keyed by server id: memory store hash map.
- Force a cache refresh workflow across servers: message plus data-store or memory-store re-read.

### Use `UpdateAsync()` for contested durable saves

```lua
local DataStoreService = game:GetService("DataStoreService")
local profileStore = DataStoreService:GetDataStore("PlayerProfiles")

local function saveCoins(userId, delta)
    return profileStore:UpdateAsync(("player/%d"):format(userId), function(current, keyInfo)
        current = current or {schemaVersion = 1, coins = 0}
        current.coins += delta
        return current, keyInfo:GetUserIds(), keyInfo:GetMetadata()
    end)
end
```

### Use messaging to wake workers, not to hold state

```lua
-- Publish: "queue has work"
-- Receiver: read the queue or map, then process authoritative state there.
```