Puerts项目中FVector_Wrap等代码在UE5中的精度损失问题分析

问题背景

在Unreal Engine游戏开发中，Puerts作为连接TypeScript/JavaScript与UE引擎的桥梁，其核心功能之一是实现数据类型在两种环境间的转换。近期发现Puerts项目中自动生成的FVector_Wrap等包装代码在UE5环境下存在精度损失问题，这直接影响到了数学运算的准确性。

问题本质

问题的根源在于数据类型转换过程中的精度损失。具体表现为：

1. 自动生成的绑定代码中大量使用了float类型
2. 在数据转换过程中发生了double->float->double的转换链
3. UE5中FVector等数学类型已改为使用double精度

这种转换链会导致数据精度在中间步骤被截断，即使最终恢复为double类型，丢失的精度也无法找回。

技术细节分析

以FVector2D为例，问题代码片段如下：

if (Info[0]->IsNumber() && Info[1]->IsNumber())
{
    float Arg0 = Info[0]->ToNumber(Context).ToLocalChecked()->Value(); // double->float
    float Arg1 = Info[1]->ToNumber(Context).ToLocalChecked()->Value();
    FVector2D* Obj = new FVector2D(Arg0, Arg1); // float->double

这段代码存在两个关键问题：

1. JavaScript中的数字类型是双精度浮点数(double)，直接转换为单精度浮点数(float)会导致精度损失
2. UE5中FVector2D内部使用double存储，从float构造会再次转换，但精度已经丢失

解决方案演进

开发团队提出了几种解决方案并进行了实践：

1. 静态绑定重写方案

通过静态绑定方式重写FVector2D的包装代码，直接使用double类型：

puerts::DefineClass<FVector2d>()
.Constructor(
    CombineConstructors(
        MakeConstructor(FVector2d),
        MakeConstructor(FVector2d,double,double),
        // 其他构造函数...
    )
)

这种方案的优势是：

• 完全避免了中间精度损失
• 代码更简洁易维护
• 支持函数重载和默认参数

2. 生成器改进方案

考虑到手动重写所有数学类型包装代码工作量巨大，团队同时探索了改进自动生成器的方案：

1. 更新生成器以识别UE5中的模板化数学类型
2. 自动生成模板绑定代码而非原始绑定
3. 添加版本判断宏以兼容不同UE版本

3. 操作符重载处理

对于操作符重载等特殊情况，采用了扩展方法包装：

struct FVector2DExtension {
    static FVector2D op_Addition(const FVector2D& self, const FVector2D& V) {
        return self + V;
    }
    // 其他操作符...
};

兼容性考虑

解决方案需要兼顾不同UE版本的差异：

1. UE4中部分数学类型使用float
2. UE5中改为使用double以支持大世界坐标
3. 部分函数签名在不同版本间有变化

通过模板和条件编译实现了跨版本兼容：

#if ENGINE_MAJOR_VERSION >= 5
using FVector2D = UE::Math::TVector2<double>;
#else
using FVector2D = ::FVector2D;
#endif

其他相关问题

在解决过程中还发现并解决了几个衍生问题：

1. 构造函数声明生成不全 - 补充了自动生成.d.ts时的构造函数声明
2. 特殊类型(如Float16Color)处理 - 添加了类型存在性检查
3. TArray模板类型签名 - 修正了模板类型的声明生成
4. 操作符-的编译问题 - 解决了不同编译器下的语法解析差异

总结

Puerts项目通过这次对数学类型包装代码的重构，不仅解决了UE5下的精度损失问题，还：

1. 统一了绑定方式，淘汰了旧的代码生成方案
2. 提高了类型转换的效率和准确性
3. 增强了跨UE版本的兼容性
4. 为后续的大世界坐标支持奠定了基础

这一改进体现了Puerts项目对引擎兼容性和数据精确性的高度重视，也为使用Puerts的开发者提供了更可靠的数学运算基础。