Vincentt XR SDK

@vincentt-xr/sdk is the AR runtime for Vincentt projects. It gives a React + react-three-fiber app a camera session, face/hand/body tracking, and the screen-space layout primitives that most AR effects are built from.

Your JSX renders directly — in local preview and in the published bundle at <slug>.vincentt.app.

Install

The SDK is installed for you when you scaffold a project from the Vincentt template, which pins a known-good version alongside its peers:

vincentt create my-app

To add it to an existing project:

pnpm add @vincentt-xr/sdk

It expects react, react-dom, three, @react-three/fiber, @react-three/drei, and @mediapipe/tasks-vision as peers. The template already pins compatible versions of all of them; mismatched copies of React or three.js are the most common source of runtime errors.

Quick start

Wrap your app in XRProvider, mount an XRScene, and add content. Trackers self-register when mounted — there is no pipeline to wire up by hand.

import { ScreenSpaceUI, ScreenText, XRProvider, XRScene } from "@vincentt-xr/sdk";
import { useFaceDetection } from "@vincentt-xr/sdk/tracking";

function Effect() {
  const detection = useFaceDetection({ numFaces: 1 });

  if (detection.face) return null;

  return (
    <ScreenSpaceUI>
      <ScreenText
        text="SHOW A FACE TO THE CAMERA"
        screenTransform={{ position: { x: 0, y: 0 }, size: { width: 400, height: 52 } }}
        fontSize={24}
      />
    </ScreenSpaceUI>
  );
}

export default function App() {
  return (
    <XRProvider>
      <XRScene>
        <Effect />
      </XRScene>
    </XRProvider>
  );
}

Import doors

The API is split by task domain. Import each symbol from the door that owns it.

| Entry point | What lives there | | -------------------------------- | ------------------------------------------------------------------------------- | | @vincentt-xr/sdk | Providers, scene root, screen-space layout, renderers, text, capture, audio | | @vincentt-xr/sdk/tracking | Face / hand / gesture / body / segmentation trackers, anchors, triggers | | @vincentt-xr/sdk/face-effects | Face mesh materials, retouch, canonical mesh, head binding | | @vincentt-xr/sdk/scene-object | Scene-object types, factories, selectors, immutable store operations | | @vincentt-xr/sdk/low-level | Raw model-node reads and custom-tracker plumbing — the escape hatch | | @vincentt-xr/sdk/debug-ui | Dev-only inspector panels; not for shipping surfaces |

Documentation

GROUNDING.md is the authoritative API reference — every component, hook, and prop, plus the composition conventions. Read it before reaching into node_modules or inventing props. It ships inside the package, so it travels with the version you actually installed.

Longer-form guides live in docs/:

• docs/introduction.mdx — the scene-object authoring model
• docs/guides/ — task guides
• docs/api/ — API pages
• docs/MIGRATION_GUIDE.md — upgrading from 1.x

Local development

pnpm install
pnpm dev            # example app
pnpm preview:tunnel # example app, reachable on a phone
pnpm build
pnpm test
pnpm typecheck

The example app under example/ is the development surface for the SDK itself. Experiments start there; once one becomes a real app it graduates to its own repo built against the packaged SDK.

Release steps are in RELEASING.md.

License

Proprietary. See LICENSE — the published package is for use with the Vincentt platform only.

Feedback

Report friction and bugs to the Vincentt team through the beta reporting flow, or open an issue on this repository.