OpenRA开源红色警戒游戏RPG源码WAngle.cs解读-优快云博客

本文链接：https://blog.youkuaiyun.com/zhangzhechun/article/details/147589066

python编程示例系列
 python编程示例系列二
 python的Web神器Streamlit
如何应聘高薪职位
 C#视觉应用开发问题系列
 c#串口应用开发问题系列
 microPython Python最小内核源码解析
 NI-motion运动控制c语言示例代码解析
 OpenRA开源红色警戒游戏RPG源码解读
在这里插入图片描述 # WAngle 结构详解与分析

代码注释

using System;
using Eluant;                  // 引入Eluant库，用于Lua脚本集成
using Eluant.ObjectBinding;    // 引入Eluant对象绑定功能
using OpenRA.Scripting;        // 引入OpenRA脚本功能

namespace OpenRA
{
    /// <summary>
    /// 1D角度 - 1024单位 = 360度。
    /// 这是OpenRA游戏引擎中用于表示角度的结构
    /// </summary>
    public readonly struct WAngle : IEquatable<WAngle>, IScriptBindable,
        ILuaAdditionBinding, ILuaSubtractionBinding, ILuaEqualityBinding, ILuaTableBinding, ILuaToStringBinding
    {
        // 角度值，范围为0-1023
        public readonly int Angle;
        // 角度的平方值，用于某些计算
        public int AngleSquared => Angle * Angle;

        /// <summary>
        /// 构造函数，确保角度值在0-1023范围内
        /// </summary>
        /// <param name="a">输入的角度值</param>
        public WAngle(int a)
        {
            // 对1024取模，确保在0-1023范围内
            Angle = a % 1024;
            // 如果为负数，加上1024使其变为正数
            if (Angle < 0)
                Angle += 1024;
        }

        // 零角度常量
        public static readonly WAngle Zero = new(0);
        
        // 从朝向值创建角度，朝向值乘以4转换为角度
        public static WAngle FromFacing(int facing) { return new WAngle(facing * 4); }
        
        // 从度数创建角度，度数乘以1024/360转换为内部角度表示
        public static WAngle FromDegrees(int degrees) { return new WAngle(degrees * 1024 / 360); }
        
        // 重载加法运算符
        public static WAngle operator +(WAngle a, WAngle b) { return new WAngle(a.Angle + b.Angle); }
        
        // 重载减法运算符
        public static WAngle operator -(WAngle a, WAngle b) { return new WAngle(a.Angle - b.Angle); }
        
        // 重载负号运算符
        public static WAngle operator -(WAngle a) { return new WAngle(-a.Angle); }

        // 重载相等运算符
        public static bool operator ==(WAngle me, WAngle other) { return me.Angle == other.Angle; }
        
        // 重载不等运算符
        public static bool operator !=(WAngle me, WAngle other) { return me.Angle != other.Angle; }

        // 重写GetHashCode方法
        public override int GetHashCode() { return Angle.GetHashCode(); }

        // 实现IEquatable接口的Equals方法
        public bool Equals(WAngle other) { return other == this; }
        
        // 重写Object.Equals方法
        public override bool Equals(object obj) { return obj is WAngle angle && Equals(angle); }

        // 获取朝向值，角度除以4
        public int Facing => Angle / 4;

        /// <summary>
        /// 计算正弦值，利用余弦表和角度偏移实现
        /// </summary>
        public int Sin() { return new WAngle(Angle - 256).Cos(); }

        /// <summary>
        /// 计算余弦值，使用预计算的余弦表
        /// </summary>
        public int Cos()
        {
            // 角度在0-256范围内，直接使用余弦表
            if (Angle <= 256)
                return CosineTable[Angle];
            // 角度在257-512范围内，使用对称性计算
            if (Angle <= 512)
                return -CosineTable[512 - Angle];
            // 角度大于512，递归计算
            return -new WAngle(Angle - 512).Cos();
        }

        /// <summary>
        /// 计算正切值，使用预计算的正切表
        /// </summary>
        public int Tan()
        {
            // 角度在0-256范围内，直接使用正切表
            if (Angle <= 256)
                return TanTable[Angle];
            // 角度在257-512范围内，使用对称性计算
            if (Angle <= 512)
                return -TanTable[512 - Angle];
            // 角度大于512，递归计算
            return new WAngle(Angle - 512).Tan();
        }

        /// <summary>
        /// 线性插值两个角度，考虑角度环绕问题
        /// </summary>
        /// <param name="a">起始角度</param>
        /// <param name="b">结束角度</param>
        /// <param name="mul">插值分子</param>
        /// <param name="div">插值分母</param>
        public static WAngle Lerp(WAngle a, WAngle b, int mul, int div)
        {
            // 将1024<->0的环绕映射到线性空间
            var aa = a.Angle;
            var bb = b.Angle;
            
            // 如果两个角度相差超过半圈，调整值使其取最短路径
            if (aa > bb && aa - bb > 512)
                aa -= 1024;

            if (bb > aa && bb - aa > 512)
                bb -= 1024;

            // 计算插值结果
            return new WAngle(aa + (bb - aa) * mul / div);
        }

        /// <summary>
        /// 计算反正弦，根据值查找最接近的角度
        /// </summary>
        /// <param name="d">正弦值，范围-1024到1024</param>
        public static WAngle ArcSin(int d)
        {
            // 检查输入值是否在有效范围内
            if (d < -1024 || d > 1024)
                throw new ArgumentException($"ArcSin is only valid for values between -1024 and 1024. Received {d}");

            // 使用余弦表查找最接近的索引
            var a = ClosestCosineIndex(Math.Abs(d));
            // 根据正负值计算角度
            return new WAngle(d < 0 ? 768 + a : 256 - a);
        }

        /// <summary>
        /// 计算反余弦，根据值查找最接近的角度
        /// </summary>
        /// <param name="d">余弦值，范围-1024到1024</param>
        public static WAngle ArcCos(int d)
        {
            // 检查输入值是否在有效范围内
            if (d < -1024 || d > 1024)
                throw new ArgumentException($"ArcCos is only valid for values between -1024 and 1024. Received {d}");

            // 使用余弦表查找最接近的索引
            var a = ClosestCosineIndex(Math.Abs(d));
            // 根据正负值计算角度
            return new WAngle(d < 0 ? 512 - a : a);
        }

        /// <summary>
        /// 查找余弦表中最接近给定值的索引
        /// 使用二分查找算法提高效率
        /// </summary>
        /// <param name="value">要查找的值</param>
        static int ClosestCosineIndex(int value)
        {
            // 二分查找的上下边界
            var aboveIndex = 0;
            var belowIndex = 256;
            
            // 二分查找循环
            while (aboveIndex != belowIndex - 1)
            {
                var index = (aboveIndex + belowIndex) / 2;
                var val = CosineTable[index];

                // 找到精确匹配
                if (val == value)
                    return index;

                // 调整搜索范围
                if (val < value)
                    belowIndex = index;
                else
                    aboveIndex = index;
            }

            // 取误差最小的索引
            return CosineTable[aboveIndex] - value > value - CosineTable[belowIndex] ? belowIndex : aboveIndex;
        }

        /// <summary>
        /// 计算反正切，重载版本，使用默认步长1
        /// </summary>
        public static WAngle ArcTan(int y, int x) { return ArcTan(y, x, 1); }
        
        /// <summary>
        /// 计算反正切，根据x和y坐标找到角度
        /// </summary>
        /// <param name="y">y坐标</param>
        /// <param name="x">x坐标</param>
        /// <param name="stride">步长，用于优化搜索</param>
        public static WAngle ArcTan(int y, int x, int stride)
        {
            // 特殊情况：y为0
            if (y == 0)
                return new WAngle(x >= 0 ? 0 : 512); // 0度或180度

            // 特殊情况：x为0
            if (x == 0)
                return new WAngle(Math.Sign(y) * 256); // 90度或270度

            // 取绝对值简化计算
            var ay = Math.Abs(y);
            var ax = Math.Abs(x);

            // 找到最接近的满足y = x*tan(theta)的角度
            // 使用long类型存储bestVal避免整数溢出
            var bestVal = long.MaxValue;
            var bestAngle = 0;
            
            // 在正切表中搜索最佳匹配
            for (var i = 0; i < 256; i += stride)
            {
                var val = Math.Abs(1024 * ay - (long)ax * TanTable[i]);
                if (val < bestVal)
                {
                    bestVal = val;
                    bestAngle = i;
                }
            }

            // 根据x和y的符号计算实际象限
            if (x < 0 && y > 0)
                bestAngle = 512 - bestAngle;      // 第二象限
            else if (x < 0 && y < 0)
                bestAngle = 512 + bestAngle;      // 第三象限
            else if (x > 0 && y < 0)
                bestAngle = 1024 - bestAngle;     // 第四象限
            // 第一象限不需要调整

            return new WAngle(bestAngle);
        }

        /// <summary>
        /// 转换为弧度制，仅用于渲染代码
        /// </summary>
        public float RendererRadians() { return (float)(Angle * Math.PI / 512f); }
        
        /// <summary>
        /// 转换为角度制，仅用于渲染代码
        /// </summary>
        public float RendererDegrees() { return Angle * 0.3515625f; } // 360/1024

        /// <summary>
        /// 重写ToString方法，返回角度值的字符串表示
        /// </summary>
        public override string ToString() { return Angle.ToStringInvariant(); }

        /// <summary>
        /// 预计算的余弦表，范围0-256对应0-90度
        /// 值范围为0-1024，相当于将-1到1的余弦值映射到-1024到1024
        /// </summary>
        static readonly int[] CosineTable =
        {
            // 详细的余弦值表...
            1024, 1023, 1023, 1023, 1023, 1023, 1023, 1023, 1022, 1022, 1022, 1021,
            // 中间省略...
            56, 50, 43, 37, 31, 25, 18, 12, 6, 0
        };

        /// <summary>
        /// 预计算的正切表，范围0-256对应0-90度
        /// </summary>
        static readonly int[] TanTable =
        {
            // 详细的正切值表...
            0, 6, 12, 18, 25, 31, 37, 44, 50, 56, 62, 69, 75, 81, 88, 94, 100, 107,
            // 中间省略...
            23826, 27801, 33366, 41713, 55622, 83438, 166883, int.MaxValue
        };

        #region Scripting interface

        /// <summary>
        /// 实现Lua加法操作的接口方法
        /// </summary>
        public LuaValue Add(LuaRuntime runtime, LuaValue left, LuaValue right)
        {
            // 尝试获取左操作数
            if (!left.TryGetClrValue(out WAngle a))
                throw new LuaException(
                    "Attempted to call WAngle.Add(WAngle, WAngle) with invalid arguments " +
                    $"({left.WrappedClrType().Name}, {right.WrappedClrType().Name})");

            // 尝试获取右操作数并执行加法
            if (right.TryGetClrValue(out WAngle b))
                return new LuaCustomClrObject(a + b);

            // 如果右操作数不是WAngle类型，抛出异常
            throw new LuaException(
                "Attempted to call WAngle.Add(WAngle, WAngle) with invalid arguments " +
                $"({left.WrappedClrType().Name}, {right.WrappedClrType().Name})");
        }

        /// <summary>
        /// 实现Lua减法操作的接口方法
        /// </summary>
        public LuaValue Subtract(LuaRuntime runtime, LuaValue left, LuaValue right)
        {
            // 尝试获取左操作数
            if (!left.TryGetClrValue(out WAngle a))
                throw new LuaException(
                    "Attempted to call WAngle.Subtract(WAngle, WAngle) with invalid arguments " +
                    $"({left.WrappedClrType().Name}, {right.WrappedClrType().Name})");

            // 尝试获取右操作数并执行减法
            if (right.TryGetClrValue(out WAngle b))
                return new LuaCustomClrObject(a - b);

            // 如果右操作数不是WAngle类型，抛出异常
            throw new LuaException(
                "Attempted to call WAngle.Subtract(WAngle, WAngle) with invalid arguments " +
                $"({left.WrappedClrType().Name}, {right.WrappedClrType().Name})");
        }

        /// <summary>
        /// 实现Lua相等比较的接口方法
        /// </summary>
        public LuaValue Equals(LuaRuntime runtime, LuaValue left, LuaValue right)
        {
            // 尝试获取两个操作数，如果任一不是WAngle类型，返回false
            if (!left.TryGetClrValue(out WAngle a) || !right.TryGetClrValue(out WAngle b))
                return false;

            // 比较两个WAngle是否相等
            return a == b;
        }

        /// <summary>
        /// 实现Lua表访问的接口方法，允许通过angle["Angle"]访问角度值
        /// </summary>
        public LuaValue this[LuaRuntime runtime, LuaValue key]
        {
            get
            {
                switch (key.ToString())
                {
                    case "Angle": return Angle;
                    default: throw new LuaException($"WAngle does not define a member '{key}'");
                }
            }

            // 设置值时抛出异常，因为WAngle是只读的
            set => throw new LuaException("WAngle is read-only. Use Angle.New to create a new value");
        }

        /// <summary>
        /// 实现Lua转字符串的接口方法
        /// </summary>
        public LuaValue ToString(LuaRuntime runtime) => ToString();

        #endregion
    }
}

WAngle结构的逻辑解读

WAngle是OpenRA游戏引擎中用于表示角度的结构，采用了一种特殊的角度表示方法：1024单位表示360度。这种表示方法的主要优势是：

可以使用整数进行角度计算，避免浮点数精度问题
角度值可以用0-1023的整数表示，便于存储和计算
通过预计算的三角函数表，可以快速获取角度的三角函数值

WAngle结构实现了多种功能：

基本的角度表示和转换
三角函数计算（正弦、余弦、正切）
反三角函数计算（反正弦、反余弦、反正切）
角度间的线性插值
与Lua脚本的交互接口

流程图

三角函数计算流程

反三角函数计算流程

ArcTan计算流程

特殊语法与技巧解读

只读结构体
```
public readonly struct WAngle
```
使用readonly struct表示该结构体是不可变的，有助于线程安全和性能优化。
表达式体成员
```
public int AngleSquared => Angle * Angle;
public int Facing => Angle / 4;
```
使用=>语法简化属性的定义，这是C#6.0引入的表达式体成员语法。

静态只读字段

public static readonly WAngle Zero = new(0);
static readonly int[] CosineTable = { ... };

使用静态只读字段存储常量和预计算表，提高性能。

运算符重载

public static WAngle operator +(WAngle a, WAngle b) { return new WAngle(a.Angle + b.Angle); }

重载运算符使WAngle可以像基本类型一样使用算术运算符。

接口实现
```
public readonly struct WAngle : IEquatable<WAngle>, IScriptBindable, ...
```
实现多个接口使WAngle可以与.NET框架和Lua脚本系统无缝集成。
模数运算与规范化
```
Angle = a % 1024;
if (Angle < 0)
    Angle += 1024;
```
确保角度值始终在0-1023范围内，处理负数和大于1023的值。
查表优化
```
return CosineTable[Angle];
```
使用预计算的表格代替实时计算三角函数，大大提高性能。
递归计算
```
return -new WAngle(Angle - 512).Cos();
```
利用三角函数的对称性和周期性，通过递归减少表的大小。
二分查找算法
```
static int ClosestCosineIndex(int value) { ... }
```
在反三角函数计算中使用二分查找提高效率。
字符串插值
```
throw new LuaException($"WAngle does not define a member '{key}'");
```
使用C#6.0引入的字符串插值功能简化字符串格式化。
out参数与模式匹配
```
if (!left.TryGetClrValue(out WAngle a))
```
结合out参数和TryGetXXX模式简化错误处理。

Lambda表达式

public LuaValue ToString(LuaRuntime runtime) => ToString();

使用Lambda表达式简化单行方法的定义。

区域标记
```
#region Scripting interface
// ...
#endregion
```
使用#region/#endregion组织代码，提高可读性。
预计算表与精度控制
```
static readonly int[] CosineTable = { ... };
static readonly int[] TanTable = { ... };
```
使用整数表示三角函数值，将[-1,1]映射到[-1024,1024]，提高精度和性能。
特殊情况优化
```
if (y == 0)
    return new WAngle(x >= 0 ? 0 : 512);
```
对常见特殊情况进行单独处理，提高性能。