服务 / TeleportService
TeleportService Class
多场景和传送服务
Table of contents
Methods
asyncGetPlayerRoomInfo(userId : string ): Promise <RoomInfo > |
---|
获取指定玩家所在的房间信息 |
asyncTeleportToRoom(roomId : string , userIds : string [], options? : TeleportOptions ): Promise <TeleportResult > server |
异步传送到指定房间 |
asyncTeleportToScene(sceneName : string , userIds : string [], options? : TeleportOptions ): Promise <TeleportResult > server |
异步传送到当前游戏的指定场景 |
getSourceInfo(teleportId : string ): RoomInfo server |
获取传送的来源信息 |
getTeleportData(teleportId : string ): TeleportData server |
获取调用传送接口时在TeleportOptions中设置的数据 |
Methods
asyncGetPlayerRoomInfo
• Static
asyncGetPlayerRoomInfo(userId
): Promise
<RoomInfo
>
获取指定玩家所在的房间信息
Parameters
userId string | 目标玩家的 userId range: 依据 userId 的长度而定 |
---|
Returns
Promise <RoomInfo > | 指定玩家所在的房间信息 |
---|
ts
@Component
export default class Server extends Script {
protected onStart(): void {
// 传送功能需要在服务端发起,在客户端使用会报错
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 当玩家加入时,倒计时5s后发起传送
setTimeout(() => {
// 假定我们想传送到UserId为"123456"的玩家所在房间一起游玩
const targetUserId: string = "123456";
// 先用asyncGetPlayerRoomInfo获取玩家所在的房间信息
TeleportService.asyncGetPlayerRoomInfo(targetUserId).then((roomInfo) => {
// 拿到RoomId
const roomId: string = roomInfo.roomId;
// 将要传送到新场景的玩家加入数组
const playerToTeleport: string[] = [player.userId];
// 可以填充要携带的额外数据
const opt: TeleportOptions = {
teleportData: "This is test data."
}
// 调用接口传送到目标房间
TeleportService.asyncTeleportToRoom(roomId, playerToTeleport, opt);
});
}, 5 * 1000);
});
}
}
}
@Component
export default class Server extends Script {
protected onStart(): void {
// 传送功能需要在服务端发起,在客户端使用会报错
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 当玩家加入时,倒计时5s后发起传送
setTimeout(() => {
// 假定我们想传送到UserId为"123456"的玩家所在房间一起游玩
const targetUserId: string = "123456";
// 先用asyncGetPlayerRoomInfo获取玩家所在的房间信息
TeleportService.asyncGetPlayerRoomInfo(targetUserId).then((roomInfo) => {
// 拿到RoomId
const roomId: string = roomInfo.roomId;
// 将要传送到新场景的玩家加入数组
const playerToTeleport: string[] = [player.userId];
// 可以填充要携带的额外数据
const opt: TeleportOptions = {
teleportData: "This is test data."
}
// 调用接口传送到目标房间
TeleportService.asyncTeleportToRoom(roomId, playerToTeleport, opt);
});
}, 5 * 1000);
});
}
}
}
asyncTeleportToRoom
• Static
asyncTeleportToRoom(roomId
, userIds
, options?
): Promise
<TeleportResult
> server
异步传送到指定房间
Parameters
roomId string | 要传送的目标游戏Id default:undefined range: 依据 roomid 的长度决定 |
---|---|
userIds string [] | 要传送的玩家userId数组 default:undefined range: 依据 roomid 的长度决定 |
options? TeleportOptions | 可选的额外传送信息. 不支持 createNewPrivateRoom 参数,设置为true也不会创建新房间 default:undefined |
Returns
Promise <TeleportResult > | 本次请求正常则返回resolve,异常则返回reject |
---|
Precautions
指定房间不存在或者可容纳人数不足,则会失败。参与传送的玩家数量越多,失败率越高
Precautions
不支持 createNewPrivateRoom 参数,设置为true也不会创建新房间
ts
@Component
export default class TeleportScript extends Script {
protected onStart(): void {
// 服务端逻辑
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 当玩家加入时,倒计时5s后发起传送,避免玩家加入立即传送,不易观察
setTimeout(() => {
// 假定我们想传送到UserId为"123456"的玩家所在房间一起游玩
const targetUserId: string = "123456";
// 先用asyncGetPlayerRoomInfo获取玩家所在的房间信息
TeleportService.asyncGetPlayerRoomInfo(targetUserId).then((roomInfo) => {
// 拿到RoomId
const roomId: string = roomInfo.roomId;
// 将要传送到新场景的玩家加入数组
const playerToTeleport: string[] = [player.userId];
// 可以填充要携带的额外数据
const opt: TeleportOptions = {
teleportData: "This is test data."
}
// 声明成功和失败的回调函数,用于处理传送接口的回调结果。
// 成功的情况一般不需要处理,会继续走后续跳转流程。
// 如果失败了,有可能是超时或者有报错,可以从回调的数据中读取信息做进一步处理。
const onSuccess = () => { }
const onFailed = (result: mw.TeleportResult) => {
switch (result.status) {
case mw.TeleportStatus.success:
break;
case mw.TeleportStatus.ignored:
// 触发太频繁了,本次请求被忽略
break;
case mw.TeleportStatus.timeout:
// 超时了,可以选择重试传送或者提示玩家
break;
case mw.TeleportStatus.error:
// 将错误信息发给所有参与的客户端
for (const userId in result.userIds) {
const player = Player.getPlayer(userId)
if (player) {
Event.dispatchToClient(player, "TeleportResult", result);
}
}
}
};
// 传送功能需要在服务端发起,在客户端使用会报错
TeleportService.asyncTeleportToRoom(roomId, playerToTeleport, opt).then(onSuccess, onFailed);
}).catch((error: Error) => {
console.error(`getPlayerRoomInfo has error: ${error.message}`);
})
}, 5 * 1000);
});
@Component
export default class TeleportScript extends Script {
protected onStart(): void {
// 服务端逻辑
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 当玩家加入时,倒计时5s后发起传送,避免玩家加入立即传送,不易观察
setTimeout(() => {
// 假定我们想传送到UserId为"123456"的玩家所在房间一起游玩
const targetUserId: string = "123456";
// 先用asyncGetPlayerRoomInfo获取玩家所在的房间信息
TeleportService.asyncGetPlayerRoomInfo(targetUserId).then((roomInfo) => {
// 拿到RoomId
const roomId: string = roomInfo.roomId;
// 将要传送到新场景的玩家加入数组
const playerToTeleport: string[] = [player.userId];
// 可以填充要携带的额外数据
const opt: TeleportOptions = {
teleportData: "This is test data."
}
// 声明成功和失败的回调函数,用于处理传送接口的回调结果。
// 成功的情况一般不需要处理,会继续走后续跳转流程。
// 如果失败了,有可能是超时或者有报错,可以从回调的数据中读取信息做进一步处理。
const onSuccess = () => { }
const onFailed = (result: mw.TeleportResult) => {
switch (result.status) {
case mw.TeleportStatus.success:
break;
case mw.TeleportStatus.ignored:
// 触发太频繁了,本次请求被忽略
break;
case mw.TeleportStatus.timeout:
// 超时了,可以选择重试传送或者提示玩家
break;
case mw.TeleportStatus.error:
// 将错误信息发给所有参与的客户端
for (const userId in result.userIds) {
const player = Player.getPlayer(userId)
if (player) {
Event.dispatchToClient(player, "TeleportResult", result);
}
}
}
};
// 传送功能需要在服务端发起,在客户端使用会报错
TeleportService.asyncTeleportToRoom(roomId, playerToTeleport, opt).then(onSuccess, onFailed);
}).catch((error: Error) => {
console.error(`getPlayerRoomInfo has error: ${error.message}`);
})
}, 5 * 1000);
});
asyncTeleportToScene
• Static
asyncTeleportToScene(sceneName
, userIds
, options?
): Promise
<TeleportResult
> server
异步传送到当前游戏的指定场景
Parameters
sceneName string | 要传送的目标场景名称 default: range: 依据场景名称而定 |
---|---|
userIds string [] | 要传送的玩家 userId 数组 default: range: 数组大小自定义 |
options? TeleportOptions | 可选的额外传送信息 default:undefined |
Returns
Promise <TeleportResult > | 本次请求正常则返回resolve,异常则返回reject |
---|
Precautions
仅限当前游戏的场景间传送,场景名不存在则会传送失败
ts
@Component
export default class TeleportScript extends Script {
protected onStart(): void {
// 服务端逻辑
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 当玩家加入时,倒计时5s后发起传送,避免玩家加入立即传送,不易观察
setTimeout(() => {
// 假定已经在编辑器中创建了一个名为"Scene1"的场景
const sceneName: string = "Scene1";
// 将要传送到新场景的玩家加入数组
const playerToTeleport: string[] = [player.userId];
// 可以填充要携带的额外数据
const opt: TeleportOptions = {
teleportData: "This is test data."
}
// 声明成功和失败的回调函数,用于处理传送接口的回调结果。
// 成功的情况一般不需要处理,会继续走后续跳转流程。
// 如果失败了,有可能是超时或者有报错,可以从回调的数据中读取信息做进一步处理。
const onSuccess = () => { }
const onFailed = (result: mw.TeleportResult) => {
switch (result.status) {
case mw.TeleportStatus.success:
break;
case mw.TeleportStatus.ignored:
// 触发太频繁了,本次请求被忽略
break;
case mw.TeleportStatus.timeout:
// 超时了,可以选择重试传送或者提示玩家
break;
case mw.TeleportStatus.error:
// 将错误信息发给所有参与的客户端
for (const userId in result.userIds) {
const player = Player.getPlayer(userId)
if (player) {
Event.dispatchToClient(player, "TeleportResult", result);
}
}
}
};
// 传送功能需要在服务端发起,在客户端使用会报错
TeleportService.asyncTeleportToScene(sceneName, playerToTeleport, opt).then(onSuccess, onFailed);
}, 5 * 1000);
});
} else {
// 客户端逻辑
Event.addServerListener("TeleportResult", (result: mw.TeleportResult) => {
console.error(`Teleport has error:`);
console.error(`errorCode: ${result.errorCode}`);
console.error(`message: ${result.message}`);
});
}
}
}
@Component
export default class TeleportScript extends Script {
protected onStart(): void {
// 服务端逻辑
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 当玩家加入时,倒计时5s后发起传送,避免玩家加入立即传送,不易观察
setTimeout(() => {
// 假定已经在编辑器中创建了一个名为"Scene1"的场景
const sceneName: string = "Scene1";
// 将要传送到新场景的玩家加入数组
const playerToTeleport: string[] = [player.userId];
// 可以填充要携带的额外数据
const opt: TeleportOptions = {
teleportData: "This is test data."
}
// 声明成功和失败的回调函数,用于处理传送接口的回调结果。
// 成功的情况一般不需要处理,会继续走后续跳转流程。
// 如果失败了,有可能是超时或者有报错,可以从回调的数据中读取信息做进一步处理。
const onSuccess = () => { }
const onFailed = (result: mw.TeleportResult) => {
switch (result.status) {
case mw.TeleportStatus.success:
break;
case mw.TeleportStatus.ignored:
// 触发太频繁了,本次请求被忽略
break;
case mw.TeleportStatus.timeout:
// 超时了,可以选择重试传送或者提示玩家
break;
case mw.TeleportStatus.error:
// 将错误信息发给所有参与的客户端
for (const userId in result.userIds) {
const player = Player.getPlayer(userId)
if (player) {
Event.dispatchToClient(player, "TeleportResult", result);
}
}
}
};
// 传送功能需要在服务端发起,在客户端使用会报错
TeleportService.asyncTeleportToScene(sceneName, playerToTeleport, opt).then(onSuccess, onFailed);
}, 5 * 1000);
});
} else {
// 客户端逻辑
Event.addServerListener("TeleportResult", (result: mw.TeleportResult) => {
console.error(`Teleport has error:`);
console.error(`errorCode: ${result.errorCode}`);
console.error(`message: ${result.message}`);
});
}
}
}
getSourceInfo
• Static
getSourceInfo(teleportId
): RoomInfo
server
获取传送的来源信息
Parameters
teleportId string | 要查询的传送 Id default: range:依据 teleportId 长度而定的 |
---|
Returns
RoomInfo | 玩家传送的来源信息 |
---|
ts
@Component
export default class Server extends Script {
protected onStart(): void {
// 获取传送来源信息的接口需要在服务端发起,在客户端使用会报错
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 用玩家的teleportId属性来查询来源信息
const sourceInfo = TeleportService.getSourceInfo(player.teleportId);
if (sourceInfo) {
console.log("Teleport from:");
console.log(`GameId: ${sourceInfo.gameId}`);
console.log(`RoomId: ${sourceInfo.roomId}`);
} else {
// 不是传送进入的当前场景,则没有来源信息
console.log("Not join by Teleport.")
}
});
}
}
}
@Component
export default class Server extends Script {
protected onStart(): void {
// 获取传送来源信息的接口需要在服务端发起,在客户端使用会报错
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 用玩家的teleportId属性来查询来源信息
const sourceInfo = TeleportService.getSourceInfo(player.teleportId);
if (sourceInfo) {
console.log("Teleport from:");
console.log(`GameId: ${sourceInfo.gameId}`);
console.log(`RoomId: ${sourceInfo.roomId}`);
} else {
// 不是传送进入的当前场景,则没有来源信息
console.log("Not join by Teleport.")
}
});
}
}
}
getTeleportData
• Static
getTeleportData(teleportId
): TeleportData
server
获取调用传送接口时在TeleportOptions中设置的数据
Parameters
teleportId string | 要查询的传送Id default: range: 依据 teleportId 的长度决定 |
---|
Returns
TeleportData | 传送时携带的数据 |
---|
ts
@Component
export default class Server extends Script {
protected onStart(): void {
// 获取传送时携带的数据的接口需要在服务端发起,在客户端使用会报错
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 用玩家的teleportId属性来查询传送时携带的数据
const data = TeleportService.getTeleportData(player.teleportId);
if (data) {
console.log(`Teleport data: ${data}`);
} else {
// 不是传送进入的当前场景,则没有携带的数据;也可能是传送时未指定数据
console.log("Not join by Teleport or no data.")
}
});
}
}
}
@Component
export default class Server extends Script {
protected onStart(): void {
// 获取传送时携带的数据的接口需要在服务端发起,在客户端使用会报错
if (SystemUtil.isServer()) {
Player.onPlayerJoin.add((player: Player) => {
// 用玩家的teleportId属性来查询传送时携带的数据
const data = TeleportService.getTeleportData(player.teleportId);
if (data) {
console.log(`Teleport data: ${data}`);
} else {
// 不是传送进入的当前场景,则没有携带的数据;也可能是传送时未指定数据
console.log("Not join by Teleport or no data.")
}
});
}
}
}