rayzee 8.8.2 → 9.1.0

package/src/managers/WalkControls.js

@@ -0,0 +1,262 @@
+import { Controls, MathUtils, Quaternion, Vector3 } from 'three';
+
+const CROSSING_SECONDS = 8;
+const FAST = 4;
+const SLOW = 0.25;
+const MAX_PITCH = MathUtils.degToRad( 89 );
+const MAX_STEP_SECONDS = 0.25;
+
+// Right, forward, up.
+const KEY_DIRECTIONS = {
+	KeyD: [ 1, 0, 0 ], ArrowRight: [ 1, 0, 0 ],
+	KeyA: [ - 1, 0, 0 ], ArrowLeft: [ - 1, 0, 0 ],
+	KeyW: [ 0, 1, 0 ], ArrowUp: [ 0, 1, 0 ],
+	KeyS: [ 0, - 1, 0 ], ArrowDown: [ 0, - 1, 0 ],
+	KeyE: [ 0, 0, 1 ],
+	KeyQ: [ 0, 0, - 1 ],
+};
+
+// Focus that types, or opens a list, keeps its keys. A widget that handled a key prevents its default.
+const TYPES_KEYS = 'input, textarea, select, [contenteditable]:not([contenteditable="false"]), '
+	+ '[role=textbox], [role=combobox], [role=listbox], [role=menu], [role=menuitem]';
+
+const speedFactor = event => event.shiftKey ? FAST : event.altKey ? SLOW : 1;
+
+const _changeEvent = { type: 'change' };
+const _startEvent = { type: 'start' };
+const _forward = new Vector3();
+const _right = new Vector3();
+const _move = new Vector3();
+const _axis = new Vector3();
+const _q = new Quaternion();
+
+/**
+ * First-person navigation: drag to look, W A S D or the arrows to walk level, E and Q to rise
+ * and sink, Shift faster, Alt slower.
+ *
+ * Rides on the orbit controls: moves only while they are enabled, and keeps their target ahead
+ * of the camera, since they re-aim the camera at it every frame.
+ */
+export class WalkControls extends Controls {
+
+	/**
+	 * @param {import('three').PerspectiveCamera} camera
+	 * @param {HTMLElement} domElement
+	 * @param {import('three/addons/controls/OrbitControls.js').OrbitControls} orbit
+	 */
+	constructor( camera, domElement, orbit ) {
+
+		super( camera, domElement );
+
+		this.orbit = orbit;
+		this.enabled = false;
+		/** Scene units per second. */
+		this.speed = 1 / CROSSING_SECONDS;
+
+		this._held = new Set();
+		this._factor = 1;
+		this._lastTime = 0;
+		this._drag = null;
+
+		this._onKeyDown = this._onKeyDown.bind( this );
+		this._onKeyUp = this._onKeyUp.bind( this );
+		this.release = this.release.bind( this );
+		this._onPointerDown = this._onPointerDown.bind( this );
+		this._onPointerMove = this._onPointerMove.bind( this );
+		this._onPointerUp = this._onPointerUp.bind( this );
+
+		if ( domElement ) this.connect( domElement );
+
+	}
+
+	get active() {
+
+		return this.enabled && this.orbit.enabled;
+
+	}
+
+	/** Cross a scene this long in about eight seconds. */
+	fitSpeed( sceneSize ) {
+
+		this.speed = ( sceneSize > 0 ? sceneSize : 1 ) / CROSSING_SECONDS;
+
+	}
+
+	connect( element ) {
+
+		super.connect( element );
+		const doc = element.ownerDocument;
+		doc?.addEventListener( 'keydown', this._onKeyDown );
+		doc?.addEventListener( 'keyup', this._onKeyUp );
+		doc?.addEventListener( 'visibilitychange', this.release );
+		doc?.defaultView?.addEventListener( 'blur', this.release );
+		element.addEventListener( 'pointerdown', this._onPointerDown );
+		element.addEventListener( 'pointermove', this._onPointerMove );
+		element.addEventListener( 'pointerup', this._onPointerUp );
+		element.addEventListener( 'pointercancel', this._onPointerUp );
+
+	}
+
+	disconnect() {
+
+		const element = this.domElement;
+		if ( ! element ) return;
+		const doc = element.ownerDocument;
+		doc?.removeEventListener( 'keydown', this._onKeyDown );
+		doc?.removeEventListener( 'keyup', this._onKeyUp );
+		doc?.removeEventListener( 'visibilitychange', this.release );
+		doc?.defaultView?.removeEventListener( 'blur', this.release );
+		element.removeEventListener( 'pointerdown', this._onPointerDown );
+		element.removeEventListener( 'pointermove', this._onPointerMove );
+		element.removeEventListener( 'pointerup', this._onPointerUp );
+		element.removeEventListener( 'pointercancel', this._onPointerUp );
+
+	}
+
+	dispose() {
+
+		this.disconnect();
+
+	}
+
+	update( delta = this._elapsed() ) {
+
+		if ( ! this._held.size || ! this.active ) return false;
+
+		let right = 0, forward = 0, up = 0;
+		for ( const code of this._held ) {
+
+			const [ r, f, u ] = KEY_DIRECTIONS[ code ];
+			right += r;
+			forward += f;
+			up += u;
+
+		}
+
+		if ( ! right && ! forward && ! up ) return false;
+
+		const camera = this.object;
+		// Level axes from the camera's right, which stays level however far it looks down.
+		_right.set( 1, 0, 0 ).applyQuaternion( camera.quaternion );
+		_forward.crossVectors( camera.up, _right ).normalize();
+		_right.crossVectors( _forward, camera.up );
+
+		_move.set( 0, 0, 0 )
+			.addScaledVector( _right, right )
+			.addScaledVector( _forward, forward )
+			.addScaledVector( camera.up, up )
+			.normalize()
+			.multiplyScalar( this.speed * this._factor * delta );
+		camera.position.add( _move );
+		this.orbit.target.add( _move );
+		camera.updateMatrixWorld();
+
+		this.dispatchEvent( _changeEvent );
+		return true;
+
+	}
+
+	_elapsed() {
+
+		const now = performance.now();
+		const delta = Math.min( ( now - this._lastTime ) / 1000, MAX_STEP_SECONDS );
+		this._lastTime = now;
+		return delta;
+
+	}
+
+	/** Turn by a drag of dx, dy pixels, so the scene follows the pointer. */
+	_look( dx, dy ) {
+
+		const camera = this.object;
+		const target = this.orbit.target;
+		const distance = camera.position.distanceTo( target ) || 1;
+		const radiansPerPixel = MathUtils.degToRad( camera.fov ) / ( this.domElement.clientHeight || 1 );
+
+		camera.quaternion.premultiply( _q.setFromAxisAngle( camera.up, dx * radiansPerPixel ) );
+
+		camera.getWorldDirection( _forward );
+		const pitch = Math.asin( MathUtils.clamp( _forward.dot( camera.up ), - 1, 1 ) );
+		const nextPitch = MathUtils.clamp( pitch + dy * radiansPerPixel, - MAX_PITCH, MAX_PITCH );
+		camera.quaternion.multiply( _q.setFromAxisAngle( _axis.set( 1, 0, 0 ), nextPitch - pitch ) );
+		camera.updateMatrixWorld();
+
+		target.copy( camera.position ).addScaledVector( camera.getWorldDirection( _forward ), distance );
+		this.dispatchEvent( _changeEvent );
+
+	}
+
+	_onKeyDown( event ) {
+
+		if ( ! this.active || event.defaultPrevented || event.target?.closest?.( TYPES_KEYS ) ) return;
+
+		// Browser shortcuts pass through, and macOS drops the key-up of a key pressed while Cmd is down.
+		if ( event.metaKey || event.ctrlKey ) {
+
+			this.release();
+			return;
+
+		}
+
+		this._factor = speedFactor( event );
+		if ( ! KEY_DIRECTIONS[ event.code ] ) return;
+
+		event.preventDefault();
+		if ( this._held.has( event.code ) ) return;
+		this._held.add( event.code );
+
+		// After the key is held: a woken loop runs its first frame inside this dispatch.
+		if ( this._held.size === 1 ) {
+
+			this._lastTime = performance.now();
+			this.dispatchEvent( _startEvent );
+
+		}
+
+	}
+
+	_onKeyUp( event ) {
+
+		this._factor = speedFactor( event );
+		this._held.delete( event.code );
+
+	}
+
+	/** Let go of every held key. */
+	release() {
+
+		this._held.clear();
+		this._factor = 1;
+
+	}
+
+	_onPointerDown( event ) {
+
+		if ( ! this.active || event.button !== 0 || ! event.isPrimary ) return;
+		this._drag = { id: event.pointerId, x: event.clientX, y: event.clientY };
+		this.domElement.setPointerCapture?.( event.pointerId );
+
+	}
+
+	_onPointerMove( event ) {
+
+		const drag = this._drag;
+		if ( ! drag || event.pointerId !== drag.id ) return;
+
+		const dx = event.clientX - drag.x;
+		const dy = event.clientY - drag.y;
+		drag.x = event.clientX;
+		drag.y = event.clientY;
+		if ( this.active && ( dx || dy ) ) this._look( dx, dy );
+
+	}
+
+	_onPointerUp( event ) {
+
+		if ( this._drag?.id !== event.pointerId ) return;
+		this._drag = null;
+		this.domElement.releasePointerCapture?.( event.pointerId );
+
+	}
+
+}

package/src/managers/helpers/OutlineHelper.js

@@ -28,12 +28,22 @@ export class OutlineHelper {
 
 		this.layer = 'scene';
 		this._enabled = true;
+		this._scene = scene;
+		this._camera = camera;
+		this._build( [] );
+
+	}
+
+	// OutlineNode reads the camera's type once, as it builds its depth test.
+	_build( selectedObjects ) {
+
+		this._orthographic = this._camera.isOrthographicCamera === true;
 
 		// Outline node (handles its own multi-pass rendering via updateBefore).
 		// It sizes its render targets from the drawing buffer of whatever renderer
 		// draws it — the view overlay surface — so no size override is needed.
-		this._outlineNode = outline( scene, camera, {
-			selectedObjects: [],
+		this._outlineNode = outline( this._scene, this._camera, {
+			selectedObjects,
 			edgeThickness: uniform( 1.0 ),
 			edgeGlow: uniform( 0.0 ),
 		} );
@@ -98,6 +108,16 @@ export class OutlineHelper {
 
 		if ( ! this.visible ) return;
 
+		if ( this._camera.isOrthographicCamera !== this._orthographic ) {
+
+			// dispose() empties the list it was given.
+			const selected = [ ...this._outlineNode.selectedObjects ];
+			this._outlineNode.dispose();
+			this._material.dispose();
+			this._build( selected );
+
+		}
+
 		const prevAutoClear = renderer.autoClear;
 		renderer.autoClear = false;
 		renderer.setRenderTarget( null );

package/src/managers/timeline/CameraTrack.js

@@ -0,0 +1,235 @@
+import { InterpolateSmooth, MathUtils, NumberKeyframeTrack, Vector3, VectorKeyframeTrack } from 'three';
+
+/**
+ * @typedef {Object} CameraPose
+ * @property {Vector3} position
+ * @property {Vector3} target - what the camera looks at
+ * @property {number} fov - vertical, degrees
+ * @property {number} orthoHeight - the view's height while orthographic, world units
+ */
+
+/** @typedef {CameraPose & { id: number, time: number }} CameraKey */
+
+// Keys closer than this in time are spread to it: an interval of zero divides by zero.
+const MIN_KEY_GAP = 1e-3;
+// Where a new key lands after the last one.
+const KEY_SPACING_SECONDS = 2;
+
+const smooth = ( Track, name, times, values ) => new Track( name, times, values, InterpolateSmooth ).createInterpolant();
+
+/**
+ * The camera's keyframes: each a view at a time, in seconds. Between keys the camera glides along a
+ * curve through their positions while looking along one through their targets; outside them it holds.
+ * The orthographic height blends in log space, so a zoom reads as steady.
+ */
+export class CameraTrack {
+
+	/**
+	 * @param {import('../CameraManager.js').CameraManager} cameraManager - where views come from and go
+	 * @param {Function} [onChange] - after keys are added, moved, changed or removed
+	 */
+	constructor( cameraManager, onChange ) {
+
+		this._cameraManager = cameraManager;
+		this._onChange = onChange;
+
+		/** @type {CameraKey[]} sorted by time */
+		this.keys = [];
+		this._nextId = 1;
+		this._interpolants = null;
+
+	}
+
+	/** Two keys or more: one is only a still view. */
+	get animates() {
+
+		return this.keys.length > 1;
+
+	}
+
+	/** Seconds from 0 to the last key. */
+	get duration() {
+
+		return this.keys.length ? this.keys[ this.keys.length - 1 ].time : 0;
+
+	}
+
+	/**
+	 * Keys the current view, KEY_SPACING_SECONDS after the last key unless given a time.
+	 * @param {number} [time]
+	 * @returns {CameraKey}
+	 */
+	addKey( time = this.keys.length ? this.duration + KEY_SPACING_SECONDS : 0 ) {
+
+		return this.add( this._cameraManager.captureView(), time );
+
+	}
+
+	/** Gives a key the current view, at the same time. */
+	updateKey( id ) {
+
+		this.update( id, this._cameraManager.captureView() );
+
+	}
+
+	/**
+	 * Puts the camera where the track has it at `time`.
+	 * @returns {boolean} whether there was a key to go to
+	 */
+	seek( time ) {
+
+		const pose = this.sample( time );
+		if ( pose ) this._cameraManager.applyPose( pose );
+		return !! pose;
+
+	}
+
+	/**
+	 * @param {CameraPose} pose - copied
+	 * @param {number} time
+	 * @returns {CameraKey}
+	 */
+	add( pose, time ) {
+
+		const key = { id: this._nextId ++, time, ...copyPose( pose ) };
+		this.keys.push( key );
+		this._changed();
+		return key;
+
+	}
+
+	/** Gives the key a new pose, at the same time. */
+	update( id, pose ) {
+
+		const key = this.get( id );
+		if ( ! key ) return;
+		Object.assign( key, copyPose( pose ) );
+		this._changed();
+
+	}
+
+	setTime( id, time ) {
+
+		const key = this.get( id );
+		if ( ! key || ! ( time >= 0 ) ) return;
+		key.time = time;
+		this._changed();
+
+	}
+
+	remove( id ) {
+
+		const count = this.keys.length;
+		this.keys = this.keys.filter( key => key.id !== id );
+		if ( this.keys.length !== count ) this._changed();
+
+	}
+
+	clear() {
+
+		if ( ! this.keys.length ) return;
+		this.keys = [];
+		this._changed();
+
+	}
+
+	/** The keys as plain data, for a saved session. */
+	serialize() {
+
+		return this.keys.map( ( { time, position, target, fov, orthoHeight } ) => ( { time, position: position.toArray(), target: target.toArray(), fov, orthoHeight } ) );
+
+	}
+
+	/** Replaces every key with the ones {@link serialize} described. */
+	restore( keys ) {
+
+		this.keys = ( keys ?? [] ).map( key => ( {
+			id: this._nextId ++,
+			time: key.time,
+			position: new Vector3().fromArray( key.position ),
+			target: new Vector3().fromArray( key.target ),
+			fov: key.fov,
+			orthoHeight: key.orthoHeight,
+		} ) );
+		this._changed();
+
+	}
+
+	dispose() {
+
+		this._cameraManager = this._onChange = null;
+
+	}
+
+	get( id ) {
+
+		return this.keys.find( key => key.id === id );
+
+	}
+
+	/**
+	 * The pose at `time`, in seconds; null without keys.
+	 * @param {number} time
+	 * @param {CameraPose} [out]
+	 * @returns {?CameraPose}
+	 */
+	sample( time, out = { position: new Vector3(), target: new Vector3(), fov: 0, orthoHeight: 0 } ) {
+
+		if ( ! this.keys.length ) return null;
+
+		const { position, target, fov, logHeight, start, end } = this._interpolants ??= this._build();
+		const at = MathUtils.clamp( time, start, end );
+		out.position.fromArray( position.evaluate( at ) );
+		out.target.fromArray( target.evaluate( at ) );
+		out.fov = fov.evaluate( at )[ 0 ];
+		out.orthoHeight = Math.exp( logHeight.evaluate( at )[ 0 ] );
+		return out;
+
+	}
+
+	_build() {
+
+		const times = [];
+		for ( const key of this.keys ) times.push( times.length ? Math.max( key.time, times[ times.length - 1 ] + MIN_KEY_GAP ) : key.time );
+		const start = times[ 0 ];
+		const end = times[ times.length - 1 ];
+
+		// Each end gets a key mirrored past it, so the curve leaves the first key and reaches the last at
+		// rest. three's ZeroSlopeEnding would flatten only the start.
+		let keys = this.keys;
+		if ( keys.length > 1 ) {
+
+			const n = keys.length;
+			times.unshift( 2 * start - times[ 1 ] );
+			times.push( 2 * end - times[ n - 1 ] );
+			keys = [ keys[ 1 ], ...keys, keys[ n - 2 ] ];
+
+		}
+
+		const vectors = pick => keys.flatMap( key => pick( key ).toArray() );
+		return {
+			start,
+			end,
+			position: smooth( VectorKeyframeTrack, '.position', times, vectors( key => key.position ) ),
+			target: smooth( VectorKeyframeTrack, '.target', times, vectors( key => key.target ) ),
+			fov: smooth( NumberKeyframeTrack, '.fov', times, keys.map( key => key.fov ) ),
+			logHeight: smooth( NumberKeyframeTrack, '.orthoHeight', times, keys.map( key => Math.log( key.orthoHeight ) ) ),
+		};
+
+	}
+
+	_changed() {
+
+		this.keys.sort( ( a, b ) => a.time - b.time );
+		this._interpolants = null;
+		this._onChange?.();
+
+	}
+
+}
+
+function copyPose( { position, target, fov, orthoHeight } ) {
+
+	return { position: position.clone(), target: target.clone(), fov, orthoHeight };
+
+}

package/src/managers/timeline/TimelineManager.js

@@ -0,0 +1,146 @@
+import { EventDispatcher, MathUtils, Timer } from 'three';
+import { EngineEvents } from '../../EngineEvents.js';
+import { CameraTrack } from './CameraTrack.js';
+
+/**
+ * The authored animation: keyframed tracks on one time axis, in seconds, of which the camera's
+ * ({@link CameraTrack}) is the first. A model's own clips stay with the AnimationManager.
+ */
+export class TimelineManager extends EventDispatcher {
+
+	/**
+	 * @param {Object} deps
+	 * @param {import('../CameraManager.js').CameraManager} deps.cameraManager
+	 * @param {Function} deps.onReset - restarts accumulation and wakes the frame loop
+	 */
+	constructor( { cameraManager, onReset } ) {
+
+		super();
+
+		this._cameraManager = cameraManager;
+		this._onReset = onReset;
+
+		this.camera = new CameraTrack( cameraManager, () => this._changed( 'camera' ) );
+
+		this._playback = null;
+		this._timer = new Timer();
+		// A hidden page's time is not played.
+		if ( typeof document !== 'undefined' ) this._timer.connect( document );
+
+	}
+
+	/** Seconds to the last key of any track. */
+	get duration() {
+
+		return this.camera.duration;
+
+	}
+
+	get animates() {
+
+		return this.camera.animates;
+
+	}
+
+	/**
+	 * Puts the scene where the timeline has it at `time`.
+	 * @param {number} time - seconds
+	 * @returns {boolean} whether anything moved
+	 */
+	seek( time ) {
+
+		return this.camera.seek( time );
+
+	}
+
+	/**
+	 * Runs the timeline in the viewport from the start, with the camera controls locked. Resolves when
+	 * it ends or {@link stop} is called; the scene stays where it got to.
+	 * @returns {Promise<void>}
+	 */
+	play() {
+
+		this.stop();
+		return new Promise( resolve => {
+
+			const controls = this._cameraManager.controls;
+			this._playback = { elapsed: 0, resolve, controlsEnabled: controls.enabled };
+			controls.enabled = false;
+			this._timer.reset();
+			this._changed();
+			this._onReset?.();
+
+		} );
+
+	}
+
+	stop() {
+
+		const playback = this._playback;
+		if ( ! playback ) return;
+		this._playback = null;
+		this._cameraManager.controls.enabled = playback.controlsEnabled;
+		this._changed();
+		playback.resolve();
+
+	}
+
+	get isPlaying() {
+
+		return !! this._playback;
+
+	}
+
+	/** Per frame, before the camera controls update. */
+	update() {
+
+		const playback = this._playback;
+		if ( ! playback ) return;
+
+		this._timer.update();
+		playback.elapsed += this._timer.getDelta();
+		const time = MathUtils.clamp( playback.elapsed, 0, this.duration );
+		this.seek( time );
+		if ( time >= this.duration ) this.stop();
+
+	}
+
+	/** Every track's keys as plain data, for a saved session. */
+	serialize() {
+
+		return { camera: this.camera.serialize() };
+
+	}
+
+	restore( state ) {
+
+		this.stop();
+		this.camera.restore( state?.camera );
+
+	}
+
+	/** Drops every key: they belonged to the scene being replaced. */
+	clear() {
+
+		this.stop();
+		this.camera.clear();
+
+	}
+
+	dispose() {
+
+		this.stop();
+		this._timer.dispose();
+		this.camera.dispose();
+		this._cameraManager = this._onReset = null;
+
+	}
+
+	/** @param {string} [track] - whose keys changed; none for playback */
+	_changed( track ) {
+
+		this.dispatchEvent( { type: EngineEvents.TIMELINE_CHANGED, track } );
+
+	}
+
+}

package/src/version.js

@@ -0,0 +1,3 @@
+import { version } from '../package.json';
+
+export const VERSION = version;