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

Programmatic input and panel focus

The adapter can drive input without a raycaster or DOM — the entry point for tests and automation:

• dispatchPointer(type, x, y, init?) synthesizes pointer events at logical scene coordinates through the same downstream path as updateIntersection (hover transitions, entity dispatch, pointerdown-driven focus, texture-dirty scheduling). Returns whether the point hit an entity. Wheel is deliberately not covered — route real WheelEvents through updateIntersection.
• dispatchKey(key, mods?, phase?) synthesizes keyboard events (phase 'press' is the default full keydown+keyup pair; 'keydown'/ 'keyup' model held keys). With panel focus, the event hits the focused entity's projected mirror so core's own listeners run (Enter/Space activation included); otherwise — or after an unprevented pass-through — it reaches window, where the scene-level channel applies its ownership gates (defaultPrevented, auto-repeat, ownsKeyboard). A focused textbox-like role owns its keys exclusively; nothing leaks to the page.
• Panel focus mirrors DOM tabbability: focus(entity) / blur() / focusedEntity / isFocusable(entity) (projected tabindex, natively-focusable tags, interactive roles). A pointerdown focuses the nearest focusable ancestor of the hit; clicking empty background blurs. Focus flips are delivered as synthetic focus/blur events so caret and highlight visuals repaint immediately in onDemand mode.

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.