Actor-reachable contextual interactions for native Three.js.
Register an object, aim at it, and press or hold. Latch finds the reachable root, explains why an action is blocked, tracks deliberate input, and returns events for your game to apply. It has no renderer, DOM, inventory, animation, or Cranberry Forge package dependency.
The accompanying Meridian Observatory is an original procedural island: collect an aether fuse, hold a clockwork crank, and ignite the dawn beacon. Open /latch.html in the Cranberry Forge showcase. Desktop supports pointer aiming, E, WASD, and orbit dragging. Station buttons walk and aim automatically; the large gold key supports touch press and hold. Raise the shutter to inspect occlusion.
Why this category
Three's official InteractiveGroup groups objects and dispatches pointer, mouse, and XR selections to descendants. THREE.Interactive provides a broader pointer/mouse/touch interaction manager and event dispatch for Three objects. These establish the familiar object interaction category. Latch concentrates on a gameplay-sized part of that category: actor reach, explicit occlusion, condition reasons, and cancellable press/hold actions returned as data.
The underlying geometric behavior follows Three's Raycaster documentation: recursive intersections are distance-sorted and delegated to each object's raycast method. Those material, face, and object-specific rules remain visible in this toolkit. The implementation is original; the references are category and API research, not incorporated source code.
Verification and showcase assets
From the Cranberry Forge source checkout, run:
node --test tests/latch.test.mjsTests cover actor reach independent of camera distance, parent transforms, nested roots, aim and actor occlusion, stable focus, repeated press gating, hold timing, release/focus/suspension/removal cancellation, completion availability, and host event processing.
dist/latch-scene.js exports createLatchScene(), a renderer-free factory using original procedural Three geometry. It returns the group, suggested camera vectors, registered target roots, aim points, walk stations, actor, occluders, an update function, and dispose. It is a showcase asset rather than a package runtime dependency. The scene can be constructed in Node and rendered with Three's official SVGRenderer for documentation previews; SVG rendering differs from the live WebGL lighting and bloom.
MIT © 2026 CranberryClock. See LICENSE.