helper

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-helper',
    template: `
        <ngt-canvas [camera]="{ position: [5, 5, 5], fov: 50 }">
            <app-soba-wrapper *canvasContent>
                <app-scene-graph />
            </app-soba-wrapper>
        </ngt-canvas>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: { class: 'helper-demo relative block h-full' },
    imports: [NgtCanvas, SobaWrapper, SceneGraph],
})
export default class Helper {
    static clientProviders = [provideNgtRenderer()];
}

scene-graph.ts

import { ChangeDetectionStrategy, Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { NgtArgs } from 'angular-three';
import { NgtsHelper } from 'angular-three-soba/abstractions';
import { BoxHelper, DirectionalLightHelper, PointLightHelper } from 'three';

@Component({
    selector: 'app-scene-graph',
    template: `
        <!-- Mesh with BoxHelper -->
        <ngt-mesh [position]="[-2, 0.5, 0]">
            <ngt-box-geometry *args="[1, 1, 1]" />
            <ngt-mesh-standard-material color="#ff6b6b" />
            <ngts-helper [type]="BoxHelper" [options]="['cyan']" />
        </ngt-mesh>

        <!-- Sphere with BoxHelper -->
        <ngt-mesh [position]="[0, 0.5, 0]">
            <ngt-sphere-geometry *args="[0.6, 32, 32]" />
            <ngt-mesh-standard-material color="#4ecdc4" />
            <ngts-helper [type]="BoxHelper" [options]="['yellow']" />
        </ngt-mesh>

        <!-- Torus with BoxHelper -->
        <ngt-mesh [position]="[2, 0.5, 0]">
            <ngt-torus-geometry *args="[0.5, 0.2, 16, 32]" />
            <ngt-mesh-standard-material color="#a29bfe" />
            <ngts-helper [type]="BoxHelper" [options]="['magenta']" />
        </ngt-mesh>

        <!-- Directional light with helper -->
        <ngt-directional-light [position]="[5, 5, 5]" [intensity]="Math.PI">
            <ngts-helper [type]="DirectionalLightHelper" [options]="[1, '#ffff00']" />
        </ngt-directional-light>

        <!-- Point light with helper -->
        <ngt-point-light [position]="[-3, 3, 0]" [intensity]="Math.PI * 2" color="#ff8800">
            <ngts-helper [type]="PointLightHelper" [options]="[0.5, '#ff8800']" />
        </ngt-point-light>
    `,
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    changeDetection: ChangeDetectionStrategy.OnPush,
    imports: [NgtArgs, NgtsHelper],
})
export class SceneGraph {
    protected readonly Math = Math;
    protected readonly BoxHelper = BoxHelper;
    protected readonly DirectionalLightHelper = DirectionalLightHelper;
    protected readonly PointLightHelper = PointLightHelper;
}

helper is a function to add helpers to existing nodes in the scene. It handles removal of the helper on destroy and auto-updates it by default.

injectHelper is deprecated. Use helper instead.

Usage

import { helper } from 'angular-three-soba/abstractions';
import { BoxHelper, PointLightHelper } from 'three';

@Component({
    selector: 'app-scene',
    template: `
        <ngt-mesh #mesh>
            <ngt-box-geometry />
            <ngt-mesh-standard-material />
        </ngt-mesh>
    `,
})
export class Scene {
    mesh = viewChild.required<ElementRef<Mesh>>('mesh');

    boxHelper = helper(this.mesh, () => BoxHelper, {
        args: () => ['cyan'],
    });
}

Options

Property	Type	Description	Default
args	() => ConstructorParameters<Helper>	Signal of constructor arguments to pass to the helper.	[]
update	boolean	Whether to automatically update the helper each frame.	true

With PointLightHelper

@Component({
    selector: 'app-scene',
    template: `
        <ngt-point-light #light [position]="[5, 5, 5]" />
    `,
})
export class Scene {
    light = viewChild.required<ElementRef<PointLight>>('light');

    lightHelper = helper(this.light, () => PointLightHelper, {
        args: () => [1, 'yellow'],
    });
}

With DirectionalLightHelper

@Component({
    selector: 'app-scene',
    template: `
        <ngt-directional-light #light [position]="[10, 10, 10]" />
    `,
})
export class Scene {
    light = viewChild.required<ElementRef<DirectionalLight>>('light');

    lightHelper = helper(this.light, () => DirectionalLightHelper, {
        args: () => [5, 'red'],
    });
}

Disabling Auto-Update

If you don’t need the helper to update every frame, set update: false:

boxHelper = helper(this.mesh, () => BoxHelper, {
    args: () => ['cyan'],
    update: false,
});

---

NgtsHelper

A declarative way to add helpers to existing nodes in the scene. It handles removal of the helper on destroy and auto-updates it by default.

Usage

import { NgtsHelper } from 'angular-three-soba/abstractions';
import { BoxHelper } from 'three';

<ngt-mesh>
    <ngt-box-geometry />
    <ngt-mesh-standard-material />
    <ngts-helper [type]="BoxHelper" [options]="['cyan']" />
</ngt-mesh>

Inputs

Input	Type	Description	Required
type	Type<Helper>	The helper constructor type.	Yes
options	ConstructorParameters<Helper>	Constructor arguments to pass to the helper.	No

With PointLightHelper

<ngt-point-light [position]="[5, 5, 5]">
    <ngts-helper [type]="PointLightHelper" [options]="[1, 'yellow']" />
</ngt-point-light>

With CameraHelper

<ngt-perspective-camera [position]="[0, 5, 10]" #camera>
    <ngts-helper [type]="CameraHelper" />
</ngt-perspective-camera>

Arguments

name	type	description	required
target	() => ElementRef<Object3D> | Object3D	Signal containing the target object to attach the helper to.	yes
helperType	() => Type<Helper>	Signal containing the helper constructor type (e.g., BoxHelper, PointLightHelper).	yes
options	Partial<NgtsHelperOptions<Helper>>	Configuration options for the helper.	no

Returns

type	description
Signal<Helper | null>	Signal containing the helper instance, or null if not yet created.