ARScene

Scene, рендеримая поверх видеопотока камеры устройства с трекингом мира — всё из Scene (опции, add/remove, события, оверлеи) применимо. Что она добавляет: async open(), запрашивающий камеру и запускающий трекинг, узлы-якоря, следующие за реальным миром, и готовые жесты размещения объектов через addControls.

Обзор

const scene = new ARScene()
const model = await Model.load(asset('./chair.glb'))
scene.root.add(model)
scene.add(model)

const controls = scene.addControls(model)     // перетаскивание / щипок / поворот для размещения
await scene.open()

model.addEventListener('track', () => console.log('anchored to the world'))

Создание и открытие

new ARScene(options?: SceneOptions & {
  mode?: 'default' | 'markers' | 'arcore' | 'detached'   // режим трекинга; по умолчанию 'default'
})

scene.mode                         // только чтение: режим, с которым она создана
scene.useWarmRender = true         // open() сначала прогревает шейдеры (по умолчанию true)

await scene.open(): Promise<void>  // запрос камеры → прогрев рендера → запуск AR → стать активной
scene.close(): void                // остановить AR-сессию и разобрать вид

open() асинхронный — он запрашивает разрешение на камеру, прогревает рендер (когда useWarmRender включён) и запускает трекинг до того, как сцена станет активной. Он отклоняется, если в камере отказано или AR не может запуститься, поэтому делай await и обрабатывай сбой.

Якоря

scene.root: Node                                              // корневой якорь мира (только чтение)
scene.createAnchor(source: FetchResponse, physicalWidth = 0.2): Node   // якорь по изображению-цели

Якорь — это Node, чей трансформ управляется трекингом — подвешивай под него свой контент. root — якорь начала мира; createAnchor создаёт якорь, следующий за источником трекинга (напр. изображением-целью, скачанным через fetch), где physicalWidth — реальная ширина цели в метрах (по умолчанию 0.2).

Узлы-якоря сообщают состояние трекинга:

anchor.addEventListener('track', () => {})      // трекинг начался
anchor.addEventListener('untrack', () => {})    // трекинг потерян
anchor.isTracked                                // текущее состояние (false для не-якорных узлов)

Управление размещением — addControls

scene.addControls(target: Node, options?: {
  minScale?: number   // наименьший равномерный масштаб при щипке; по умолчанию 0.08
  maxScale?: number   // наибольший; по умолчанию 2
  pan?: boolean       // перетаскивание одним пальцем; по умолчанию true
  pinch?: boolean     // масштаб двумя пальцами; по умолчанию true
  twist?: boolean     // поворот двумя пальцами; по умолчанию true
}): { remove(): void }

Классическое AR-взаимодействие размещения объекта, готовое:

• Один палец тащит цель по плоскости земли, относительно того, куда смотрит камера (вверх по экрану уводит её от тебя). Высота (мировой Y) остаётся фиксированной.
• Два пальца щипком масштабируют (равномерно, зажато minScale/maxScale) и поворотом вращают цель вокруг её оси Y.

Построено полностью на публичном touch-API (touchstart сцены + ev.track) — это удобство, а не примитив. Вызови .remove() на возвращённом хэндле, чтобы отсоединить слушатели.

Смотрите также

• Scene — всё унаследованное: опции, add/remove, оверлеи, warmRender, события.
• Node — события track/untrack, isTracked, иерархия.
• Model — загрузка размещаемого GLB.
• События указателя и жесты — touch-поверхность, на которой построен addControls.