angular-three-tweakpane

This library provides Tweakpane integration for Angular Three, enabling easy creation of debug UI controls for tweaking parameters in your 3D scenes.

Documentation

All public APIs are documented with JSDoc comments. Your IDE will provide inline documentation, parameter hints, and examples as you code.

Installation

npm install angular-three-tweakpane tweakpane
# yarn add angular-three-tweakpane tweakpane
# pnpm add angular-three-tweakpane tweakpane

Make sure to already have angular-three installed

Usage

Declarative API with tweaks()

The recommended way to create controls:

1. Add tweakpaneAnchor directive to your ngt-canvas
2. Add <tweakpane-pane> somewhere in your scene
3. Use tweaks() in any component within the canvas

import { Component, ChangeDetectionStrategy, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { tweaks, TweakpaneAnchor, TweakpanePane } from 'angular-three-tweakpane';

@Component({
	template: `
		<ngt-mesh [position]="[params.x(), params.y(), params.z()]">
			<ngt-box-geometry />
			<ngt-mesh-standard-material [color]="params.color()" />
		</ngt-mesh>

		<tweakpane-pane title="Controls" />
	`,
	imports: [TweakpanePane],
	schemas: [CUSTOM_ELEMENTS_SCHEMA],
	changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SceneGraph {
	params = tweaks('Position', {
		x: { value: 0, min: -5, max: 5 },
		y: { value: 0, min: -5, max: 5 },
		z: { value: 0, min: -5, max: 5 },
		color: { value: '#ff0000', color: true },
	});
}

@Component({
	template: `
		<ngt-canvas tweakpaneAnchor>
			<app-scene-graph *canvasContent />
		</ngt-canvas>
	`,
	imports: [NgtCanvas, TweakpaneAnchor, SceneGraph],
})
export class Experience {}

Nested Folders

params = tweaks('Settings', {
	basic: 42,
	position: tweaks.folder('Position', {
		x: { value: 0, min: -5, max: 5 },
		y: { value: 0, min: -5, max: 5 },
		z: { value: 0, min: -5, max: 5 },
	}),
	material: tweaks.folder('Material', {
		color: { value: '#ff0000', color: true },
		metalness: { value: 0.5, min: 0, max: 1 },
		roughness: { value: 0.5, min: 0, max: 1 },
	}),
});

// Access nested values
this.params.position.x(); // Signal<number>
this.params.material.color(); // Signal<string>

Two-Way Binding with Existing Signals

filteringEnabled = signal(true);
gravity = signal(9.8);

params = tweaks('Settings', {
	filteringEnabled: this.filteringEnabled, // two-way binding
	gravity: this.gravity,
});

Buttons (Actions)

params = tweaks('Actions', {
	reset: { action: () => this.reset(), label: 'Reset All' },
	randomize: { action: () => this.randomize() },
});

Component-Based API

For more control, use individual components:

import {
	TweakpanePane,
	TweakpaneFolder,
	TweakpaneNumber,
	TweakpaneColor,
	TweakpaneCheckbox,
	TweakpaneButton,
} from 'angular-three-tweakpane';

@Component({
	template: `
		<tweakpane-pane title="Controls">
			<tweakpane-folder title="Position">
				<tweakpane-number [(value)]="x" label="X" [params]="{ min: -5, max: 5 }" />
			</tweakpane-folder>
			<tweakpane-color [(value)]="color" label="Color" />
			<tweakpane-checkbox [(value)]="visible" label="Visible" />
			<tweakpane-button title="Reset" (click)="reset()" />
		</tweakpane-pane>
	`,
	imports: [TweakpanePane, TweakpaneFolder, TweakpaneNumber, TweakpaneColor, TweakpaneCheckbox, TweakpaneButton],
})
export class Controls {
	x = signal(0);
	color = signal('#ff0000');
	visible = signal(true);

	reset() {
		this.x.set(0);
		this.color.set('#ff0000');
		this.visible.set(true);
	}
}

Control Types

| Component | Description | Config Type | | ------------------- | ---------------------------------- | -------------------------------- | | TweakpaneNumber | Numeric input with optional slider | { value, min?, max?, step? } | | TweakpaneText | Text input | { value } | | TweakpaneCheckbox | Boolean toggle | { value } | | TweakpaneColor | Color picker | { value, color: true } | | TweakpaneList | Dropdown select | { value, options: [...] } | | TweakpanePoint | 2D/3D/4D point input | { value, x?, y?, z?, w? } | | TweakpaneButton | Clickable button | { action: () => void, label? } | | TweakpaneFolder | Collapsible group | tweaks.folder(name, config) |

Pane Positioning

<tweakpane-pane title="Debug" top="8px" right="8px">
  <!-- controls -->
</tweakpane-pane>

Available position inputs: top, right, bottom, left, width