- 门户「金钻宇宙」:删掉启动仪式 / 宇宙首屏晶体 / 盘符机架 / 读盘舱及其 CSS、图标; 换成星系图(portal/assets/universe/,three.js r170 自托管于 assets/vendor/,第一次打开板块才下载) + 窗下世界线卡片;#0001 深链飞到对应世界线;世界线数据只留 config.js 一份 - 像素字子集重做(旧字全保留 + 新字);其余板块与改动前逐像素一致 - 后端审查:add_call 写库失败不再打断渲染机回传;多进程同时首启只导入一次(+1 条测试,共 38); 撤销「处理过了」清掉 handled_at - 交接文档-2026-10.md:变更清单 / 功能增删 / 接口与数据格式变更 / 设计规范 / 业务逻辑 / 部署运维 - 交付清单哈希重算;README、旧交接说明指路 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
交接说明 · 金钻宇宙星系图(portal/assets/universe/)
状态:已接进门户(2026-10-05):
portal/index.html的「金钻宇宙」板块就是它,原来的启动仪式 / 盘符机架 / 读盘舱已删除。 风格参考:《绝地潜兵 2》银河战争地图 —— 旋臂星系 + 星云 + 扇区 + 补给线;每条世界线是一个星系,点进去是一颗卡通星球 + 档案卡。
1. 文件
| 文件 | 干什么 | 日常要不要改 |
|---|---|---|
assets/universe/config.js |
全部内容和外观配置:世界线档案、每颗星球的风格 / 颜色 / 卫星、星系配色、扇区名、粒子数量。门户主脚本的 UNIVERSES 也从这里读 |
改这个 |
assets/universe/planets.js |
卡通星球材质库(每种「风格」= 一段着色器 + 默认参数) | 加新风格时改 |
assets/universe/galaxy.js |
引擎:画星系、星云、补给线、名牌,处理拖动 / 缩放 / 点击 / 档案卡 / 运镜 | 一般不用动 |
assets/universe/universe.css |
观星窗、档案卡、窗下世界线卡片、手机布局的样式 | 改版式时改 |
portal/index.html 里 #view-universe + 底部那段 <script type="module"> |
板块骨架(窗户 / 名牌层 / HUD / 档案卡 / 卡片列表)和接线代码 | 改交互时改 |
assets/vendor/three.module.min.js |
three.js r170(MIT,自托管,不连外网) | 不动 |
没有任何贴图、模型文件:星球、星云、星点全是着色器实时生成的,所以没有版权问题,也不用担心图片加载慢。
2. 常见改动
加一条新世界线
config.js→UNIVERSES里把对应的空槽(比如{ no: '0005', empty: true })换成完整档案:字段和门户页原来的{ no: '0005', name: '名字', kind: '原创', tag: '一句话副标题', tags: ['标签1', '标签2'], desc: '档案正文' },UNIVERSES一模一样(no / name / kind / tag / tags / desc),可以直接拷。config.js→LOOKS里按编号加外观:'0005': { style: 'ice', r: 1.2, orbit: [34, 2], accent: '#9FE3FF', colors: ['#…', '#…', '#…', '#…'], // 可选:覆盖风格默认的四个颜色 ring: true, // 可选:光环(默认没有;用户觉得突兀,现在一颗都没开) atm: '#9FE3FF', // 可选:大气辉光(默认没有;之前「每颗星外面一个罩子」就是它) moons: [{ style: 'rock', r: 0.3, d: 2.6, speed: 0.5 }], // 可选:卫星(纯装饰) why: '为什么长这样(写给后来的人看)' },orbit: [离中心距离, 第几条旋臂]:距离 060,旋臂 03。别和别的星系放太近(差 8 以上比较好看)。- 不写
LOOKS的世界线会自动用EMPTY_LOOK(全息线框的「未点亮」样子),放在外圈。
- 刷新页面即可。HUD 上的「世界线 / 已点亮 / 空槽」数字是自动数的。
只换一颗星球的颜色
改它 LOOKS 里的 colors(四个颜色,含义见下表)。不写就用风格默认值。
改整张图的配色
config.js → GALAXY.colors:底色、核心色、旋臂内外色、星云几组颜色、线条色、UI 强调色(名牌 / 数字的金色)。
建议整张图只用这几种颜色,别给每颗星单独配一个刺眼的颜色 —— 上一版就是因为颜色太杂被说丑。
改扇区名 / 粒子数量 / 散落星球数量
GALAXY.sectors(6 个扇区名)、GALAXY.particles、GALAXY.nebulae、GALAXY.decorPlanets(桌面 / 手机分开设)。
手机卡的话先把 particles.mobile 降到 10000、nebulae.mobile 降到 10。
3. 现有的星球风格(planets.js → STYLES)
| 风格 | 长什么样 | 四个颜色依次是 | 现在给谁用 / 为什么 |
|---|---|---|---|
crystal |
多面体切面、每面颜色随朝向变、内部发光脉络 | 主色 / 副色 / 高光色 / 闪点 | 零号宇宙:晶钻超算本体 |
paper |
米白纸面、铅笔等高线、暗面排线、红笔圈、淡蓝涂色 | 纸色 / 铅笔色 / 红笔色 / 涂色 | 火柴人宇宙:小时候课上画的 |
ice |
纬向冰带、极冠、冰裂纹、冰面高光 | 冰白 / 冰蓝 / 裂纹色 / 极冠色 | 极寒世界:冰河期、-50℃ |
neon |
深紫地表、霓虹街区网格、闪烁窗灯 | 地表 / 霓虹 A / 霓虹 B / 窗灯 | 没落赛博城 |
duality |
一半白昼一半夜空,交界一条发光波浪线 | 白昼 / 云 / 夜空 / 夜云 | 善恶等级(设定还在酝酿,先按名字做;定了再换) |
gas |
卡通条纹气态行星 + 风暴眼 | 条纹 A / 条纹 B / 深色带 / 风暴 | 散落的无名星球、卫星 |
rock |
卡通陨坑岩石星 | 亮面 / 暗面 / 坑底 / 坑沿 | 散落的无名星球、卫星 |
ghost |
半透明全息线框球 | 线色 / 边缘色 / - / - | 空槽(未点亮) |
所有风格共用:三档卡通明暗(亮 / 中 / 暗)+ 冷色阴影(shadow)+ 很弱的轮廓光(rim)+ 墨线描边(outline,写 null 不描边)。
大气辉光(atm)和光环(ring)都是可选的,默认关 —— 用户反馈过「罩子」「环」很突兀、辉光太曝。
加一种新风格
在 STYLES 里加一项:
myStyle: {
defaults: { colors: ['#…','#…','#…','#…'], shadow: '#…', rim: '#…', outline: '#…', glow: 0 },
frag: `void main(){ vec3 V = normalize(cameraPosition - vW); vec3 N = normalize(vN);
vec3 base = mix(uC0, uC1, smoothstep(-0.2, 0.3, fbm(vP*2.0 + uSeed))); // vP = 球面上的点(单位向量)
gl_FragColor = vec4(shade(base, N, V), uAlpha); }`,
},
着色器里能用:snoise(vec3) 噪声、fbm(vec3) 分形噪声、aline(x, 线宽) 抗锯齿细线、shade(颜色, N, V) 统一上卡通光、
uC0~uC3 四个颜色、uT 时间、uSeed 种子、uGlow 自发光强度。然后在 LOOKS 里 style: 'myStyle' 就能用。
4. 交互
开场 / 飞行动画(运镜库在 galaxy.js 的 MOVES 里)
全部按时间走(和帧率无关),慢设备上也是同一条连贯的路线。
| 运镜 | 名字 | 怎么动 | 现在给谁 |
|---|---|---|---|
| 推进 | push |
先转过去对准(前 40%),再笔直推进去,不绕圈 | 火柴人宇宙 |
| 放大 | zoom |
先用长焦把它拉近(视角收窄到 14°),再一边推进一边把视角放回来 | 零号宇宙 |
| 升空俯冲 | rise |
先拉高到几乎俯视,再从上面扎下去 | 极寒世界 |
| 跃迁 | warp |
慢起步、中段猛冲、末段刹住;冲的时候视角张开、镜头轻轻一滚 | 没落赛博城 |
| 绕行 | orbit |
边飞边绕过去,中途抬高拉远一点 | 善恶等级;以及「上一个 / 下一个」在星系之间切换时 |
| 拉远 | pull |
回星系图:先往后退,再抬头看全景 | 「回到星系图」 |
| 开场 · 盘旋落下 | introSweep |
从高空、更远处绕半圈落到正常视角 | 开场(GALAXY.intro) |
| 开场 · 垂直坠入 | introDive |
从正上方很远处直着落下来,最后才抬起镜头 | 开场(GALAXY.intro,默认随机二选一) |
-
每条世界线用哪个入场运镜:
config.js→LOOKS[编号].enter;不写就按 push / zoom / rise / warp / orbit 轮流。 -
档案卡和镜头同步:点下去时旧档案先收起,镜头飞到 78% 的时候档案卡才滑出来(内容也那时才换),和星球落定同时到。 嵌在页面里时
onFocus(u, 'start')在起飞时回调(列表马上高亮),onFocus(u, 'arrive')在快到时回调(这时再出正文)。 -
飞的途中用户拖动 / 缩放:运镜立刻停在原地交还控制权,没出来的档案卡马上补出来,不会丢。
-
加一种新运镜:往
MOVES里加一项{ dur: 毫秒, path(from, to, k) { … 往 view 里写 az/el/dist/tx/ty/tz/fov/roll … } },再在enter里写它的名字。 -
开场在画面第一次进入视口时开始;星系从暗处亮起来(约 2.4 秒),镜头落定后名牌才浮现。「载入中」在第一帧画出来时才淡出。
-
总览时星系会放大一点(桌面 1.35 倍、手机 1.9 倍)好认,飞近时恢复真实大小。
-
桌面:拖动转视角、滚轮缩放、点星球或名牌飞过去、
←/→切上一个 / 下一个、Esc回到星系图。 -
手机:单指拖动、双指缩放、点名牌或星球飞过去;飞过去后星球在上半屏、档案卡是底部抽屉,「回到星系图」在卡里。
-
系统设置了「减少动态效果」:星系不自转、镜头直接切过去、星云不流动。
-
名牌是真正的
<button>,键盘 Tab 能选中。
5. 手机端处理过的冲突(这次修的)
| 问题 | 怎么修的 |
|---|---|
| HUD 的说明文字和星系名牌叠在一起 | 手机只留标题 + 一行读数;落在 HUD 范围里的名牌自动藏起来 |
| 名牌贴边被切掉 | 名牌位置夹在屏幕内(左右各留 6px) |
| 档案卡挡住星球 | 选中后镜头把星球挪到上半屏,档案卡做成底部抽屉(最高 44% 屏高,内容多了卡里自己滚) |
| 左下「回到星系图」被抽屉盖住 | 手机上隐藏它,按钮放进档案卡(整行宽,好点) |
| 空槽名牌太多太挤 | 手机只显示已点亮的名牌,空槽只留星球本身 |
| 不能缩放 | 加了双指缩放 |
| 近处的星点糊成大光斑 | 星点像素大小设了上限 |
| 手机画面比桌面稀、星系只是小点 | 手机和桌面用几乎一样的数量,星点大小按距离补偿,总览时星系放大 1.9 倍 |
| 名牌前的小方块色点 | 去掉了(全站规矩:文字前不放色点) |
| 散落的无名星球乱、互相重叠、卫星有的反着转 | 减到 14 颗;摆放时和核心、各星系(含卫星轨道)、彼此之间都留距离;卫星一律同向转 |
验证:无头浏览器 390×844 / 1440×900 各截一轮,五颗星球逐个飞进去截图,控制台 0 报错、无横向滚动、所有名牌都在屏幕内且不压 HUD。
6. 在门户里是怎么接的
<head>里:assets/universe/universe.css+ 一段importmap(把three指到assets/vendor/three.module.min.js)。- 主脚本之前:
<script src="assets/universe/config.js">—— 主脚本一解析就要读window.JZ_UNIVERSE(首页总览的计数、#0001深链都用它)。 - 页面底部一段
<script type="module">:- 按
config.js渲染窗下的世界线卡片和空槽; - 对外挂
window.__jzUniverse = { show(), fly(编号) }; - 第一次
show()时才import('./assets/universe/galaxy.js'),three.js 跟着下载(约 690KB,gzip 后约 170KB)。首页、画展等别的板块不下载它。
- 按
- 主脚本:
showBoard('universe')调__jzUniverse.show();#0001这种旧深链调__jzUniverse.fly('0001');飞到哪条,地址栏就replaceState成#编号,可以直接分享。
mountGalaxy() 的可选参数(门户都用上了):
| 参数 | 干什么 | 门户怎么用 |
|---|---|---|
onFocus(u, phase) |
选中 / 取消选中时回调(u 是档案或 null;phase 是 start 起飞 / arrive 快到) |
窗下卡片跟着高亮;地址栏跟着改 |
layout() |
返回 {x, y}:选中时星球往左 / 往上挪多少 |
桌面 {x:0.17}(右边是窗内档案卡);手机 {y:0.26}(档案卡是窗里的底部抽屉) |
wheelZoom() |
返回 false 时普通滚轮留给页面滚动,按住 Ctrl 才缩放 |
不全屏时 false,全屏时 true |
onReady() |
第一帧画好 | 淡出「星图载入中」 |
返回值 api.fly(no) / api.home() / api.resize() |
从外面控制 | 点卡片 → 先把窗户滚到眼前再 fly;切全屏 / 切回板块后 resize |
另外:画面滚出视口时自动暂停渲染(省电);手机上星图里的手势全归星图(touch-action:none:单指转、双指缩放,页面不会跟着滑),窗户只占屏幕约 64%,上下留了滑页面的地方,窗下有一句提示。
星图起不来(没有 WebGL)时,窗里显示原因,下面的世界线卡片照常能看。
7. 改了什么(相对原门户)
删掉:启动仪式(逐字 / 权限扫描 / 欢迎)、宇宙首屏的晶体线框画布(CrystalView)、盘符机架(抽插 / 读盘舱 / 键盘翻页)、两枚只给插卡用的图标(--icd-logo 白标、--icd-people 火柴人)。
保留:首页右侧的晶钻徽记、#0001 / #rack 旧链接(分别飞到那条世界线 / 打开宇宙板块)。
8. 性能
- 桌面:4.2 万星点 + 32 片星云 + 14 颗散落星球 + 11 个星系(含卫星)。手机:3.6 万星点 + 28 片星云 + 14 颗(为了和桌面画面一致,只少一点点)。
- ⚠️ 帧率还没在真机上测过(只在无头浏览器的软件渲染里验证了画面和交互),上线前请用一台普通手机和一台集显笔记本各打开看一下。
- 手机像素比上限 1.5;星点大小按镜头距离补偿,手机和桌面看起来一样密。
- 每颗星球一个绘制调用(加描边、大气各一个),没有实时阴影、没有后处理。
- 卡的话按第 2 节降粒子数;再不行把
planets.js里球体的SphereGeometry(r, 96, 64)降到(r, 48, 32)。
9. 版权
- three.js:MIT(
vendor/three-LICENSE.txt)。 - 噪声函数:Ashima Arts / Stefan Gustavson 的 3D simplex noise(MIT),写在
planets.js里。 - 星球、星云、星点:全部程序生成,无外部素材。
- 上一版用过的 NASA 星球贴图已经全部撤掉(不再需要署名)。
10. 部署注意(踩过的坑)
- 静态文件可能被缓存。改了 JS / CSS 一定要换版本号,四处一起换:
portal/index.html里的universe.css?v=、config.js?v=、底部模块脚本里的galaxy.js?v=,以及galaxy.js里的import './planets.js?v='。 2026-10-05 踩过:一个坏掉的 galaxy.js 被缓存住,修好之后打开还是「加载不出来」。 - 检查语法要按 ES 模块检查(把文件拷成
.mjs再node --check),按普通脚本检查会漏掉「重复声明」这类错误。