跳到主要内容
AI教程

运行、构建并探索 Portals：471 个生成的 3D 世界

本教程将介绍如何从源代码运行 Portals、创建可部署的静态构建、探索其中 471 个生成的世界，并了解其世界、传送门、声音、图形和选择系统。你还将了解主要代码的位置，以及如何着手扩展该项目。

AI我搜编辑部阅读约 10 分钟
运行、构建并探索 Portals：471 个生成的 3D 世界

什么是 Portals？

Portals 是一段无需操作的浏览器飞行体验，穿越 471 个生成式 3D 世界。摄像机沿预设路径前进，抵达传送门后直接进入下一个正在运行的世界，中间不会出现剪切或淡入淡出。你无法操控飞行方向，但可以控制飞行速度、呈现方式、声音、画面效果以及世界选择。

黄昏时穿越雪镇的仲冬特快列车

该项目使用 JavaScript 和 three.js 构建。每个世界都会在浏览器中生成几何结构和纹理，音频则在播放过程中合成。世界不会加载外部 3D 模型、纹理图片或声音文件。该项目还是一个静态网站：不需要账户、应用服务器或跟踪服务。

截至 2026 年 11 月 9 日，该仓库代表的是 s8f 版本。该版本包含约 140 万行 JavaScript 代码和 471 个世界。

主要功能

  • 471 个生成式世界：内容涵盖荒野、城市、海洋、室内空间、天空、外星环境、史前场景、受艺术启发的地点、文学世界、电影和电视作品灵感、古代奇观，以及 AI 圈内玩笑。
  • 无缝传送门：当前世界与传送门另一侧的世界会同时运行，让摄像机无需过渡画面即可穿越。
  • 程序化资产：几何结构、纹理和声音都在浏览器中生成，而不是作为传统世界资产加载。
  • 自动飞行：每个世界都会提供摄像机路径和持续时间。大多数飞行约持续 40 到 50 秒。
  • 自适应画面：自动模式会根据显卡估算画质等级，并调整渲染分辨率以保持流畅运行。
  • 本地偏好设置：已浏览世界、收藏和设置都会保存在浏览器存储中。
  • 图库与旅程：图库展示所有世界，20 条精选旅程则按固定顺序播放选定的世界。
  • 静态部署：生产构建会在 dist 中生成普通文件，可由静态 Web 主机提供服务。

前置要求

你需要 Node.js 18 或更高版本，以及 Git。直接预览源代码不需要安装或执行构建步骤。虽然建议使用独立显卡，但该项目也能以降低的画质运行在手机和较旧的笔记本电脑上。

确认 Node.js 版本：

node --version

如果结果低于 18，请先更新 Node.js 再继续。

直接从源代码运行 Portals

1. 克隆仓库

git clone https://github.com/emollick/ai-portals.git
cd ai-portals

2. 启动本地源代码服务器

npm start

在浏览器中打开 http://localhost:8000。这会直接提供当前源代码树，无需先安装软件包或进行编译。

源代码预览有两个已知限制。图库无法识别新添加的世界，也无法显示生成的描述页面。首次访问时，浏览器控制台还会报告缺少 atlas.json 文件，因为该文件只有在构建过程中才会生成。

创建并预览生产构建

安装构建依赖，生成部署包，然后启动预览服务器：

npm install
npm run build
npm run preview

生成的静态网站会写入 dist。打开 http://localhost:8001 即可查看。

构建过程会使用 esbuild 压缩项目脚本，并创建仅用于部署的资源，包括：

  • 为每个世界和旅程生成的小型分享预览页面。
  • 列出所有世界及其描述的普通页面。
  • 记录哪些世界为新增世界的图库数据。
  • 托管配置文件。

复现 s8f 版本

构建命令支持版本标记。根据仓库文档，以下命令在 2026 年 11 月 9 日逐文件、逐字节复现了线上 s8f 版本：

npm run build -- --stamp s8f

开发时使用普通构建。只有在确实需要版本元数据，或希望复现文档所述版本时，才使用该标记。

基本控制与使用方法

Portals 会自动开始飞行。声音默认关闭，如果想听到合成音轨，请按 S。键盘控制如下：

  • 空格键：暂停或继续飞行。
  • 右方向键：加速前往下一个传送门。
  • S：开启或关闭声音。
  • G：启用柔和模式，让摄像机运行更稳定并保持地平线水平。
  • H：将当前世界保存为收藏。
  • P：保存图片。
  • I：打开图库、旅程和搜索界面。
  • O：打开画面、摄像机、艺术风格、旅程、伴侣和时间选项。
  • F：进入或退出全屏模式。

移动鼠标会在屏幕底部显示控制栏。控制栏包含与键盘控制对应的按钮，以及节奏滑块和现实至奇异滑块。在窗口较窄时，滑块会移入选项界面。

一次有用的首次探索

  1. 启动源代码预览或生产预览。
  2. 按S启用音频。
  3. 让一个完整世界播放完毕，以便观察正常的传送门穿越。
  4. 如果摄像机移动让你感到不适，按G。
  5. 按I打开画廊，然后搜索或浏览完整收藏。
  6. 调整现实至奇异，控制异常世界被选中的频率。
  7. 遇到想收藏的世界时，按H。

无缝传送门的工作方式

城堡传送门，展示漂浮在太空中的绿色小世界

穿越约一秒后，引擎会选择下一个世界。它会在渲染帧之间每次用几毫秒构建该世界，然后在世界仍处于视野之外时预热其着色器和纹理。

目的地并不是静态预览。第二台摄像机会在每一帧中，将下一个正在运行的世界渲染到传送门开口内。摄像机即将抵达入口前，引擎会将目的地提升为当前世界，并继续飞行。如果准备尚未完成，当前飞行会减速并在传送门前等待。

世界的选择方式

选择器会优先选择访客尚未见过的世界。在一次访问的前十几个世界中，它偏向选择项目评审代理评分最高的世界。每个世界都有从1到5的质量等级，这些等级有助于决定哪些体验会较早出现。

选择器还会寻找对比。它倾向于选择在类型、亮度或温度上不同于当前环境的目的地。现实至奇异设置控制较为奇异的条目出现的频率。

了解项目布局

最重要的文件和目录包括：

  • index.html：应用页面。
  • src/main.js：键盘控制、选项和底部控制栏。
  • src/core：飞行、传送门、世界选择、声音和图形质量系统。
  • src/kit：共享的世界构建组件，例如天空、水域、地形、植物、动物、建筑和室内环境。
  • src/worlds：每个世界对应一个模块、世界注册表和入口大厅。
  • src/parts：各个世界使用的主要场景部件。
  • src/extras.js：游乐设施、伙伴和艺术风格列表。
  • src/rides、src/companions和src/styles：这些额外内容的实现。
  • src/ui：画廊和分享代码，以及网站唯一的样式表ui.css。
  • vendor/three：捆绑的 three.js 库。
  • thumbs：画廊缩略图。
  • design：构建时读取的世界文本和发布到达表。
  • tools：构建脚本和本地服务器。

世界模块的结构

世界是src/worlds下的一个文件。其默认导出是一个包含build函数的对象。世界还必须在src/worlds/index.js中注册，并提供标题、类型和说明，因为选择器和画廊都会读取该列表。

build函数会返回三个必要元素：

  • 一个 three.js 场景。
  • 一条摄像机路径。
  • 一段飞行时长。

大多数世界会将主要场景部件放在src/parts下的独立文件中。src/kit中的共享设施提供可复用组件，无需每个世界分别实现常见景物。

研究或扩展世界时的安全工作流程

  1. 在src/worlds下选择一个与你想了解的环境类型相似的现有世界。
  2. 沿着它的导入关系查看src/parts和src/kit，了解场景是如何组装的。
  3. 检查其默认导出和build函数，了解仓库实际使用的对象结构和摄像机路径约定。
  4. 查看src/worlds/index.js中的对应注册信息，确认所需的标题、类型和说明元数据。
  5. 运行npm start进行快速源代码测试。
  6. 创建生产构建，以验证生成的画廊和分享资源。

这个仓库规模异常庞大，因此改造一个相近的世界，比推断未记录的 API 或从头构建模块更安全。

声音和图形行为

声音合成

每个世界都会获得一个缓慢和弦与几声钟鸣。大多数世界还会使用安静的环境音床，例如风声、水声、室内底噪或持续的太空嗡鸣。一个世界最多可以添加三层从十九种可用效果中选出的音效，包括雨声、海浪、鸟鸣和远处的钟声。浏览器音频引擎会合成这些声音，而不是加载音频文件。

自动图形质量

将图形设置为“自动”时，Portals 会根据显卡估算合适的质量等级。随后，它会提高或降低绘制分辨率，以帮助保持流畅飞行。在较旧的笔记本电脑或手机上，尝试更高要求的设置前应保持“自动”启用。

高级提示

使用轻柔模式提升无障碍体验

按下 G 可让镜头更稳定，并保持地平线水平。如果正常飞行会引起不适，这是首先应该尝试的设置。

测试源代码版本和构建版本

使用源代码服务器进行快速迭代，但部署前务必检查 dist 构建版本。部分图库数据、描述页面、分享预览和托管设置只有在构建后才会生成。

测试门户就绪状态，而不只是场景外观

世界必须在穿越前准备就绪。修改世界代码时，既要观察接近其门户的过程，也要观察目标场景本身。繁重的生成过程或着色器准备可能会让飞行在等待时变慢。

使用旅程实现可重复的序列

Portals 包含 20 个旅程，会按固定顺序播放各个世界。例如一滴水从冰雹前往深海；拉远视角则从活细胞内部开始。当你想要比普通选择器更具引导性的体验时，固定序列非常有用。

遵守存储和隐私边界

该应用没有后端，也不会向服务器发送账户、跟踪、收藏或设置数据。调试收藏或已查看世界的行为时，请记住这些值由浏览器存储。

发布更改前检查许可协议

该仓库采用 CC BY-NC-SA 4.0 许可发布，允许在署名并使用相同许可的前提下进行非商业分享和改编。three.js 和部分简短函数适用单独的条款。在重新发布修改后的构建版本前，请阅读 LICENSE 和 THIRD-PARTY-NOTICES.txt，尤其要注意 README 还记录了其他着色器和工具函数的来源。

结论

Portals 将程序化 three.js 场景、合成音频、自适应图形、后台世界生成和双世界渲染结合起来，打造出不间断的浏览器旅程。你可以立即使用 npm start 探索源代码，使用 npm run build 生成完整的可部署网站，并在研究或扩展其架构时参考项目布局和现有世界模块。