Weapons/ToolGun/SnapGrid.cs

World-space snap grid overlay for the toolgun. Computes snapped corner positions from the hovered surface plane and draws a grid mesh through a SceneDynamicObject, fitted to prop bounds or a projected world patch. Partial class, with mesh-surface helpers defined elsewhere.

/// <summary>
/// Manages a world-space snap grid overlay projected onto a surface plane.
/// </summary>
public sealed partial class SnapGrid
{
	public float CellSize { get; set; }
	public float MaskRadius { get; set; }

	/// <summary>
	/// Fallback half-extent used when the hovered object has no usable bounds.
	/// </summary>
	public float GridSize { get; set; }

	[ConVar( "sandbox.snapgrid.nofade", ConVarFlags.Cheat )]
	private static bool NoFade { get; set; } = false;

	public SnapGrid( float cellSize = 4f, float maskRadius = 64f, float gridSize = 48f )
	{
		CellSize = cellSize;
		MaskRadius = maskRadius;
		GridSize = gridSize;
	}

	private sealed class SnapGridSceneObject : SceneDynamicObject
	{
		public SnapGridSceneObject( SceneWorld world ) : base( world )
		{
			Transform = Transform.Zero;
			Flags.IsOpaque = false;
			Flags.IsTranslucent = true;
			Flags.CastShadows = false;
			RenderLayer = SceneRenderLayer.OverlayWithDepth;
		}

		public void WriteSurface( List<Vertex> vertices )
		{
			Bounds = BBox.FromPoints( vertices.Select( v => v.Position ) );
			Init( Graphics.PrimitiveType.Triangles );
			AddVertex( System.Runtime.InteropServices.CollectionsMarshal.AsSpan( vertices ) );
		}

		public void Write( Vector3 faceOrigin, Vector3 faceRight, Vector3 faceUp, Vector2 faceHalfExtents )
		{
			var halfW = faceHalfExtents.x;
			var halfH = faceHalfExtents.y;

			// The quad follows the surface bounds, independently of the grid's anchor.
			var quadCenter = faceOrigin;

			var v00 = quadCenter - faceRight * halfW - faceUp * halfH;
			var v10 = quadCenter + faceRight * halfW - faceUp * halfH;
			var v11 = quadCenter + faceRight * halfW + faceUp * halfH;
			var v01 = quadCenter - faceRight * halfW + faceUp * halfH;

			Bounds = BBox.FromPositionAndSize( quadCenter, MathF.Sqrt( halfW * halfW + halfH * halfH ) * 2f );

			Span<Vertex> verts = stackalloc Vertex[6]
			{
				new Vertex( v00 ),
				new Vertex( v11 ),
				new Vertex( v10 ),
				new Vertex( v00 ),
				new Vertex( v01 ),
				new Vertex( v11 ),
			};

			Init( Graphics.PrimitiveType.Triangles );
			AddVertex( verts );
		}
	}

	private SnapGridSceneObject _sceneObj;
	private Material _material;

	private Vector3 _cachedOrigin;
	private Vector3 _worldPatchCenter;
	private Vector3 _cachedNormal;
	private Vector3 _cachedRight;
	private Vector3 _cachedUp;
	private Vector2 _cachedHalfExtents;
	private GameObject _cachedObject;
	private bool _hasPlane;
	private Vertex[] _snapVertices;
	private uint[] _snapIndices;

	/// <summary>
	/// The snapped world-space position of the highlighted corner
	/// </summary>
	public Vector3 LastSnapWorldPos { get; private set; }
	public Vector3 LastSnapWorldNormal { get; private set; }
	public bool HasValidSnap { get; private set; }

	/// <summary>
	/// Returns the nearest grid corner index (cx, cy) and its world-space position,
	/// given the face plane in world space and the aim world position.
	/// </summary>
	public static (int cx, int cy, Vector3 snapPos) ComputeSnap(
		Vector3 faceOriginWs,
		Vector3 faceRightWs,
		Vector3 faceUpWs,
		float cellSize,
		Vector3 aimPosWs )
	{
		var offset = aimPosWs - faceOriginWs;
		var cx = (int)MathF.Round( Vector3.Dot( offset, faceRightWs ) / cellSize );
		var cy = (int)MathF.Round( Vector3.Dot( offset, faceUpWs ) / cellSize );

		var snapPos = faceOriginWs + faceRightWs * (cx * cellSize) + faceUpWs * (cy * cellSize);
		return (cx, cy, snapPos);
	}

	/// <summary>
	/// Updates the collision-based snap target and render-mesh overlay.
	/// After calling, read <see cref="LastSnapWorldPos"/> for a snapped position
	/// </summary>
	public void Update( SceneWorld world, GameObject hoveredObject, Vector3 aimWorldPos, Vector3 hitNormalWorld )
	{
		if ( !_sceneObj.IsValid() )
		{
			_material ??= Material.FromShader( "shaders/snap_grid.shader" );
			_sceneObj = new SnapGridSceneObject( world ) { Material = _material };
		}

		_sceneObj.RenderingEnabled = true;

		// Refresh the surface frame to follow moving props and stepped faces.
		var faceNormal = hitNormalWorld.Normal;
		var isWorld = hoveredObject.Tags.Has( "world" );
		if ( !isWorld )
		{
			var renderer = hoveredObject.GetComponentInChildren<ModelRenderer>( false );
			var rotation = renderer.IsValid() ? renderer.WorldRotation : hoveredObject.WorldRotation;
			var n = rotation.Inverse * faceNormal;
			var x = MathF.Abs( n.x ); var y = MathF.Abs( n.y ); var z = MathF.Abs( n.z );
			var axis = z >= x && z >= y ? new Vector3( 0, 0, MathF.Sign( n.z ) )
				: x >= y ? new Vector3( MathF.Sign( n.x ), 0, 0 ) : new Vector3( 0, MathF.Sign( n.y ), 0 );
			faceNormal = rotation * axis;
		}
		// Object planes are refreshed so translated, scaled and stepped surfaces stay aligned.

		if ( isWorld )
		{
			UpdateWorldPlane( hoveredObject, aimWorldPos, faceNormal );
		}
		else
		{
			_cachedNormal = faceNormal;
			_cachedObject = hoveredObject;

			var (obbCenter, obbHalfExtents, obbRotation, obbValid) = GetObjectOBB( hoveredObject );

			if ( obbValid )
			{
				// Align the grid so its "up" direction matches the object's world-space up
				// projected onto the face plane. This orients grid lines with the object's
				// natural rotation on every face, including tilted surfaces.
				var objUp = obbRotation * Vector3.Up;
				var dotUp = Vector3.Dot( objUp, faceNormal );

				if ( MathF.Abs( dotUp ) < 0.99f )
				{
					// Project the object's up onto the face plane and use it as the grid up.
					_cachedUp    = (objUp - faceNormal * dotUp).Normal;
					_cachedRight = Vector3.Cross( faceNormal, _cachedUp ).Normal;
				}
				else
				{
					// Degenerate: object's up is nearly parallel to the face normal
					// (e.g., hovering the top/bottom face of an upright object).
					// Fall back to the OBB axis most parallel to the face plane.
					var a0 = obbRotation * new Vector3( 1, 0, 0 );
					var a1 = obbRotation * new Vector3( 0, 1, 0 );
					var a2 = obbRotation * new Vector3( 0, 0, 1 );
					var d0 = MathF.Abs( Vector3.Dot( a0, faceNormal ) );
					var d1 = MathF.Abs( Vector3.Dot( a1, faceNormal ) );
					var d2 = MathF.Abs( Vector3.Dot( a2, faceNormal ) );
					var refAxis = d0 <= d1 && d0 <= d2 ? a0 : d1 <= d2 ? a1 : a2;
					_cachedRight = (refAxis - faceNormal * Vector3.Dot( refAxis, faceNormal )).Normal;
					_cachedUp    = Vector3.Cross( _cachedRight, faceNormal ).Normal;
				}

				_cachedOrigin = obbCenter;
				_cachedHalfExtents = ProjectedHalfExtents( obbHalfExtents, obbRotation, _cachedRight, _cachedUp );
			}
			else
			{
				// Fallback: generic tangent for world geometry.
				var refAxis = MathF.Abs( Vector3.Dot( faceNormal, Vector3.Up ) ) > 0.9f
					? Vector3.Forward
					: Vector3.Up;
				_cachedRight = Vector3.Cross( faceNormal, refAxis ).Normal;
				_cachedUp = Vector3.Cross( _cachedRight, faceNormal ).Normal;
				_cachedOrigin = aimWorldPos;
				_cachedHalfExtents = new Vector2( GridSize, GridSize );
			}

			_hasPlane = true;
		}

		var meshSurface = !isWorld && BuildCollisionSurface( hoveredObject, faceNormal );
		var planarSurface = meshSurface && TryPlanarSurface( aimWorldPos );
		var roundSurface = meshSurface && !planarSurface && TryRoundSurface( hoveredObject );
		if ( roundSurface ) faceNormal = _cachedNormal;
		if ( meshSurface && !planarSurface && !roundSurface ) SelectConnectedSurface( aimWorldPos );

		var halfExtents = _cachedHalfExtents;

		// Scale down cell size so at least one cell fits within the object's face.
		var cellSize = CellSize;
		var minHalf = MathF.Min( halfExtents.x, halfExtents.y );
		while ( minHalf < cellSize && cellSize > 0.1f )
			cellSize *= 0.5f;

		// Anchor prop grids to the fitted face edge rather than an arbitrary model centre.
		var gridOrigin = isWorld || roundSurface ? _cachedOrigin : _cachedOrigin - _cachedRight * halfExtents.x - _cachedUp * halfExtents.y;

		// Fit complete cells between the selected rectangular face boundaries.
		var spacing = new Vector2( cellSize, cellSize );
		if ( !isWorld && !roundSurface )
		{
			spacing.x = halfExtents.x * 2f / Math.Max( 1, (int)MathF.Round( halfExtents.x * 2f / cellSize ) );
			spacing.y = halfExtents.y * 2f / Math.Max( 1, (int)MathF.Round( halfExtents.y * 2f / cellSize ) );
		}
		// Compute the nearest snap line
		var (_, _, snapPos) = ComputeSnap( gridOrigin, _cachedRight, _cachedUp, cellSize, aimWorldPos );
		if ( !isWorld && !roundSurface )
		{
			var offset = aimWorldPos - gridOrigin;
			snapPos = gridOrigin
				+ _cachedRight * (MathF.Round( Vector3.Dot( offset, _cachedRight ) / spacing.x ) * spacing.x)
				+ _cachedUp * (MathF.Round( Vector3.Dot( offset, _cachedUp ) / spacing.y ) * spacing.y);
		}
		if ( roundSurface ) snapPos = ComputeRoundSnap( aimWorldPos, cellSize );
		HasValidSnap = true;
		LastSnapWorldNormal = faceNormal;
		if ( meshSurface )
		{
			snapPos = SnapToSurface( snapPos, aimWorldPos, faceNormal, gridOrigin, cellSize, spacing, roundSurface );
		}
		LastSnapWorldPos = snapPos;
		_sceneObj.RenderingEnabled = HasValidSnap;

		// Unfitted surfaces still need a face plane, not the object's centre plane.
		// Translate only in the normal direction so the lattice remains stable.
		if ( !isWorld && !planarSurface && !roundSurface )
		{
			var planeOffset = faceNormal * Vector3.Dot( snapPos - _cachedOrigin, faceNormal );
			_cachedOrigin += planeOffset;
			gridOrigin += planeOffset;
		}
		var boundsOrigin = isWorld ? _worldPatchCenter : _cachedOrigin;
		if ( meshSurface ) _sceneObj.WriteSurface( _surfaceVertices );
		else _sceneObj.Write( boundsOrigin, _cachedRight, _cachedUp, halfExtents );
		_sceneObj.Attributes.Set( "MeshSurface", meshSurface ? 1f : 0f );
		_sceneObj.Attributes.Set( "PlanarSurface", planarSurface ? 1f : 0f );
		_sceneObj.Attributes.Set( "RoundSurface", roundSurface ? 1f : 0f );
		_sceneObj.Attributes.Set( "RoundRadius", _roundRadius );
		_sceneObj.Attributes.Set( "AngleStep", _roundAngleStep );

		_sceneObj.Attributes.Set( "SnapPoint", snapPos );
		_sceneObj.Attributes.Set( "SnapNormal", LastSnapWorldNormal );
		_sceneObj.Attributes.Set( "GridOrigin", gridOrigin );
		_sceneObj.Attributes.Set( "BoundsOrigin", boundsOrigin );
		_sceneObj.Attributes.Set( "GridRight", _cachedRight );
		_sceneObj.Attributes.Set( "GridUp", _cachedUp );
		_sceneObj.Attributes.Set( "AimPoint", aimWorldPos );
		_sceneObj.Attributes.Set( "MaskRadius", NoFade ? float.MaxValue : MaskRadius );
		_sceneObj.Attributes.Set( "HalfExtents", halfExtents );
		_sceneObj.Attributes.Set( "CellSize", cellSize );
		_sceneObj.Attributes.Set( "CellSpacing", spacing );
		_sceneObj.Attributes.Set( "SnapCornerX", Vector3.Dot( snapPos - gridOrigin, _cachedRight ) / spacing.x );
		_sceneObj.Attributes.Set( "SnapCornerY", Vector3.Dot( snapPos - gridOrigin, _cachedUp ) / spacing.y );
	}

	private static bool InsideTriangle( Vector3 point, Vector3 a, Vector3 b, Vector3 c, Vector3 normal )
	{
		const float tolerance = 0.001f;
		return Vector3.Dot( Vector3.Cross( b - a, point - a ), normal ) >= -tolerance
			&& Vector3.Dot( Vector3.Cross( c - b, point - b ), normal ) >= -tolerance
			&& Vector3.Dot( Vector3.Cross( a - c, point - c ), normal ) >= -tolerance;
	}
	private void UpdateWorldPlane( GameObject hoveredObject, Vector3 aimPos, Vector3 normal )
	{
		var planeChanged = !_hasPlane || hoveredObject != _cachedObject ||
			Vector3.Dot( normal, _cachedNormal ) < 0.9999f ||
			MathF.Abs( Vector3.Dot( aimPos - _cachedOrigin, _cachedNormal ) ) > 0.01f;

		if ( planeChanged )
		{
			_cachedObject = hoveredObject;
			_cachedNormal = normal;
			var reference = MathF.Abs( Vector3.Dot( normal, Vector3.Up ) ) > 0.9f ? Vector3.Forward : Vector3.Up;
			_cachedRight = Vector3.Cross( normal, reference ).Normal;
			_cachedUp = Vector3.Cross( _cachedRight, normal ).Normal;
			// Project the world origin so returning to this plane uses the same lattice.
			_cachedOrigin = ProjectOntoPlane( Vector3.Zero, aimPos, normal );
			_worldPatchCenter = _cachedOrigin;
			_hasPlane = true;
		}

		// Leave enough margin for the cursor's fade mask before moving the patch.
		var halfSize = MathF.Ceiling( MathF.Max( GridSize, MaskRadius + CellSize ) * 2f / CellSize ) * CellSize;
		_cachedHalfExtents = new Vector2( halfSize, halfSize );
		var offset = aimPos - _worldPatchCenter;
		var u = Vector3.Dot( offset, _cachedRight );
		var v = Vector3.Dot( offset, _cachedUp );
		var threshold = halfSize - MaskRadius - CellSize;
		if ( planeChanged || MathF.Abs( u ) > threshold || MathF.Abs( v ) > threshold )
		{
			var anchorOffset = aimPos - _cachedOrigin;
			var cellU = MathF.Round( Vector3.Dot( anchorOffset, _cachedRight ) / CellSize );
			var cellV = MathF.Round( Vector3.Dot( anchorOffset, _cachedUp ) / CellSize );
			_worldPatchCenter = _cachedOrigin + _cachedRight * (cellU * CellSize) + _cachedUp * (cellV * CellSize);
		}
	}

	/// <summary>
	/// Hide the overlay
	/// </summary>
	public void Hide()
	{
		if ( _sceneObj != null && _sceneObj.IsValid() )
			_sceneObj.RenderingEnabled = false;
		_hasPlane = false;
	}

	// ---------------------------------------------------------------------------
	// Helpers

	/// <summary>
	/// Returns the OBB (oriented bounding box) of <paramref name="go"/> in world space.
	/// Prefers model-local bounds (tight, rotation-aware) over collider world AABB.
	/// </summary>
	private static (Vector3 Center, Vector3 HalfExtents, Rotation Rotation, bool Valid) GetObjectOBB( GameObject go )
	{
		var worldTx = go.WorldTransform;
		var rot = worldTx.Rotation;
		var scale = worldTx.Scale;

		// Try model-local bounds first — these are tight and unaffected by world rotation.
		BBox? localBox = null;
		var mr = go.GetComponentInChildren<ModelRenderer>( false );
		if ( mr != null && mr.Model != null )
			{
			localBox = mr.Model.PhysicsBounds;
			worldTx = mr.WorldTransform;
			rot = worldTx.Rotation;
			scale = worldTx.Scale;
		}

		if ( localBox == null )
		{
			var smr = go.GetComponentInChildren<SkinnedModelRenderer>( false );
			if ( smr != null && smr.Model != null )
				localBox = smr.Model.PhysicsBounds;
		}

		if ( localBox != null )
		{
			var lb = localBox.Value;
			if ( lb.Size.Length > 0.1f )
			{
				var center = worldTx.PointToWorld( lb.Center );
				var halfExtents = lb.Size * 0.5f * new Vector3( MathF.Abs( scale.x ), MathF.Abs( scale.y ), MathF.Abs( scale.z ) );
				return (center, halfExtents, rot, true);
			}
		}

		// Fallback: world AABB from colliders, treated as an identity-rotation OBB.
		var colliders = go.GetComponentsInChildren<Collider>( false, true ).ToArray();
		if ( colliders.Length > 0 )
		{
			var box = colliders[0].GetWorldBounds();
			for ( int i = 1; i < colliders.Length; i++ )
				box = box.AddBBox( colliders[i].GetWorldBounds() );

			if ( box.Size.Length > 0.1f )
				return (box.Center, box.Size * 0.5f, Rotation.Identity, true);
		}

		return (Vector3.Zero, Vector3.Zero, Rotation.Identity, false);
	}

	/// <summary>
	/// Projects <paramref name="point"/> onto the plane defined by <paramref name="planePoint"/> and <paramref name="normal"/>.
	/// </summary>
	private static Vector3 ProjectOntoPlane( Vector3 point, Vector3 planePoint, Vector3 normal )
	{
		return point - normal * Vector3.Dot( point - planePoint, normal );
	}

	/// <summary>
	/// Returns the half-extents of an OBB projected along <paramref name="right"/> and <paramref name="up"/>.
	/// Uses the OBB support function, which correctly handles rotated objects.
	/// </summary>
	private static Vector2 ProjectedHalfExtents( Vector3 obbHalfExtents, Rotation obbRotation, Vector3 right, Vector3 up )
	{
		// Explicitly rotate the three local unit axes into world space to avoid
		// ambiguity with named helpers (Right/Up/Forward vary by coordinate convention).
		var ax = obbRotation * new Vector3( 1, 0, 0 );
		var ay = obbRotation * new Vector3( 0, 1, 0 );
		var az = obbRotation * new Vector3( 0, 0, 1 );
		var e = obbHalfExtents;

		var halfRight = MathF.Abs( e.x * Vector3.Dot( ax, right ) )
					  + MathF.Abs( e.y * Vector3.Dot( ay, right ) )
					  + MathF.Abs( e.z * Vector3.Dot( az, right ) );

		var halfUp = MathF.Abs( e.x * Vector3.Dot( ax, up ) )
				   + MathF.Abs( e.y * Vector3.Dot( ay, up ) )
				   + MathF.Abs( e.z * Vector3.Dot( az, up ) );

		return new Vector2( halfRight, halfUp );
	}

	/// <summary>
	/// Destroys the underlying scene object.
	/// </summary>
	public void Destroy()
	{
		_sceneObj?.Delete();
		_sceneObj = null;
	}
}