用途:在 Decentraland 场景中搭建多人联机玩法,由无头权威服务器掌控游戏状态、校验变更并防作弊,服务端与客户端共用同一套代码。需要基础 CRDT 多人联机(无服务器)时,应改用 multiplayer-sync 技能。
必要用法:必须安装 auth-server 分支 SDK——npm install @dcl/sdk@auth-server,标准 @dcl/sdk 不含 isServer、registerMessages、Storage、EnvVar 等 API。scene.json 必须设置 authoritativeMultiplayer: true、worldConfiguration.name,以及 logsPermissions(列出可查看服务端日志的钱包地址,否则 console.log 不显示)。运行使用常规预览;当 scene.json 里开启该标志后,预览会在后台自动启动权威服务器。
主要能力:
- 服务端/客户端分支:用 isServer()(来自 @dcl/sdk/network)区分逻辑,服务端无渲染运行,可通过 PlayerIdentityData 读取真实玩家位置。
- 带校验的同步组件:自定义组件用全局 validateBeforeChange,内置组件(Transform、GltfContainer)用逐实体校验,限制仅 AUTH_SERVER_PEER_ID 可改。创建并保护实体后用 syncEntity(entity, [componentIds]) 同步。
- 消息通信:用 registerMessages() 定义消息,方向含客户端到服务端、服务端到全体或指定客户端;客户端发消息前需等待 isStateSyncronized()(注意 SDK 拼写)返回 true。
- Storage:服务端专用的 world 与 player 存储,仅接受字符串,对象需 JSON.stringify/parse。
- EnvVar:读取环境变量,本地用 .env,生产用 npx sdk-commands deploy-env。
建议结构:共享的 schemas.ts 与 messages.ts 放 shared/,服务端逻辑放 server/,UI 与输入放 client/。
限制与注意:运行时为沙箱 QuickJS,无 fs、http 等 Node API,仅支持 setTimeout/setInterval;时间戳等大数应用 Schemas.Int64;服务端读取玩家位置时不要信任客户端上报数据。其余细节(认证流程、状态协调等)见 {baseDir}/references/server-patterns.md。