Weapons/ToolGun/ToolMode.SnapGrid.cs

Partial class for the toolgun's tool modes that adds a snap grid overlay. Traces the surface under the player's aim, updates a SnapGrid, locks the snap plane while the snap key is held, and steers the camera aim onto the resulting snap point.

public abstract partial class ToolMode
{
	/// <summary>
	/// When true (default), a SnapGrid overlay is shown on the hovered object surface.
	/// Override to return false to opt out.
	/// </summary>
	public virtual bool UseSnapGrid => false;

	/// <summary>
	/// Label for the snap hint, shown whenever this tool uses the snap grid.
	/// </summary>
	public virtual string SnapAction => UseSnapGrid && !AbsorbMouseInput ? "#tool.hint.snap" : null;

	/// <summary>
	/// The active snap grid, updated every frame in <see cref="OnControl"/>.
	/// Null when snap grid is disabled or the tool is inactive.
	/// </summary>
	protected SnapGrid SnapGrid { get; private set; }

	/// <summary>
	/// While snapping, the unsnapped aim driven by the mouse. The grid is traced from this,
	/// and the real camera is steered onto the resulting snap point.
	/// </summary>
	private Angles? _snapFreeAim;

	/// <summary>
	/// True when the snap grid was updated from a valid surface this frame.
	/// </summary>
	private bool _hasSnapTarget;
	private SelectionPoint _snapSelection;
	private SelectionPoint _lockedSnapPlane;
	private bool _snapHeld;
	private bool _snapAimDirty;
	private Vector3 _lockedAimLocal;

	private void DisableSnapGrid()
	{
		SnapGrid?.Destroy();
		SnapGrid = null;
		_snapHeld = false;
		_lockedSnapPlane = default;
		_snapFreeAim = null;
		_hasSnapTarget = false;
	}

	/// <summary>
	/// While hovering an object, hold alt key to keep the camera aim snapped to the grid
	/// </summary>
	public virtual void OnCameraMove( Player player, ref Angles angles )
	{
		// Skip when the mode is absorbing mouse input for its own purposes (e.g. Weld rotation stage).
		if ( AbsorbMouseInput || SnapGrid == null || !Input.Down( "snap" ) )
		{
			_snapFreeAim = null;
			return;
		}

		var currentAngles = player.Controller.EyeAngles;

		_snapAimDirty |= MathF.Abs( angles.pitch ) > 0.00001f || MathF.Abs( angles.yaw ) > 0.00001f;
		var freeAim = (_snapFreeAim ?? currentAngles) + angles;
		freeAim.pitch = freeAim.pitch.Clamp( -89f, 89f );
		_snapFreeAim = freeAim;

		// Resolve this input's target before steering, rather than using the previous frame's point.
		UpdateSnapTarget();

		var desiredAngles = _hasSnapTarget
			? Rotation.LookAt( SnapGrid.LastSnapWorldPos - player.EyeTransform.Position ).Angles()
			: freeAim;

		angles = desiredAngles - currentAngles;
	}

	/// <summary>
	/// The ray the snap grid is traced from, free aim while snapping, otherwise the eyes.
	/// </summary>
	private SelectionPoint TraceSnapGrid()
	{
		var player = Toolgun?.Owner;
		if ( !player.IsValid() ) return default;

		if ( _snapFreeAim is not { } freeAim )
			return TraceFromRay( player.EyeTransform.ForwardRay, 4096, player.GameObject );

		var ray = new Ray( player.EyeTransform.Position, freeAim.Forward );
		return TraceFromRay( ray, 4096, player.GameObject );
	}

	/// <summary>
	/// Override to control which objects show the snap grid. Excludes player geometry by default.
	/// </summary>
	protected virtual bool ShouldDisplaySnapGrid( GameObject go )
	{
		return !go.Tags.Has( "player" );
	}

	public virtual void OnControl()
	{
		UpdateSnapTarget();
		DispatchActions();
	}

	private void UpdateSnapTarget()
	{
		_hasSnapTarget = false;
		if ( !UseSnapGrid || AbsorbMouseInput ) return;

		var held = Input.Down( "snap" );
		if ( !held )
		{
			_snapHeld = false;
			_lockedSnapPlane = default;
		}
		else if ( !_snapHeld )
		{
			// Capture once per press, before mouse input can select another surface.
			_snapHeld = true;
			_lockedSnapPlane = _snapSelection.IsValid() ? _snapSelection : TraceSnapGrid();
			if ( _lockedSnapPlane.IsValid() ) _lockedAimLocal = _lockedSnapPlane.LocalTransform.Position;
		}

		var preview = held ? _lockedSnapPlane : TraceSnapGrid();
		if ( held && preview.IsValid() )
		{
			var player = Toolgun?.Owner;
			if ( !player.IsValid() ) return;
			var plane = _lockedSnapPlane.WorldTransform();
			var direction = _snapFreeAim?.Forward ?? player.EyeTransform.Forward;
			var denominator = Vector3.Dot( direction, plane.Rotation.Forward );
			if ( _snapAimDirty && MathF.Abs( denominator ) > 0.0001f )
			{
				var distance = Vector3.Dot( plane.Position - player.EyeTransform.Position, plane.Rotation.Forward ) / denominator;
				if ( distance >= 0 && distance <= 4096 )
					_lockedAimLocal = preview.GameObject.WorldTransform.PointToLocal( player.EyeTransform.Position + direction * distance );
			}
			_snapAimDirty = false;
			var local = preview.LocalTransform;
			local.Position = _lockedAimLocal;
			preview.LocalTransform = local;
		}
		_hasSnapTarget = preview.IsValid() && ShouldDisplaySnapGrid( preview.GameObject );
		if ( _hasSnapTarget )
		{
			SnapGrid ??= new SnapGrid();
			SnapGrid.Update( Scene.SceneWorld, preview.GameObject, preview.WorldPosition(), preview.WorldTransform().Rotation.Forward );
			if ( !SnapGrid.HasValidSnap )
			{
				_hasSnapTarget = false;
				return;
			}
			var snapped = preview.WorldTransform();
			snapped.Position = SnapGrid.LastSnapWorldPos;
			snapped.Rotation = Rotation.LookAt( SnapGrid.LastSnapWorldNormal );
			preview.LocalTransform = preview.GameObject.WorldTransform.ToLocal( snapped );
			_snapSelection = preview;
		}
		else
		{
			SnapGrid?.Hide();
			if ( !held ) _snapSelection = default;
		}
	}
}