3.5 ‐ 03 Property variables and hints

Description

Properties are values exported accessible from the editor, hints are used to specify the variable type expected on exported variables

Syntax

Registering a variable with godot.register_property

    godot.register_property(Class:ClassName, string:variable_name,  Any:value)
    // or
    godot.register_property(Class:ClassName, string:variable_name,  {
        type: int:CoreType,           // See Core Types list below
        hint: int:PropertyHint,       // See PropertyHint list below
        hint_string: string:arguments?,
        default: matches type
    });

Type and Hints

godot Core Types

All types can be found in the 🔗 official godot core types documentation

enum Variant.Type {
    // See documentation for exhaustive explanations
    "TYPE_NIL":0,
    "TYPE_BOOL":1,
    "TYPE_INT":2,
    "TYPE_REAL":3,
    "TYPE_STRING":4,
    "TYPE_VECTOR2":5,
    "TYPE_RECT2":6,
    "TYPE_VECTOR3":7,
    "TYPE_TRANSFORM2D":8,
    "TYPE_PLANE":9,
    "TYPE_QUAT":10,
    "TYPE_AABB":11,
    "TYPE_BASIS":12,
    "TYPE_TRANSFORM":13,
    "TYPE_COLOR":14,
    "TYPE_NODE_PATH":15,
    "TYPE_RID":16,
    "TYPE_OBJECT":17,
    "TYPE_DICTIONARY":18,
    "TYPE_ARRAY":19,
    "TYPE_RAW_ARRAY":20,
    "TYPE_INT_ARRAY":21,
    "TYPE_REAL_ARRAY":22,
    "TYPE_STRING_ARRAY":23,
    "TYPE_VECTOR2_ARRAY":24,
    "TYPE_VECTOR3_ARRAY":25,
    "TYPE_COLOR_ARRAY":26,
    "TYPE_MAX":27,
};

godot PropertyHint and arguments

All hints can be found in the 🔗 official godot hint types documentation

enum PropertyHint {
    // See documentation for exhaustive explanations
    PROPERTY_HINT_NONE = 0,                     // Any                           hint_string: none
    PROPERTY_HINT_RANGE = 1,                    // int | float                   hint_string: min,max,step?,or_greater?,or_lesser?
    PROPERTY_HINT_EXP_RANGE = 2,                // int | float                   hint_string: min,max,step?,or_greater?,or_lesser?
    PROPERTY_HINT_ENUM = 3,                     // int | float | string          hint_string: value1,value2,value3,...
    PROPERTY_HINT_EXP_EASING = 4,               // float                         hint_string: attenuation? || inout?
    PROPERTY_HINT_LENGTH = 5,                   // Deprecated hint, unused.
    PROPERTY_HINT_KEY_ACCEL = 7,                // Deprecated hint, unused.
    PROPERTY_HINT_FLAGS = 8,                    // int(bitmask[flag])            hint_string: NONE
    PROPERTY_HINT_LAYERS_2D_RENDER = 9,         // int(bitmask[2DRenderLayer])   hint_string: NONE
    PROPERTY_HINT_LAYERS_2D_PHYSICS = 10,       // int(bitmask[2DPhysicsLayer])  hint_string: NONE
    PROPERTY_HINT_LAYERS_3D_RENDER = 11,        // int(bitmask[3DRenderLayer])   hint_string: NONE
    PROPERTY_HINT_LAYERS_3D_PHYSICS = 12,       // int(bitmask[3DPhysicsLayer])  hint_string: NONE
    PROPERTY_HINT_FILE = 13,                    // string(res://Path)            hint_string: *.ext? (eg: *.jpg,*.png)
    PROPERTY_HINT_DIR = 14,                     // string(res://Path)            hint_string: NONE
    PROPERTY_HINT_GLOBAL_FILE = 15,             // string(/OS/Path)              hint_string: *.ext? (eg: *.jpg,*.png)
    PROPERTY_HINT_GLOBAL_DIR = 16,              // string(/OS/Path)              hint_string: NONE
    PROPERTY_HINT_RESOURCE_TYPE = 17,           // Ressource                     hint_string: type (eg: Texture)
    PROPERTY_HINT_MULTILINE_TEXT = 18,          // string                        hint_string: NONE
    PROPERTY_HINT_PLACEHOLDER_TEXT = 19,        // string                        hint_string: placeholderText
    PROPERTY_HINT_COLOR_NO_ALPHA = 20,          // {R,G,B}                       hint_string: NONE
    PROPERTY_HINT_IMAGE_COMPRESS_LOSSY = 21,    // bool                          hint_string: NONE
    PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS = 22, // bool                          hint_string: NONE
}

How to use it with examples

Export a float

export default class MyClass extends godot.Node {
    constructor() {}
    _ready() {
        console.log(this.myFloat);
    }
}

godot.register_property(MyClass, "myFloat",  {
    type: godot.TYPE_REAL
});

Export a float in range

Note: The range must be set according to the step to show as slider, a big range with small steps will end up in a textbox (eg: 0,200, 0.01 -> too small to display a slider)

export default class MyClass extends godot.Node {
    constructor() {}
    _ready() {
        console.log(this.myFloat);
    }
}

godot.register_property(MyClass, "myFloat",  {
    type: godot.TYPE_REAL,
    hint: godot.PROPERTY_HINT_RANGE,
    hint_string: "0,5,0.5"
});

Export a NodePath

Note: The value of a NodePath is a string, you need to use get_node to get the actual node

export default class MyClass extends godot.Node {
    constructor() {}
    _ready() {
        // get_node_or_null avoids crash
        const myElement = this.get_node_or_null(this.myPath);
        console.log(myElement);
    }
}

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

Export a FilePath

Note: The value of a FilePath is a string, you need to use load to get the actual File

export default class MyClass extends godot.Node {
    constructor() {}
    _ready() {
        const my3DObject = godot.load(this.myRessourcePath);
        const myFirstInstance = my3DObject.duplicate();
        const mySecondInstance = my3DObject.duplicate();
    }
}

godot.register_property(MyClass, "myRessourcePath",  {
    type: godot.TYPE_STRING,
    hint: godot.PROPERTY_HINT_FILE
});

Note: To export a Curve head to the Q&A section as its use derives from the standard syntax

Advanced use

setters and getters can be used as hooks to run operations when a value is changed but needs a shadow value to return to avoid crashes

export default class MyClass extends godot.Node {
    constructor() {
        this.myObject = null;
        this._my_shadow_file_Path = null;
    }
    get myRessourcePath() {
        return this._my_shadow_file_Path;
    }
    set myRessourcePath(strValue) {
        this._my_shadow_file_Path = strValue;
        try {
            this.myObject = godot.load(this._my_shadow_file_Path);
        } catch(error) {
            console.error("Path could not be loaded", error);
            this.myObject = null;
        }
    }
    _ready() {
        if (typeof this._my_shadow_file_Path === "string" && typeof this.myObject === "object") {
            // Note that here, this.myRessourcePath is a mirror of this._my_shadow_file_Path
            console.log("my object is loaded");
        }
    }
}

godot.register_property(MyClass, "myRessourcePath",  {
    type: godot.TYPE_STRING,
    hint: godot.PROPERTY_HINT_FILE
});

Next: Signals ➡️