TRIKOMI 3D SDK Documentation

Plugin Reference

ViewerStore

viewerStore is a singleton MobX observable store exported from @trikomi/core. It acts as the reactive bridge between the 3D engine and React UI components. Wrap components with MobX's observer() to auto-render on store changes.

import { viewerStore } from '@trikomi/core';
import { observer } from 'mobx-react-lite';

// In React components:
const MyUI = observer(() => (
  <div>{viewerStore.activeModelName}</div>
));

// Update from anywhere – UI auto-updates:
viewerStore.setBackgroundColor('#1a1a2e');
viewerStore.setActiveModelName('My Model');

Key observable properties include activeModelName, backgroundColor, isModelLoading, modelError, floorTransparent, and environmentIntensity.

Demo Applications

Each app is an independent Vite + React workspace under apps/ that imports @trikomi/core as a dependency.

3D Viewer (apps/viewer)

A complete 3D model viewer with a full plugin suite. Demonstrates using nearly all available plugins together. Features a side panel MaterialEditor for PBR material editing, a ModelLoader for drag-and-drop GLTF uploads, and a DiamondTest page for showcasing the ray-tracing diamond shader.

Sportswear Configurator (apps/sportswear-configurator)

An interactive jersey configurator. Users can change panel colors, upload logos, add text, switch fabric normal maps (mesh / knit / smooth), and move graphics freely on the UV canvas. Uses a custom TextureCompositor to composite SVG layers onto a WebGL canvas texture in real time.

Key architecture

• TextureCompositor — composites SVG base + user logos + text into a single THREE.CanvasTexture.
• ConfiguratorStore — MobX store tracking parts, colors, logos, and text items.
• Fabric normal maps loaded from public/textures/; SVG base from public/textures/JSY-85 RL.svg.

Eyewear Try-on (apps/eyewear-tryon)

Augmented Reality eyewear try-on using FaceMocapPlugin and a live webcam feed. Tracks 478 facial landmarks via MediaPipe and positions/orients 3D glasses onto the face in real time. Allows material editing of lens and frame properties. Includes a natural lighting mode that samples the webcam background for environment-matched reflections.

Setup notes

• Requires HTTPS (webcam permission). In dev, uses @vitejs/plugin-basic-ssl for a self-signed cert.
• MediaPipe WASM is loaded from public/assets/wasm/. In prod the path resolves to ../assets/wasm/.
• The face occluder (head_occluder.obj) is rendered as a depth mask to hide the glasses behind the face boundary.

Face Motion Capture (apps/face-mocap)

Full-face motion capture streaming blend shapes to Unreal Engine or Unity via a WebSocket LiveLink protocol. Tracks 52 ARKit-compatible blend shapes. Supports raccoon and glasses avatar modes for local preview. Blend shapes are displayed in real time in the UI panel.

LiveLink

Enter your Unreal/Unity LiveLink server address (e.g. 192.168.1.100:11111) in the panel and click Connect. Blend shape data is streamed over WebSocket.

Jewelry Configurator (apps/jewelry-configurator)

Showcases the DiamondPlugin with an engagement ring model. Demonstrates multi-bounce ray-traced internal reflections with wavelength-accurate dispersion (fire). Supports switching gem cut styles and adjusting render quality settings.

Box Configurator (apps/box-configurator)

A parametric 3D box builder. Users set width, height, depth, wall thickness, and flap style. The box geometry is procedurally generated by the BoxBuilder class from scratch using THREE.BufferGeometry. Supports switching between different lid types.

360 Virtual Tour (apps/360tour)

An interactive 360-degree virtual tour editor and viewer. Uses the TourPlugin from the @trikomi/tour package to render spherical panorama images and place interactive hotspots. Features a TourEditor interface for dragging and connecting hotspots to link rooms together, and a VirtualTour viewer for navigating the finalized tours.

Build Pipeline

1. Packages Build (Core SDK & Plugins)

The core SDK and all separated plugin packages (like @trikomi/face-mocap, @trikomi/tour, etc.) are bundled with esbuild, not Vite. This keeps them modular, framework-agnostic, and produces clean ES modules. The core build also:

• Performs security hardening and integrity checks on the compiled output.
• Copies 3D assets (.glb, .hdr, .exr) to dist/assets/.
• Generates TypeScript type declarations.

2. App Builds (Vite)

Each app is built independently with vite build. All apps use these key config values:

// apps/<any-app>/vite.config.ts
defineConfig({
  base: './',               // Relative asset references → works in any subfolder
  publicDir: '../../public', // Shared WASM, Draco, textures
  build: {
    outDir: '../../dist/<appname>',
  }
})

3. Monorepo Merge (build-monorepo.js)

After all apps are built, this script:

1. Creates a shared dist/assets/ directory.
2. Rewrites index.html asset references from ./assets/ → ../assets/ so they point to the shared root.
3. Moves each app's hashed JS/CSS/WASM chunks into the shared dist/assets/ folder.
4. Copies the root index.html hub page to dist/index.html.

Final dist layout

Asset Path Strategy

Because apps are built with base: './' and deployed in subfolders (e.g. /demos/viewer/), absolute paths like /draco/ would resolve to the domain root — not the demo subfolder root. The following pattern is used throughout:

The same pattern applies to:

• Draco decoder: GLTFPlugin — import.meta.env.DEV ? '/draco/gltf/' : '../draco/gltf/'
• MediaPipe WASM: FaceMocapPlugin constructor arg — DEV ? '/assets/wasm' : '../assets/wasm'
• Textures: Sportswear ThreeCanvas — DEV ? '/textures/' : '../textures/'