angular-threejs
angular-three-theatre
This library provides Theatre.js integration for Angular Three, enabling powerful animation and motion design capabilities for 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-theatre @theatre/core @theatre/studio
# yarn add angular-three-theatre @theatre/core @theatre/studio
# pnpm add angular-three-theatre @theatre/core @theatre/studioMake sure to already have
angular-threeinstalled
Usage
Basic Setup
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { TheatreProject, TheatreSheet, TheatreSheetObject } from 'angular-three-theatre';
@Component({
template: `
<theatre-project name="My Project">
<ng-container sheet="Scene">
<ng-template sheetObject="Box" [sheetObjectProps]="{ x: 0, y: 0, z: 0 }" let-values="values">
<ngt-mesh [position]="[values().x, values().y, values().z]">
<ngt-box-geometry />
<ngt-mesh-standard-material />
</ngt-mesh>
</ng-template>
</ng-container>
</theatre-project>
`,
imports: [TheatreProject, TheatreSheet, TheatreSheetObject],
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class SceneGraph {}Enable Studio (Development)
The studio directive is applied to theatre-project:
import { TheatreProject, TheatreStudio } from 'angular-three-theatre';
@Component({
template: `
<theatre-project name="My Project" [studio]="isDevelopment">
<ng-container sheet="Scene">
<!-- sheet objects here -->
</ng-container>
</theatre-project>
`,
imports: [TheatreProject, TheatreStudio],
})
export class SceneGraph {
isDevelopment = !environment.production;
}Sequence Playback
The sequence directive must be used together with the sheet directive:
import { TheatreProject, TheatreSheet } from 'angular-three-theatre';
@Component({
template: `
<theatre-project name="My Project">
<ng-container sheet="Scene" [sequence]="{ autoplay: true, rate: 1 }" #seq="sequence">
<p>Position: {{ seq.position() }}</p>
<button (click)="seq.play()">Play</button>
<button (click)="seq.pause()">Pause</button>
<!-- sheet objects here -->
</ng-container>
</theatre-project>
`,
imports: [TheatreProject, TheatreSheet],
})
export class SceneGraph {}Sync Three.js Properties
Use the sync directive to synchronize Three.js object properties with Theatre.js:
import { TheatreSheetObject } from 'angular-three-theatre';
@Component({
template: `
<ng-template sheetObject="myMaterial">
<ngt-mesh-standard-material
[sync]="material"
[syncProps]="['opacity', 'roughness', 'metalness']"
#material
/>
</ng-template>
`,
imports: [TheatreSheetObject],
})
export class AnimatedMaterial {}Transform Controls
Use theatre-transform component for position, rotation, and scale animation:
import { TheatreSheetObject } from 'angular-three-theatre';
@Component({
template: `
<ng-template sheetObject="myCube">
<theatre-transform>
<ngt-mesh>
<ngt-box-geometry />
<ngt-mesh-standard-material />
</ngt-mesh>
</theatre-transform>
</ng-template>
`,
imports: [TheatreSheetObject],
})
export class TransformableObject {}Directives and Components
| Export | Selector | Description |
|---|---|---|
TheatreProject |
theatre-project |
Root container for Theatre.js project |
TheatreSheet |
[sheet] |
Creates an animation sheet (includes Sequence) |
TheatreSequence |
[sheet][sequence] |
Controls sequence playback |
TheatreStudio |
theatre-project[studio] |
Enables Theatre.js Studio UI |
TheatreSheetObject |
ng-template[sheetObject] |
Creates animatable properties |
TheatreSheetObjectSync |
[sync] |
Syncs Three.js object properties |
TheatreSheetObjectTransform |
theatre-transform |
Adds transform controls |
Convenience Exports
For easier importing, the library provides combined exports:
// TheatreSheet includes both TheatreSheetImpl and TheatreSequence
import { TheatreSheet } from 'angular-three-theatre';
// TheatreSheetObject includes TheatreSheetObjectImpl, TheatreSheetObjectSync, and TheatreSheetObjectTransform
import { TheatreSheetObject } from 'angular-three-theatre';Sheet Object Template Context
The sheetObject directive provides the following template context:
<ng-template
sheetObject="myObject"
[sheetObjectProps]="{ opacity: 1 }"
let-values="values"
let-sheetObject="sheetObject"
let-select="select"
let-deselect="deselect"
>
<!-- values() returns the current animated values -->
<!-- sheetObject() returns the Theatre.js sheet object instance -->
<!-- select() selects this object in Studio -->
<!-- deselect() deselects this object in Studio -->
</ng-template>Transformers
Built-in property transformers for Theatre.js props:
color- RGBA color pickerdegrees- Radian to degrees conversioneuler- Euler rotation controlsnormalized- 0-1 range sliderside- Material side propertygeneric- Fallback for common types