Files
jinzuanwork/portal/assets/universe/交接说明.md
T
ywsandClaude Opus 5.5 09b229deee portal: 金钻宇宙换成星系图(three.js 懒加载)+ 推送前审查 + 总交接文档
- 门户「金钻宇宙」:删掉启动仪式 / 宇宙首屏晶体 / 盘符机架 / 读盘舱及其 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>
2026-10-05 17:31:36 +00:00

189 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 交接说明 · 金钻宇宙星系图(`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. 常见改动
### 加一条新世界线
1. `config.js` → `UNIVERSES` 里把对应的空槽(比如 `{ no: '0005', empty: true }`)换成完整档案:
```js
{ no: '0005', name: '名字', kind: '原创', tag: '一句话副标题', tags: ['标签1', '标签2'], desc: '档案正文' },
```
字段和门户页原来的 `UNIVERSES` 一模一样(`no / name / kind / tag / tags / desc`),可以直接拷。
2. `config.js` → `LOOKS` 里按编号加外观:
```js
'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: [离中心距离, 第几条旋臂]`:距离 0~60,旋臂 0~3。别和别的星系放太近(差 8 以上比较好看)。
- 不写 `LOOKS` 的世界线会自动用 `EMPTY_LOOK`(全息线框的「未点亮」样子),放在外圈。
3. 刷新页面即可。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` 里加一项:
```js
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`),按普通脚本检查会漏掉「重复声明」这类错误。