angular-three 4.0.0-next.47 → 4.0.0-next.49

package/README.md

@@ -1,32 +1,31 @@
 # `angular-three`
 
-A custom Renderer for Angular 18+ that uses Three.js to render 3D scenes.
+A custom Renderer for Angular 19+ that uses Three.js to render 3D scenes.
 
-## Compatibility
+## Official documentation
 
-Angular Three v2 is still in beta and aims to be compatible with Angular 17+.
+Please visit [angularthree-docs-next](https://angularthree-docs-next.netlify.app)
 
 ## Installation
 
 ```bash
-npm install angular-three@beta ngxtension three
-# yarn add angular-three@beta ngxtension three
-# pnpm add angular-three@beta ngxtension three
+npm install -D angular-three-plugin@next
+npx ng generate angular-three-plugin:init
 ```
 
-> Make sure to install `@types/three` as well
-
 ## Usage
 
+- Create a `SceneGraph` component for your 3D scene graph
+
 ```typescript
 import { extend } from 'angular-three';
 import { Mesh, BoxGeometry } from 'three';
 
 extend({
-	Mesh, // makes ngt-mesh available
-	BoxGeometry, // makes ngt-box-geometry available
-	/* ... */
-	MyMesh: Mesh, // makes ngt-my-mesh available
+ Mesh, // makes ngt-mesh available
+ BoxGeometry, // makes ngt-box-geometry available
+ /* ... */
+ MyMesh: Mesh, // makes ngt-my-mesh available
 });
 
 // alternatively for demo purposes, you can use the following
@@ -34,189 +33,45 @@ extend({
 // This includes the entire THREE.js namespace
 
 @Component({
-	// This Component is rendered in the Custom Renderer
-	template: `
-		<ngt-mesh>
-			<ngt-box-geometry />
-		</ngt-mesh>
-	`,
-	schemas: [CUSTOM_ELEMENTS_SCHEMA], // required
-	changeDetection: ChangeDetectionStrategy.OnPush,
+ selector: 'app-scene-graph',
+ template: `
+  <ngt-mesh>
+   <ngt-box-geometry />
+  </ngt-mesh>
+ `,
+ schemas: [CUSTOM_ELEMENTS_SCHEMA], // required
+ changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class SceneGraph {}
-
-@Component({
-	// This Component is rendered normally in Angular.
-	selector: 'app-my-experience',
-	template: `
-		<ngt-canvas [sceneGraph]="SceneGraph" />
-	`,
-	imports: [NgtCanvas],
-})
-export class MyExperience {
-	SceneGraph = SceneGraph;
-}
-```
-
-> The Component that renders `NgtCanvas` (`MyExperience` in this case) controls the dimensions of the canvas so make sure to style it accordingly.
-
-### Inputs
-
-- `sceneGraph: Type<any>`: **required**. This is the Component that renders your 3D Scene graph. It must be a standalone Component.
-- `gl?: NgtGLOptions`: This input allows you to configure the WebGL renderer used by Angular Three. You can provide a THREE.js renderer instance, properties for the default renderer, or a function that returns a renderer based on the canvas element.
-- `size?: NgtSize`: Specifies the dimensions of the renderer. If omitted, the component will automatically measure the canvas dimensions.
-- `shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<WebGLShadowMap>`: Enables or disables shadows in the scene. You can provide a boolean value to toggle shadows on or off, or use specific strings to control the shadow type. Additionally, you can pass partial WebGLShadowMap options for fine-tuning.
-- `legacy?: boolean`: Disables three r139 color management when set to true.
-- `linear?: boolean`: Switches off automatic sRGB color space and gamma correction when set to true.
-- `flat?: boolean`: Uses THREE.NoToneMapping instead of THREE.ACESFilmicToneMapping when set to true.
-- `orthographic?: boolean`: Creates an orthographic camera instead of a perspective camera when set to true.
-- `frameloop?: 'always' | 'demand' | 'never'`: Controls the rendering mode. 'always' renders continuously, 'demand' renders only on state changes, and 'never' gives you manual control over rendering.
-- `performance?: Partial<Omit<NgtPerformance, 'regress'>>`: Allows you to configure performance options for adaptive performance.
-- `dpr?: NgtDpr`: Sets the target pixel ratio. You can provide a single number or a range [min, max].
-- `raycaster?: Partial<Raycaster>`: Configures the default raycaster used for interaction.
-- `scene?: Scene | Partial<Scene>`: Provides a THREE.js scene instance or properties to create a default scene.
-- `camera?: NgtCamera | Partial<NgtObject3DNode<Camera>>`: Provides a THREE.js camera instance or properties to create a default camera. You can also set the manual property to true to take control of the camera projection.
-- `events?: (store: NgtSignalStore<NgtState>) => NgtEventManager<HTMLElement>`: Allows you to customize the event manager for handling pointer events.
-- `eventSource?: HTMLElement | ElementRef<HTMLElement>`: Specifies the target element where events are subscribed. By default, it's the div wrapping the canvas.
-- `eventPrefix?: 'offset' | 'client' | 'page' | 'layer' | 'screen'`: Sets the event prefix used for canvas pointer events.
-- `lookAt?: Vector3 | Parameters<Vector3['set']>`: Defines the default coordinate for the camera to look at.
-
-### Outputs
-
-- `created`: Emitted when the canvas is created.
-- `pointerMissed`: Emitted when a pointer event is not captured by any element (aka clicking on the canvas)
-
-## Intellisense support
-
-Since Angular Three is a custom Renderer, the elements are not recognized by the Angular Language Service.
-
-### Jetbrains IDE
-
-The consumers can add `web-types` property to the workspace's `package.json` and set the value to `node_modules/angular-three/web-types.json`.
-
-```json
-{
-	"web-types": "node_modules/angular-three/web-types.json"
-}
-```
-
-### VSCode
-
-Similarly, there's `node_modules/angular-three/metadata.json` file that can be used to provide intellisense support for VSCode users.
-
-The consumers can enable it via `html.customData` in their `settings.json` file.
-
-```json
-{
-	"html.customData": ["node_modules/angular-three/metadata.json"]
-}
-```
-
-## Input Bindings
-
-Input bindings for `ngt-*` elements work the same way as they do in Angular.
-
-> You can consult THREE.js documentation on what is available on the entities
-
-```html
-<ngt-mesh [position]="[x, y, z]" [rotation]="[x, y, z]">
-	<ngt-mesh-basic-material color="hotpink" />
-</ngt-mesh>
 ```
 
-## Events
-
-Angular Three Custom Renderer supports the following events on applicable objects (`ngt-mesh`, `ngt-group` etc...)
-
-```
-'click',
-'contextmenu',
-'dblclick',
-'pointerup',
-'pointerdown',
-'pointerover',
-'pointerout',
-'pointerenter',
-'pointerleave',
-'pointermove',
-'pointermissed',
-'pointercancel',
-'wheel',
-```
-
-In addition, there are 2 special events that the consumers can listen to;
-
-- `attached`: when the element is attached to its parent
-- `updated`: when the element properties are updated
-
-## Constructor Arguments
-
-In THREE.js, there are some entities that require the consumers to dispose and recreate them if their parameters change; like the Geometries.
-
-To handle this, Angular Three exports a `NgtArgs` structural directive that always accepts an Array of values. The consumers can consult THREE.js documentations to know what values are applicable for what entities and their order.
-
-```html
-<!-- for example, new BoxGeometry(width, height, depth) -->
-<ngt-box-geometry *args="[width, height, depth]" />
-```
-
-`NgtArgs`, as a structural directive, ensures to create a new instance of the entity when the value changes
-
-## Parameters
-
-Beside the normal properties that `ngt-*` elements can accept for Input bindings, the consumers can also pass a `parameters` object to a special property `[parameters]` on the elements. This parameters object will be used to apply the properties on the entity.
-
-```html
-<!-- instead of <ngt-mesh [position]="[x, y, z]" [scale]="scale" /> -->
-<ngt-mesh [parameters]="{ position: [x, y, z], scale }" />
-```
-
-## Element Queries
-
-The consumers can query for the THREE.js entities like they would do in normal HTML Angular Template.
+- Render the `SceneGraph` with `NgtCanvas`
 
 ```ts
-@Component({
-	template: `
-		<ngt-mesh #mesh></ngt-mesh>
-	`,
-})
-export class Box {
-	mesh = viewChild.required<ElementRef<Mesh>>('mesh');
-	//  notice that it is an ElementRef of THREE.Mesh instead of an HTMLElement
-}
-```
+import { NgtCanvas } from 'angular-three/dom';
+import { SceneGraph } from './scene-graph';
 
-## Animation Loop
-
-In order to participate in the animation loop, use `injectBeforeRender` inject function
-
-```ts
 @Component({
-	/*...*/
+ // This Component is rendered normally in Angular.
+ selector: 'app-my-experience',
+ template: `
+  <ngt-canvas>
+   <app-scene-graph *canvasContent />
+  </ngt-canvas>
+ `,
+ imports: [NgtCanvas],
 })
-export class Box {
-	mesh = viewChild.required<ElementRef<Mesh>>('mesh');
-
-	constructor() {
-		injectBeforeRender(() => {
-			// runs every frame
-			const mesh = this.mesh().nativeElement;
-			mesh.rotation.x += 0.01;
-		});
-	}
-}
+export class MyExperience {}
 ```
 
-## Store
+> The Component that renders `NgtCanvas` (`MyExperience` in this case) controls the dimensions of the canvas so make sure to style it accordingly.
 
-Angular Three keeps track of its state via an internal store. The consumers can access this store via the `injectStore` inject function
+- Finally, provide the custom renderer in `bootstrapApplication`
 
 ```ts
-export class Box {
-	store = injectStore();
-	viewport = this.store.select('viewport'); // Signal<NgtViewport>
-	camera = this.store.select('camera'); // Signal<NgtCamera> - the default camera
-	/* many more properties */
-}
+import { provideNgtRenderer } from 'angular-three/dom';
+
+bootstrapApplication(AppComponent, {
+ providers: [provideNgtRenderer()],
+});
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "angular-three",
-	"version": "4.0.0-next.47",
+	"version": "4.0.0-next.49",
 	"publishConfig": {
 		"access": "public"
 	},