这是「开源项目介绍」系列第五篇,写的是我开源出来的另一个方向完全不同的项目:浏览器里的《桃花源记》水墨青绿 3D 活态世界(v1.0.1)。

项目地址:github.com/fomalhaut1998/taohuayuan · 在线体验:taohuayuan.fomal.cc(主站,Vercel 自动部署)| 备用域名:taohuayuan.fomal.cn | GitHub Pages:github.fomal.cc/taohuayuan(fomalhaut1998.github.io/taohuayuan 同址跳转)。

纯静态构建、无后端、无运行时外部请求,发一条链接给朋友就能直接点开漫游,桌面键鼠和手机触屏都能用。代码以 MIT 许可开源,本地声景短采样各自保留 CC0 / CC BY 4.0 署名许可。

一、为什么要造一座「不用打工」的桃花源

网上的 Web 3D 开源项目通常走两个极端:一种是“五分钟技术 Demo”,摆几棵树加个水面着色器,转两圈鼠标十秒就关掉了;另一种是往浏览器里硬塞传统游戏套路——NPC 头顶挂黄色感叹号、地面画发光指引箭头、屏幕角落摆满体力条、饥饿值、背包格子、经验金币和“探索进度 12/100”。

但陶渊明写《桃花源记》,最打动人的恰恰是没有紧迫感。渔人只是忘路之远近,忽逢桃花林,穿过极狭的山洞之后看到桑竹鸡犬、村人设酒杀鸡,住了几日便辞去。

所以立项之初我就把体验拆成双层节奏,同时把负面红线写进项目文档:

  1. 三幕叙事闭环(15–25 分钟可走完):从开屏四时绘本画幕入画,经历「缘溪入山 → 豁然开朗 → 做客辞别 → 迷津再寻不得」三幕收束,终章墨幕落下后依然可以选择留驻桃源。陶渊明的原文一字不改地作核心竖排文言呈现,不用说教文字解释寓意。
  2. 桃源闲居(随时把主线搁到一边):不推主线也不会错过世界。桃源简册(Q)里收了 8 阶主线与 9 桩乡邻支线托付,只写古雅短线索和圆点进度;如果不想自己找路,在舆图(M)上标记「所往」后,会有落英风丝或夜萤顺着山风为你引路——没设目标时,这套引路系统严格做到 0 draw call。
  3. 死守负面红线:没有体力、没有饥饿、没有背包合成与买卖、没有经验值与百分比收集焦虑条,也没有头顶感叹号和强行打断视角的引导弹窗。

二、它长什么样:四时物候 × 十二时辰 × 四态天气

先看六张实机画面。以下全部由游戏内置的「画卷工坊」(O)直接导出原图——系统会自动识别镜头所在的地景区域、匹配联句并钤上印章,没有经过任何后期修图:

桃花林 · 春深 · 晴昼(画卷工坊原图导出)

桃花林 · 春深 · 晴昼——夹岸数百步,中无杂树,远方即是山口一线天。

东皋观云亭 · 春深 · 晴昼

东皋观云亭 · 春深 · 晴昼——渔舟逐水爱山春,两岸桃花夹古津。

东皋牧羊坡 · 夏荷 · 晴昼

东皋牧羊坡 · 夏荷 · 晴昼——土地平旷,屋舍俨然,有良田美池桑竹之属。

桃源村 · 秋粟 · 晴昼

桃源村 · 秋粟 · 晴昼——暧暧远人村,依依墟里烟。狗吠深巷中,鸡鸣桑树颠。

桃源村 · 冬雪 · 晴暮

桃源村 · 冬雪 · 晴暮——俯瞰银装谷,炊烟一线温。

美池 · 春深 · 晴夜

美池 · 春深 · 晴夜——醉后不知天在水,满船清梦压星河。

整座山谷挂在东晋太元十一年(公元 386 年)二十四节气公历时钟上,与十二时辰(晨 / 昼 / 暮 / 夜)、四候(春深落英 / 夏初新荷 / 秋熟金粟 / 冬寂薄雪)以及四态天气(晴 / 雨 / 雾 / 冬雪)连续联动。

冬候不是简单改个雾色应付了事:进冬之后地面会渐进积雪,池溪边缘会结出岸冰,舆图换成雪韵底色,雪地里走过会留下足迹,晴天正午的屋檐还会往下滴化雪水;而当你切回春候时,所有顶点色、实例色和显隐状态都会逐字节无损还原,不留半点冬雪残留的脏色。

三、800×800 六大地理圈层与活态细节

整张地形扩到了 800×800,共 24 处 POI、20 个命名分区与探索迷雾舆图(走过的地方才逐片揭晓),按地理纵深分成六个圈层:

地理圈层里面有什么
武陵溪口与外郊缘溪起步的浅滩、桃花夹岸、渡口芦苇与外郊水路
山口一线天仅容人行的窄峡山洞与微光洞口,兼做声学与视野门户
核心村落与良田美池农耕家宅、桑竹、良田水碓、六博案几、大池与木桥
谷地边野观云亭、晒秋坪、避秦残碑、牧羊坡、望稼楼、三叠泉、药庐茶灶
外山秘境与深坳幽壑烂柯石枰、古窑、鹿柴望川台、松风茶寮、云樵茅舍、冷泉幽轩等
山野彩蛋秘境散落在山野角落的 7 处隐秘风景与彩蛋

世界里跑着一套昼夜与天气节律:村人在白昼汲水、浣洗、聚谈、春畴牛耕,入夜生起炊烟、院落夜宴灯火;鸡犬鸭鹅、池鱼群鸟、林间鹿群各自按时辰作息;天降大雨时,村人与禽兽会循着避雨棚各自去避雨。

交互全部做成不带功利的轻体验:

  • 可以在第一 / 第三人称(V)之间切换,轻跃低障(Space);
  • 可以到溪边撑舟,按 X 收篙随波漂流,或者在溪畔放竹叶花船、用青石打水漂;
  • 找张石凳或草席落座(E),或者干脆按 C 驻足静听风声水声,看到古琴还可以用 1–5 按五声音阶抚琴相和;
  • 按 G 近观草木鸟兽虫鱼,把器物与风物考据(六博、鱼梁、水碓等)收入图鉴;
  • 按 P / B 御风俯瞰全谷,或者按 L 开启「入画巡游」自动沿精选空中航线游览(自带三维碰撞净空保护,不穿山不撞树)。

四、美术与声景:克制比堆料更难

为了守住水墨青绿的骨相,这个项目定了一条几乎不留退路的视觉契约:

  • 禁写实、禁 PBR:禁用 MeshStandardMaterial / MeshPhysicalMaterial,禁用粗糙度/法线/金属度贴图,禁照片级位图,禁 PointLight / SpotLight 和全局 shadowMap,也不用廉价全屏后处理滤镜。
  • 母本色板:宣纸 #F2EAD9、墨 #262626、桃花 #E8A0A8、青绿 #7BA05B、深青 #4A7C6F、淡山剪影 #A8B5A0。所有 3D 造型一律低多边形 flatShading + 顶点色,辅以少数 Canvas 程序化绘制纹理与远山青灰阶梯消隐。
  • 克制的动态光照:全场景核心照明只有 1 DirectionalLight + 1 HemisphereLight,配合轻量地面接触阴影;水面波光倒影、笔意横云、草木风摆、落英飞雪与夜萤都通过轻量自定义 GLSL 或 onBeforeCompile 注入实现。当同一材质叠加多处着色注入时,必须链式拼接 customProgramCacheKey 防止程序缓存互踩。

声音方面,同样走「大音希声」的路线:原生 Web Audio 空间混音打底,人进山洞时会触发洞门声学遮蔽(tunnelOcclusion / portalBloom),远处的声音按距离做空气吸收,脚步声随脚下踩的是木板、青石、泥土还是草地切换材质。再叠上总共只有约 0.36 MiB 的本地短采样(五声、古琴、箫、远磬与鸡犬鸟鸣),留白稀疏、不吵闹,也不发任何外部音频或在线 TTS 请求。

五、工程底盘:运行时只依赖一个 three

技术栈刻意压到极简:

  • 构建与核心:Vite 6 + Three.js(ES Modules)+ 原生 Web API(WebGL / Canvas 2D / Web Audio / localStorage / IndexedDB / Pointer Events)。不引 React Three Fiber,不引 Cannon / Rapier 等第三方物理引擎。
  • 批量合批与裁剪:桃林、竹林、松柏、芦苇、草甸、落英雪片、群鱼飞鸟全走 InstancedMesh 批次合并,社区村民也收进共享合批池(createCommunityActorPool),统一归 static-visibility.js 做分块距离压缩与远景 LOD(坡上花树、红枫、山岩、茶丛、草丛与谷穗远距减面约 73%–81%);ground-surface.js 采用 8m 空间网格加速地表高度与材质查询,河道距离计算带 AABB 剪枝;山口一线天天然充当室内/室外洞门裁剪(Portal Culling)边界,一旦开启御风(P/B)或巡游(L)升到高空,洞门自动解除并消去洞口压暗。
  • 热路径零分配:每帧 update 循环禁止新建临时 Vector3 / Color / Matrix4 或拼 hex 颜色字符串,避免漫游半小时后 GC 抖动掉帧。
  • 跨端性能预算:桌面 1080p 稳定 ≥ 60fps、同屏 draw calls < 260;集显轻薄本基准档 ≥ 55fps;移动端触屏采用多指通道隔离(左屏虚拟摇杆、右屏划屏视角与上下文触控钮互不抢占)以及基于 visualViewport 的动态 HUD 防遮挡布局,动态封顶 DPR ≤ 1.5 并做竖屏 FOV 柔性补偿,跑在 30–45fps。
  • 分包与双层持久化:package.json 单源驱动 PROJECT_META 与构建版本注入,vite.config.js 通过 manualChunks 把 three、世界数据、核心几何、村落、外山扩建、氛围、玩法等拆成独立 chunk,画卷工坊与移动端触控等非首屏重面板走动态 import() 按需加载。行旅进度、音频偏好、舆图迷雾、简册状态存进 localStorage 的 7 个键,而画卷工坊导出的原生高分辨率原图存进 IndexedDB(taohua.scrolls.originals.v1),兼容无痕模式与存储受限降级。
  • 93 项自动化回归检查:npm test 跑完 93 项检查脚本,门禁覆盖几何完整性、批次合批、碰撞安全、音频许可清单、版本元信息与热路径分配规则。

六、把「世界宪法」一起开源:如何跟 AI 长期共建一个 3D 世界

这个项目在多轮开发、大世界扩建与性能打磨中使用的 AI 工具为 Gemini4 Neon&Gemini4 Carbon(Antigravity)、Qwen4Max&GPT 6.1 Sol(DSH)。跟平常小工具最大的不同,是我在仓库根目录一并放出了 PROJECT_BRIEF.md(世界契约 v3.0)和 PROMPTS.md(提示词模板 v3.0)。

一个 800×800、横跨几十个模块的 3D 世界,靠一两轮对话是不可能写完的。多轮迭代下来,有几条踩坑得来的规矩比代码本身更值钱:

  • 不要锁死文件字节:早期如果禁止改 world.json 或旧模块,AI 为了过关就会在别的模块里硬编码覆盖值、或者往旧对象上挂“寄生字段”和猴子补丁,久而久之架构就会腐化。正确做法是用 93 项 npm test 锁死行为与几何契约,放开源码正道重构。
  • 新区域接入「九件套」:往桃源里加一片新景物,地面高度与材质采样、低障碰撞(≤ 1.32m)、天色注册、四候双向还原、静态可见性与 LOD、洞门高空联动、舆图迷雾与图鉴、静听/落座/避雨、画卷题跋识别——九步少一环都会穿帮(比如人踩穿地面、或者御风飞上高空看不见新房子)。
  • 分清软件光栅与真机帧率:无头浏览器跑出来的 SwiftShader 只能验证几何、合批 draw calls、三角形面数和画面有没有穿模,绝对不能当作真机 GPU 帧率。

如果你也在做需要长周期迭代的 AI 协作工程,这两份文档可以直接拿去当模板改。

七、怎么玩 & 本地跑起来

直接点开在线版体验:

桌面端常用键位(移动端直接用屏幕左摇杆、右划屏和屏上动作钮):

键位作用
WASD / 方向键行走(Shift 疾行、Space 轻跃)
V第一 / 第三人称视角切换
E / X情境交互(交谈 / 撑舟 / 落座 / 放花船)/ 收篙随波
M / Q / J舆图 / 桃源简册 / 游记
G / C近观识物入图鉴 / 驻足静听
O / L画卷工坊 / 入画巡游(L 或 Esc 归步)
P / B御风漫游
T / R / K / N切十二时辰 / 天气四态 / 四时物候 / 雅音三档
?桃源小笺(完整键位与帮助)

如果想在本地拉源码跑起来或二次改造(需要 Node.js ≥ 18):

1
2
3
4
5
6
7
git clone https://github.com/fomalhaut1998/taohuayuan.git
cd taohuayuan
npm install
npm run dev # 本地开发预览(Vite)
npm run build # 产出纯静态 dist/
npm run preview # 预览构建产物(端口 4173)
npm test # 运行 93 项自动化回归检查

打包出来的 dist/ 是纯静态文件,扔到 Vercel、GitHub Pages、Netlify 或任意 Nginx 上都能直接跑;仓库 v1.0.1 的 Release 里也附带了相对路径构建产物(taohuayuan-v1.0.1-web.zip,base=./),解压后用任意静态服务器托管即可用于任意子目录或离线局域网分享。

八、开源许可与链接

代码以 MIT 许可开源;public/audio/ 下的本地声景短采样来源于 Freesound 等公开社区,主要为 CC0-1.0(个别 CC BY 4.0),逐条署名与许可原文在仓库 public/audio/round3/NOTICE.md 中列出,再分发时请保留该说明。