Communitygithub.com

移动优先3D

为移动端(手机/平板)提供专用3D/WebGL网站体验——设备profile检测、轻量渲染与纹理集、竖屏取景框避免目标物(带环行星、星系)被裁剪、底部表单、菜单表单、安全区域、触摸行为及更短滚动。构建3D网站或遇到“在手机上被切掉/不完美/慢/丑”问题时始终使用。

移动优先3D 是什么?

此技能专为构建移动优先的3D/WebGL网站而设计,解决传统桌面3D体验在手机和平板上的常见问题:元素被裁剪、性能低下、交互不适配。它通过自动检测设备类型(基于指针精度和屏幕尺寸)并启用单独的渲染profile,在保持视觉质量的同时大幅降低计算负担(如降低DPR上限、纹理分辨率、体积采样数)。其核心是竖屏取景系统,通过数学公式计算每个目标物的安全距离,并整体下移视图确保目标物位于画面上三分之一区域,避免被文字面板遮挡。此外,它还提供完整的移动端布局方案,包含底部表单(bottom sheet)、汉堡菜单、安全区域适配、更短的滚动距离以及触摸专属交互行为。技能要求开发者对每个关键内容beat在真实设备尺寸(如375×812、412×915)下进行数值验证(通过readPixels检查发光区域是否落在宽度5%-95%区间),并明确告知用户是否未经真实设备测试。支持的平台包括所有现代浏览器,特别针对WebGL和Three.js等3D框架优化。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/forpc1428-eng/cosmic-forge/tree/HEAD/skills/mobile-first-3d

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

移动优先3D 是做什么的?

手机不是缩小版的桌面。构建一个独立的profile,通过一个类名 html.mobile 切换。

1. 检测

const MOBILE = qs.get('m') === '1' || (qs.get('m') !== '0' &&
  (matchMedia('(pointer: coarse)').matches || Math.min(innerWidth, innerHeight) < 600));
document.documentElement.classList.toggle('mobile', MOBILE);

使用 ?m=1 / ?m=0 强制启用/禁用——在桌面仿真环境中测试时必不可少。

2. 渲染profile

设置桌面手机
DPR上限 / 最大像素1.5 / 3.2 MP1.25 / 1.0 MP
测地线步数220150
体积采样数3624
天空盒烘烤尺寸768 / 512384 / 256
纹理集textures/hd (~6 MB)textures/m (~1.2 MB)
鼠标视差/环视开启关闭 (仅触控;仿真器会发送鼠标事件)

3. 竖屏取景 (大多数“被裁剪”问题的根源)

  • 竖屏下的水平视场角很小:tan(hFOV/2) = tan(vFOV/2)·aspect (在52°和0.46宽高比时约为0.22)。
  • 每个目标物的距离 = max(R·distMul·1.25, visibleRadius·7.6);visibleRadius包含环 (土星≈2.35 R,天王星≈1.8 R)。
  • 瞄准目标物,然后将整个视图向下倾斜约0.21弧度,使其位于画面上三分之一区域,位于文字面板上方。(偏移目标会导致相机移动时横向漂移。)
  • 采用更正面的光照(约45°相位):侧光照亮的半黑行星在小屏幕上看起来像是“被裁剪”。
  • 在内容停留期间锁定瞄准(零目标切线)——避免偏离中心。
  • 数值验证:渲染一帧,readPixels 行穿越目标物区域,检查发光区域是否在宽度5%–95%之内。

4. 布局

  • 面板 → 底部表单:left:0; right:0; bottom:0; max-height:60vh; overflow:auto,渐变背景,padding-bottom: calc(54px + env(safe-area-inset-bottom))。
  • 标题 clamp(34px, 10vw, 52px);英雄名称分两行显示。
  • 导航 → 汉堡菜单 + 全屏模糊面板,提供44px衬线文字链接。
  • 隐藏装饰性导轨;缩短标签(仅显示名称);如果与滚动提示冲突,则隐藏落地滚动提示。
  • 更短的滚动:介绍部分约320vh,旅程部分约2600vh(手机惯性滚动更快)。
  • viewport-fit=cover,100svh 粘性阶段,320px宽度下无水平溢出。

5. 测试矩阵(仿真不够,但这是最低要求)

375×812 和 390×844 竖屏、412×915 Android、768×1024 平板。每个内容beat:目标物完全可见且居中位于面板上方,文字可读,没有任何内容被刘海屏或home bar遮挡。诚实告知用户是否已完成真实设备测试。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相关技能