API
Return to top
TeleportService
编辑

服务 / 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

Returns ​

Promise<RoomInfo>指定玩家所在的房间信息
使用示例:创建一个名为"ServerScript"的脚本，放在场景中。代码如下：
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
userIds string[]要传送的玩家userId数组
options? TeleportOptions可选的额外传送信息. 不支持 createNewPrivateRoom 参数，设置为true也不会创建新房间 default:undefined

Returns ​

Promise<TeleportResult>本次请求正常则返回resolve，异常则返回reject

Precautions

指定房间不存在或者可容纳人数不足，则会失败。参与传送的玩家数量越多，失败率越高

Precautions

不支持 createNewPrivateRoom 参数，设置为true也不会创建新房间

使用示例:创建一个名为"TeleportScript"的脚本，放在场景中，设置为双端。代码如下：

Parameters ​

gameIdstring
userIdsstring[]
sceneName?string
options?TeleportOptions

Returns ​

Promise<TeleportResult>
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);
            });

Parameters ​

roomId string要传送的目标游戏Id
userIds string[]要传送的玩家userId数组
options? TeleportOptions可选的额外传送信息. 不支持 createNewPrivateRoom 参数，设置为true也不会创建新房间 default:undefined

Returns ​

Promise<TeleportResult>本次请求正常则返回resolve，异常则返回reject

asyncTeleportToScene
​

• Static asyncTeleportToScene(sceneName, userIds, options?): Promise<TeleportResult> server

异步传送到当前游戏的指定场景

Parameters ​

sceneName string要传送的目标场景名称
userIds string[]要传送的玩家 userId 数组
options? TeleportOptions可选的额外传送信息 default:undefined

Returns ​

Promise<TeleportResult>本次请求正常则返回resolve，异常则返回reject

Precautions

仅限当前游戏的场景间传送，场景名不存在则会传送失败

使用示例:在编辑器中创建了一个名为"Scene1"的场景。创建一个名为"TeleportScript"的脚本，放在场景中，设置为双端。代码如下：
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

Returns ​

RoomInfo玩家传送的来源信息
使用示例:创建一个名为"ServerScript"的脚本，放在场景中。代码如下：
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

Returns ​

TeleportData传送时携带的数据
使用示例:创建一个名为"ServerScript"的脚本，放在场景中。代码如下：
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.")
                }
            });
        }
    }
}