Troika JS

Troika is a collection of JavaScript tools for creating interactive graphics in the browser, optimized for data visualization. It is divided into two main categories:

1. The Troika Framework: A fully featured system for managing entire scenes using a declarative model. It features a component architecture, CSS-like animations, and DOM-like interaction handling.
2. Troika Three.js Tools: A set of standalone utilities that do not depend on the main framework and can be used in pure Three.js projects or other frameworks like AFrame or react-three-fiber.

Key capabilities include 3D/WebGL graphics, 2D Canvas graphics, high-performance text rendering, and GPU instancing.

The troika-xr package extends troika-3d scenes with WebXR capabilities. It provides the necessary infrastructure to transition a standard 3D scene into an immersive XR experience. Key features include:

• WebXR Session Management: UI components for launching WebXR sessions.
• Stereoscopic Rendering: Support for rendering stereoscopic camera views.
• Head Tracking: 6DoF (Six Degrees of Freedom) head tracking.
• Controller Support: Controller tracking with pointer raycasting that integrates directly into the main event system.
• XR Helpers: Basic helper facades for common XR tasks like teleportation and menus.

The troika-3d-ui package enables the creation of user interfaces within 3D scenes using a layout system that behaves similarly to CSS Flexbox. Because it renders in WebGL, these interfaces can utilize Three.js materials and include fully 3D objects within the layout. It is also compatible with WebXR.

Key features include:

• Flexbox Layout: Uses a layout engine inspired by CSS Flexbox.
• High-Quality Text: Leverages the troika-3d-text engine, allowing elements to auto-size based on text content and providing high-quality antialiased text rendering.

A scene descriptor is a plain JavaScript object that describes the structure of your scene at a specific point in time. Instead of manually creating, updating, or destroying individual objects, you provide new descriptors as your application state changes. Troika compares the new descriptor to the previous one and automatically manages the lifecycle (creation, destruction, and updates) of Facade instances to match the new state.

This declarative approach is highly inspired by React, where descriptors behave like JSX and Facades behave like Components.

{
  facade: BallFacade,
  x: 1,
  y: 5,
  z: -10,
  color: 0x3333cc
}

Troika 3D is designed for creating interactive 3D scenes using WebGL. It leverages Three.js for WebGL state management, scene graphs, 3D primitives, math utilities, and shaders.

Key Responsibilities:

• Troika: Manages the Three.js renderer, world matrix calculations, and raycasting for pointer events.
• Developer: You are responsible for setting up Three.js meshes, geometries, and materials, and updating them within your Object3DFacade implementations.

Advanced 3D Capabilities:

• Position-synced HTML overlays.
• GPU instancing abstraction.
• Flexbox-based user interfaces.
• WebXR support.

Troika provides a separate package for defining graphics using the 2D Canvas API. It utilizes the same scene/facade patterns and core conveniences (animations, pointer events) found in the 3D framework.

This is useful for:

• Projects that do not require 3D.
• Providing a graceful fallback for browsers where WebGL is unavailable.

The easing parameter in a Tween controls the rate of change over time. You can use:

1. Built-in named easings: Strings referring to standard easing functions (similar to jQuery Easing or easings.net).
2. Custom easing functions: A function that accepts a single parameter t (the fraction of time passed, from 0 to 1) and returns a number representing the progress.

In standard Three.js, the engine performs brute-force matrix updates for every object in the scene graph every frame. Troika optimizes this by:

1. Setting scene.autoUpdate = false and threeObject.matrixAutoUpdate = false for all managed objects.
2. Recalculating the local matrix only when transform properties (x, y, z, rotateX|Y|Z, or scaleX|Y|Z) change.
3. Recalculating the worldMatrix only when the local matrix or the parent's worldMatrix changes.

This reduces the per-frame matrix update cost to nearly zero for static scenes, even in very large environments.

When an XR session is active, hand controllers are automatically added to the scene. Controllers that provide a target ray will automatically raycast objects, mapping hits to standard pointer events:

• Pointer Events: mouseover, mousemove, and drag are mapped from the controller ray.
• Button Events: Controller buttons map to mousedown, mouseup, and click.
• Thumbstick Events: Thumbsticks map to wheel events.

Event Properties: Because these events occur in 3D space rather than on a 2D screen, they do not contain clientX or clientY. Instead, they include:

• ray: A THREE.Ray representing the ray that triggered the hit.
• eventSource: A reference to the XRInputSource facade that triggered the event (useful for distinguishing between left and right hand inputs).