Vectojs three

VectoJS Three

Use this skill to place a live VectoJS 2D interface onto a Three.js texture and route 3D pointer input back into the VectoJS scene.

Integration workflow

1. Install @vectojs/core, @vectojs/three, three, and @vectojs/ui if using UI components.
2. Create one ThreeAdapter per VectoJS panel texture.
3. Add VectoJS entities to adapter.vectoScene, then start the inner scene.
4. Add adapter.mesh or the adapter texture/material to the host Three.js scene.
5. In the host pointer/wheel loop, raycast against the adapter mesh and call adapter.updateIntersection(...).
6. Call adapter.dispose() when removing the panel.

Read references/three-recipes.md for snippets.

Constraints

• The default output is a flat textured plane, not DOM rendered in 3D.
• VectoJS logical hit-testing remains 2D even when the mesh is transformed in world space.
• The host application owns the camera, renderer, controls, XR session, raycaster, and occlusion rules.
• Raycast UVs should map to the adapter’s logical width/height; do not use backing-store size for layout math.
• Texture resolution affects sharpness and upload cost. Choose dimensions for the viewing distance.

Common mistakes

Mistake	Correction
Adding an offscreen adapter canvas to the DOM	Add adapter.mesh to Three.js; the canvas backs the texture.
Forgetting to call updateIntersection	Route host raycaster events into the adapter each pointer/wheel event.
Dispatching by screen coordinates	Use raycast UVs through ThreeAdapter.
Keeping disposed textures alive	Call adapter.dispose() and remove host references.
Expecting full DOM a11y inside XR	Treat the 3D panel as canvas texture; provide host-level semantics where needed.

Version and backend gotchas (source-verified)

• three ≤ 0.1.3: ThreeRenderer.flush() performed a full GL render, and the Scene flushes around every non-batched node — frame cost grew O(N²) in entity count. three 0.1.4 renders once per frame via the present() hook; upgrade before profiling anything else.
• Native input inside a texture is limited. The adapter's canvas is offscreen, so the Scene's projected a11y elements are never connected to the document; updateIntersection falls back to VectoJS's own event dispatch. Buttons/hover/wheel work; full native IME/text editing does not — keep text entry outside the 3D panel or accept simplified input.
• stroke() line width is effectively 1px on most platforms (LineBasicMaterial.linewidth is a known WebGL limitation). Draw thick lines as filled shapes instead.
• Texture caches (three 0.1.7+): both fillText and drawImage textures are cached with a 256-entry LRU (text keyed by font|color|text). Before 0.1.7 drawImage allocated a texture per call per frame, so reusing a source canvas mattered more; it is still good practice for very large images.
• GPU context loss + runtime DPR (three 0.1.7+): ThreeRenderer recovers on its own. webglcontextlost is preventDefault()-ed (required, or the browser never fires the restore event) and flips isContextLost(), which makes present() a no-op while lost; webglcontextrestored re-applies pixel ratio and size (a restore can land on a different display) and forces a repaint. A (resolution: Ndppx) media query re-applies setPixelRatio when DPR changes at runtime (monitor move, browser zoom) and re-arms itself. All of it is guarded for SSR/OffscreenCanvas and torn down in dispose(). Do not add your own context-loss listener — you would fight the built-in recovery.