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.

ECMAScript/misc/godot.d.ts

Lines 151 to 161 in 4d1715e

	interface PropertyInfo {
	type?: VariantType;
	name?: string;
	hint?: PropertyHint;
	/**@see PropertyHint */
	hint_string?: string;
	/** @see PropertyUsageFlags */
	usage?: number;
	/** Default value of the property */
	default?: any;
	}

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
   

   ECMAScript/misc/decorators.ts

   Lines 44 to 66 in 4d1715e

   	/**
   	* Register an enumeration property
   	* @param enumeration Enumeration name list
   	* @param default_value The default value of the property
   	*/
   	export function enum_property<T extends godot.Object>(enumeration: string[], default_value?: string|number) {
   	return function (target: T, property: string, descriptor?: any) {
   	const pi: godot.PropertyInfo = {
   	hint: godot.PropertyHint.PROPERTY_HINT_ENUM,
   	type: typeof(default_value) === 'string' ? godot.TYPE_STRING : godot.TYPE_INT,
   	hint_string: '',
   	default: typeof(default_value) === 'string' ? default_value : 0
   	};
   	for (let i = 0; i < enumeration.length; i++) {
   	pi.hint_string += enumeration[i];
   	if (i < enumeration.length - 1) {
   	pi.hint_string += ',';
   	}
   	}
   	godot.register_property(target, property, pi);
   	return descriptor;
   	}
   	}

[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