Communitygithub.com

VectoJS Three

此技巧用於將即時 VectoJS 2D 介面放置到 Three.js 紋理上,並將 3D 指標輸入路由回 VectoJS 場景。

VectoJS Three 是什麼?

VectoJS Three 技巧使開發者能將 VectoJS 2D 介面無縫嵌入 Three.js 3D 場景中,作為紋理貼圖。它使用 ThreeAdapter 管理 VectoJS 面板紋理,並在宿主應用程式的指標/滾輪事件循環中,透過光線投射 UV 座標將 3D 指標輸入反向饋送至 VectoJS 場景,實現邏輯上的 2D 互動。此技巧支援 Cursor、Claude Code、Codex 及 GitHub Copilot 等平台,並在 SKILL.md 文件中提供逐步整合工作流程、常見錯誤修正表格及版本注意事項(如 three ≤ 0.1.3 的渲染效能問題)。開發者需注意,此方法預設輸出為平坦紋理平面,而非 DOM 渲染的 3D 元素;完整的 DOM 無障礙功能在 XR 環境中受限,文字輸入建議在 3D 面板外部處理。

相容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add vectojs/vectojs-skills

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

VectoJS Three 是做什麼的?

使用此技巧將即時的 VectoJS 2D 介面放置到 Three.js 紋理上,並將 3D 指標輸入路由回 VectoJS 場景。

整合工作流程

  1. 安裝 @vectojs/core、@vectojs/three、three 及 @vectojs/ui(如使用 UI 元件)。
  2. 為每個 VectoJS 面板紋理建立一個 ThreeAdapter。
  3. 將 VectoJS 實體新增至 adapter.vectoScene,然後啟動內部場景。
  4. 將 adapter.mesh 或適配器的紋理/材質新增至主 Three.js 場景。
  5. 在主機的指標/滾輪循環中,對適配器網格進行光線投射,並呼叫 adapter.updateIntersection(...)。
  6. 移除面板時,呼叫 adapter.dispose()。

請參閱 references/three-recipes.md 以取得程式碼片段。

限制

  • 預設輸出為平坦紋理平面,而非 DOM 渲染的 3D 物件。
  • 即使網格在世界空間中進行變換,VectoJS 的邏輯碰撞檢測仍維持在 2D 空間。
  • 宿主應用程式擁有相機、渲染器、控制器、XR 工作階段、光線投射器以及遮擋規則。
  • 光線投射 UV 應對應至適配器的邏輯 width/height;請勿使用後備儲存大小進行版面計算。
  • 紋理解析度會影響清晰度和上傳成本。請根據觀看距離選擇適當的尺寸。

常見錯誤

錯誤修正
將離屏適配器畫布加入 DOM將 adapter.mesh 加入 Three.js;畫布作為紋理的後備儲存。
忘記呼叫 updateIntersection在每次指標/滾輪事件中,將宿主光線投射事件路由至適配器。
使用螢幕座標進行分派透過 ThreeAdapter 使用光線投射 UV 座標。
讓已釋放的紋理持續存活呼叫 adapter.dispose() 並移除宿主中的參考。
期望在 XR 環境中擁有完整的 DOM 無障礙功能將 3D 面板視為畫布紋理;如有需要,在宿主層級提供語意。

版本與後端注意事項(來源已驗證)

  • three ≤ 0.1.3:ThreeRenderer.flush() 會執行完整的 GL 渲染,且場景會對每個非批次處理的節點進行清除——因此每個畫面的成本會隨實體數量呈 O(N²) 增長。three 0.1.4 透過 present() 鉤子每個畫面僅渲染一次;在進行任何效能分析前請先升級。
  • 紋理內的原生輸入功能有限。 適配器的畫布為離屏,因此場景的投影無障礙元素永遠不會連接到文件;updateIntersection 會回退到 VectoJS 自身的事件分派。按鈕/懸停/滾輪可正常運作;完整的原生 IME/文字編輯則無法使用——請將文字輸入保留在 3D 面板外部,或接受簡化後的輸入。
  • stroke() 線條寬度在大多數平台上實際上為 1px(LineBasicMaterial.linewidth 是已知的 WebGL 限制)。建議改用填充形狀繪製粗線條。
  • ThreeRenderer.drawImage 每呼叫一次每個畫面就會分配一個紋理(在 clear() 時釋放);請盡可能重複使用來源畫布。fillText 從 three 0.1.4 開始會進行快取(以字型|顏色|文字為鍵的 LRU,共 256 個條目)——在 ≤ 0.1.3 版本中,它仍有每次呼叫的成本,因此建議使用 MSDFTextEntity。

相關技能