Document advanced property support

[TomCaserta]

Right now it's very difficult to figure out how to actually 'export' (in the Godot meaning of that) NodePaths and other types. I saw the latest release notes and figured out that support has been added for something like as the 'default value':

{
    type: godot.VariantType.TYPE_NODE_PATH,
    name: 'Tile Map',
}

But only after crashing the editor a few times by trying to set default value to something like new godot.TileMap() .

Would be great to have this documented along with all the valid usages. I can pick this one up and improve the documentation but I'd like to learn more first about everything before I do so to make sure I document it correctly.

[Geequlim]

@TomCaserta For me writing English documents is a huge challenge. I will be very grateful if you can help improve the documentation.

The godot.register_property recives two kind of value for third argument to export properties to godot.

function register_property(target: GodotClass | godot.Object, name: string, info: PropertyInfo);
function register_property(target: GodotClass | godot.Object, name: string, value: any);

The first one recives an object with the interface godot.PropertyInfo.
https://github.com/Geequlim/ECMAScript/blob/4d1715e3c52dea4f02ed8fe22a6981cca8e0f3da/misc/godot.d.ts#L151-L161
We can define all kind of properties godot supported with a PropertyInfo object and this is how godot define a property internally. In GDScript we define PropertyInfo values by various of export statements.

The second one recives a default value for convinient. The PropertyInfo is made automaticlly from the default value.

godot.register_property(MyClass, 'number_value', 3.14);

Is same with

godot.register_property(MyClass, 'number_value',  {
	type: godot.TYPE_REAL,
	hint: godot.PropertyHint.PROPERTY_HINT_NONE,
	hint_string: "",
	default: 3.14
});

About how to make a PropertyInfo object for your property ? You can reference the comments of godot.PropertyHint values.

enum PropertyHint {
    /** No hint for the edited property. */
    PROPERTY_HINT_NONE = 0,
    /** Hints that an integer or float property should be within a range specified via the hint string `"min,max"` or `"min,max,step"`. The hint string can optionally include `"or_greater"` and/or `"or_lesser"` to allow manual input going respectively above the max or below the min values. Example: `"-360,360,1,or_greater,or_lesser"`. */
    PROPERTY_HINT_RANGE = 1,
    /** Hints that an integer or float property should be within an exponential range specified via the hint string `"min,max"` or `"min,max,step"`. The hint string can optionally include `"or_greater"` and/or `"or_lesser"` to allow manual input going respectively above the max or below the min values. Example: `"0.01,100,0.01,or_greater"`. */
    PROPERTY_HINT_EXP_RANGE = 2,
    /** Hints that an integer, float or string property is an enumerated value to pick in a list specified via a hint string such as `"Hello,Something,Else"`. */
    PROPERTY_HINT_ENUM = 3,
    /** Hints that a float property should be edited via an exponential easing function. The hint string can include `"attenuation"` to flip the curve horizontally and/or `"inout"` to also include in/out easing. */
    PROPERTY_HINT_EXP_EASING = 4,
    /** Deprecated hint, unused. */
    PROPERTY_HINT_LENGTH = 5,
    /** Deprecated hint, unused. */
    PROPERTY_HINT_KEY_ACCEL = 7,
    /** Hints that an integer property is a bitmask with named bit flags. For example, to allow toggling bits 0, 1, 2 and 4, the hint could be something like `"Bit0,Bit1,Bit2,,Bit4"`. */
    PROPERTY_HINT_FLAGS = 8,
    /** Hints that an integer property is a bitmask using the optionally named 2D render layers. */
    PROPERTY_HINT_LAYERS_2D_RENDER = 9,
    /** Hints that an integer property is a bitmask using the optionally named 2D physics layers. */
    PROPERTY_HINT_LAYERS_2D_PHYSICS = 10,
    /** Hints that an integer property is a bitmask using the optionally named 3D render layers. */
    PROPERTY_HINT_LAYERS_3D_RENDER = 11,
    /** Hints that an integer property is a bitmask using the optionally named 3D physics layers. */
    PROPERTY_HINT_LAYERS_3D_PHYSICS = 12,
    /** Hints that a string property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like `"*.png,*.jpg"`. */
    PROPERTY_HINT_FILE = 13,
    /** Hints that a string property is a path to a directory. Editing it will show a file dialog for picking the path. */
    PROPERTY_HINT_DIR = 14,
    /** Hints that a string property is an absolute path to a file outside the project folder. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like `"*.png,*.jpg"`. */
    PROPERTY_HINT_GLOBAL_FILE = 15,
    /** Hints that a string property is an absolute path to a directory outside the project folder. Editing it will show a file dialog for picking the path. */
    PROPERTY_HINT_GLOBAL_DIR = 16,
    /** Hints that a property is an instance of a `Resource`-derived type, optionally specified via the hint string (e.g. `"Texture"`). Editing it will show a popup menu of valid resource types to instantiate. */
    PROPERTY_HINT_RESOURCE_TYPE = 17,
    /** Hints that a string property is text with line breaks. Editing it will show a text input field where line breaks can be typed. */
    PROPERTY_HINT_MULTILINE_TEXT = 18,
    /** Hints that a string property should have a placeholder text visible on its input field, whenever the property is empty. The hint string is the placeholder text to use. */
    PROPERTY_HINT_PLACEHOLDER_TEXT = 19,
    /** Hints that a color property should be edited without changing its alpha component, i.e. only R, G and B channels are edited. */
    PROPERTY_HINT_COLOR_NO_ALPHA = 20,
    /** Hints that an image is compressed using lossy compression. */
    PROPERTY_HINT_IMAGE_COMPRESS_LOSSY = 21,
    /** Hints that an image is compressed using lossless compression. */
    PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS = 22,
}

Examples

1. How to export a node path

godot.register_property(MyClass, "node", { type: godot.TYPE_NODE_PATH });

2. How to make a decorator to export enumeration property
   https://github.com/Geequlim/ECMAScript/blob/4d1715e3c52dea4f02ed8fe22a6981cca8e0f3da/misc/decorators.ts#L44-L66

[94pxls]

I've made a PR related to this issue.
#93

[why-try313]

I'm creating a wiki repo for anyone wanting to use this module. So far it's just a first shot for a global documentation, i'll come back here when a comprehensible and somehow complete version is done.

To come:

• Documentation
• 3.5 version at first, 4.0 when the module is stable
• Script templates/examples
• quick links on home page (hints, tooled, and reusable methods that we often forget) turns out GitHub already generates those

[nmerget]

Should be documented: https://geequlim.github.io/ECMAScript/getting-started/#how-to-export-properties