Geequlim
Document advanced property support
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.
@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
- How to export a node path
godot.register_property(MyClass, "node", { type: godot.TYPE_NODE_PATH });
- How to make a decorator to export enumeration property https://github.com/Geequlim/ECMAScript/blob/4d1715e3c52dea4f02ed8fe22a6981cca8e0f3da/misc/decorators.ts#L44-L66
I've made a PR related to this issue. https://github.com/GodotExplorer/ECMAScript/pull/93
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
