35. 传送门和世界之间的连接
第 16 章的 Networking.LocalPlayer.TeleportTo 用于当前世界内的位置变化。跨世界移动需要客户端离开当前实例、加载目标世界并加入目标实例;VRC Portal Marker 提供这种入口。
找到目标 World ID
Section titled “找到目标 World ID”World ID 的形式为 wrld_ 加 UUID,例如:
wrld_f995a2eb-7ddc-4558-aef1-815c3b23df6c可以从 VRChat 网站的世界详情页 URL 获取:
https://vrchat.com/home/world/wrld_f995a2eb-7ddc-4558-aef1-815c3b23df6c自己上传的世界也可在 SDK 的内容管理入口核对 ID。复制完整 ID,确认目标的实际名称、发布者与可访问平台,避免凭相似名称选择。
公开链接不改变作品归属。说明牌应注明目标世界与作者;涉及私有世界、活动限制或非公开内容时,先核对访问条件,不把 Portal 当作绕过权限的方式。
- 新建空 GameObject,例如
Portal_World1。 - 添加
VRC Portal Marker。 - 将
World保持None,填入目标World ID。 - 如需替换门上显示的名称,填写
Custom Portal Name;否则保留目标世界名称。 - 将物体放在通道旁的可见位置,避免与 Spawn、墙或其他门重叠。
Build & Test检查运行时生成的 Portal 外观、位置和进入行为。
也可使用 SDK 的示例 Prefab。Worlds SDK 3.10.5 包内的路径是 Samples/UdonExampleScene/Prefabs/VRCPortalMarker.prefab:在 Package Manager 中选择 VRChat Worlds,若 Samples 尚未导入,先导入 Udon Example Scene;在 Project 搜索 VRCPortalMarker,核对类型为 Prefab,再拖入场景并填写目标。示例根物体包含 Marker 与 Trigger Collider。保留自己的 World ID 配置记录,升级 SDK 后重新验证,不把 Prefab 实例关系当作运行时行为永远不变的保证。
VRC Portal MarkerWorld ID wrld_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxCustom Portal Name 留空,或填写清楚的目的地名称World None运行时外观由客户端生成,不需要为了生成标准 Portal 另外制作一套 Mesh。Inspector 的空物体位置并不能单独证明门底离地多少米,应在客户端检查。
官方说明:固定 World ID 的 Portal 会指向目标世界的已有公开实例;没有公开实例时指向新实例。它不是输入 World ID 就能指定某个朋友所在实例。
玩家可以走入 Portal 切换世界;打开 VRChat 菜单时也可以选择 Portal 查看目标信息。不要将后者直接写成所有设备都用同一个 Interact 键进入。
Home 与 Hub
Section titled “Home 与 Hub”World 字段还提供:
| 选项 | 目的地 |
|---|---|
None | 使用填写的 World ID |
Home | 当前玩家自己的 Home 世界 |
Hub | VRChat Hub 世界 |
Home 对不同玩家可能指向不同世界。说明牌可写 回家 / Home,但不应把它描述成某一个固定地点。
旧资料可能包含 Search Term、Sort Order 等搜索字段。当前官方组件页以 World ID、Custom Portal Name 和 World 为主要配置;教程与实际 SDK 不一致时,核对当前 Inspector 和官方文档。
组成一个 Hub
Section titled “组成一个 Hub”Hub 可以集中多个目的地入口,例如社群作品、展览分区或活动会场:
Hub├─ Portals│ ├─ Portal_World1│ ├─ Portal_World2│ └─ Portal_World3└─ Signs ├─ Sign_World1 ├─ Sign_World2 └─ Sign_World3- 将三个 Portal 分开摆放,可从
2.5米间距开始测试。 - 每个 Portal 配一块第 34 章的 World Space Canvas,显示世界名、用途和作者。
- 出生点与入口留出行走空间,避免玩家加载后直接进入另一个世界。
- 标识哪些区域会离开当前实例。
- 分别验证每扇门,不能以其中一扇成功代表全部成功。
例子:
月光小屋 / Moonlight Room聊天与作品展示作者:示例作者名自定义 Portal 名称只影响显示,不更改目标世界名称或所有权。使用译名时可以同时保留原名,便于玩家核对目的地。
离开与返回的状态
Section titled “离开与返回的状态”Portal 会结束当前客户端在该实例中的世界运行状态。返回同一个世界也不代表所有本地字段自动恢复。
需要跨次访问保留的数据,应单独设计 Persistence,并验证恢复时机;普通 [UdonSynced] 变量用于当前实例状态,不等于持久存储。只提供导航功能的 Hub 可以在每次加载时使用初始布局。
控制 Portal 的可用性
Section titled “控制 Portal 的可用性”按活动状态开放入口时,先把普通 GameObject 的启用状态和客户端生成的 Portal 分开验证。Unity 的 SetActive 会改变目标物体的本地激活状态;父级仍禁用时,设为 true 不会使它在层级中激活。VRChat 的 Marker 文档没有承诺客户端生成的门体在运行时如何随启用、禁用、再启用而变化。
以下是供客户端验收的完整开关小例,不表示已经通过 Portal 生命周期测试:
using UdonSharp;using UnityEngine;
public class PortalAvailabilityTest : UdonSharpBehaviour{ public GameObject portalMarker; public bool openOnInteract = true;
public override void Interact() { if (openOnInteract) OpenPortal(); else ClosePortal(); }
public void OpenPortal() { SetMarkerActive(true); }
public void ClosePortal() { SetMarkerActive(false); }
private void SetMarkerActive(bool value) { if (portalMarker == null) { Debug.LogWarning("PortalAvailabilityTest: missing portalMarker"); return; } portalMarker.SetActive(value); Debug.Log("Portal marker activeSelf=" + portalMarker.activeSelf + ", activeInHierarchy=" + portalMarker.activeInHierarchy); }}- 创建两个带 Box Collider 的独立 Cube 按钮,命名
Portal_Open、Portal_Close。新建同名 U# 脚本文件PortalAvailabilityTest.cs,保存、等待编译并检查 Console,再挂到两个按钮。 - 两个
Portal Marker槽都指向同一个带 Marker 的物体;开按钮勾选Open On Interact,关按钮取消勾选。Interaction Text 分别写「开放入口 / Open portal」和「关闭入口 / Close portal」。 - 按钮不能放在被禁用的 Marker 下面。Marker 的父级保持启用,先将 Marker 物体本身设为禁用,保存测试场景。
- 执行
Build & Test。依次测试初始禁用→开放、开放→关闭、关闭→再开放。每一步分别记录日志中的 activeSelf / activeInHierarchy、门体是否出现或残留,以及是否还能进入。进入测试会离开当前实例,回到测试场景后需要重新执行相应操作序列。 - 再用初始启用的版本测试一次,并加入第二位玩家核对两台客户端的差别。记录 Unity、SDK、客户端和平台版本;ClientSim 的对象开关、Unity Console 或上述两个布尔值都不能证明真实 Portal 进入行为。Build & Test 的日志应在客户端日志中查找。
只有这组目标客户端测试符合需求,才把开关用于活动显示。若门体残留或重新启用不生成,保留静态 Portal 导航,并把动态开放需求列为未实现,不以隐藏说明牌代替关闭 Portal。此开关也不改变目标世界的权限,不能作为安全门禁。
本例只改变操作玩家的客户端。公共活动状态需要另按同步变量与状态恢复同步布尔值,再在本地应用显式开/关;这还必须覆盖初始进入、后加入和所有权变化,不能把本例的两个按钮当作完整同步实现。
Hub 的可选组合练习
Section titled “Hub 的可选组合练习”- 个人音乐开关:从全局 2D 音乐与本地静音创建独立音源和 MusicSwitch,再与三个 Portal 组合。检查静音后走近每扇门、返回 Hub 的初始状态;没有使用持久化时,不要求离开前的本地静音值自动恢复。
- 按用途组织入口:社群作品可按作者列入口;作品集可按年份列入口;活动可按议程列入口并写明有效范围。保留目标原名和作者归属,各方案都逐门核对 World ID、权限与平台。
- 布局对照:可先将最近 Portal 放在 Spawn 前方约
4米处,再按实际可走路线调整。这是布局起点,不是 SDK 安全阈值;测试 Spawn Radius 和多人出生后是否有人误入。
| 现象 | 检查项 |
|---|---|
| 目标无法加载 | World ID 是否完整、目标是否存在且可访问 |
| 某个平台不能进入 | 目标是否提供该平台构建 |
| 门与地面或墙重叠 | 运行时位置、朝向与邻近 Collider |
| 进入了不同实例 | 固定 World ID 的公开实例选择规则,而非指定实例 |
| 牌子与实际目的地不同 | ID、Custom Portal Name 和说明牌是否对应 |
检查清单与练习
Section titled “检查清单与练习”制作三个不同目的地的 Portal,并逐个检查:
- ID 来自已核对的目标世界详情
- 名称和作者归属清楚
- 出生和普通行走路线不会意外经过 Portal
- 运行时外观与地面位置正确
- 目标权限和平台构建允许计划中的玩家进入
- PC 与计划支持的移动设备分别测试
- 若控制启用状态,已验证本地与同步行为