跳转到内容

35. 传送门和世界之间的连接

约 35 分钟 内容:基础 动手章

第 16 章的 Networking.LocalPlayer.TeleportTo 用于当前世界内的位置变化。跨世界移动需要客户端离开当前实例、加载目标世界并加入目标实例;VRC Portal Marker 提供这种入口。

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 当作绕过权限的方式。

  1. 新建空 GameObject,例如 Portal_World1。
  2. 添加 VRC Portal Marker。
  3. 将 World 保持 None,填入目标 World ID。
  4. 如需替换门上显示的名称,填写 Custom Portal Name;否则保留目标世界名称。
  5. 将物体放在通道旁的可见位置,避免与 Spawn、墙或其他门重叠。
  6. 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 Marker
World ID wrld_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Custom Portal Name 留空,或填写清楚的目的地名称
World None

运行时外观由客户端生成,不需要为了生成标准 Portal 另外制作一套 Mesh。Inspector 的空物体位置并不能单独证明门底离地多少米,应在客户端检查。

官方说明:固定 World ID 的 Portal 会指向目标世界的已有公开实例;没有公开实例时指向新实例。它不是输入 World ID 就能指定某个朋友所在实例。

玩家可以走入 Portal 切换世界;打开 VRChat 菜单时也可以选择 Portal 查看目标信息。不要将后者直接写成所有设备都用同一个 Interact 键进入。

World 字段还提供:

选项目的地
None使用填写的 World ID
Home当前玩家自己的 Home 世界
HubVRChat Hub 世界

Home 对不同玩家可能指向不同世界。说明牌可写 回家 / Home,但不应把它描述成某一个固定地点。

旧资料可能包含 Search Term、Sort Order 等搜索字段。当前官方组件页以 World ID、Custom Portal Name 和 World 为主要配置;教程与实际 SDK 不一致时,核对当前 Inspector 和官方文档。

Hub 可以集中多个目的地入口,例如社群作品、展览分区或活动会场:

Hub
├─ Portals
│ ├─ Portal_World1
│ ├─ Portal_World2
│ └─ Portal_World3
└─ Signs
├─ Sign_World1
├─ Sign_World2
└─ Sign_World3
  1. 将三个 Portal 分开摆放,可从 2.5 米间距开始测试。
  2. 每个 Portal 配一块第 34 章的 World Space Canvas,显示世界名、用途和作者。
  3. 出生点与入口留出行走空间,避免玩家加载后直接进入另一个世界。
  4. 标识哪些区域会离开当前实例。
  5. 分别验证每扇门,不能以其中一扇成功代表全部成功。

例子:

月光小屋 / Moonlight Room
聊天与作品展示
作者:示例作者名

自定义 Portal 名称只影响显示,不更改目标世界名称或所有权。使用译名时可以同时保留原名,便于玩家核对目的地。

Portal 会结束当前客户端在该实例中的世界运行状态。返回同一个世界也不代表所有本地字段自动恢复。

需要跨次访问保留的数据,应单独设计 Persistence,并验证恢复时机;普通 [UdonSynced] 变量用于当前实例状态,不等于持久存储。只提供导航功能的 Hub 可以在每次加载时使用初始布局。

按活动状态开放入口时,先把普通 GameObject 的启用状态和客户端生成的 Portal 分开验证。Unity 的 SetActive 会改变目标物体的本地激活状态;父级仍禁用时,设为 true 不会使它在层级中激活。VRChat 的 Marker 文档没有承诺客户端生成的门体在运行时如何随启用、禁用、再启用而变化。

以下是供客户端验收的完整开关小例,不表示已经通过 Portal 生命周期测试:

PortalAvailabilityTest.cs
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);
}
}
  1. 创建两个带 Box Collider 的独立 Cube 按钮,命名 Portal_Open、Portal_Close。新建同名 U# 脚本文件 PortalAvailabilityTest.cs,保存、等待编译并检查 Console,再挂到两个按钮。
  2. 两个 Portal Marker 槽都指向同一个带 Marker 的物体;开按钮勾选 Open On Interact,关按钮取消勾选。Interaction Text 分别写「开放入口 / Open portal」和「关闭入口 / Close portal」。
  3. 按钮不能放在被禁用的 Marker 下面。Marker 的父级保持启用,先将 Marker 物体本身设为禁用,保存测试场景。
  4. 执行 Build & Test。依次测试初始禁用→开放、开放→关闭、关闭→再开放。每一步分别记录日志中的 activeSelf / activeInHierarchy、门体是否出现或残留,以及是否还能进入。进入测试会离开当前实例,回到测试场景后需要重新执行相应操作序列。
  5. 再用初始启用的版本测试一次,并加入第二位玩家核对两台客户端的差别。记录 Unity、SDK、客户端和平台版本;ClientSim 的对象开关、Unity Console 或上述两个布尔值都不能证明真实 Portal 进入行为。Build & Test 的日志应在客户端日志中查找。

只有这组目标客户端测试符合需求,才把开关用于活动显示。若门体残留或重新启用不生成,保留静态 Portal 导航,并把动态开放需求列为未实现,不以隐藏说明牌代替关闭 Portal。此开关也不改变目标世界的权限,不能作为安全门禁。

本例只改变操作玩家的客户端。公共活动状态需要另按同步变量与状态恢复同步布尔值,再在本地应用显式开/关;这还必须覆盖初始进入、后加入和所有权变化,不能把本例的两个按钮当作完整同步实现。

  • 个人音乐开关:从全局 2D 音乐与本地静音创建独立音源和 MusicSwitch,再与三个 Portal 组合。检查静音后走近每扇门、返回 Hub 的初始状态;没有使用持久化时,不要求离开前的本地静音值自动恢复。
  • 按用途组织入口:社群作品可按作者列入口;作品集可按年份列入口;活动可按议程列入口并写明有效范围。保留目标原名和作者归属,各方案都逐门核对 World ID、权限与平台。
  • 布局对照:可先将最近 Portal 放在 Spawn 前方约 4 米处,再按实际可走路线调整。这是布局起点,不是 SDK 安全阈值;测试 Spawn Radius 和多人出生后是否有人误入。
现象检查项
目标无法加载World ID 是否完整、目标是否存在且可访问
某个平台不能进入目标是否提供该平台构建
门与地面或墙重叠运行时位置、朝向与邻近 Collider
进入了不同实例固定 World ID 的公开实例选择规则,而非指定实例
牌子与实际目的地不同ID、Custom Portal Name 和说明牌是否对应

制作三个不同目的地的 Portal,并逐个检查:

  • ID 来自已核对的目标世界详情
  • 名称和作者归属清楚
  • 出生和普通行走路线不会意外经过 Portal
  • 运行时外观与地面位置正确
  • 目标权限和平台构建允许计划中的玩家进入
  • PC 与计划支持的移动设备分别测试
  • 若控制启用状态,已验证本地与同步行为