Files
jinzuanwork/portal/assets/universe/交接说明.md
T
ywsandClaude Opus 5.5 fd72f7192e 全站按设计预览站重做(门户改多页 + 下单页对齐)、新加载动画、金钻宇宙开场星门;站点信息集中到 site-info.js
- 门户:单页改成 index / gallery / tools / universe / links / about 六页,标记 / 样式 / 交互照预览站;内容照旧读 content/site.js
- 画展:预览站作品墙 + 原有全部功能(筛选、排序、看过的、高清、本站视频、B 站、全景、动态壁纸、观展统计、外链);按最矮列投放保证时间顺序
- 加载动画 boot.js:像素钻石垒成形 → 白光 → 店名逐字 → 进度条 → 幕布上收(每个标签页只放一次,减少动效时不放)
- 金钻宇宙开场 gate.js:星门(钻石 + 光谱环 + 世界线格子逐个点亮),星系画好后炸开接镜头俯冲
- 下单页:全站顶栏 / 底栏 / 页脚、宽版面、落地「怎么下单?」两张路卡 + 下过单了 + 模板样图;下单逻辑和按钮 id 不动
- 站点固定信息(域名 / 群号 / 备案号 / 邮箱)只在 assets/site-info.js,仓库是占位,正式服务器只换这一个文件
- 像素字体换成常用 3755 字 + 全部内容的子集(门户和下单页共用);旧链接 /#/板块、/#0001 自动跳新页
- 交接文档 / 星系图说明 / nginx 片段同步更新

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 06:15:44 +00:00

217 lines
17 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);2026-10-06 起门户是多页,星系图在 `portal/universe.html`(样子按设计预览站),开场是 `gate.js` 的「星门」(星系第一帧画好才打开,接上下面的镜头俯冲)。
> 风格参考:《绝地潜兵 2》银河战争地图 —— 旋臂星系 + 星云 + 扇区 + 补给线;每条世界线是一个星系,点进去是一颗卡通星球 + 档案卡。
---
## 1. 文件
| 文件 | 干什么 | 日常要不要改 |
|---|---|---|
| `assets/universe/config.js` | **全部内容和外观配置**:世界线档案、每颗星球的风格 / 颜色 / 卫星、星系配色、扇区名、粒子数量。门户主脚本的 `UNIVERSES` 也从这里读 | **改这个** |
| `assets/universe/planets.js` | 卡通星球材质库(每种「风格」= 一段着色器 + 默认参数) | 加新风格时改 |
| `assets/universe/galaxy.js` | 引擎:画星系、星云、补给线、名牌,处理拖动 / 缩放 / 点击 / 档案卡 / 运镜 | 一般不用动 |
| `assets/universe/universe.css` | 观星窗、档案卡、窗下世界线卡片、手机布局的样式 | 改版式时改 |
| `portal/universe.html`(`#skywin` + 底部那段 `<script type="module">`)+ `universe-page.css` + `gate.js` | 页面骨架(窗户 / 名牌层 / HUD / 档案卡 / 卡片列表)、接线代码、开场星门 | 改交互时改 |
| `assets/vendor/three.module.min.js` | three.js r170(MIT,自托管,不连外网) | 不动 |
**没有任何贴图、模型文件**:星球、星云、星点全是着色器实时生成的,所以没有版权问题,也不用担心图片加载慢。
---
## 2. 常见改动
### 加一条新世界线
> **2026-10-05 起推荐用内容后台**(门户顶栏最右边的铅笔 →「金钻宇宙」→「点亮一条」):填档案、下拉选外观,预览、发布就上线。
> 后台发布的内容写在 `portal/content/site.js`(`window.JZ_CONTENT.universe`),`config.js` 末尾会用它**覆盖**下面写死的
> `UNIVERSES` / `LOOKS`;`config.js` 里那两份只是兜底(内容文件读不到时用)。`GALAXY`、`EMPTY_LOOK` 不归后台管,还是改这个文件。
>
> 不用后台、直接改文件的话(比如本地调试):
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。**可以不写** —— 不写就交给 `layout.js` 自动排位(见下)。
- 不写 `LOOKS` 的世界线会自动用 `EMPTY_LOOK`(全息线框的「未点亮」样子),放在外圈。
### 位置和补给线是怎么排的(`layout.js`,纯计算,可单独测试)
1. **写了 `orbit` 的**(现在的 0000–0004):就放在那儿,补给线从核心连过去。
2. **空槽**:按**编号**放在外圈固定槽位(从 `GALAXY.firstSlot` 号起,轮流分到各条旋臂)。只看自己的编号,点亮一个,别的空槽不挪。
空槽的淡虚线接到离它最近、又不穿过别的星的那颗已点亮的星(没有就接核心)。
3. **已点亮但没写 `orbit` 的**(后台新点亮的):自动在中圈的旋臂上挑位置 —— 跟核心、已有星系(连同卫星轨道)留足距离,
各条旋臂尽量均匀;补给线接到「比它更靠近核心、离它最近」的那颗星,而且不能从别的星中间穿过。
按编号从小到大一颗颗排,每颗只看排在前面的,所以**新加一条,已有的星和线都不动**。
实测:连续点亮 10 条,已有的一次都没动,两两不挤,线不穿星。
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`,中文名在 `STYLE_LABELS`)
内容后台「金钻宇宙」页的「星球风格」下拉、「外观预设」一览都来自这里(一览里是真实渲染)。2026-10-05 加了带「新」的 10 种。
| 风格 | 长什么样 | 现在给谁用 |
|---|---|---|
| `earth` 新 · 类地(卡通地球) | 蓝海 + 绿色大陆 + 沙漠块 + 极冠 + 慢慢飘的白云,海岸一圈墨线 | 后台新点亮的默认 |
| `ocean` 新 · 海洋 | 几乎全是水,深浅两色 + 零星小岛 + 岛边浪线 + 条状云 | — |
| `jungle` 新 · 丛林 | 深浅两层绿 + 一团团树冠 + 弯弯的河 + 雾 | — |
| `desert` 新 · 荒漠 | 弯曲沙丘条纹 + 红色台地(墨线轮廓)+ 一点极冠 | — |
| `tundra` 新 · 冻原 | 霜白和青灰 + 深色针叶林 + 结冰的湖 | — |
| `ice` · 冰封 | 纬向冰带、极冠、冰裂纹、冰面高光 | 极寒世界 |
| `lava` 新 · 熔岩 | 深色岩壳 + 发光裂缝和岩浆池(慢慢呼吸) | — |
| `toxic` 新 · 毒雾 | 酸绿 / 黄绿扭曲气流 + 一点紫 + 冒泡亮点 | — |
| `barren` 新 · 荒芜岩球 | 灰色岩面 + 大小两层陨坑(坑沿墨线、坑底更暗) | — |
| `gas` · 气态巨星 | 卡通条纹 + 风暴眼 | 散落的无名星球、卫星 |
| `icegiant` 新 · 冰巨星 | 蓝色细条纹 + 深色风暴眼 + 白色流云 | — |
| `ringed` 新 · 带环巨星 | 气态巨星 + 一圈压低颜色的卡通扁环(**只有这个预设自带光环**) | — |
| `crystal` · 晶体 | 多面体切面、每面颜色随朝向变、内部发光脉络 | 零号宇宙 |
| `paper` · 铅笔纸面 | 米白纸面、铅笔等高线、暗面排线、红笔圈 | 火柴人宇宙 |
| `neon` · 霓虹城 | 深紫地表、霓虹街区网格、闪烁窗灯 | 没落赛博城 |
| `duality` · 善恶两半 | 一半白昼一半夜空,交界发光波浪线 | 善恶等级 |
| `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/universe.html` 里的 `universe-page.css?v=`、`gate.js?v=`、`config.js?v=`、底部模块脚本里的 `galaxy.js?v=`,以及 `galaxy.js` 里的 `import './planets.js?v='` / `'./layout.js?v='`。
2026-10-05 踩过:一个坏掉的 galaxy.js 被缓存住,修好之后打开还是「加载不出来」。
- 检查语法要按 ES 模块检查(把文件拷成 `.mjs` 再 `node --check`),按普通脚本检查会漏掉「重复声明」这类错误。