Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

预览你的场景

场景预览中你可以看到的内容

一旦你 构建了一个新场景 或下载了一个 场景示例 ，你就可以在本地预览它。

在 Creator Hub 中使用 Scene Editor

请确保你已经 安装了 Creator Hub.

  1. 打开你的场景项目。

  2. 点击 播放 按钮在右上角。这将打开一个新窗口，里面运行着 Decentraland Desktop Explorer，仅加载你的场景。在那里你可以在场景中移动并与交互式物品互动。



选择预览位置

点击 播放 按钮旁边的箭头以打开 播放选项 菜单。主面板是你选择场景运行方式的地方：

  • 桌面客户端：在 Decentraland Desktop Explorer 中打开预览。这是默认选项。

  • Web (Bevy)：使用 Bevy Web 客户端在浏览器中打开预览。相当于 --web CLI 标志。

  • 显示用于移动设备的二维码：显示一个二维码，可将你的场景预览打开在 Decentraland 移动应用中。请使用与你的电脑连接到同一 Wi‑Fi 网络的手机扫描该二维码。点击弹窗周围的深色区域即可关闭。详见 在移动端预览 了解详情。

桌面客户端选项

将鼠标悬停在 桌面客户端 在 播放选项 菜单上可打开一个子菜单，其中包含仅影响桌面客户端的设置：

  • 启用地形：切换场景周围的地形。默认启用；关闭它可以降低场景的内存占用。当场景自身设置已经隐藏地形时，该项会变灰。

  • 多实例预览：允许多个 Explorer 窗口同时运行，这样你就可以 在本地测试多人场景。启用后，每个窗口都会要求你登录，因此你可以在每个窗口中以不同玩家身份连接。

  • 启用 MCP 服务器：启动启用了 MCP 自动化服务器的 Explorer，这样 AI 代理就可以查看并控制正在运行的预览。仅在你的项目 SDK 版本支持时可见。详见 借助 AI 进行氛围编程 完整流程。

  • 压缩资源：使用本地生成的资源包预览场景，与在生产环境中经过 资源包转换后渲染的方式一致。首次运行会转换所有资源，大型场景可能需要几分钟。仅在你的平台和项目的 SDK 版本支持时可见。详见 使用优化后的资源预览.

场景的控制台输出不需要菜单选项。Creator Hub 每次你运行预览时都会为你打开它。详见 Creator Hub 控制台.

提示： 你也可以直接在 Decentraland 移动应用中预览你的场景。使用 Creator Hub 中的 显示用于移动设备的二维码 选项，或在 CLI 中运行 npm run start -- --mobile 。详见 在移动端预览 了解详情。

使用 CLI

要预览场景，请在场景的主文件夹中运行以下命令：

任何缺失的依赖都会被安装，然后 CLI 会在你的系统中创建一个本地 Web 服务器，并通过 decentraland:// deeplink 在 Decentraland Desktop 客户端中启动场景。Desktop 客户端是默认的预览目标。

如果想改为在浏览器标签页中预览，请添加 -- --web （或 -- --bevy-web）以便在 decentraland.org/bevy-web/.

中的 Bevy Web 客户端里打开场景。每次你对场景进行更改时，预览都会自动重新加载并更新，因此无需再次运行该命令。

📔 注意：有些场景依赖与外部服务器通信来执行自定义逻辑或存储和读取数据。预览这类场景时，你通常还需要在另一个端口上本地运行该服务器。请查看场景的 readme，了解如何同时启动服务器和场景。

预览命令的参数

你可以将以下标志添加到 npm run start 命令中以更改其行为：

  • -- --web （别名 -- --bevy-web）在 decentraland.org/bevy-web/ 而不是 Desktop Explorer 中打开 Bevy Web 浏览器客户端的预览。基于 Chromium 的浏览器（Chrome 142+）需要“本地网络访问”权限，托管页面才能访问你的本地预览服务器——当浏览器请求访问你设备上的应用时，点击“允许”。

  • -- --mobile （别名 -- -m）在终端中显示一个二维码，可在 Decentraland 移动应用 中打开你的场景，使用与其连接到同一 Wi‑Fi 网络的手机。详见 在移动端预览.

  • -- --skip-build 跳过构建，仅在预览模式下提供文件。

  • -- --port （别名 -- -p）为运行场景指定一个特定端口。否则将使用任何可用端口。

  • -- --no-browser （别名 -- -b）以阻止预览自动打开新的浏览器标签页。

  • -- -w 或 -- --no-watch 以不监视文件系统更改，并避免在场景代码变更时进行热重载。

  • -- --ci 在远程 Unix 服务器上运行 parcel 预览器。

  • -- --multi-instance 允许同时运行多个 Explorer 实例。

  • -- --local-ab 使用优化后的资源包进行预览。Desktop Explorer 会在预览期间自行将场景资源转换为资源包，与场景在生产环境中的渲染方式一致。相当于 Creator Hub 中的 压缩资源 选项。仅适用于 Desktop Client（不适用于 Bevy Web 客户端）。详见 使用优化后的资源预览.

  • -- --no-client 禁止所有自动启动（桌面 Explorer deeplink、浏览器打开、移动端二维码）。文件监视器仍会在桌面 Explorer 自行连接时通知它。当外部工具掌控 Explorer 进程时很有用。

  • -- --mcp 在 Explorer 中启用 MCP 服务器（通过 deeplink 参数转发）。

  • -- --mcp-port Explorer 中 MCP 服务器的端口（通过 deeplink 参数转发）。例如： npm run start -- --mcp --mcp-port 3001.

📔 注意：参数需要用两组连字符添加，例如 npm run start -- --web3.

使用优化后的资源预览

当你发布场景时，Decentraland 服务器会将其所有 3D 模型转换为资源包，这是一种更轻量、加载和渲染都更快的优化格式。详见 资源包转换。默认情况下，本地预览会跳过这一步，改为加载原始模型。

启用优化资源后，你在预览场景时会在本地执行同样的转换。这有两个好处：

  • 预览加载更快、运行更流畅，尤其是在包含大量 3D 模型的场景中。

  • 你看到的模型会与玩家发布后看到的完全一致，因此你可以在发布前发现资源压缩方面的任何问题。

此选项只影响你的本地预览。已发布的场景始终会在服务器上转换，不论你是否使用此选项。

要启用它：

  • 在 Creator Hub 中：打开 播放选项 旁边的 播放 按钮，悬停在 桌面客户端上，然后勾选 压缩资源.

  • 在 CLI 中：运行 npm run start -- --local-ab.

启用此选项后，Decentraland explorer 会在你的机器上将场景的 3D 模型转换为资源包，然后再加载它们。对于大多数场景来说，转换几乎是瞬时完成的，但如果场景的资源非常庞大，首次预览可能会更久。已转换的模型会被缓存，因此后续预览中只需转换新增或修改过的资源。

💡 提示：如果某个资源的转换因任何原因失败，预览会回退为加载原始 3D 模型，就像普通预览一样。

将场景上传到 decentraland

一旦你对场景满意，就可以将其上传并发布到 Decentraland。为此，你必须拥有 LAND、Decentraland NAME 或 ETH ENS 名称，或者获得拥有这些权限的人的授权。详见 发布 了解操作说明。

预览场景尺寸

预览中显示的场景尺寸基于场景配置。

可在 Scene Editor 中场景菜单的第二个标签页里进行编辑。



使用下拉菜单并点击 应用布局 来更改场景的尺寸。你也可以点击每个单独的地块，将其从布局中切换关闭。



你也可以编辑 scene.json 文件，在“parcels”字段中列出多个地块。详见 通过命令行设置地块 了解更多详情。

💡 提示：在运行预览时，只要这些地块相邻并排列成相同形状，地块坐标就不需要与你的场景最终实际使用的坐标完全一致。之后当你 部署场景.

查看场景控制台

通过点击  图标在右上角。在这里你可以看到任何错误消息，以及你的场景通过 console.log().

打印到控制台的任何文本。你也可以按下键盘上的 ` 键来打开它。你还可以按 Shift + ` 将控制台打开得更大一些，以便查看更多文本。

Creator Hub 控制台

Creator Hub 会在不离开编辑器的情况下显示相同的输出，而且默认就是这样。运行一个预览和一个 CONSOLE 标签页会出现在 文件系统 和 资源包 旁边，位于编辑器底部面板中。

若要阻止控制台自动打开，请取消勾选 打开调试控制台 下的 播放选项 在 编辑器 标签页中的 Creator Hub 设置。

要把控制台移到一边，请点击其标题栏中标有 在单独窗口中打开控制台的弹出图标。控制台会作为一个名为 控制台的独立窗口打开，你可以把它移到第二个显示器上，并在编辑时保持可见。

这个独立窗口有一个 清除控制台 按钮，以及一个 重新停靠到编辑器中 按钮，可将控制台返回到底部面板。同时编辑器中的 CONSOLE 标签页会显示 控制台已在单独窗口中打开 并提供一个 停靠回这里 按钮，作用相同。

💡 提示：控制台在分离状态下仍会持续收集输出，因此重新停靠不会丢失任何内容。当没有预览在运行时，它会显示 运行场景以查看调试输出.

在本地测试多人场景

如果你启动场景预览并在两个（或更多）不同的 explorer 窗口中打开它，每个打开的窗口都会被视为一个独立玩家，而一个模拟通信服务器将使这些玩家保持同步。

在一个窗口中与场景交互，然后切换到另一个窗口，看看该交互的效果也会在那里可见。

使用 Creator Hub，打开 多实例预览 在 桌面客户端 的子菜单中的 播放选项，然后第二次点击 播放 按钮以打开第二个 Decentraland explorer 窗口。你必须在两个窗口中使用不同地址连接。场景重新加载时，相同会话将保持打开。



作为替代方案，你可以在浏览器 URL 中输入以下内容来打开第二个 Decentraland explorer 窗口：

decentraland://realm=http://127.0.0.1:8000&local-scene=true&debug=true&multi-instance=true

高级：使用远程资源包快速迭代

💡 提示：对于大多数场景来说，使用资源包进行预览最简单的方法是启用 优化资源，它会在本地转换你的模型，并始终反映其最新版本。下面的模式是一种替代方案，它重用已发布在服务器上的资源包。

对于包含大量 3D 模型的重场景，你可以通过重用已经发布在 Decentraland 服务器上的 资源包 来加快场景加载和重载，而不是加载未经优化的原始 3D 模型。这在仅进行代码更改的迭代时尤其有用。

要启用此模式，请使用以下参数启动 Decentraland Desktop 客户端：

该 <ab-source> 参数会根据场景已发布到何处而变化：

  • 在 Genesis City 中: --lsd-remote-ab-server Genesis

  • 在 World 中: --lsd-remote-ab-world <world-name>.dcl.eth

例如，要预览一个已部署到某个 World 的场景的本地副本：

在这两种情况下， --realm http://127.0.0.1:8000/ 将客户端指向你的本地预览服务器（先运行 npm run start 以启动它），并且 --local-scene true 告诉客户端从那里加载场景代码。

📔 重要：当使用此模式时，建议 所有 资源都已发布，并且其资源包已由内容服务器完全处理完毕。如果你添加了任何新资源，它们将不会使用优化加载，而是像你正常运行预览时那样以原始 gltf 文件加载。但如果你本地修改了一个已经发布过的资源，并保持相同文件名，那么你看到的将是该资源已发布的旧版本。

在这种情况下，请先重新部署场景，等待几分钟让资源包生成完成（见 资源包转换），然后再恢复使用此模式进行仅代码迭代。

上一页开发工作流
下一页使用 CLI

最后更新于