game-world
基于 webcityim/game-world 的 3D 网页世界:一颗地球大小的行星,
地表散布着程序化生成的城市,可以用手柄从轨道一路飞到街头,落地步行,和建筑、行人、物件互动。
技术栈:yarn + Vite + TypeScript + three.js WebGPURenderer(不支持 WebGPU 的浏览器自动回落到 WebGL2)。
快速开始
corepack enable
yarn install
yarn dev # http://localhost:5173
yarn build # 产物在 dist/
yarn typecheck
URL 参数:
| 参数 | 作用 |
|---|
?poi=3 | 启动时的书签(1 = 轨道,2 = 首都鸟瞰,3 = 首都街头 …) |
?time=0.5 | 一天中的时刻(0 = 首都正午,0.5 = 午夜) |
?webgl | 强制 WebGL2 后端(排查 WebGPU 驱动问题) |
?noshadow | 关闭阴影 |
?threshold=0.016 | 手柄摇杆死区 |
?radius=6371000 / ?exag=2.5 / ?seed=123 | 行星半径(米) / 地形垂直夸张 / 地形种子 |
世界里有什么
| 城市 | 风格 | 特色 | 可交互地标 |
|---|
| 风岚城(首都) | 欧式小镇 | 约 2250 栋木筋房 / 石灰墙房屋、城墙与四座城门、郊外风车和麦田 | 大教堂钟楼(敲钟)、风车(调速)、广场 4 家 HTML 商铺 |
| 青瓦镇 | 东方 | 翘檐多层屋顶、石台基、红色檐柱、樱花树、灯笼路灯 | 七层宝塔门前的铜锣(一键点亮 / 熄灭全城灯笼) |
| 金沙城 | 沙漠 | 平顶女儿墙、圆顶、遮阳篷、棕榈与绿洲 | 圆顶宫殿前的喷泉(开关) |
| 霓虹都 | 现代 | 玻璃幕墙退台塔楼,中心区 150~230 m,中央超高塔约 330 m | 中央塔电梯(直达观景台 / 返回地面) |
| 麦浪村 | 欧式村庄 | 小型聚落,可以从首都高空看到 | 小教堂钟楼 |
每座城市里还有:每栋房子的门可以开关、路灯可以单独开关、散落的宝箱(开启获得摩拉)、
沿街行走的行人(交谈时会停下转身)。四大奇观(世界树、浮空岛、水晶尖塔、天环)位于首都 8~25 km 外,
在城里抬头就能看到。
昼夜循环 20 分钟一圈(按 T 快进 3 小时):夜里窗户随机亮灯、路灯点亮,从轨道上能看到各城市的灯光。
操作
手柄
通用:Start 切换飞行 / 步行 · A 交互 · Y / X 下一个 / 上一个书签 · Select 回到轨道
飞行:逻辑移植自 WebGPU-Art/protea(src/gamepad.ts + src/control.mts),
R3 进入 Roll 模式,L3 回到稳定视角:
| 手柄 | 稳定视角(默认) | Roll 模式 |
|---|
| 右摇杆 | 左右 / 上下平移 | 偏航 / 俯仰 |
| 左摇杆 Y | 前后 | 前后 |
| 左摇杆 X | 偏航 | 翻滚 |
| 十字键 ↑↓ | 俯仰 | 上下平移 |
| 十字键 ←→ | 翻滚 | 左右平移 |
| L1 / R1 | 加速(平移 ×8,旋转 ×4) | 同左 |
| L2 / R2 | scale 增大 / 减小(速度 ∝ 1/scale) | 同左 |
| B | 翻滚回正 | 同左 |
步行:左摇杆移动 · 右摇杆视角 · L1 / R1 奔跑 · B 跳跃。从高空切到步行时会直接落到脚下的地面或屋顶。
和 protea 的差异:protea 是自由 6 自由度相机,这里"上"始终是行星法线,所以多了 B 键回正翻滚;
摇杆死区默认 0.08(protea 是 0.016,多数手柄会漂移)。
键鼠
| 键鼠 | 动作 |
|---|
| 拖动鼠标 / 方向键 | 视角 |
| WASD | 移动 |
| Space / C | 上升 / 下降(步行时 Space 跳跃) |
| Shift / Z / 滚轮 | 加速 / 减速 / 缩放 |
| G | 飞行 / 步行 |
| F / Enter | 交互 |
| Q,E / L | 翻滚 / 回正 |
| T | 时间快进 3 小时 |
| 1-9, 0 | 书签 |
| H | 隐藏操作说明 |
| Esc | 关闭商铺页面 |
结构
src/
config.ts 全局常量(行星半径、LOD 参数、商铺激活距离...)
main.ts 渲染器、选址、光照 / 阴影 / 雾 / 昼夜、物理、交互、书签、HUD
controls/
input.ts 键鼠 + Gamepad API
player.ts 球面玩家控制器:飞行(protea 手柄映射)+ 步行(重力、跳跃、碰撞)
city/
layout.ts 城市布局:网格道路、街区、临街地块、中心广场、公园、道路图
styles.ts 四种建筑风格:房屋生成器、地标、配色、树种、行人台词
builder.ts 合并几何体构建器(墙、双坡 / 四坡 / 翘檐屋顶、穹顶、圆锥...)
material.ts TSL 外立面着色器:窗户、玻璃幕墙、木筋墙、瓦片、石板、道路标线、夜间灯光
props.ts 实例化物体:树、路灯、门、宝箱、行人
city.ts 城市:分帧生成、城墙 / 郊外、碰撞、交互查询、远景夜灯
rng.ts 确定性随机数
world/
noise.ts 带种子的 3D 梯度噪声
terrain.ts 海拔函数(大陆 / 山脉 / 丘陵 / 河谷)、地表配色、压平区域
planet.ts 立方体球面 + 四叉树 LOD、水面、裙边、浮动原点
anchor.ts 挂在行星表面的锚点(本地 ↔ 行星坐标)+ 选址(pickSites)
wonders.ts 奇观入口(再导出 wonder/*:世界树、石林、天然拱门、浮空岛、水晶尖塔、天环、龙脊)
vegetation.ts 实例化植被(树、灌木、草、花、石),按 LOD 分层
geo.ts 程序化几何工具(扫掠、位移、焊接、顶点着色)
shops/
htmlTexture.ts HTML in Canvas(原生 drawElementImage / SVG foreignObject 兜底)
patterns.ts 生成式图案 SVG:Clifford / Lorenz / Rule 30 / 内摆线
pages.ts 商铺页面(真实 HTML+CSS,内嵌实时重绘的图案)
shop.ts 商铺建筑、广场、按距离开关页面
ui/
ui.ts 交互提示、消息气泡、商铺页面浮层
城市是怎么生成的
- 选址:首都选在绿色低地、周围 1.8 km 内起伏小于 160 m 的地方;奇观和其他城市在首都周围的环带内螺旋采样;
沙漠城按生物群系在全球范围找干旱带。选好后把地形在城市范围内压平。
- 布局(
layout.ts):间距 P 的正交道路网,每 4 条一条大道;边界是带噪声的圆;
普通街区沿四边切出朝街的地块,中间留院子;现代风格的街区改为 2×2 栋塔楼。
- 建筑(
styles.ts):每个地块调用所属风格的生成器,输出墙体、屋顶、烟囱、檐柱、女儿墙、穹顶等,
全部写进同一个合并几何体;同时返回碰撞盒和门的位置。
- 细节全部在像素着色器里(
material.ts):每个面带 (u, v, 面宽, 类型, 随机数) 属性,
着色器据此画出对齐的窗格、楼层、木筋、瓦片、石板缝和道路标线;远处自动淡化细节,避免闪烁。
- 可交互物体用 InstancedMesh,每个实例的矩阵 / 颜色可以单独改(开门、熄灯、开箱、行人走动)。
- 城市在相机 70 km 内开始分帧生成(每帧几毫秒),45 km 外隐藏细节,只剩夜间的灯点。
一座首都约 2250 栋建筑、18 万顶点,生成约 0.2 s。
交互与物理
- 在城市范围内,玩家位置换算到城市本地坐标,与建筑 / 树 / 路灯的碰撞盒做二维推出;矮于 0.55 m 的台阶可以直接迈上去,
从上方落下时可以站上屋顶。野外按地形高度。
- 交互查询用空间哈希找视线前方 3 m 内的门 / 路灯 / 宝箱 / 行人 / 地标,准星下显示提示。
大尺度渲染
- 位置全部用 float64(JS number)保存;地形块和城市的顶点都相对各自的中心存储,
渲染时相机固定在原点、整个世界减去相机位置(浮动原点),所以 6371 km 半径下地面也不抖动。
logarithmicDepthBuffer 解决 0.3 m ~ 3×10^8 m 的深度范围。- 四叉树按相机距离细分(最大层级 15,块宽约 300 m、顶点间距约 10 m),
子块没生成完之前继续画父块;每帧只花固定的 CPU 时间预算生成块,地平线以外的块直接剔除。
- 阴影只在离地 1.5 km 以内开启,阴影相机跟随玩家(±140 m)。
HTML in Canvas
首都广场商铺的墙上有一块"屏幕",内容是真实的 HTML 页面:
- 支持原生
layoutsubtree + drawElementImage 的浏览器(Chrome 实验特性)走原生路径,DOM 变化自动重绘。
- 其他浏览器自动用 SVG
foreignObject 兜底(静态快照,每秒刷新一次)。
- 距离 > 220 m 时页面被关闭(原生路径把 canvas 从 DOM 摘掉、停止重绘),只显示熄灭的屏幕;< 140 m 时重新打开。
- 走到商铺门口按 A / F,同一份 HTML 会以真实 DOM 打开成全屏浮层。
该提案的 API 仍在演进,htmlTexture.ts 里的调用都做了特性检测,接口变动时只需要改这一个文件。
部署
.github/workflows/upload.yaml 参考 calcit-lang/respo-calcit-workflow:
- 构建时设置
VITE_BASE_URL=https://cos-sh.tiye.me/<owner>/<repo>/(PR 为 .../pr/),vite.config.ts 读取它作为 base
- 静态资源上传到腾讯云 COS
- push 到
main 时 rsync 到服务器;同仓库的 PR 发布到 /pr/ 预览目录
需要配置的仓库 Secrets:COS_BUCKET、COS_SECRET_ID、COS_SECRET_KEY、rsync_private_key。
仓库初期没有 yarn.lock,CI 会自动用 --no-immutable 安装;本地跑过一次 yarn install 并提交 yarn.lock 后,CI 会切换为 --immutable。
路线图
悬浮菜单与平滑飞行
右上角的可折叠菜单列出所有预设位置(轨道 / 城市 / 奇观),点击后沿球面弧线平滑飞过去(距离越远越高、越久),
到达后自动切换到该位置的模式(街头为步行)。飞行途中推摇杆 / 按移动键可以随时打断。数字键 1-9/0 与手柄 Y/X 也走同一套平滑飞行。
开发流程
主分支只通过 PR 合并:每个 PR 会跑类型检查与构建,并发布到 /pr/ 预览目录。
地貌、奇观与性能
- 地貌:全球噪声叠加了高地山脉、台地(丹霞)、河网和湖泊;首都额外有设计好的地貌——盆地被群山环绕,一条河从北面的山里蜿蜒流过、汇入南边的湖。
只有靠近才会加载更细的地形块(四叉树 LOD)。
- 地貌分区(
Terrain.addZone):沙漠(沙丘 + 平顶孤山)、草原(缓坡 + 稀疏树)、峡谷(高原 + 阶梯状谷壁)、断崖(两道陡崖线)、湖泊(湖盆 + 岸滩)。
首都周围 10~35 km 内各放了一块,金沙城是沙海 + 绿洲,麦浪村是草甸;菜单的「地貌」分组可以直接飞过去。
- 奇观(7 处):世界树、石林、天然拱门、浮空岛、水晶尖塔、天环、龙脊。每个奇观有"细节层",相机离得远时只画主体轮廓。
- 折叠 UI:菜单 / 信息面板 / 说明三块都可以折叠(右上角 −/＋ 按钮,或 M / I / H 键),状态会记住。
- 性能:远处城市只留灯光、近处才显示树 / 路灯 / 行人等小物件;阴影贴图隔帧更新;动态分辨率(
?dpr=1 可固定);
奇观的重复小物件(果实、石柱、树)用实例化绘制。
