跳到主要内容
服务端逻辑与 Events

本页尚未翻译,当前显示英文版本。

Cloud Function 与 RPC

把关键规则留在服务器上:游戏只发出请求,由服务器代码做决定。 服务端逻辑是一个 Cloud Function 或一个 Game server,各自独立部署。游戏用 PlayServCode.CallAsync 调用 Cloud Function 并得到强类型结果;用 PlayServRpc.InvokeAsync 调用正在运行的 Game server。

using Playserv.Wrapper;
using UnityEngine;

var result = await PlayServCode.CallAsync<ClaimReward, RewardGranted>(
    "claim-match-reward", new ClaimReward { MatchId = matchId });

if (result.IsSuccess)
    Debug.Log($"+{result.Value.Coins} coins");
else
    Debug.LogWarning(result.Error.SourceCode);

选择调用方式

PlayServCode.CallAsyncPlayServRpc.InvokeAsync
调用目标已部署的 Cloud Function按名称指定的 Cloud Function 或 Game server
传输方式单独的请求SDK 保持的长连接
适用场景请求-响应:领取奖励、购买物品、校验操作调用正在运行的 Game server
版本可以调用带标签的版本不能选择版本

如果只是读写自己的数据,两者都不需要:请使用 Record。


调用 Cloud Function

部署 Function

编写 Function 并用 CLI 部署,参见使用 CLI 部署。它的 slug,例如 claim-match-reward,就是游戏调用时使用的名称。

允许游戏调用

Function manifest 中的 execute 设置必须允许来自客户端的调用。如果它的认证要求 Player,游戏必须已登录。参见 Functions → Settings。

调用

CallAsync<TRequest, TResponse>(slug, body) 把 body 以 JSON 发送,并把响应读取为 TResponse。CallAsync<TResponse>(slug) 则不带请求体调用。

选项(PlayServFunctionCallOptions)作用
Version调用某个带标签的版本,而不是最新版本。标签不存在时以 function_version_not_found 失败,不会回退到最新版本。
TimeoutSeconds游戏等待的时长。平台最多等待 Function 60 秒,因此设置更长的超时没有意义。
Query · Headers查询参数和自定义请求头。
StrictResponseTypes响应与 TResponse 不匹配时直接失败,而不是尽量填充能填的字段。

CallAsync 总是发送 POST 请求。如需其他方法或原始请求体,请使用 PlayServCode.InvokeAsync(new PlayServFunctionRequest { … })。InvokeBytesAsync 和 DownloadToFileAsync 返回二进制响应;WebGL 中不支持下载到文件。


识别调用者

SDK 每次调用都会附带已登录 Player 的会话。平台校验会话后把 Player 传给你的 Function,因此 Function 知道是谁在调用。在 C# Function 中,它是 Caller.PlayerId,另有 Caller.IsPlayer 和 Caller.IsAnonymous。

永远不要信任请求体中的 Player ID

任何人都可以在请求体中放入任意 ID。请以平台传入的调用者为准确定 Player,并按你的规则校验游戏发来的每个值。


调用 Game server(RPC)

using Playserv.RPC;
using Playserv.Wrapper;

PlayServRpcResult<RoundPreview> preview = await PlayServRpc.InvokeAsync<PreviewRequest, RoundPreview>(
    "arena", "round.preview", new PreviewRequest { Round = 3 });   // sent as "Round": names must match the handler's parameters, case included

InvokeAsync(service, method, request) 通过游戏的连接发送调用。服务名是某个已部署的 Function 或 Game server 的名称:PlayServ 会把它转换为 kebab-case,并去掉末尾的 Service,因此 "Arena" 和 "ArenaService" 都会到达 arena。方法名会原样传给目标。

细节取值
超时默认 30 秒;可通过 PlayServRpcInvokeOptions.Timeout 另行设置。通过 RPC 调用的 Cloud Function 必须在 20 秒内响应。
结果IsSuccess、Value 和 Error。超时和失败都在结果中返回,而不是作为异常抛出:Error.Code 为 Timeout、ServerError 等,UnifiedError.SourceCode 给出平台的具体原因。
不等待响应PlayServRpc.Invoke(service, method, payload) 发送调用后不等待响应。
带 Room 的 Game server只有参与其某个进行中 Room 的 Player 才能调用它。

Unity Game server 通过注册在 PlayServServerRpcRegistry 中的处理器响应 RPC,参见 Game server 托管。


Function 调用的错误与限制

对于 CallAsync,错误在 result.Error 中返回;Error.SourceCode 说明发生了什么,Error.Retryable 表示重试是否有用。只有参数错误、缺少客户端密钥和取消操作会抛出异常。

SourceCode何时出现
not_found当前 Project 和 Environment 中没有该 slug 的 Function。
function_version_not_foundVersion 标签不存在。
function_execute_forbidden该 Function 不接受来自游戏的调用。
player_auth_required该 Function 需要已登录的 Player。
function_unreachableFunction 没有在 60 秒内响应,或已停止运行。
function_response_too_large响应超过 16 MiB。
function_transport_failed网络故障。可重试。

其他任何状态都来自你的 Function 本身,响应体在 result.Response 中。

让发放奖励的调用可以安全重复

超时并不代表 Function 没有执行:它可能在游戏停止等待之后才完成。对于发放东西的调用,请传入这次操作的 ID,例如比赛 ID,让 Function 忽略带有相同 ID 的第二次调用。


后续步骤

更新于 2026年10月22日