feat(rapier): support fallback content when physics fails to load RAPIER wasm

BREAKING CHANGE: in order to support fallback content, physics content
has to be wrapped with `ng-template` to defer the render of
RigidBodies/Colliders within the `NgtrPhysics` component.

```html
<ngtr-physics>
  <!-- template defers the rendering until RAPIER finishes initializing
-->
  <ng-template>
    <ngt-object3D ngtrRigidBody />
    <!-- ... -->
  </ng-template>
</ngtr-physics>
```

This breaking change is for a dev preview (undocumented as well) Rapier
package so we'll only bump a minor version instead of major

Author: nartc

apps/kitchen-sink/src/app/rapier/basic/basic.ts

@@ -10,31 +10,33 @@ import { NgtsOrbitControls } from 'angular-three-soba/controls';
 		<ngts-perspective-camera [options]="{ makeDefault: true, position: [5, 5, 5] }" />
 
 		<ngtr-physics [options]="{ debug: true }">
-			<ngt-object3D ngtrRigidBody [options]="{ colliders: 'hull' }" [position]="[0, 5, 0]">
-				<ngt-mesh>
-					<ngt-torus-geometry />
-				</ngt-mesh>
-			</ngt-object3D>
+			<ng-template>
+				<ngt-object3D ngtrRigidBody [options]="{ colliders: 'hull' }" [position]="[0, 5, 0]">
+					<ngt-mesh>
+						<ngt-torus-geometry />
+					</ngt-mesh>
+				</ngt-object3D>
 
-			@if (currentCollider() === 1) {
-				<ngt-object3D ngtrCuboidCollider [args]="[1, 0.5, 1]" (collisionExit)="currentCollider.set(2)" />
-			} @else if (currentCollider() === 2) {
-				<ngt-object3D
-					ngtrCuboidCollider
-					[position]="[0, -1, 0]"
-					[args]="[3, 0.5, 3]"
-					(collisionExit)="currentCollider.set(3)"
-				/>
-			} @else if (currentCollider() === 3) {
-				<ngt-object3D
-					ngtrCuboidCollider
-					[position]="[0, -3, 0]"
-					[args]="[6, 0.5, 6]"
-					(collisionExit)="currentCollider.set(4)"
-				/>
-			} @else {
-				<ngt-object3D ngtrCuboidCollider [position]="[0, -6, 0]" [args]="[20, 0.5, 20]" />
-			}
+				@if (currentCollider() === 1) {
+					<ngt-object3D ngtrCuboidCollider [args]="[1, 0.5, 1]" (collisionExit)="currentCollider.set(2)" />
+				} @else if (currentCollider() === 2) {
+					<ngt-object3D
+						ngtrCuboidCollider
+						[position]="[0, -1, 0]"
+						[args]="[3, 0.5, 3]"
+						(collisionExit)="currentCollider.set(3)"
+					/>
+				} @else if (currentCollider() === 3) {
+					<ngt-object3D
+						ngtrCuboidCollider
+						[position]="[0, -3, 0]"
+						[args]="[6, 0.5, 6]"
+						(collisionExit)="currentCollider.set(4)"
+					/>
+				} @else {
+					<ngt-object3D ngtrCuboidCollider [position]="[0, -6, 0]" [args]="[20, 0.5, 20]" />
+				}
+			</ng-template>
 		</ngtr-physics>
 
 		<ngts-orbit-controls />

apps/kitchen-sink/src/app/rapier/wrapper-default.ts

@@ -42,21 +42,23 @@ export class Floor {}
 			<ng-container *ngComponentOutlet="component()" />
 		} @else {
 			<ngtr-physics [options]="{ debug: debug(), interpolate: interpolate(), paused: paused() }">
-				<ngt-directional-light [castShadow]="true" [position]="10">
-					<ngt-value [rawValue]="-40" attach="shadow.camera.bottom" />
-					<ngt-value [rawValue]="40" attach="shadow.camera.top" />
-					<ngt-value [rawValue]="-40" attach="shadow.camera.left" />
-					<ngt-value [rawValue]="40" attach="shadow.camera.right" />
-					<ngt-value [rawValue]="1024" attach="shadow.mapSize.width" />
-					<ngt-value [rawValue]="-0.0001" attach="shadow.bias" />
-				</ngt-directional-light>
+				<ng-template>
+					<ngt-directional-light [castShadow]="true" [position]="10">
+						<ngt-value [rawValue]="-40" attach="shadow.camera.bottom" />
+						<ngt-value [rawValue]="40" attach="shadow.camera.top" />
+						<ngt-value [rawValue]="-40" attach="shadow.camera.left" />
+						<ngt-value [rawValue]="40" attach="shadow.camera.right" />
+						<ngt-value [rawValue]="1024" attach="shadow.mapSize.width" />
+						<ngt-value [rawValue]="-0.0001" attach="shadow.bias" />
+					</ngt-directional-light>
 
-				<ngts-environment [options]="{ preset: 'apartment' }" />
-				<ngts-orbit-controls />
+					<ngts-environment [options]="{ preset: 'apartment' }" />
+					<ngts-orbit-controls />
 
-				<ng-container *ngComponentOutlet="component()" />
+					<ng-container *ngComponentOutlet="component()" />
 
-				<app-floor />
+					<app-floor />
+				</ng-template>
 			</ngtr-physics>
 		}
 	`,

apps/kitchen-sink/src/app/soba/bruno-simons-20k/experience.ts

@@ -121,11 +121,13 @@ export class Model {
 		</ngts-environment>
 
 		<ngtr-physics [options]="{ debug: debug(), gravity: [0, -4, 0] }">
-			<app-model [position]="[1, 0, -1.5]" />
-			<app-hats />
-			<ngt-object3D ngtrRigidBody="fixed" [options]="{ colliders: false }" [position]="[0, -1, 0]">
-				<ngt-object3D ngtrCuboidCollider [args]="[1000, 1, 1000]" />
-			</ngt-object3D>
+			<ng-template>
+				<app-model [position]="[1, 0, -1.5]" />
+				<app-hats />
+				<ngt-object3D ngtrRigidBody="fixed" [options]="{ colliders: false }" [position]="[0, -1, 0]">
+					<ngt-object3D ngtrCuboidCollider [args]="[1000, 1, 1000]" />
+				</ngt-object3D>
+			</ng-template>
 		</ngtr-physics>
 
 		<ngts-accumulative-shadows

libs/rapier/src/lib/physics.ts

@@ -1,12 +1,16 @@
+import { NgTemplateOutlet } from '@angular/common';
 import {
 	ChangeDetectionStrategy,
 	Component,
 	computed,
+	contentChild,
 	DestroyRef,
+	Directive,
 	effect,
 	inject,
 	input,
 	signal,
+	TemplateRef,
 	untracked,
 } from '@angular/core';
 import RAPIER, { ColliderHandle, EventQueue, Rotation, Vector, World } from '@dimforge/rapier3d-compat';
@@ -46,27 +50,43 @@ const defaultOptions: NgtrPhysicsOptions = {
 	debug: false,
 };
 
+@Directive({ selector: 'ng-template[rapierFallback]', standalone: true })
+export class NgtrPhysicsFallback {
+	static ngTemplateContextGuard(_: NgtrPhysicsFallback, ctx: unknown): ctx is { error: string } {
+		return true;
+	}
+}
+
 @Component({
 	selector: 'ngtr-physics',
 	standalone: true,
 	template: `
-		@if (debug()) {
-			<ngtr-debug [world]="worldSingleton()?.proxy" />
+		@if (rapierConstruct()) {
+			@if (debug()) {
+				<ngtr-debug [world]="worldSingleton()?.proxy" />
+			}
+
+			<ngtr-frame-stepper
+				[ready]="ready()"
+				[stepFn]="step.bind(this)"
+				[type]="updateLoop()"
+				[updatePriority]="updatePriority()"
+			/>
+
+			<ng-container [ngTemplateOutlet]="content()" />
+		} @else if (rapierError() && !!fallbackContent()) {
+			<ng-container [ngTemplateOutlet]="$any(fallbackContent())" [ngTemplateOutletContext]="{ error: rapierError() }" />
 		}
-		<ngtr-frame-stepper
-			[ready]="ready()"
-			[stepFn]="step.bind(this)"
-			[type]="updateLoop()"
-			[updatePriority]="updatePriority()"
-		/>
-		<ng-content />
 	`,
 	changeDetection: ChangeDetectionStrategy.OnPush,
-	imports: [NgtrDebug, NgtrFrameStepper],
+	imports: [NgtrDebug, NgtrFrameStepper, NgTemplateOutlet],
 })
 export class NgtrPhysics {
 	options = input(defaultOptions, { transform: mergeInputs(defaultOptions) });
 
+	content = contentChild.required(TemplateRef);
+	fallbackContent = contentChild(NgtrPhysicsFallback);
+
 	protected updatePriority = pick(this.options, 'updatePriority');
 	protected updateLoop = pick(this.options, 'updateLoop');
 
@@ -90,7 +110,8 @@ export class NgtrPhysics {
 	private store = injectStore();
 	private destroyRef = inject(DestroyRef);
 
-	private rapierConstruct = signal<typeof RAPIER | null>(null);
+	protected rapierConstruct = signal<typeof RAPIER | null>(null);
+	protected rapierError = signal<string | null>(null);
 	rapier = this.rapierConstruct.asReadonly();
 
 	ready = computed(() => !!this.rapier());
@@ -124,7 +145,7 @@ export class NgtrPhysics {
 			.then(this.rapierConstruct.set.bind(this.rapierConstruct))
 			.catch((err) => {
 				console.error(`[NGT] Failed to load rapier3d-compat`, err);
-				return Promise.reject(err);
+				this.rapierError.set(err?.message ?? err.toString());
 			});
 
 		effect(() => {

libs/rapier/src/lib/rigid-body.ts

@@ -175,6 +175,12 @@ export class NgtrAnyCollider {
 		const worldSingleton = this.physics.worldSingleton();
 		if (!worldSingleton) return;
 
+		const localState = getLocalState(this.objectRef.nativeElement);
+		if (!localState) return;
+
+		const parent = localState.parent();
+		if (!parent || !(parent as Object3D).isObject3D) return;
+
 		const state = this.createColliderState(
 			collider,
 			this.objectRef.nativeElement,
@@ -478,6 +484,11 @@ export class NgtrRigidBody {
 		if (!options.colliders) options.colliders = physicsColliders;
 
 		const objectLocalState = getLocalState(this.objectRef.nativeElement);
+		if (!objectLocalState) return [];
+
+		const parent = objectLocalState.parent();
+		if (!parent || !(parent as Object3D).isObject3D) return [];
+
 		// track object's children
 		objectLocalState?.nonObjects();
 
@@ -511,6 +522,12 @@ export class NgtrRigidBody {
 
 		const transformState = untracked(this.transformState);
 
+		const localState = getLocalState(this.objectRef.nativeElement);
+		if (!localState) return;
+
+		const parent = localState.parent();
+		if (!parent || !(parent as Object3D).isObject3D) return;
+
 		const state = this.createRigidBodyState(body, this.objectRef.nativeElement);
 		this.physics.rigidBodyStates.set(body.handle, transformState ? transformState(state) : state);