NgtsPointerLockControls

Preview

canvas.ts

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { SobaWrapper } from '@soba/wrapper.ts';
import { NgtCanvas, provideNgtRenderer } from 'angular-three/dom';
import { SceneGraph } from './scene-graph';

@Component({
    selector: 'app-pointer-lock-controls',
    template: `
        <ngt-canvas [camera]="{ position: [0, 1, 5], fov: 75 }">
            <app-soba-wrapper *canvasContent [controls]="null" [grid]="false">
                <app-scene-graph />
            </app-soba-wrapper>
        </ngt-canvas>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: { class: 'pointer-lock-controls-demo relative block h-full' },
    imports: [NgtCanvas, SobaWrapper, SceneGraph],
})
export default class PointerLockControls {
    static clientProviders = [provideNgtRenderer()];
}

scene-graph.ts

import { ChangeDetectionStrategy, Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';
import { NgtArgs } from 'angular-three';
import { NgtsPointerLockControls } from 'angular-three-soba/controls';

@Component({
    selector: 'app-scene-graph',
    template: `
        <!-- Floor -->
        <ngt-mesh [rotation]="[-Math.PI / 2, 0, 0]" [position]="[0, 0, 0]">
            <ngt-plane-geometry *args="[20, 20]" />
            <ngt-mesh-standard-material color="#444" />
        </ngt-mesh>

        <!-- Some objects to look at -->
        <ngt-mesh [position]="[-3, 1, -3]">
            <ngt-box-geometry *args="[1, 2, 1]" />
            <ngt-mesh-standard-material color="#ff6b6b" />
        </ngt-mesh>

        <ngt-mesh [position]="[3, 0.5, -5]">
            <ngt-sphere-geometry *args="[0.5, 32, 32]" />
            <ngt-mesh-standard-material color="#4ecdc4" />
        </ngt-mesh>

        <ngt-mesh [position]="[0, 0.75, -8]">
            <ngt-cone-geometry *args="[0.75, 1.5, 32]" />
            <ngt-mesh-standard-material color="#a29bfe" />
        </ngt-mesh>

        <ngt-mesh [position]="[5, 1, -2]">
            <ngt-torus-geometry *args="[0.5, 0.2, 16, 32]" />
            <ngt-mesh-standard-material color="#ffeaa7" />
        </ngt-mesh>

        <!-- Pointer lock controls -->
        <ngts-pointer-lock-controls (lock)="onLock()" (unlock)="onUnlock()" />

        <!-- UI overlay -->
        @if (!isLocked()) {
            <ngt-group>
                <!-- This is just for visual reference - actual UI would be HTML overlay -->
            </ngt-group>
        }
    `,
    styles: `
        :host {
            position: relative;
        }
    `,
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    changeDetection: ChangeDetectionStrategy.OnPush,
    imports: [NgtArgs, NgtsPointerLockControls],
})
export class SceneGraph {
    protected readonly Math = Math;
    isLocked = signal(false);

    onLock() {
        this.isLocked.set(true);
    }

    onUnlock() {
        this.isLocked.set(false);
    }
}

NgtsPointerLockControls is a wrapper around Three.js PointerLockControls which provides first-person style controls by locking the mouse pointer.

Usage

import { NgtsPointerLockControls } from 'angular-three-soba/controls';

<ngts-pointer-lock-controls />

With Selector

Use the selector option to specify which elements should trigger pointer lock when clicked.

<ngts-pointer-lock-controls [options]="{ selector: '#lock-button' }" />

Handling Events

<ngts-pointer-lock-controls
  (lock)="onLock()"
  (unlock)="onUnlock()"
  (change)="onChange($event)"
/>

onLock() {
  console.log('Pointer locked');
}

onUnlock() {
  console.log('Pointer unlocked');
}

onChange(event: any) {
  console.log('Camera orientation changed');
}

Outputs

name	type	description
lock	void	Emits when the pointer is locked.
unlock	void	Emits when the pointer is unlocked.
change	any	Emits when the camera orientation changes.

Options

options input accepts any properties from PointerLockControls in addition to the following:

Properties

name	type	description
camera	THREE.Camera	The camera to control. If not provided, the default camera will be used.
domElement	HTMLElement	The DOM element to attach the controls to. If not provided, the current connected element will be used.
makeDefault	boolean	Whether to make this control the default one. Default: false
enabled	boolean	Whether the controls are enabled. Default: true
selector	string	A CSS selector for elements that will trigger pointer lock on click.