feat: Native object now guaranteed bound during JS initializaation.

Previously, when a JS class was being instantiated for an existing
native Godot object (e.g. ResourceLoader.load('...')) the JS
instance wasn't actually being bound to the native Godot object
until AFTER the JS instance was constructed/initialized. This
created a problem in which field/property initializers and the
constructor were unable to call any native functions, but could
call JS functions.

Now, the Godot object is always bound to our instantiated object
as part of our Godot native class constructor. Thus, we can now
safely call methods during initialization. Importantly, this also
fixes TC39 Stage 3 decorator @bind.signal() support for fields.

Author: Benjamin-Dobell

bridge/jsb_bridge_helper.cpp

@@ -42,7 +42,7 @@ namespace jsb
                     // read script class id from the javascript Class object (the constructor object)
                     const v8::Local<v8::Object> prototype = prototype_val.As<v8::Object>();
                     const v8::Local<v8::Object> dt_base_obj = prototype->Get(context, jsb_name(environment, constructor)).ToLocalChecked().As<v8::Object>();
-                    if (!dt_base_obj->Get(context, jsb_symbol(environment, CrossBind)).ToLocal(&cross_bind_sym) || !cross_bind_sym->IsString())
+                    if (!dt_base_obj->Get(context, jsb_symbol(environment, ClassModuleId)).ToLocal(&cross_bind_sym) || !cross_bind_sym->IsString())
                     {
                         break;
                     }

bridge/jsb_class_info.cpp

@@ -316,7 +316,7 @@ namespace jsb
         }
 
         // trick: save godot class id for convenience of getting it in JS class constructor
-        class_obj->Set(p_context, jsb_symbol(environment, CrossBind), environment->get_string_value(p_module.id)).Check();
+        class_obj->Set(p_context, jsb_symbol(environment, ClassModuleId), environment->get_string_value(p_module.id)).Check();
 
         const v8::Local<v8::Object> dt_base_obj =
             class_obj
@@ -325,7 +325,7 @@ namespace jsb
             ->Get(p_context, jsb_name(environment, constructor)).ToLocalChecked().As<v8::Object>();
         jsb_check(class_obj != dt_base_obj);
 
-        const v8::Local<v8::Value> dt_base_tag = dt_base_obj->Get(p_context, jsb_symbol(environment, CrossBind)).ToLocalChecked();
+        const v8::Local<v8::Value> dt_base_tag = dt_base_obj->Get(p_context, jsb_symbol(environment, ClassModuleId)).ToLocalChecked();
         existed_class_info->base_script_module_id = dt_base_tag->IsString() ? environment->get_string_name(dt_base_tag.As<v8::String>()) : StringName();
         JSB_LOG(Verbose, "%s script %d inherits script module %s native: %d",
             p_module.source_info.source_filepath, p_module.script_class_id, existed_class_info->base_script_module_id, *native_class_id);

bridge/jsb_environment.cpp

@@ -298,8 +298,6 @@ namespace jsb
                 context->SetAlignedPointerInEmbedderData(kContextEmbedderData, this);
                 context_.Reset(isolate_, context);
 
-                js_only_constructor_tag_.Reset(isolate_, impl::Helper::new_noop_function(isolate_, context));
-
                 // init module cache, and register the global 'require' function
                 {
                     const v8::Local<v8::Object> cache_obj = v8::Object::New(isolate_);
@@ -874,8 +872,7 @@ namespace jsb
 
     void* Environment::get_verified_object(const v8::Local<v8::Object>& p_obj, NativeClassType::Type p_type) const
     {
-        if (!TypeConvert::is_object(p_obj, p_type)
-            || (NativeClassType::Type) (uintptr_t) p_obj->GetAlignedPointerFromInternalField(IF_ClassType) != p_type)
+        if (!TypeConvert::is_object(p_obj, p_type))
         {
             return nullptr;
         }
@@ -1200,7 +1197,7 @@ namespace jsb
         v8::Local<v8::Context> context = context_.Get(isolate);
         v8::Context::Scope context_scope(context);
 
-        // In Editor, the script can be attached to an Object after it created in JS (e.g. 'enter_tree' as a child node of a script attached parent node)
+        // Can occur at runtime if object.set_script(...) is used, or in the editor due to hot-reloading etc.
         if (const NativeObjectID object_id = this->try_get_object_id(p_this))
         {
             JSB_LOG(Verbose, "crossbinding on previously bound object %d (addr:%d), rebind it to script class %d", object_id, (uintptr_t) p_this, p_class_id);
@@ -1211,13 +1208,11 @@ namespace jsb
         }
 
         StringName js_class_name;
-        NativeClassID native_class_id;
         v8::Local<v8::Object> class_obj;
 
         {
             const ScriptClassInfoPtr class_info = this->get_script_class(p_class_id);
             js_class_name = class_info->js_class_name;
-            native_class_id = class_info->native_class_id;
             class_obj = class_info->js_class.Get(isolate);
             JSB_LOG(VeryVerbose, "crossbind %s %s(%d) %d", class_info->js_class_name, class_info->native_class_name, class_info->native_class_id, (uintptr_t) p_this);
             jsb_check(!class_obj->IsNullOrUndefined());
@@ -1241,17 +1236,18 @@ namespace jsb
 
         const impl::TryCatch try_catch_run(isolate);
 
-        v8::Local<v8::Function> js_only_constructor_tag = js_only_constructor_tag_.Get(isolate);
         v8::Local<v8::Value> class_prototype = class_obj->Get(context, jsb_name(this, prototype)).ToLocalChecked();
-        js_only_constructor_tag->Set(context, jsb_name(this, prototype), class_prototype).Check();
+        v8::Local<v8::Function> new_target = impl::Helper::new_noop_function(isolate_, context);
+        new_target->Set(context, jsb_name(this, prototype), class_prototype).Check();
+        new_target->Set(context, jsb_symbol(this, ConstructorBindObject), v8::External::New(isolate, p_this)).Check();
 
         v8::Local<v8::Object> reflect = context->Global()->Get(context, jsb_name(this, Reflect)).ToLocalChecked().As<v8::Object>();
         v8::Local<v8::Function> reflect_construct = reflect->Get(context, jsb_name(this, construct)).ToLocalChecked().As<v8::Function>();
 
         v8::Local<v8::Value> reflect_args[] = {
                 class_obj,
                 arguments,
-                js_only_constructor_tag
+                new_target
         };
 
         v8::MaybeLocal<v8::Value> constructed_value = reflect_construct->Call(context, reflect, 3, reflect_args);
@@ -1269,8 +1265,8 @@ namespace jsb
             JSB_LOG(Error, "bad instance '%s", js_class_name);
             return {};
         }
-        const NativeObjectID object_id = this->bind_godot_object(native_class_id, p_this, instance.As<v8::Object>());
-        return object_id;
+
+        return this->try_get_object_id(p_this);
     }
 
     void Environment::rebind(Object *p_this, ScriptClassID p_class_id)

bridge/jsb_environment.h

@@ -46,7 +46,8 @@ namespace jsb
             Doc,
             MemberDocMap,
 
-            CrossBind,               // a symbol can only be used from C++ to indicate calling from cross-bind
+            ClassModuleId,           // provides quick access from a class' constructor to its corresponding module ID
+            ConstructorBindObject,   // indicates a constructor invocation is binding to an existing Godot native object
 
             // Exposed as properties on the `godot` module
             FloatType,
@@ -197,8 +198,6 @@ namespace jsb
 
         internal::VariantInfoCollection variant_info_collection_;
 
-        v8::Global<v8::Function> js_only_constructor_tag_;
-
     public:
         enum class Type : uint8_t
         {
@@ -596,19 +595,6 @@ namespace jsb
         // NOTE: you can't get a shadow environment with this method
         static std::shared_ptr<Environment> _access();
 
-        /**
-         * Should a constructor call only construct a JavaScript object i.e. skip creation of the native Godot Object?
-         * This occurs when we have an existing Godot object that we wish to "cross bind" with its JavaScript
-         * implementation. For example, when instantiating a packed scene, Godot creates the objects first; we must then
-         * cross bind these existing objects with their JavaScript implementation.
-         * @param function
-         * @return
-         */
-        bool is_js_only_constructor_tag(const v8::Local<v8::Function> function)
-        {
-            return function == js_only_constructor_tag_;
-        }
-
     private:
         void exec_async_calls();
         void exec_async_call(AsyncCall::Type p_type, void* p_binding);

bridge/jsb_transpiler.h

@@ -306,26 +306,30 @@ namespace jsb
 
             // We need to handle different binding scenarios:
             //
-            // 1. Instantiating a new Godot object (e.g. new SubClass() in JS) with a new JS script class instance.
-            // 2. Instantiating a JS class to be attached to an existing Godot Object e.g., scene instantiation.
+            // 1. Instantiating only the script class instance, which is to be bound to an existing Godot Object.
+            // 2. Instantiating a new native Godot object along with the newly instantiated script class.
 
             jsb_check(info.NewTarget()->IsFunction());
             v8::Local<v8::Context> context = isolate->GetCurrentContext();
             const v8::Local<v8::Function> new_target = info.NewTarget().As<v8::Function>();
 
-            if (environment->is_js_only_constructor_tag(new_target))
+            const v8::Local<v8::Object> self = info.This();
+
+            // 1. binding to an existing Godot object
+            v8::Local<v8::Value> bind_object_value;
+            if (new_target->Get(context, jsb_symbol(environment, ConstructorBindObject)).ToLocal(&bind_object_value) && bind_object_value->IsExternal())
             {
-                JSB_LOG(Verbose, "cross binding from C++. %s(%d)", class_name, class_id);
+                JSB_LOG(Verbose, "binding to JS instance to existing native object. %s(%d)", class_name, class_id);
+                environment->bind_godot_object(class_id, (Object*) bind_object_value.As<v8::External>()->Value(), self);
                 return;
             }
 
-            // (case-0) directly instantiate from an underlying native class (it's usually called from scripts)
+            // 2a. directly instantiating a Godot native object (via its corresponding JavaScript wrapper class)
             if (new_target->HasOwnProperty(context, jsb_symbol(environment, ClassId)).ToChecked())
             // if (class_info->clazz.NewTarget(isolate) == new_target)
             {
                 internal::StringNames& names = internal::StringNames::get_singleton();
                 const StringName original_name = names.get_original_name(class_name);
-                const v8::Local<v8::Object> self = info.This();
                 Object* gd_object = ClassDB::instantiate(original_name);
 
                 // IS IT A TRUTH that ref_count==1 after creation_func??
@@ -334,16 +338,15 @@ namespace jsb
                 return;
             }
 
-            // (case-1) new from scripts
-            v8::Local<v8::Value> cross_bind_sym;
-            if (new_target->Get(context, jsb_symbol(environment, CrossBind)).ToLocal(&cross_bind_sym) && cross_bind_sym->IsString())
+            // 2b. instantiating a sub-class of a native Godot object (JavaScript wrapper class)
+            v8::Local<v8::Value> module_id_value;
+            if (new_target->Get(context, jsb_symbol(environment, ClassModuleId)).ToLocal(&module_id_value) && module_id_value->IsString())
             {
-                const StringName script_module_id = environment->get_string_name(cross_bind_sym.As<v8::String>());
+                const StringName script_module_id = environment->get_string_name(module_id_value.As<v8::String>());
                 jsb_check(environment->get_module_cache().find(script_module_id));
                 JSB_LOG(Verbose, "(newbind) constructing %s(%s) which extends %s(%d) from script",
                     environment->get_script_class(environment->get_module_cache().find(script_module_id)->script_class_id)->js_class_name, script_module_id,
                     class_name, class_id);
-                const v8::Local<v8::Object> self = info.This();
                 ScriptClassInfo::instantiate(environment, script_module_id, self);
                 return;
             }

scripts/jsb.runtime/src/godot.annotations.ts

@@ -944,6 +944,8 @@ export function createClassBinder(): ClassBinder {
                     throw new Error("The createClassBinder() requires modern decorator support. Disable legacy decorators (experimentalDecorators) in your tsconfig.json");
                 }
 
+                context = proxy.proxy_unwrap_value(context);
+
                 const name = context.name;
 
                 if (typeof name !== "string") {
@@ -954,18 +956,18 @@ export function createClassBinder(): ClassBinder {
 
                 if (context.kind === "accessor") {
                     return {
-                        get: jsb.internal.create_script_signal_getter(name),
+                        get: proxy.proxy_unwrap_value(jsb.internal.create_script_signal_getter(name)),
                         set: () => {
                             throw new Error(`Signal properties cannot be reassigned. Did you mean to .connect() a callback instead?`);
                         },
                     } satisfies ClassMemberDecoratorReturn<ClassAccessorDecoratorContext<Godot.Object, Godot.Signal>> as any;
                 } else if (context.kind === "field") {
                     context.addInitializer(function (this: Godot.Object) {
-                        context.access.set(this, jsb.internal.create_script_signal_getter(name).call(this));
+                        context.access.set(this, proxy.proxy_unwrap_value(jsb.internal.create_script_signal_getter(name)).call(this));
                     });
                     return undefined as any;
                 } else if (context.kind === "getter") {
-                    return jsb.internal.create_script_signal_getter(name) satisfies
+                    return proxy.proxy_unwrap_value(jsb.internal.create_script_signal_getter(name)) satisfies
                         ClassMemberDecoratorReturn<ClassGetterDecoratorContext<Godot.Object, Godot.Signal>> as any;
                 } else {
                     throw new Error(`The signal decorator can not be used to decorate a ${(context as ClassMemberDecoratorContext).kind}. A \`readonly\` field is recommended.`);