Game/Entity/CameraEntity.Tracking.cs

Partial CameraEntity class handling camera target tracking. Finds a nearby Player, Npc, Rigidbody or the owner, smoothly aims and zooms at it with an exponentially damped rotation and fov, and drives a child head bone to the aim direction.

using Sandbox.Npcs;

public enum CameraTrackingTarget
{
	[Title( "#entity.camera_tracking.owner" )] Owner,
	[Title( "#entity.camera_tracking.player" )] NearestPlayer,
	[Title( "#entity.camera_tracking.npc" )] NearestNpc,
	[Title( "#entity.camera_tracking.player_npc" )] NearestPlayerOrNpc,
	[Title( "#entity.camera_tracking.entity" )] NearestEntity
}

public sealed partial class CameraEntity
{
	[Property, ClientEditable, ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" )]
	public bool Tracking { get; set; }

	[Property, ClientEditable, Title( "#entity.property.camera_tracking_target" ), ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" )]
	public CameraTrackingTarget TrackingTarget { get; set; } = CameraTrackingTarget.Owner;

	[Property, ClientEditable, Range( 0.1f, 20f ), Title( "#entity.property.camera_tracking_speed" ), Description( "#entity.description.camera_tracking_speed" ), ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" )]
	public float TrackingLerpSpeed { get; set; } = 5f;

	[Property, ClientEditable, Range( 0f, 8192f ), Title( "#entity.property.camera_tracking_range" ), Description( "#entity.description.camera_tracking_range" ), ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" )]
	public float TrackingRange { get; set; } = 2048f;

	[Property, ClientEditable, Title( "#entity.property.camera_tracking_return" ), Description( "#entity.description.camera_tracking_return" ), ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" )]
	public bool ReturnToOriginal { get; set; } = true;

	[Property, ClientEditable, Title( "#entity.property.camera_tracking_offset" ), Description( "#entity.description.camera_tracking_offset" ), ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" )]
	public Vector3 TrackingOffset { get; set; }

	[Property, ClientEditable, Title( "#entity.property.camera_tracking_zoom" ), Description( "#entity.description.camera_tracking_zoom" ), ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" )]
	public bool ZoomToFit { get; set; }

	[Property, ClientEditable, Range( -60f, 60f ), Title( "#entity.property.camera_tracking_zoom_offset" ), Description( "#entity.description.camera_tracking_zoom_offset" ), ToggleGroup( "Tracking", Label = "#entity.group.camera_tracking" ), ShowIf( nameof( ZoomToFit ), true )]
	public float ZoomOffset { get; set; }

	Component _trackingTarget;
	Vector3 _smoothedTarget;
	float _trackingFov;
	Rotation _trackingRotation;
	Transform _trackingView;
	bool _trackingInitialized;
	RealTimeSince _sinceTargetSearch = 999f;
	CameraTrackingTarget _lastTrackingTarget;
	float _lastTrackingRange = -1;

	Transform PhysicalView => Feed.IsValid() ? Feed.PhysicalViewTransform : WorldTransform;

	/// <summary>
	/// The field of view to draw with: zoomed to fit the target while tracking with <see cref="ZoomToFit"/>, else <see cref="Fov"/>.
	/// </summary>
	public float ViewFov => Tracking && _trackingInitialized ? _trackingFov : ClampedFov;

	GameObject _head;
	GameObject Head => _head.IsValid() ? _head : _head = GameObject.Children.FirstOrDefault( x => x.Name == "head" );

	Transform HeadMount( GameObject head ) => new( head.WorldPosition, WorldRotation );

	void ResetTracking()
	{
		_trackingInitialized = false;
		_trackingTarget = null;
		_sinceTargetSearch = 999f;
		if ( Head is { } head && head.IsValid() ) head.LocalRotation = Rotation.Identity;
		if ( Feed.IsValid() ) Feed.UseLensView( ClampedFov );
	}

	void UpdateTracking()
	{
		if ( !Tracking )
		{
			if ( _trackingInitialized ) ResetTracking();
			return;
		}

		var head = Head;
		var hasHead = head.IsValid();
		var mount = hasHead ? HeadMount( head ) : PhysicalView;

		float range = float.IsFinite( TrackingRange ) ? TrackingRange.Clamp( 0f, 8192f ) : 2048f;
		float speed = float.IsFinite( TrackingLerpSpeed ) ? TrackingLerpSpeed.Clamp( 0.1f, 20f ) : 5f;
		float blend = 1f - MathF.Exp( -speed * MathF.Max( Time.Delta, 0f ) );

		bool hasTarget = TryTrackingPoint( _trackingTarget, out var targetPoint, out var targetRadius )
			&& (targetPoint - mount.Position).LengthSquared <= range * range;
		// Keep following the selected actor every frame, but avoid a full scene scan
		// every frame for every camera. Lost/out-of-range targets are replaced immediately.
		if ( _sinceTargetSearch >= 0.15f || _lastTrackingTarget != TrackingTarget || _lastTrackingRange != range
			|| _trackingTarget is not null && !hasTarget )
		{
			_trackingTarget = FindTrackingTarget( mount.Position, range );
			_sinceTargetSearch = 0;
			_lastTrackingTarget = TrackingTarget;
			_lastTrackingRange = range;
			hasTarget = TryTrackingPoint( _trackingTarget, out targetPoint, out targetRadius );
		}

		// aim at a point beside the target, in world space - above a player's head, say
		var offset = TrackingOffset.IsFinite ? TrackingOffset : Vector3.Zero;
		targetPoint += offset;

		if ( !_trackingInitialized )
		{
			_trackingFov = ClampedFov;
			_trackingRotation = mount.Rotation;
			float distance = hasTarget ? MathF.Max( (targetPoint - mount.Position).Length, 32f ) : 256f;
			_smoothedTarget = mount.Position + mount.Forward * distance;
			_trackingInitialized = true;
		}

		if ( hasTarget )
		{
			// Deliberately retain this point across target changes instead of snapping to
			// the newly chosen actor. Exponential interpolation is frame-rate independent.
			_smoothedTarget = _smoothedTarget.LerpTo( targetPoint, blend );
			var direction = _smoothedTarget - mount.Position;
			if ( direction.LengthSquared > 0.01f )
				_trackingRotation = Rotation.Slerp( _trackingRotation, Rotation.LookAt( direction.Normal ), blend );
		}
		else
		{
			if ( ReturnToOriginal )
				_trackingRotation = Rotation.Slerp( _trackingRotation, mount.Rotation, blend );
			// Reacquisition starts from the current aim, including while returning home.
			float distance = MathF.Max( (_smoothedTarget - mount.Position).Length, 32f );
			_smoothedTarget = mount.Position + _trackingRotation.Forward * distance;
		}

		// zoom eases at the same speed as the aim, back out to the set fov when there's nothing to fit.
		// Measured to the target itself, not the offset point beside it
		var fitFov = ZoomToFit && hasTarget ? FitFov( (targetPoint - offset).Distance( mount.Position ), targetRadius ) : ClampedFov;
		_trackingFov = MathX.Lerp( _trackingFov, fitFov, blend );

		if ( hasHead )
		{
			// a world rotation, so it aims right however the body is lying or tumbling
			head.WorldRotation = _trackingRotation;
			_trackingView = PhysicalView;
		}
		else _trackingView = new Transform( mount.Position, _trackingRotation );
	}

	Component FindTrackingTarget( Vector3 origin, float range )
	{
		Component nearest = null;
		float closest = range * range;
		void Consider( Component candidate )
		{
			if ( !TrySearchPoint( candidate, out var point ) ) return;
			float distance = (point - origin).LengthSquared;
			if ( distance > closest || nearest is not null && distance == closest ) return;
			closest = distance;
			nearest = candidate;
		}

		if ( TrackingTarget == CameraTrackingTarget.Owner )
		{
			if ( GetComponent<Ownable>()?.Owner is { } owner ) Consider( Player.FindForConnection( owner ) );
			return nearest;
		}

		var entities = TrackingTarget == CameraTrackingTarget.NearestEntity;
		if ( entities || TrackingTarget is CameraTrackingTarget.NearestPlayer or CameraTrackingTarget.NearestPlayerOrNpc )
			foreach ( var player in Scene.GetAllComponents<Player>() ) Consider( player );
		if ( entities || TrackingTarget is CameraTrackingTarget.NearestNpc or CameraTrackingTarget.NearestPlayerOrNpc )
			foreach ( var npc in Scene.GetAllComponents<Npc>() ) Consider( npc );

		// anything else physical: props, vehicles, contraptions, other cameras. One body per object, not this camera
		if ( entities )
		{
			var seen = new HashSet<GameObject>();
			foreach ( var body in Scene.GetAllComponents<Rigidbody>() )
			{
				var root = body.GameObject.Root;
				if ( root == GameObject.Root || !seen.Add( root ) ) continue;
				if ( root.GetComponent<Player>() is not null || root.GetComponent<Npc>() is not null ) continue;
				Consider( body );
			}
		}

		return nearest;
	}

	/// <summary>
	/// Where a candidate is, for finding the nearest - its origin for a physics object, so a scene full of props doesn't
	/// measure every bounding box a few times a second.
	/// </summary>
	bool TrySearchPoint( Component candidate, out Vector3 point )
	{
		if ( candidate is Rigidbody body && body.IsValid() && body.Active && body.Scene == Scene )
		{
			point = body.GameObject.Root.WorldPosition;
			return point.IsFinite;
		}

		return TryTrackingPoint( candidate, out point, out _ );
	}

	/// <summary>
	/// The point to aim at on a target, and how big it is (the radius of its bounds) for <see cref="ZoomToFit"/>.
	/// </summary>
	bool TryTrackingPoint( Component target, out Vector3 point, out float radius )
	{
		point = default;
		radius = 0f;
		if ( !target.IsValid() || !target.Active || target.Scene != Scene ) return false;
		switch ( target )
		{
			case Player player when player.Health > 0 && player.Controller.IsValid():
				// Track the player's physical eyes, never their remote camera view.
				point = player.EyeTransform.Position;
				radius = BoundsRadius( player.GameObject );
				break;
			case Npc npc when npc.Health > 0:
				if ( npc.Renderer.IsValid() && npc.Renderer.GetAttachment( "eyes" ) is { } eyes )
					point = eyes.Position;
				else if ( npc.Renderer.IsValid() && npc.Renderer.Model is { } model && model.Bounds.Size.IsFinite )
					point = npc.Renderer.WorldTransform.PointToWorld( model.Bounds.Center );
				else point = npc.WorldPosition;
				radius = BoundsRadius( npc.GameObject );
				break;
			case Rigidbody body:
				// the middle of the whole object, not wherever its origin happens to be
				var bounds = body.GameObject.Root.GetBounds();
				point = bounds.Size.IsFinite && bounds.Size.LengthSquared > 0f ? bounds.Center : body.GameObject.Root.WorldPosition;
				radius = bounds.Size.IsFinite ? bounds.Size.Length * 0.5f : 0f;
				break;
			default: return false;
		}
		return point.IsFinite;
	}

	static float BoundsRadius( GameObject go )
	{
		var size = go.GetBounds().Size;
		return size.IsFinite ? size.Length * 0.5f : 0f;
	}

	/// <summary>
	/// The fov that fits a target of this radius at this distance, plus <see cref="ZoomOffset"/>.
	/// </summary>
	float FitFov( float distance, float radius )
	{
		if ( !float.IsFinite( distance ) || !float.IsFinite( radius ) || radius <= 0f ) return ClampedFov;

		// half the angle the target's bounding sphere covers from here - from inside it, as wide as it goes
		var half = distance > radius ? MathF.Asin( radius / distance ) : MathF.PI * 0.5f;

		// the lens's fov runs across the width, and a widescreen frame is shorter than it is wide, so fit the height
		// and a little more so the target isn't touching the edges
		const float aspect = 16f / 9f;
		const float margin = 1.1f;
		var across = 2f * MathF.Atan( MathF.Tan( half ) * aspect ) * (180f / MathF.PI) * margin;

		var zoom = float.IsFinite( ZoomOffset ) ? ZoomOffset.Clamp( -60f, 60f ) : 0f;
		return (across + zoom).Clamp( 1f, 150f );
	}
}