TableTopGizmo.cs

/*
 * Copyright (C) 2020-2023 Tilt Five, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
using UnityEngine;
 
#if UNITY_EDITOR
using UnityEditor;
using System.Collections.Generic;
 
namespace TiltFive
{
    public class TableTopGizmo {
 
        #region Private Structs
 
        private struct GameboardMesh
        {
            public string boardMeshAssetPath;
            public string surfaceMeshChildPath;
            public string borderMeshChildPath;
            public string stageMeshChildPath;
            public string stageCornerMeshChildPath;
 
            public GameObject meshObj;
            public Mesh meshSurface;
            public Mesh meshBorder;
            public Mesh meshStage;
            public Mesh meshStageCorner;
 
            public bool TryLoadMeshes()
            {
                bool allMeshesLoaded = meshObj != null && meshBorder != null && meshSurface != null
                && meshStage != null && meshStageCorner != null;
 
                if (!allMeshesLoaded)
                {
                    LoadGameboardModel(boardMeshAssetPath, surfaceMeshChildPath, borderMeshChildPath,
                        stageMeshChildPath, stageCornerMeshChildPath,
                        out meshObj, out meshSurface, out meshBorder, out meshStage, out meshStageCorner);
                }
                return !allMeshesLoaded;
            }
 
            public void LoadGameboardModel(string meshAssetPath, string surfaceMeshChildPath, string borderMeshChildPath,
            string stageMeshChildPath, string stageCornerMeshChildPath,
            out GameObject meshObj, out Mesh meshSurface, out Mesh meshBorder, out Mesh meshStage, out Mesh meshStageCorner)
            {
                meshObj = AssetDatabase.LoadAssetAtPath<GameObject>(meshAssetPath);
 
                TryGetMesh(surfaceMeshChildPath, out meshSurface);
                TryGetMesh(borderMeshChildPath, out meshBorder);
                TryGetMesh(stageMeshChildPath, out meshStage);
                TryGetMesh(stageCornerMeshChildPath, out meshStageCorner);
            }
 
            private bool TryGetMesh(string meshPath, out Mesh resultMesh)
            {
                var meshTransform = meshObj.transform.Find(meshPath);
                if(meshTransform != null && meshTransform.TryGetComponent<MeshFilter>(out var meshFilter))
                {
                    resultMesh = meshFilter.sharedMesh;
                    return true;
                }
                resultMesh = null;
                return false;
            }
        }
 
        private struct LineSegment
        {
            public LineSegment(Vector3 start, Vector3 end, int LOD)
            {
                this.Start = start;
                this.End = end;
                this.LOD = LOD;
            }
            public Vector3 Start;
            public Vector3 End;
            public int LOD;
        }
 
        private struct GizmoReferenceFrame : System.IDisposable
        {
            private Matrix4x4 previousGizmoMatrix;
 
            public GizmoReferenceFrame(Matrix4x4 temporaryGizmoReferenceFrame)
            {
                previousGizmoMatrix = Gizmos.matrix;
                Gizmos.matrix = temporaryGizmoReferenceFrame;
            }
 
            public void Dispose()
            {
                Gizmos.matrix = previousGizmoMatrix;
            }
        }
 
        private struct GizmoColor : System.IDisposable
        {
            private Color previousGizmoColor;
            public GizmoColor(Color temporaryGizmoColor)
            {
                previousGizmoColor = Gizmos.color;
                Gizmos.color = temporaryGizmoColor;
            }
 
            public GizmoColor(Color temporaryGizmoColor, float alphaOverride)
                : this(new Color(temporaryGizmoColor.r, temporaryGizmoColor.g, temporaryGizmoColor.b, alphaOverride))
            {
            }
 
            public GizmoColor(float r, float g, float b)
                : this(new Color(r,g,b))
            {
            }
 
            public GizmoColor(float r, float g, float b, float a)
                : this(new Color(r, g, b, a))
            {
            }
 
            public void Dispose()
            {
                Gizmos.color = previousGizmoColor;
            }
        }
 
        #endregion Private Structs
 
        private GameboardMesh gameboardMesh_LE = new GameboardMesh()
        {
            boardMeshAssetPath = MeshAssets.GetPathToGameboardMesh(GameboardType.GameboardType_LE),
            surfaceMeshChildPath = "Surface_LE",
            borderMeshChildPath = "Border_LE",
            stageMeshChildPath = "Stage_LE",
            stageCornerMeshChildPath = "Stage_Corner_LE"
        };
 
        private GameboardMesh gameboardMesh_XE = new GameboardMesh()
        {
            boardMeshAssetPath = MeshAssets.GetPathToGameboardMesh(GameboardType.GameboardType_XE),
            surfaceMeshChildPath = "Surface_Flat",
            borderMeshChildPath = "Border_Flat",
            stageMeshChildPath = "Stage_Flat",
            stageCornerMeshChildPath = "Stage_Corner_Flat"
        };
 
        private GameboardMesh gameboardMesh_XE_Raised = new GameboardMesh()
        {
            boardMeshAssetPath = MeshAssets.GetPathToGameboardMesh(GameboardType.GameboardType_XE_Raised),
            surfaceMeshChildPath = "Surface_Raised",
            borderMeshChildPath = "Border_Raised",
            stageMeshChildPath = "Stage_Raised",
            stageCornerMeshChildPath = "Stage_Corner_Raised"
        };
 
        private string logoMeshAssetPath = MeshAssets.GetPathToT5LogoMesh();
        private string logoBorderChildPath = "Circle";
        private string logoLeftCharacterChildPath = "Tilt";
        private string logoRightCharacterChildPath = "Five";
 
        private ScaleSettings scaleSettings;
        private GameBoardSettings gameBoardSettings;
        private float scaleToUWRLD_USTAGE => scaleSettings.GetScaleToWorldSpaceFromGameboardSpace(gameBoardSettings.gameBoardScale);
        private GameBoard.GameboardExtents gameboardExtents = new GameBoard.GameboardExtents(
            GameBoard.GameboardExtents.GAMEBOARD_SIZE_LE);
 
        private float totalGameBoardWidthInMeters =>
            usableGameBoardWidthInMeters + 2f * GameBoard.GameboardExtents.BORDER_WIDTH_IN_METERS;
        private float totalGameBoardLengthInMeters =>
            usableGameBoardLengthInMeters + 2f * GameBoard.GameboardExtents.BORDER_WIDTH_IN_METERS;
 
        private float usableGameBoardWidthInMeters => gameboardExtents.ViewableSpanX.ToMeters;
        private float usableGameBoardLengthInMeters => gameboardExtents.ViewableSpanZ.ToMeters;
 
        private GameboardType gameboardType;
 
        private GameObject logoObj;
        private Mesh meshLogoBorder;
        private Mesh meshLogoLeftCharacter;
        private Mesh meshLogoRightCharacter;
 
        private Mesh meshRuler;
        private List<LineSegment> rulerData;
 
 
        // The lines comprising the board gizmo's unit grid.
        private List<LineSegment> xGridLines;
        private List<LineSegment> zGridLines;
        private float yGridOffset;
 
        private readonly Color t5Orange = new Color(0.9450980392156862f, 0.34901960784313724f, 0.13333333333333333f);
        private readonly Color t5LightGray = new Color(0.9607843137254902f, 0.9647058823529412f, 0.9647058823529412f);
        private readonly Color t5Gray = new Color(0.3764705882352941f, 0.39215686274509803f, 0.4392156862745098f);
        private void Configure(ScaleSettings scaleSettings, GameBoardSettings gameBoardSettings,
            float gridOffsetY, GameBoard.GameboardExtents gameboardExtents)
        {
            this.scaleSettings = scaleSettings;
            this.gameBoardSettings = gameBoardSettings;
            this.yGridOffset = gridOffsetY;
            this.gameboardExtents = gameboardExtents;
 
            gameboardMesh_LE.TryLoadMeshes();
            gameboardMesh_XE.TryLoadMeshes();
            gameboardMesh_XE_Raised.TryLoadMeshes();
 
            if(null == logoObj)
            {
                logoObj = AssetDatabase.LoadAssetAtPath<GameObject>(logoMeshAssetPath);
            }
 
            if(null == meshLogoBorder)
            {
                var transform = logoObj.transform.Find( logoBorderChildPath );
                if(transform != null)
                {
                    if(transform.TryGetComponent<MeshFilter>(out var meshFilter))
                    {
                        meshLogoBorder = meshFilter.sharedMesh;
                    }
                }
            }
            if(null == meshLogoLeftCharacter)
            {
                var transform = logoObj.transform.Find( logoLeftCharacterChildPath );
                if(transform != null)
                {
                    if(transform.TryGetComponent<MeshFilter>(out var meshFilter))
                    {
                        meshLogoLeftCharacter = meshFilter.sharedMesh;
                    }
                }
            }
            if(null == meshLogoRightCharacter)
            {
                var transform = logoObj.transform.Find( logoRightCharacterChildPath );
                if(transform != null)
                {
                    if(transform.TryGetComponent<MeshFilter>(out var meshFilter))
                    {
                        meshLogoRightCharacter = meshFilter.sharedMesh;
                    }
                }
            }
 
            var previousGameboardType = gameboardType;
            gameboardType = gameBoardSettings.currentGameBoard.GetDisplayedGameboardType(gameBoardSettings);
 
            bool gameboardTypeChanged = previousGameboardType != gameboardType;
 
            if (null == xGridLines || null == zGridLines || gameboardTypeChanged)
            {
                ResetGrid();
            }
 
            if(null == meshRuler || gameboardTypeChanged)
            {
                ConstructRulerMesh(gameboardExtents.ViewableSpanX, "meshRuler", out meshRuler);
            }
        }
 
        public void ConstructRulerMesh(Length rulerLength, string meshName, out Mesh meshRuler)
        {
            var rulerData = new List<LineSegment>();
 
            float oneMillimeterLengthInMeters = new Length(1, LengthUnit.Millimeters).ToMeters;
 
            // For the centimeter ruler, we're going to draw regular marks for centimeters, and smaller ones for millimeters.
            for (int i = 0; i * oneMillimeterLengthInMeters < rulerLength.ToMeters; i++)
            {
                float currentDistance = i * (oneMillimeterLengthInMeters / rulerLength.ToMeters);
                float smallestFractionOfBoardWidth = 1f / 150f;
 
                float tickMarkLength = smallestFractionOfBoardWidth;
                int lod = 3;
 
                lod -= i % 5 == 0 ? 1 : 0;
                lod -= i % 10 == 0 ? 1 : 0;
 
                tickMarkLength += (3 - lod) * smallestFractionOfBoardWidth;
 
                rulerData.Add(new LineSegment(new Vector3(currentDistance, 0f, 0f), new Vector3(currentDistance, 0f, tickMarkLength), lod));
            }
 
            float oneSixteenthInchLengthInMeters = new Length(1 / 16f, LengthUnit.Inches).ToMeters;
 
            // For the inch ruler, we're going to draw regular marks for inches, and smaller ones for half/quarter/eighth/sixteenth inches.
            for (int i = 0; i * oneSixteenthInchLengthInMeters < rulerLength.ToMeters; i++)
            {
                float currentDistance = i * (oneSixteenthInchLengthInMeters / rulerLength.ToMeters);
                float smallestFractionOfBoardWidth = 1f / 300f;
 
                float tickMarkLength = smallestFractionOfBoardWidth;
                int lod = 5;
 
                lod -= i % 2 == 0 ? 1 : 0;
                lod -= i % 4 == 0 ? 1 : 0;
                lod -= i % 8 == 0 ? 1 : 0;
                lod -= i % 16 == 0 ? 1 : 0;
 
                tickMarkLength += (5 - lod) * smallestFractionOfBoardWidth;
 
                float offsetFromCentimeterRuler = 1 / 16f;
                rulerData.Add(new LineSegment(
                    new Vector3(currentDistance, 0f, offsetFromCentimeterRuler - tickMarkLength),
                    new Vector3(currentDistance, 0f, offsetFromCentimeterRuler),
                    lod));
            }
 
            meshRuler = new Mesh();
            meshRuler.name = meshName;
 
            int vertArraySizeRatio = 4;     // There are 4 vertices for every line in rulerData.
            Vector3[] verts = new Vector3[rulerData.Count * vertArraySizeRatio];
 
            int triArraySizeRatio = 6;      // There are 6 triangle vertex indices for every line in rulerData.
            int[] triangles = new int[rulerData.Count * triArraySizeRatio];
 
            float lineThickness = 1 / 2800f;
 
            // We want to offset the x vector component to achieve line thickness.
            var lineThicknessOffset = Vector3.right * (lineThickness / 2f);
 
            for (int i = 0; i < rulerData.Count; i++)
            {
                var line = rulerData[i];
 
                var bottomLeft = line.Start - lineThicknessOffset + Vector3.left / 2 + Vector3.back / 32f;
                var topLeft = line.End - lineThicknessOffset + Vector3.left / 2 + Vector3.back / 32f;
 
                var bottomRight = line.Start + lineThicknessOffset + Vector3.left / 2 + Vector3.back / 32f;
                var topRight = line.End + lineThicknessOffset + Vector3.left / 2 + Vector3.back / 32f;
 
                var vertIndex = i * vertArraySizeRatio;
                verts[vertIndex] = bottomLeft;
                verts[vertIndex + 1] = topLeft;
                verts[vertIndex + 2] = bottomRight;
                verts[vertIndex + 3] = topRight;
 
                var triIndex = i * triArraySizeRatio;
                triangles[triIndex] = vertIndex;        // bottomLeft
                triangles[triIndex + 1] = vertIndex + 1;    // topLeft
                triangles[triIndex + 2] = vertIndex + 2;    // bottomRight
 
                triangles[triIndex + 3] = vertIndex + 2;  // bottomRight
                triangles[triIndex + 4] = vertIndex + 1;  // topLeft
                triangles[triIndex + 5] = vertIndex + 3;  // topRight
            }
 
            meshRuler.vertices = verts;
            meshRuler.triangles = triangles;
            meshRuler.RecalculateNormals();
        }
 
        // Defines a series of line segments in gameboard space (-)
        public void ResetGrid(ScaleSettings newScaleSettings = null, GameBoardSettings newGameBoardSettings = null)
        {
            if (newScaleSettings != null)
            {
                this.scaleSettings = newScaleSettings;
            }
            if(newGameBoardSettings != null)
            {
                this.gameBoardSettings = newGameBoardSettings;
            }
 
            if(xGridLines == null)
            {
                xGridLines = new List<LineSegment>();
            }
            else xGridLines.Clear();
 
            if(zGridLines == null)
            {
                zGridLines = new List<LineSegment>();
            }
            else zGridLines.Clear();
 
            var lineLengthZ = 0.5f;
            var linePosOffsetZ = lineLengthZ - 0.5f;
            var lineStartPosZ = lineLengthZ;
            var lineStopPosZ = -lineLengthZ + linePosOffsetZ;
            var minDimension = Mathf.Min(usableGameBoardWidthInMeters, usableGameBoardLengthInMeters);
            var oneUnit = scaleSettings.oneUnitLengthInMeters / minDimension;
            // Starting from the center outward, define x-axis grid lines in 1-unit increments.
            for (int i = 0; i * scaleSettings.oneUnitLengthInMeters < usableGameBoardWidthInMeters / 2; i++)
            {
                float distanceFromCenter = i * (scaleSettings.oneUnitLengthInMeters / minDimension);
                int lod = 1;    // TODO: Change this later
 
                xGridLines.Add(new LineSegment(new Vector3(distanceFromCenter, 0, lineStartPosZ), new Vector3(distanceFromCenter, 0, lineStopPosZ), lod));
 
                // No need to draw a second overlapping pair of lines along the origin when i == 0.
                if(i < 1) {continue;}
 
                xGridLines.Add(new LineSegment(new Vector3(-distanceFromCenter, 0, lineStartPosZ), new Vector3(-distanceFromCenter, 0, lineStopPosZ), lod));
            }
 
            // Starting from the center outward, define z-axis grid lines in 1-unit increments.
            for (int i = 0; i * scaleSettings.oneUnitLengthInMeters < usableGameBoardWidthInMeters / 2; i++)
            {
                float distanceFromCenter = i * (scaleSettings.oneUnitLengthInMeters / minDimension);
                int lod = 1;    // TODO: Change this later
 
                zGridLines.Add(new LineSegment(new Vector3(0.5f, 0, distanceFromCenter), new Vector3(-0.5f, 0, distanceFromCenter), lod));
 
                // No need to draw a second overlapping pair of lines along the origin when i == 0.
                if(i < scaleSettings.oneUnitLengthInMeters) { continue; }
 
                zGridLines.Add(new LineSegment(new Vector3(0.5f, 0, -distanceFromCenter), new Vector3(-0.5f, 0, -distanceFromCenter), lod));
            }
        }
 
        public void Draw(ScaleSettings scaleSettings, GameBoardSettings gameBoardSettings,
            float alpha, bool showGrid, float gridOffsetY = 0f)
        {
            Configure (scaleSettings, gameBoardSettings, gridOffsetY, gameboardExtents);
 
            if (null == gameBoardSettings) { return; }
 
            GameboardMesh gameboardMesh;
 
            switch (gameboardType)
            {
                case GameboardType.GameboardType_XE:
                    gameboardMesh = gameboardMesh_XE;
                    break;
                case GameboardType.GameboardType_XE_Raised:
                    gameboardMesh = gameboardMesh_XE_Raised;
                    break;
                default:
                case GameboardType.GameboardType_LE:
                case GameboardType.GameboardType_None:
                    gameboardMesh = gameboardMesh_LE;
                    break;
            }
 
            var rotToUSTAGE_UBOARD = GetRotToUSTAGE_UBOARD(gameBoardSettings);
 
            Matrix4x4 mtxUWRLD_USTAGE = gameBoardSettings.currentGameBoard.transform.localToWorldMatrix * Matrix4x4.Scale(Vector3.one * scaleToUWRLD_USTAGE);
 
            //------------------------------------------------------------------------------------------
            // Draw the gameboard attached to the stage origin.
            //------------------------------------------------------------------------------------------
 
            // When the physical board orientation matches the stage orientation, the stage borders are redundant (and visually busy).
            // We will hide the stage gizmo when the physical gameboard orientation is mostly aligned with the stage orientation (i.e. gravity).
            // This is meant to gracefully handle the imperfect real world, in which tabletops might not be perfectly level.
 
            // Start by defining some angular deflection thresholds.
            var fadeInStartAngle = 3f;   // Start fading in above 3 degrees of rotation
            var fadeInEndAngle = 10f;    // Finish fading in by 10 degrees of rotation
            var stageGizmoAlpha = GetStageOpacity(rotToUSTAGE_UBOARD, fadeInStartAngle, fadeInEndAngle, alpha);
 
            DrawStage(gameboardMesh, mtxUWRLD_USTAGE, stageGizmoAlpha);
 
            //------------------------------------------------------------------------------------------
            // Draw the physical gameboard orientation.
            //------------------------------------------------------------------------------------------
 
            // Determine which corner of the physical gameboard is lowest in stage space.
            var lowestCorner_USTAGE = GetLowestCorner(rotToUSTAGE_UBOARD);
 
            var verticalOffset_USTAGE = -lowestCorner_USTAGE.pos_USTAGE.y;
            var mtxUSTAGE_UBOARD = Matrix4x4.TRS(verticalOffset_USTAGE * Vector3.up, rotToUSTAGE_UBOARD, Vector3.one);
            var mtxUWRLD_UBOARD = mtxUWRLD_USTAGE * mtxUSTAGE_UBOARD;
 
            DrawPhysicalBoard(gameboardMesh, mtxUWRLD_UBOARD, alpha);
 
            if (showGrid)
            {
                DrawGrid(alpha);
                DrawRulers(alpha);
            }
        }
 
        private void DrawStage(GameboardMesh gameboardMesh, Matrix4x4 mtxGizmo, float alpha)
        {
            if (alpha <= 0f)
            {
                return;
            }
 
            using (new GizmoReferenceFrame(mtxGizmo))
            {
                if (gameboardMesh.meshStage != null)
                {
                    using (new GizmoColor(1.0f, 1.0f, 1.0f, alpha))
                    {
                        Gizmos.DrawMesh(gameboardMesh.meshStage);
                    }
                }
 
                if (gameboardMesh.meshStageCorner != null)
                {
                    using (new GizmoColor(t5Orange, alpha))
                    {
                        Gizmos.DrawMesh(gameboardMesh.meshStageCorner, 0);
                    }
                }
 
                if (gameboardMesh.meshSurface != null)
                {
                    using (new GizmoColor(0.5f, 0.5f, 0.5f, alpha / 2f))
                    {
                        Gizmos.DrawMesh(gameboardMesh.meshSurface, 0);
                    }
                }
            }
        }
 
        private (GameBoard.Corner corner, Vector3 pos_USTAGE) GetLowestCorner(Quaternion rotToUSTAGE_UBOARD)
        {
            // Start by obtaining the extents of the current gameboard.
            // We'll need them for obtaining corner postions in a moment.
            T5_GameboardSize gameboardSize;
 
            switch (gameboardType)
            {
                case GameboardType.GameboardType_XE:
                    gameboardSize = GameBoard.GameboardExtents.GAMEBOARD_SIZE_XE;
                    break;
                case GameboardType.GameboardType_XE_Raised:
                    gameboardSize = GameBoard.GameboardExtents.GAMEBOARD_SIZE_XE_RAISED;
                    break;
                case GameboardType.GameboardType_LE:
                default:
                    gameboardSize = GameBoard.GameboardExtents.GAMEBOARD_SIZE_LE;
                    break;
            }
 
            GameBoard.GameboardExtents gameboardExtents = new GameBoard.GameboardExtents(gameboardSize);
 
            // Determine which corner of the physical gameboard is lowest in stage space.
            (GameBoard.Corner corner, Vector3 pos_USTAGE) lowestCorner_USTAGE
                    = (GameBoard.Corner.FarLeft, rotToUSTAGE_UBOARD * gameboardExtents.GetCornerPositionInGameboardSpace(GameBoard.Corner.FarLeft));
 
            for (GameBoard.Corner corner = GameBoard.Corner.FarRight; (int)corner < 4; corner++)
            {
                var cornerPos_USTAGE = rotToUSTAGE_UBOARD * gameboardExtents.GetCornerPositionInGameboardSpace(corner);
 
                if (cornerPos_USTAGE.y < lowestCorner_USTAGE.pos_USTAGE.y)
                {
                    lowestCorner_USTAGE = (corner, cornerPos_USTAGE);
                }
            }
            return lowestCorner_USTAGE;
        }
 
        private Quaternion GetRotToUSTAGE_UBOARD(GameBoardSettings gameboardSettings)
        {
            var rotToUSTAGE_UBOARD = gameboardSettings.enableGameboardOrientationOverride
                ? Quaternion.Euler(gameboardSettings.gameboardOrientationOverride)
                : gameboardSettings.physicalGameboardOrigin == null ? Quaternion.identity : gameboardSettings.physicalGameboardOrigin.transform.localRotation;
            return rotToUSTAGE_UBOARD;
        }
 
        private float GetStageOpacity(Quaternion rotToULBOARD_ULSTAGE, float lowerAngleThreshold, float higherAngleThreshold, float baseOpacity)
        {
            /*
             * A naive approach to doing this might be to compare the stage's normal vector (y-axis, gravity, etc)
             * to the physical gameboard's normal, using the measured angular deflection to lerp between the angle thresholds.
             * However, this approach does not account for yaw rotations about the y-axis.
             * We're going to need to do this the right way and compare rotations using quaternions.
             *
             * Luckily, a quaternion is also a Vector4, so we can use dot products to check for rotations
             * that are "aligned", "perpendicular", or "opposite", resulting in values of 1, 0, and -1 respectively.
             * Subtle rotations like the ones we care about are still nearly-aligned with the default pose,
             * so they will result in dot products close to 1.0 (or -1.0, which is covered below).
             *
             * To avoid converting back to degrees, we can just lerp between a couple reference rotations
             * (based on the angle thresholds defined above) and their corresponding dot products with the default orientation.
             *
             * One gotcha to this approach is that we must use the absolute value of the dot product to handle rotations that are
             * visually equivalent to the default rotation. This is because a 360 degree rotation about an arbitrary axis is equivalent
             * to the "opposite" quaternion of the identity quaternion we started with, and the dot product result is -1.
             * If left alone, this would fall outside the threshold range and result in the gizmo persisting at values near 360 degrees,
             * then fading around 720 degrees, a pattern that would continue alternating the gizmo's visibility behavior in 360 degree increments.
             * Mathematically this makes sense, but it defies intuition and confuses users without being relevant to the task at hand.
             * Dropping the negative sign lets the border gizmo fade properly in response to all functionally equivalent rotations.
             */
            var alignmentWithStage = 1f - Mathf.Abs(Quaternion.Dot(Quaternion.identity, rotToULBOARD_ULSTAGE));
            var referenceAlignmentStartThreshold = 1f - Quaternion.Dot(Quaternion.identity, Quaternion.Euler(Vector3.right * lowerAngleThreshold));
            var referenceAlignmentEndThreshold = 1f - Quaternion.Dot(Quaternion.identity, Quaternion.Euler(Vector3.right * higherAngleThreshold));
            return Mathf.Lerp(0f, baseOpacity,
                Mathf.Min(Mathf.Max(alignmentWithStage - referenceAlignmentStartThreshold, 0f) / (referenceAlignmentEndThreshold - referenceAlignmentStartThreshold), 1f));
        }
 
        private void DrawPhysicalBoard(GameboardMesh gameboardMesh, Matrix4x4 mtxGizmo, float alpha)
        {
            if (alpha <= 0f)
            {
                return;
            }
 
            using (new GizmoReferenceFrame(mtxGizmo))
            {
                if (gameboardMesh.meshSurface != null)
                {
                    using (new GizmoColor(0.5f, 0.5f, 0.5f, alpha))
                    {
                        Gizmos.DrawMesh(gameboardMesh.meshSurface, 0);
                    }
                }
 
                if (gameboardMesh.meshBorder != null)
                {
                    using (new GizmoColor(0.0f, 0.0f, 0.0f, alpha))
                    {
                        Gizmos.DrawMesh(gameboardMesh.meshBorder, 0);
                    }
                }
 
                if (meshLogoBorder != null && meshLogoLeftCharacter != null && meshLogoRightCharacter != null)
                {
                    DrawLogo(Gizmos.matrix, alpha);
                }
            }
        }
 
        private void DrawLogo(Matrix4x4 mtxGizmo, float alpha)
        {
            if (alpha <= 0f)
            {
                return;
            }
 
            using (new GizmoReferenceFrame(mtxGizmo))
            {
                using (new GizmoColor(t5LightGray, alpha))
                {
                    Gizmos.DrawMesh( meshLogoBorder, 0 );
                }
 
                using (new GizmoColor(t5Orange, alpha))
                {
                    Gizmos.DrawMesh(meshLogoLeftCharacter, 0);
                }
 
                using (new GizmoColor(t5Gray, alpha))
                {
                    Gizmos.DrawMesh(meshLogoRightCharacter, 0);
                }
            }
        }
 
        private void DrawGrid(float alpha)
        {
            var contentScaleFactor = scaleToUWRLD_USTAGE;
            float heightOffsetInMeters = yGridOffset * scaleSettings.oneUnitLengthInMeters;
            float lengthOffsetInMeters = Mathf.Max(usableGameBoardLengthInMeters - usableGameBoardWidthInMeters, 0f) / 2f;
 
            var gameBoardTransform = gameBoardSettings.currentGameBoard.transform;
 
            // Define the transformations for the grid origin and orientation.
            Matrix4x4 mtxPreTransform = Matrix4x4.Scale(
                Vector3.one * Mathf.Min(usableGameBoardWidthInMeters, usableGameBoardLengthInMeters));
                //new Vector3(usableGameBoardWidthInMeters, 1f, usableGameBoardLengthInMeters));
            Matrix4x4 mtxGizmo = Matrix4x4.TRS(
                gameBoardSettings.gameBoardCenter + (gameBoardTransform.up * heightOffsetInMeters / contentScaleFactor),
                gameBoardTransform.rotation,
                Vector3.one / contentScaleFactor ) * mtxPreTransform;
 
            // Unless we're using inches, grid lines should appear in groups of 10.
            var gridLinePeriod = scaleSettings.contentScaleUnit == LengthUnit.Inches ? 12 : 10;
 
            // We want to fade out grid lines spaced closer than 10 pixels on the screen.
            // We'll do two iterations of fading out.
            float beginFadeThreshold = 20f;
            float endFadeThreshold = 10f;
 
            // To determine the spacing, we'll sample a position under the camera (even if it's off the board).
            TryGetCameraPositionOverGameBoard(out var cameraPositionOverGameBoard);
            Vector3 testUnitVector = cameraPositionOverGameBoard + Vector3.right * scaleSettings.oneUnitLengthInMeters / contentScaleFactor;
            Vector3 secondTestUnitVector = cameraPositionOverGameBoard + Vector3.right * gridLinePeriod * scaleSettings.oneUnitLengthInMeters / contentScaleFactor;
 
            var screenSpaceDistance = (SceneView.currentDrawingSceneView.camera.WorldToScreenPoint(testUnitVector)
                - SceneView.currentDrawingSceneView.camera.WorldToScreenPoint(cameraPositionOverGameBoard)).magnitude;
            var secondScreenSpaceDistance = (SceneView.currentDrawingSceneView.camera.WorldToScreenPoint(secondTestUnitVector)
                - SceneView.currentDrawingSceneView.camera.WorldToScreenPoint(cameraPositionOverGameBoard)).magnitude;
 
            // Check the sampled values against the thresholds we defined above and calculate transparency values.
            var beginFade = screenSpaceDistance < beginFadeThreshold;
            var endFade = screenSpaceDistance < endFadeThreshold;
 
            var beginSecondFade = secondScreenSpaceDistance < beginFadeThreshold;
            var endSecondFade = secondScreenSpaceDistance < endFadeThreshold;
 
            var fadeFactor = 1f - Mathf.Clamp((beginFadeThreshold - screenSpaceDistance) / endFadeThreshold, 0f, 1f);
            var secondFadeFactor = 1f - Mathf.Clamp((beginFadeThreshold - secondScreenSpaceDistance) / endFadeThreshold, 0f, 1f);
 
            var fadeAlpha = alpha * fadeFactor;
            var secondFadeAlpha = alpha * secondFadeFactor;
 
            // Finally, draw some grid lines.
            using (new GizmoReferenceFrame(mtxGizmo))
            {
                DrawGridLines(xGridLines, gridLinePeriod, alpha, beginFade, endFade, fadeAlpha, beginSecondFade, endSecondFade, secondFadeAlpha);
                DrawGridLines(zGridLines, gridLinePeriod, alpha, beginFade, endFade, fadeAlpha, beginSecondFade, endSecondFade, secondFadeAlpha);
            }
        }
 
        private void DrawGridLines(List<LineSegment> lines, int gridLinePeriod, float alpha, bool beginFade, bool endFade,
            float fadeAlpha, bool beginSecondFade, bool endSecondFade, float secondFadeAlpha)
        {
            var gridLinePeriodSquared = gridLinePeriod * gridLinePeriod;
            var mtxGizmo = Gizmos.matrix;
 
            // We want to use a sphere around the projected cursor position to check for collision with lines on the grid.
            // Any lines that collide will be colored differently. Set the sphere diameter to a single content unit, and scale it as the grid fades.
            float cursorSphereRadius = scaleToUWRLD_USTAGE * (scaleSettings.oneUnitLengthInMeters / 2f);
            if(endSecondFade)
            {
                cursorSphereRadius *= (gridLinePeriod * gridLinePeriod) / 2f;
            }
            else if(endFade)
            {
                cursorSphereRadius *= gridLinePeriod / 2f;
            }
 
            for(int i = 0; i < lines.Count; i++)
            {
                // Determine whether we should skip drawing this line.
                var isPeriodic = i % gridLinePeriod == 0 || i % gridLinePeriod == gridLinePeriod - 1;
                if(endFade && !isPeriodic) { continue; }
 
                var isDoublePeriodic = i % gridLinePeriodSquared == 0 || i % gridLinePeriodSquared == gridLinePeriodSquared - 1;
                if(endSecondFade && !isDoublePeriodic) { continue; }
 
                // We'll need the current line defined in world space to check for cursor collision.
                var currentGridLineSegment = lines[i];
                var transformedLineSegment = new LineSegment(
                    mtxGizmo.MultiplyPoint3x4(currentGridLineSegment.Start),
                    mtxGizmo.MultiplyPoint3x4(currentGridLineSegment.End), currentGridLineSegment.LOD);
 
                var lineCollidesWithCursor = TryGetCursorPosition(out var cursorPosition)
                    && CheckRaySphereCollision(cursorPosition, cursorSphereRadius, transformedLineSegment);
 
                // Apply any fading required by the camera's distance from the grid.
                var lineAlpha = alpha;
                if(beginSecondFade && !isDoublePeriodic)
                {
                    lineAlpha = secondFadeAlpha;
                }
                else if(beginFade && !isPeriodic)
                {
                    lineAlpha = fadeAlpha;
                }
 
                using (lineCollidesWithCursor
                    ? new GizmoColor(1f, 0f, 0f, alpha)
                    : new GizmoColor(1f, 1f, 1f, lineAlpha))
                {
                    // If the line collides with the cursor, project it on the edges of the board.
                    if (lineCollidesWithCursor)
                    {
                        var xLineExtensionFactor = totalGameBoardWidthInMeters / usableGameBoardWidthInMeters;
                        var zLineExtensionFactor = totalGameBoardLengthInMeters / usableGameBoardLengthInMeters;
 
                        // We need to know which direction to extend it. It's either x-axis aligned or z-axis aligned.
                        var lineDifference = currentGridLineSegment.End - currentGridLineSegment.Start;
                        var xAxisAligned = Mathf.Abs(Vector3.Dot(Vector3.right, lineDifference)) == 1;
 
                        var mtxPreTransform = Matrix4x4.Scale(
                            (xAxisAligned ? new Vector3(xLineExtensionFactor, 1f, 1f) : new Vector3(1f, 1f, zLineExtensionFactor)));
                        var newMtxWorld = Matrix4x4.TRS(
                            gameBoardSettings.currentGameBoard.transform.position,
                            gameBoardSettings.currentGameBoard.transform.rotation,
                            new Vector3(scaleToUWRLD_USTAGE * usableGameBoardWidthInMeters, 0f, scaleToUWRLD_USTAGE * usableGameBoardWidthInMeters));
 
                        // Finally, draw a line.
                        using (new GizmoReferenceFrame(newMtxWorld))
                        {
                            Gizmos.DrawLine(currentGridLineSegment.Start, mtxPreTransform.MultiplyPoint3x4(currentGridLineSegment.Start));
                            Gizmos.DrawLine(currentGridLineSegment.End, mtxPreTransform.MultiplyPoint3x4(currentGridLineSegment.End));
                        }
                    }
                    Gizmos.DrawLine(currentGridLineSegment.Start, currentGridLineSegment.End);
                }
            }
        }
 
        private bool TryGetCursorPosition(out Vector3 intersectPoint)
        {
            var sceneView = UnityEditor.SceneView.currentDrawingSceneView;
            var sceneViewCamera = sceneView.camera;
            var mousePos = Event.current.mousePosition - sceneView.position.position;
 
            // Get the mouse position
            mousePos = GUIUtility.GUIToScreenPoint(mousePos);
 
            // The calls above tends to include some extra invisible space above the rendered scene view, so we compensate.
            var frameOffset = Vector2.down * 36f;
            mousePos.y = (sceneViewCamera.pixelHeight - mousePos.y - frameOffset.y);
 
            var ray = sceneViewCamera.ScreenPointToRay(mousePos);
 
            return TryGetGridPlanePosition(ray, out intersectPoint);
        }
 
        private bool TryGetCameraPositionOverGameBoard(out Vector3 intersectPoint)
        {
            var ray = new Ray(UnityEditor.SceneView.currentDrawingSceneView.camera.transform.position, -gameBoardSettings.currentGameBoard.transform.up);
            return TryGetGridPlanePosition(ray, out intersectPoint);
        }
 
        private bool TryGetGridPlanePosition(Ray ray, out Vector3 intersectPoint)
        {
            // Set up the collision plane
            var planeOffsetY = (yGridOffset * scaleSettings.oneUnitLengthInMeters) / scaleToUWRLD_USTAGE;
            var gridPlane = new Plane(
                gameBoardSettings.currentGameBoard.transform.up,
                gameBoardSettings.currentGameBoard.transform.localToWorldMatrix.MultiplyPoint3x4(planeOffsetY * Vector3.up));
 
            if(gridPlane.Raycast(ray, out var intersectionDistance))
            {
                // Get the point along the ray intersecting the plane.
                intersectPoint = ray.GetPoint(intersectionDistance);
                return true;
            }
 
            intersectPoint = Vector3.zero;
            return false;
        }
 
        private bool CheckRaySphereCollision(Vector3 sphereCenter, float sphereRadius, LineSegment lineSegment){
 
            var ray = new Ray(lineSegment.Start, lineSegment.End - lineSegment.Start);
 
            Vector3 rayToSphereCenterDistance = ray.origin - sphereCenter;
            float a = Vector3.Dot(ray.direction, ray.direction);
            float b = 2f * Vector3.Dot(rayToSphereCenterDistance, ray.direction);
            float c = Vector3.Dot(rayToSphereCenterDistance, rayToSphereCenterDistance) - sphereRadius * sphereRadius;
            float discriminant = (b * b) - (4*a*c);
            return discriminant > 0;
        }
 
        private void DrawRulers(float alpha)
        {
            if(meshRuler == null) { return; }
 
            var contentScaleFactor = scaleToUWRLD_USTAGE;
            float borderWidthInMeters = GameBoard.GameboardExtents.BORDER_WIDTH_IN_METERS;
            float lengthOffsetInMeters = Mathf.Max(usableGameBoardLengthInMeters - usableGameBoardWidthInMeters, 0f) / 2f;
            var gameBoardTransform = gameBoardSettings.currentGameBoard.transform;
            var gameboardCenter = gameBoardSettings.gameBoardCenter;
 
            Matrix4x4 mtxPreTransform = Matrix4x4.Scale(new Vector3(usableGameBoardWidthInMeters, 1f, usableGameBoardLengthInMeters));
 
            using (new GizmoColor(1f, 0.8320962f, 0.3803922f, alpha))
            {
                // Far edge
                Matrix4x4 mtxWorld = Matrix4x4.TRS(gameboardCenter + (gameBoardTransform.forward * lengthOffsetInMeters / contentScaleFactor) + (0.5f * (usableGameBoardLengthInMeters + borderWidthInMeters) * gameBoardTransform.forward) / contentScaleFactor,
                    Quaternion.Euler(gameBoardSettings.gameBoardRotation),
                    Vector3.one / contentScaleFactor );
                using (new GizmoReferenceFrame(mtxWorld * mtxPreTransform))
                {
                    Gizmos.DrawMesh(meshRuler, 0 );
                }
 
                // Near edge
                mtxWorld = Matrix4x4.TRS(gameboardCenter - (0.5f * (usableGameBoardWidthInMeters + borderWidthInMeters) * gameBoardTransform.forward) / contentScaleFactor,
                    Quaternion.Euler(gameBoardSettings.gameBoardRotation),
                    Vector3.one / contentScaleFactor );
                using (new GizmoReferenceFrame(mtxWorld * mtxPreTransform))
                {
                    Gizmos.DrawMesh(meshRuler, 0 );
                }
 
                // Right edge
                mtxPreTransform = Matrix4x4.TRS( Vector3.zero, Quaternion.Euler(0.0f, 90.0f, 0.0f), Vector3.one * usableGameBoardWidthInMeters);
                mtxWorld = Matrix4x4.TRS(gameboardCenter + (0.5f * (usableGameBoardWidthInMeters + borderWidthInMeters) * gameBoardTransform.right) / contentScaleFactor,
                    Quaternion.Euler(gameBoardSettings.gameBoardRotation),
                    Vector3.one / contentScaleFactor );
                using (new GizmoReferenceFrame(mtxWorld * mtxPreTransform))
                {
                    Gizmos.DrawMesh(meshRuler, 0 );
                }
 
                // Left Edge
                mtxWorld = Matrix4x4.TRS(gameboardCenter - (0.5f * (usableGameBoardWidthInMeters + borderWidthInMeters) * gameBoardTransform.right) / contentScaleFactor,
                    Quaternion.Euler(gameBoardSettings.gameBoardRotation),
                    Vector3.one / contentScaleFactor );
                using (new GizmoReferenceFrame(mtxWorld * mtxPreTransform))
                {
                    Gizmos.DrawMesh(meshRuler, 0 );
                }
            }
        }
    }
}
#endif