Communitygithub.com

mobile-first-3d

專為手機/平板設計的重度 3D/WebGL 網站體驗——裝置特性偵測、輕量渲染設定與紋理集、直向相機取景以確保主體(如帶環行星、星系)不被裁切、底部面板、選單面板、安全區域、觸控行為與更短的滾動長度。每當建置 3D 網站,或有人說「在手機上被切掉/看不清楚/很慢/很醜」時,請務必使用此技能。

mobile-first-3d 是什麼?

這個技能提供了一套完整的行動裝置優先 3D 開發模式,針對手機和平板上的 WebGL/Three.js 網站進行深度優化。它透過 `html.mobile` 單一 class 切換,自動偵測觸控裝置與小螢幕,並強制使用較低的 DPR、紋理解析度與幾何複雜度,以確保效能。核心亮點在於解決直向模式下的視角裁切問題——技能會自動計算主體距離、向下傾斜視角約 0.21 弧度讓主體位於畫面中上三分之一處,並調整燈光角度避免小螢幕上的「裁切」錯覺。此外,它還規範了底部面板佈局、大字型系統、全螢幕選單與安全區域處理,並附有具體的測試矩陣(375×812、390×844、412×915 等),確保在真實裝置上主體不裁切、文字可讀。支援 ?m=1 與 ?m=0 強制切換模式,便於桌面模擬測試。這項技能適用於所有需要行動端優化的 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 的新對話。

說明文件

Mobile-first 3D(行動裝置優先 3D)

手機不是小桌機。請建立獨立的設定檔,透過一個 class 切換: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. 渲染設定

項目桌機手機
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. 直向取景(大多數「被裁切」錯誤的來源)

  • 直向模式下的水平視野(hFOV)很小: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);主要名稱分成兩行。
  • 導航 → 漢堡選單 + 全螢幕模糊面板,搭配 44 px 襯線字體連結。
  • 隱藏裝飾性欄杆;縮短標籤(僅顯示名稱);如果與滾動提示衝突則隱藏登入滾動提示。
  • 更短的滾動:開場約 320vh,旅程約 2600vh(手機以動量方式滾動速度更快)。
  • viewport-fit=cover,100svh 黏性階段,在 320 px 寬度下無水平溢出。

5. 測試矩陣(模擬不夠,但這是最低標準)

375×812 和 390×844 直向、412×915 Android、768×1024 平板。每個內容節拍:主體完全可見且置於面板上方,文字可讀,沒有東西藏在瀏海/Home Bar 下方。當尚未在真實裝置上測試時,請誠實告知使用者。

Individual skills in this repo

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

相關技能