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

17 KiB
Raw Blame History

交接说明 · 金钻宇宙星系图(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 })换成完整档案:
    { no: '0005', name: '名字', kind: '原创', tag: '一句话副标题', tags: ['标签1', '标签2'], desc: '档案正文' },
    
    字段和门户页原来的 UNIVERSES 一模一样(no / name / kind / tag / tags / desc),可以直接拷。
  2. 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。可以不写 —— 不写就交给 layout.js 自动排位(见下)。
    • 不写 LOOKS 的世界线会自动用 EMPTY_LOOK(全息线框的「未点亮」样子),放在外圈。

位置和补给线是怎么排的(layout.js,纯计算,可单独测试)

  1. 写了 orbit 的(现在的 0000–0004):就放在那儿,补给线从核心连过去。
  2. 空槽:按编号放在外圈固定槽位(从 GALAXY.firstSlot 号起,轮流分到各条旋臂)。只看自己的编号,点亮一个,别的空槽不挪。 空槽的淡虚线接到离它最近、又不穿过别的星的那颗已点亮的星(没有就接核心)。
  3. 已点亮但没写 orbit 的(后台新点亮的):自动在中圈的旋臂上挑位置 —— 跟核心、已有星系(连同卫星轨道)留足距离, 各条旋臂尽量均匀;补给线接到「比它更靠近核心、离它最近」的那颗星,而且不能从别的星中间穿过。 按编号从小到大一颗颗排,每颗只看排在前面的,所以新加一条,已有的星和线都不动。 实测:连续点亮 10 条,已有的一次都没动,两两不挤,线不穿星。
  4. 刷新页面即可。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 里加一项:

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),按普通脚本检查会漏掉「重复声明」这类错误。