Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork36
Godot Bindings
All godot types (Object & Primitive) are defined in the built-in modulegodot in javascript. Most of them are lazily loaded until actually used in scripts.
Godot enums are exposed in javascript asenum, and the underlying constant values which already defined in enums are eliminated from bindings.
Note
The name of enum value can be retrieved by reading from enum type with the value as the key.
For example:
import{Image}from"godot";// read enum value from the nested enum in classletmode:Image.AlphaMode=Image.AlphaMode.ALPHA_NONE;// can not read enum constant value from class// Image.ALPHA_NONE is not defined in GodotJS.// this statement prints '0'console.log(mode);// this statement prints 'ALPHA_NONE'console.log(Image.AlphaMode[mode]);
GodotVariant values are automatically translated to the primitive types in javascript if available.
| Variant Type in Godot | Counterpart in JS | Caveats |
|---|---|---|
| NIL | any | NIL used as a type stands for any variant type parameter in Godot |
| INT | number | INT is represented asint64 in Godot, therefore only values less than the max value of int32 can be translated without loss. |
| FLOAT | number | |
| STRING | string | |
| STRING_NAME | string |
All variant types not mentioned above are exposed asclass in javascript (such asVector2Vector3PackedStringArray etc.).
Note
All primitive types which represented asVariant are pooled inEnvironment ifJSB_WITH_VARIANT_POOL is enabled to reduce unnecessary cost on repeatedly memory allocation.
The javascript class variant values behave like value type when passing betweenJS andC++, they areNOT by-reference. But in pure javascript, they are still by-reference.
letvalue=newVector3();// Input get a copy of the value since it's implemented in C++Input.set_gyroscope(value);functionmodify(v:Vector3){v.x=1;}// after this statement, `value.x` will be 1, since value itself is passed by-referencemodify(value);// node.position is NOT modified, since `node.position` is actually a getter implemented in C++ which returns a copy of it.modify(node.position);
And, avoid coding property assignments like this:node.position.x = 0;, although, it works in GDScript.
It's not an error in javascript (which is more DANGEROUS), the actually modifed value is just a copy ofnode.position.
StringName optimization is completely transparent in javascript. When passingStringName parameters, a mapping betweenStringName andv8::String will be automatically cached to avoid repeatedly allocation of newv8::String objects and GodotVariant objects.
import{Input,Node2D}from'godot';classMyActorextendsNode2D{_process(){// so it's relatively lightweight to directly use a string hereif(Input.is_action_just_pressed("confirm")){// ...}}}
IfJSB_IMPLICIT_PACKED_ARRAY_CONVERSION is defined astrue,Packed Array will be implicitly converted from javascriptArray.
leta1=newPackedStringArray();leta2=newPackedStringArray();a2.append("test2");a1.append_array(["hey","there"]);// implicit, it will fail if `JSB_IMPLICIT_PACKED_ARRAY_CONVERSION` is `0`a1.append_array(a2);// explicit// To get value from PackedArray use `get_indexed`a1.get_indexed(2);// To set value in PackedArray use `set_indexed`a1.set_indexed(2,"new value");letb1=newPackedByteArray();b1.append_array([20,1,6,5]);// ArrayBuffer is implicitly treated as PackedByteBuffer even if `JSB_IMPLICIT_PACKED_ARRAY_CONVERSION` is `0`// See `PackedByteArray and ArrayBuffer`b1.append_array(newArrayBuffer(16));
A javascriptArrayBuffer can be used as aPackedByteArray implicitly.
letfile=FileAccess.open(filePath,FileAccess.ModeFlags.WRITE);letbuffer=newArrayBuffer(16);letview=newUint8Array(buffer);view.fill(0);file.store_buffer(buffer);
But reversely,PackedByteArray.to_array_buffer is required to get anArrayBuffer fromPackedByteArray.
letpacked=FileAccess.get_file_as_bytes("res://something.txt");// 'packed' is a `PackedByteArray`console.log(packed.size());// 'buffer' is a `ArrayBuffer`letbuffer=packed.to_array_buffer();console.log(buffer.byteLength);
Scripting
Utilities
Experimental Features
Advanced
Misc