Back to Details

roblox-server-data

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Roblox Server & Shared Data

Roblox 服务器与共享数据

When to Load

加载时机

Load for server-level or cross-server data: leaderboards (OrderedDataStore), cross-server messaging (MessagingService), shared world state, persistent non-player data, season/guild data. For player data (DataStore, ProfileStore, session locking), use 
roblox-data
.
适用于服务器级或跨服务器数据：排行榜（OrderedDataStore）、跨服务器消息传递（MessagingService）、共享世界状态、持久化非玩家数据、赛季/公会数据。若处理玩家数据（DataStore、ProfileStore、会话锁定），请使用
roblox-data
。

Quick Reference

快速参考

OrderedDataStore (Leaderboards)

OrderedDataStore（排行榜）

  • Sortable DataStore. Keys must be positive integers (use UserId).
  • GetSortedAsync(ascending, pageSize, minValue, maxValue)
    → sorted pages
  • For leaderboards ONLY — not player data
luau
local store = DataStoreService:GetOrderedDataStore("LeaderboardCoins")
store:SetAsync(player.UserId, playerCoins)
local top10 = store:GetSortedAsync(false, 10):GetCurrentPage()
  • 可排序的DataStore。键必须为正整数（建议使用UserId）。
  • GetSortedAsync(ascending, pageSize, minValue, maxValue)
    → 返回排序后的分页数据
  • 仅用于排行榜 — 不可用于玩家数据
luau
local store = DataStoreService:GetOrderedDataStore("LeaderboardCoins")
store:SetAsync(player.UserId, playerCoins)
local top10 = store:GetSortedAsync(false, 10):GetCurrentPage()

MessagingService (Cross-Server)

MessagingService（跨服务器）

  • Real-time communication between server instances
  • SubscribeAsync(topic, callback)
    / 
    PublishAsync(topic, message)
  • No delivery guarantee — design for idempotency
luau
MessagingService:SubscribeAsync("ServerShutdown", function(msg) print(msg.Data) end)
MessagingService:PublishAsync("ServerShutdown", "server-" .. game.JobId)
  • 服务器实例间的实时通信
  • SubscribeAsync(topic, callback)
    / 
    PublishAsync(topic, message)
  • 不保证消息送达 — 设计时需考虑幂等性
luau
MessagingService:SubscribeAsync("ServerShutdown", function(msg) print(msg.Data) end)
MessagingService:PublishAsync("ServerShutdown", "server-" .. game.JobId)

GlobalDataStore (Shared State)

GlobalDataStore（共享状态）

  • Non-player shared state: guild data, season config, global counters
  • Same API as DataStore but different conceptual use
  • Use 
    UpdateAsync
    for atomic read-modify-write (prevents race conditions)
  • Never use for player data — no session locking
  • 非玩家共享状态：公会数据、赛季配置、全局计数器
  • API与DataStore相同，但使用场景不同
  • 使用
    UpdateAsync
    实现原子性读写（防止竞态条件）
  • 绝不可用于玩家数据 — 无会话锁定机制

Persistent World State Patterns

持久化世界状态模式

  • Building/construction games: serialize player-built structures to DataStore, reload on join
  • Season/leaderboard data: OrderedDataStore for rankings, GlobalDataStore for season metadata
  • Guild/clan data: GlobalDataStore with guild ID as key, MessagingService for real-time guild chat
  • Economy counters: GlobalDataStore for server-wide currency totals, UpdateAsync for atomic increments
  • 建造类游戏：将玩家建造的结构序列化为DataStore数据，玩家加入时重新加载
  • 赛季/排行榜数据：使用OrderedDataStore存储排名，GlobalDataStore存储赛季元数据
  • 公会/氏族数据：以公会ID为键存储在GlobalDataStore，使用MessagingService实现实时公会聊天
  • 经济计数器：使用GlobalDataStore存储全服务器范围的货币总量，通过UpdateAsync实现原子递增

Cross-Server Patterns

跨服务器模式

  • Server registration: publish server info on start, heartbeat on interval
  • Player migration: notify old server to release locks via MessagingService
  • Global events: publish to all servers, each handles locally
  • 服务器注册：启动时发布服务器信息，定期发送心跳包
  • 玩家迁移：通过MessagingService通知旧服务器释放锁定
  • 全局事件：向所有服务器发布事件，各服务器本地处理

Pitfalls

注意事项

  • MessagingService is fire-and-forget — no delivery guarantee, no ordering
  • GlobalDataStore has same rate limits as player DataStores — don't spam
  • OrderedDataStore keys MUST be positive integers (use UserId)
  • Never store Instances — serialize to primitives first
  • UpdateAsync for any shared counter to prevent lost updates
Need more detail? Load 
references/full.md
for the complete reference with code examples, API tables, and edge cases.
  • MessagingService是“发后即忘”模式 — 不保证送达，也不保证排序
  • GlobalDataStore与玩家DataStore具有相同的速率限制 — 请勿频繁调用
  • OrderedDataStore的键必须是正整数（建议使用UserId）
  • 切勿存储实例对象 — 需先序列化为基本数据类型
  • 任何共享计数器都要使用UpdateAsync，以防止更新丢失
需要更多细节？ 加载
references/full.md
获取完整参考文档，包含代码示例、API表格和边缘情况说明。