[UE] Bug: [UE] Bug: 使用QuickJs时碰到相同的符号但大小写有区别，会产生错误。

[watsonsong]

前置阅读 | Pre-reading

• 文档/Doc
• Issues
• FAQ

Puer的版本 | Puer Version

Master(>1.0.9)

UE的版本 | UE Version

5.6.1

发生在哪个平台 | Platform

Editor(win)

错误信息 | Error Message

以QuickJS作为后端的时候，创建一个蓝图并在其中定义一个和某个已有方法同名，但大小写不同的函数，例如SetForcedLODModel，这会导致和C++的UStaticMeshComponent::SetForcedLodModel同名，但大小写不同。

class StartupGameMode extends UE.GameModeBase {
    override ReceiveBeginPlay(): void {
        const bpPath = "/Game/BP_Test.BP_Test_C";
        const bpClass = UE.Class.Load(bpPath);
        const bpInstance = UE.GameplayStatics.BeginDeferredActorSpawnFromClass(
            this,
            bpClass,
            null,
            UE.ESpawnActorCollisionHandlingMethod.AlwaysSpawn
        ) as UE.Game.Data.BP_Test.BP_Test_C;
        UE.GameplayStatics.FinishSpawningActor(bpInstance, undefined);
        bpInstance.SetForcedLODModel();
    }
}

例如这里调用SetForcedLODModel，会提示函数找不到。似乎是因为SetForcedLODModel的调用在QuickJS中被转换成了SetForcedLodModel，然后QuickJs会使用SetForcedLodModel这个版本去调用蓝图的函数产生找不到的情况。
不确定是因为FName或者某个符号的转换的时候出现的问题。

关注了FAQ中关于打包后运行时报一些字段找不到的回答，但是这个情况是v8表现和quickjs不同。目前是跨BP，整个UE工程的所有FName相互之间都不能大小写冲突了。例如一个BP的某个函数的参数名和另外一个BP的函数名如果字母相同大小写不同也会出现问题，这样的限制会导致无法维护。另外是此现象只在quickjs的backend中出现，v8下没有问题。感觉有可能是代码中关于WITH_QUICKJS的宏导致。

问题重现 | Bug reproduce

构建任意蓝图，创建任意一个和已有符号(无论蓝图还是C++)同名但大小写不同的方法，例如SetForcedLODModel。
在JavaScript中创建这个对象并调用其方法。开启使用QuickJs并构建WIndows的包，执行会发现无法访问的错误：

[2025.11.19-04.06.46:833][  0]Puerts: Error: (0x000001C7849F8F70) call StartupGameMode_C::ReceiveBeginPlay of 000001C7848FAA80 fail: TypeError: not a function
    at ReceiveBeginPlay (..\..\..\PuertsTest\Content\JavaScript\StartupGameMode.js:18:20)

我在FFunctionTranslator::Init中追加了一些日志：

void FFunctionTranslator::Init(UFunction* InFunction, bool IsDelegate)
{
    if (InFunction->GetFName().ToString().Equals("SetForcedLODModel", ESearchCase::IgnoreCase))
    {
        UE_LOG(LogTemp, Warning, TEXT("## FFunctionTranslator::Init: %s::%s"), *InFunction->GetOuterUClass()->GetName(), *InFunction->GetFName().ToString());
    }
    
    // ...
}

v8::Local<v8::FunctionTemplate> FStructWrapper::ToFunctionTemplate(v8::Isolate* Isolate, v8::FunctionCallback Construtor)
{
        for (TFieldIterator<UFunction> FuncIt(Class, EFieldIteratorFlags::ExcludeSuper); FuncIt; ++FuncIt)
        {
            UFunction* Function = *FuncIt;
            // ...
            UE_LOG(LogTemp, Warning, TEXT("## Bind %s::%s"), *Class->GetName(), *FuncName);
            if (Function->HasAnyFunctionFlags(FUNC_Static))
            // ...
       }
}

发现编辑器中打印

## Bind BP_Test_C::SetForcedLODModel
## FFunctionTranslator::Init: BP_Test_C::SetForcedLODModel

QuickJs的包体打印:

## Bind BP_Test_C::SetForcedLodModel
## FFunctionTranslator::Init: BP_Test_C::SetForcedLodModel

v8的包体打印:

## Bind BP_Test_C::SetForcedLodModel
## FFunctionTranslator::Init: BP_Test_C::SetForcedLodModel

v8和QuickJs打印的符号都是SetForcedLodModel，但实际v8却调用SetForcedLODModel成功了

[watsonsong]

我这样Hack了一下之后，QuickJs调用函数就成功了：

// in FStructWrapper::ToFunctionTemplate
FString FuncName = Function->GetName();
if (FuncName.Equals("SetForcedLODModel", ESearchCase::IgnoreCase))
{
    FuncName = "SetForcedLODModel";
}

auto Key = FV8Utils::InternalString(Isolate, FuncName);

看起来对v8::FunctionTemplate的Set，似乎v8的运行时不区分大小写，但是quicjks的区分。不确定为什么会如此：
Result->Set(Key, FunctionTranslator->ToFunctionTemplate(Isolate));

[chexiongsheng]

这是UE的FName不区分大小写导致的。
v8之所以没问题，是这里利用了v8的这个特性来规避了：https://github.com/Tencent/puerts/blob/master/unreal/Puerts/Source/JsEnv/Private/StructWrapper.cpp#L370
但qjs没有这个。
另外一个思路是在js层面去做，现在静态函数就是在js层面用proxy去做：https://github.com/Tencent/puerts/blob/master/unreal/Puerts/Content/JavaScript/puerts/uelazyload.js#L30
你试试把成员也用proxy来实现，这样可以同时兼容v8和qjs

[watsonsong]

这是UE的FName不区分大小写导致的。 v8之所以没问题，是这里利用了v8的这个特性来规避了：https://github.com/Tencent/puerts/blob/master/unreal/Puerts/Source/JsEnv/Private/StructWrapper.cpp#L370 但qjs没有这个。 另外一个思路是在js层面去做，现在静态函数就是在js层面用proxy去做：https://github.com/Tencent/puerts/blob/master/unreal/Puerts/Content/JavaScript/puerts/uelazyload.js#L30 你试试把成员也用proxy来实现，这样可以同时兼容v8和qjs

感谢，SetHandler是v8的接口支持C++里面实现proxy（效率会高一些？），提前先Hook掉setter和getter。然后RequiredFName把原本访问的key转换为FName再转换回去得到适合的大小写形式。
QuickJS没法用C++的API来注册一个Handler，只能js层用proxy来执行这个关键的getFNameString的转换吧。

最好的方式是js层识别一下如果是quickjs的话再增加这个proxy。感觉这个还是很有必要，否则FName的空间是整个工程，要求整个工程的任何名字都保持大小写一致不太现实。

[chexiongsheng]

js proxy只触发一次，效率也不会低，你可以试着参考静态的实现了PR过来

[watsonsong]

我导出了一下getFNameString做了一个测试，大致如下：

function wrapInstance(instance: any) {
    const data = new Proxy(instance, {
        get(target, prop) {
            // 跳过内部特殊符号和方法，直接返回原始值
            if (prop === Symbol.toPrimitive || 
                prop === 'toString' || 
                prop === 'valueOf' || 
                prop === Symbol.toStringTag ||
                prop === '__proto__') {
                return Reflect.get(target, prop);
            }

            const translatedProp = typeof prop === 'string' ? getFNameString(prop) : prop;
            console.info(`## Cast ${String(prop)}(${typeof prop}) to ${String(translatedProp)}`);

            const value = target[translatedProp];
            console.info(`## value ${String(value)}(${typeof value})`);

            // 如果是函数，绑定正确的 this 上下文
            if (typeof value === 'function' && prop !== 'constructor') {
                return function(...args) {
                    // 绑定到原始实例的上下文
                    return value.apply(target, args);
                };
            }

            return value;
        }
    });
    return data;
}

class StartupGameMode extends UE.GameModeBase {
    override ReceiveBeginPlay(): void {
        const isGamePaused = UE.GameplayStatics.IsGamePaused(this);
        console.info(`IsGamePaused: ${isGamePaused}`);

        const bpPath = "/Game/Data/BP_Test.BP_Test_C";
        const bpClass = UE.Class.Load(bpPath);
        let bpInstance = UE.GameplayStatics.BeginDeferredActorSpawnFromClass(
            this,
            bpClass,
            null,
            UE.ESpawnActorCollisionHandlingMethod.AlwaysSpawn
        ) as UE.Game.Data.BP_Test.BP_Test_C;
        bpInstance = wrapInstance(bpInstance);
        UE.GameplayStatics.FinishSpawningActor(bpInstance, undefined);
        console.log(`## bpInstance = ${bpInstance}`);
        bpInstance.SetForcedLODModel();
    }
}

生成出来的Instance在实例上加了一个Proxy。这样转换之后打包出来能工作，但是编辑器内反而会出现问题：

## Cast SetForcedLODModel(string) to SetForcedLodModel
## value undefined(undefined)

如果是在SetHandler里面，应该编辑器下所有符号v8中都是‘Symbol’就直接跳过了。但是v8下所有访问到Proxy的prop都是string类型的。

另外似乎没有现成的位置给js去自动注入绑定一个class。只有在FJsEnvImpl::GetTemplateInfoOfType里面TypeToTemplateInfoMap查找缓存不存在的时候，单独调用到JS层去给class加一层Proxy。

[watsonsong]

上面是在实例上设置Proxy，我想测试一下在class级别如何设置Proxy但是发现对应的get方法无法调用到：

function interceptClass(cls) {
    console.error(`## interceptClass ${cls}, ${Object.keys(cls)}, ${typeof cls}`);
    let cls_proxy = new Proxy(cls, {
        get : function(cls, name) {
            const fname = typeof name === 'string' ? getFNameString(name) : name;
            console.error(`## interceptClass get ${cls}, ${String(name)}, ${String(fname)}.`);
            const p = Object.getOwnPropertyDescriptor(cls, fname);
            if (p) {
                Object.defineProperty(cls, name, p);
                return cls[fname];
            }
        }
    });
    Object.setPrototypeOf(cls_proxy, Object.getPrototypeOf(cls));
    Object.setPrototypeOf(cls, cls_proxy);
}

const bpPath = "/Game/Data/BP_Test.BP_Test_C";
const bpClass = UE.Class.Load(bpPath);
let jsclass = blueprint.tojs(bpClass);
interceptClass(jsclass);

let bpInstance = UE.GameplayStatics.BeginDeferredActorSpawnFromClass(
    this,
    bpClass,
    null,
    UE.ESpawnActorCollisionHandlingMethod.AlwaysSpawn
) as UE.Game.Data.BP_Test.BP_Test_C;
UE.GameplayStatics.FinishSpawningActor(bpInstance, undefined);
bpInstance.SetForcedLODModel();

拿到jsclass之后进行interceptClass，但是在访问SetForcedLODModel的时候，并不会触发到cls_proxy的get方法。不知道这种写法哪里的理解有问题？

测试以及问了各路AI，发现JavaScript的Proxy想替代访问key，只有在对象实例的级别进行替换。如果这样感觉比较合适的地点是FJsEnvImpl::Bind的时候，对ClassWrapper进行一个处理。

所以在Bind的位置，通过类似v8::Globalv8::Function GetESMMain;的机制去调用一个JS的函数，把JsObject传递给此函数处理之后再返回。是否和合理的写法？

感谢指点

[watsonsong]

// JSObject参数改成引用支持返回
void FJsEnvImpl::Bind(FClassWrapper* ClassWrapper, UObject* UEObject,
    v8::Local<v8::Object>& JSObject)    // Just call in FClassReflection::Call, new a Object
{
    const bool bIsClass = UEObject->IsA<UClass>();
    const bool IsCDO = UEObject->HasAnyFlags(RF_ClassDefaultObject | RF_ArchetypeObject);
#if PUERTS_KEEP_UOBJECT_REFERENCE
    const bool IsNativeTakeJsRef = ClassWrapper->IsNativeTakeJsRef;
#else
    const bool ClassWrapperIsNativeTakeJsRef = ClassWrapper->IsNativeTakeJsRef;    //这个值只有mixin会进行设置
    const bool IsUClass = UEObject->IsA<UClass>();
    const bool IsNativeTakeJsRef = (IsCDO || IsUClass) ? false : ClassWrapperIsNativeTakeJsRef;
#endif
    
    // JSObject如果被替换成Proxy之后，这里会失败.
    DataTransfer::SetPointer(MainIsolate, JSObject, UEObject, 0);
    DataTransfer::SetPointer(MainIsolate, JSObject, nullptr, 1);
    
    if (!IsCDO && !bIsClass)
    {
      // 如果不是CDO，调用JS层的WrapInstanceFName函数
      v8::Isolate* Isolate = MainIsolate;
      const auto Context = DefaultContext.Get(Isolate);
      
      v8::TryCatch TryCatch(Isolate);
      v8::Handle<v8::Value> Args[] = {JSObject};
  
      auto MaybeRet = WrapInstanceFName.Get(Isolate)->Call(Context, v8::Undefined(Isolate), 1, Args);
      
      if (!TryCatch.HasCaught())
      {
          if (!MaybeRet.IsEmpty())
          {
              JSObject = MaybeRet.ToLocalChecked().As<v8::Object>();
          }
      }
      else
      {
          Logger->Error(FString::Printf(TEXT("wrap instance FName exception %s"), *FV8Utils::TryCatchToString(Isolate, &TryCatch)));
      }
  }

    
    ObjectMap.Emplace(UEObject, v8::UniquePersistent<v8::Value>(MainIsolate, JSObject));
    
    if (!IsNativeTakeJsRef)
    {
        SetJsTakeRef(UEObject, ClassWrapper);
    }
}

// uelazyload.js
function wrapInstance(instance) {
    console.info(`## wrapInstance ${instance}`);
    return new Proxy(instance, {
        get(target, prop) {
            // 跳过内部特殊符号和方法，直接返回原始值
            if (prop === Symbol.toPrimitive || 
                prop === 'toString' || 
                prop === 'valueOf' || 
                prop === Symbol.toStringTag ||
                prop === '__proto__') {
                return Reflect.get(target, prop);
            }

            const translatedProp = typeof prop === 'string' ? getFNameString(prop) : prop;
            console.info(`## Cast ${String(prop)}(${typeof prop}) to ${String(translatedProp)}`);

            const value = target[translatedProp];
            console.info(`## value ${String(value)}(${typeof value})`);

            // 如果是函数，绑定正确的 this 上下文
            if (typeof value === 'function' && prop !== 'constructor') {
                return function(...args) {
                    // 绑定到原始实例的上下文
                    return value.apply(target, args);
                };
            }

            return value;
        }
    });
}
puerts.__wrapInstanceFName = wrapInstance

对应的wrapInstance能正确的在Bind的时候触发，并获取到返回值。但实际访问成员函数的时候会失败。想请教看看做法是否不正确。

[chexiongsheng]

我导出了一下getFNameString做了一个测试，大致如下：

function wrapInstance(instance: any) {
    const data = new Proxy(instance, {
        get(target, prop) {
            // 跳过内部特殊符号和方法，直接返回原始值
            if (prop === Symbol.toPrimitive || 
                prop === 'toString' || 
                prop === 'valueOf' || 
                prop === Symbol.toStringTag ||
                prop === '__proto__') {
                return Reflect.get(target, prop);
            }

            const translatedProp = typeof prop === 'string' ? getFNameString(prop) : prop;
            console.info(`## Cast ${String(prop)}(${typeof prop}) to ${String(translatedProp)}`);

            const value = target[translatedProp];
            console.info(`## value ${String(value)}(${typeof value})`);

            // 如果是函数，绑定正确的 this 上下文
            if (typeof value === 'function' && prop !== 'constructor') {
                return function(...args) {
                    // 绑定到原始实例的上下文
                    return value.apply(target, args);
                };
            }

            return value;
        }
    });
    return data;
}

class StartupGameMode extends UE.GameModeBase {
    override ReceiveBeginPlay(): void {
        const isGamePaused = UE.GameplayStatics.IsGamePaused(this);
        console.info(`IsGamePaused: ${isGamePaused}`);

        const bpPath = "/Game/Data/BP_Test.BP_Test_C";
        const bpClass = UE.Class.Load(bpPath);
        let bpInstance = UE.GameplayStatics.BeginDeferredActorSpawnFromClass(
            this,
            bpClass,
            null,
            UE.ESpawnActorCollisionHandlingMethod.AlwaysSpawn
        ) as UE.Game.Data.BP_Test.BP_Test_C;
        bpInstance = wrapInstance(bpInstance);
        UE.GameplayStatics.FinishSpawningActor(bpInstance, undefined);
        console.log(`## bpInstance = ${bpInstance}`);
        bpInstance.SetForcedLODModel();
    }
}

生成出来的Instance在实例上加了一个Proxy。这样转换之后打包出来能工作，但是编辑器内反而会出现问题：

## Cast SetForcedLODModel(string) to SetForcedLodModel
## value undefined(undefined)

如果是在SetHandler里面，应该编辑器下所有符号v8中都是‘Symbol’就直接跳过了。但是v8下所有访问到Proxy的prop都是string类型的。

另外似乎没有现成的位置给js去自动注入绑定一个class。只有在FJsEnvImpl::GetTemplateInfoOfType里面TypeToTemplateInfoMap查找缓存不存在的时候，单独调用到JS层去给class加一层Proxy。

不是应该在静态实现附近加成员的实现，外部无感知的吗？

[watsonsong]

尝试了纯Js的方法是直接修改UObject这个类的prototype，给它加一个Proxy。任何查找不到的名字最终都会汇聚到这里，执行一次getFNameString后重新出发receiver的访问。这样只用修改一下纯js就能工作。

同时也在换另外一种方案：问题的本质其实是因为FName的缘故，运行时通过UE反射系统拿到的名字的准确大小写信息都是丢失的。如果在生成d.ts的时候顺便生成一张反差表，记录每个UClass中的Method和Property的名字，组成的Map<FName, FString>的配对。在ToFunctionTemplate里面去Set的时候反查一下，似乎是能Work的方法。而且也不区分v8和quickjs这种后端的区别。

感觉不是很优雅(增加一堆运行时数据)，但感觉还是比较有效。主要只用改到StructWrapper的ToFunctionTemplate以及FPropertyTranslator::SetAccessor。

[chexiongsheng]

建议proxy方法就可以了，可以提个PR或者贴下代码我看看。

[watsonsong]

建议proxy方法就可以了，可以提个PR或者贴下代码我看看。

测试是在uelazyload.js中增加了：

let uobjectCls = loadUEType('Object').prototype;
let uobjectCls_proxy = new Proxy(Object.getPrototypeOf(uobjectCls), {
    get: function (_uobjectCls, name, receiver) {
        const p = _uobjectCls[name];
        if (p != null) {
            return _uobjectCls[name];
        } else if (name != getFNameString(name)) {
            return receiver[getFNameString(name)];
        }
    },
});
Object.setPrototypeOf(uobjectCls, uobjectCls_proxy);

这样可以工作，但应该不是最优的。应该没法转换完之后，给距离最近的Class的prototype中把查询到的name给define进去。

[chexiongsheng]

静态那不是有个参考吗？那种实现方式实测对性能基本没影响。
成员方法不能按类似的方式？