General definition¶

Object is the base class for almost everything. Most classes in Godotinherit directly or indirectly from it. Objects provide reflection andeditable properties, and declaring them is a matter of using a singlemacro like this.

classCustomObject:publicObject{GDCLASS(CustomObject,Object);// this is required to inherit};

This makes Objects gain a lot of functionality, like for example

obj=memnew(CustomObject);print_line("Object class: ",obj->get_class());// print object classobj2=Object::cast_to<OtherClass>(obj);// converting between classes, this also works without RTTI enabled.

Registering an Object¶

ClassDB is a static class that holds the entire list of registeredclasses that inherit from Object, as well as dynamic bindings to alltheir methods properties and integer constants.

Classes are registered by calling:

ClassDB::register_class<MyCustomClass>()

Registering it will allow the class to be instanced by scripts, code, orcreating them again when deserializing.

Registering as virtual is the same but it can't be instanced.

ClassDB::register_virtual_class<MyCustomClass>()

Object-derived classes can override the static functionstaticvoid_bind_methods(). When one class is registered, thisstatic function is called to register all the object methods,properties, constants, etc. It's only called once. If an Object derivedclass is instanced but has not been registered, it will be registered asvirtual automatically.

Inside_bind_methods, there are a couple of things that can be done.Registering functions is one:

ClassDB::bind_method(D_METHOD("methodname","arg1name","arg2name"),&MyCustomMethod);

Default values for arguments can be passed in reverse order:

ClassDB::bind_method(D_METHOD("methodname","arg1name","arg2name"),&MyCustomType::method,DEFVAL(-1));// default value for arg2name

D_METHOD is a macro that converts "methodname" to a StringName for moreefficiency. Argument names are used for introspection, but whencompiling on release, the macro ignores them, so the strings are unusedand optimized away.

Check_bind_methods of Control or Object for more examples.

If just adding modules and functionality that is not expected to bedocumented as thoroughly, theD_METHOD() macro can safely be ignored and astring passing the name can be passed for brevity.

Constants¶

Classes often have enums such as:

enumSomeMode{MODE_FIRST,MODE_SECOND};

For these to work when binding to methods, the enum must be declaredconvertible to int, for this a macro is provided:

VARIANT_ENUM_CAST(MyClass::SomeMode);// now functions that take SomeMode can be bound.

The constants can also be bound inside_bind_methods, by using:

BIND_CONSTANT(MODE_FIRST);BIND_CONSTANT(MODE_SECOND);

Properties (set/get)¶

Objects export properties, properties are useful for the following:

• Serializing and deserializing the object.

• Creating a list of editable values for the Object derived class.

Properties are usually defined by the PropertyInfo() class. Usuallyconstructed as:

PropertyInfo(type,name,hint,hint_string,usage_flags)

For example:

PropertyInfo(Variant::INT,"amount",PROPERTY_HINT_RANGE,"0,49,1",PROPERTY_USAGE_EDITOR)

This is an integer property, named "amount", hint is a range, range goesfrom 0 to 49 in steps of 1 (integers). It is only usable for the editor(edit value visually) but won't be serialized.

Another example:

PropertyInfo(Variant::STRING,"modes",PROPERTY_HINT_ENUM,"Enabled,Disabled,Turbo")

This is a string property, can take any string but the editor will onlyallow the defined hint ones. Since no usage flags were specified, thedefault ones are PROPERTY_USAGE_STORAGE and PROPERTY_USAGE_EDITOR.

There are plenty of hints and usage flags available in object.h, give them acheck.

Properties can also work like C# properties and be accessed from scriptusing indexing, but this usage is generally discouraged, as usingfunctions is preferred for legibility. Many properties are also boundwith categories, such as "animation/frame" which also make indexingimpossible unless using operator [].

From_bind_methods(), properties can be created and bound as long asset/get functions exist. Example:

ADD_PROPERTY(PropertyInfo(Variant::INT,"amount"),"set_amount","get_amount")

This creates the property using the setter and the getter.

Binding properties using_set/_get/_get_property_list¶

An additional method of creating properties exists when more flexibilityis desired (i.e. adding or removing properties on context).

The following functions can be overridden in an Object derived class,they are NOT virtual, DO NOT make them virtual, they are called forevery override and the previous ones are not invalidated (multilevelcall).

protected:void_get_property_list(List<PropertyInfo>*r_props)const;// return list of propertiesbool_get(constStringName&p_property,Variant&r_value)const;// return true if property was foundbool_set(constStringName&p_property,constVariant&p_value);// return true if property was found

This is also a little less efficient sincep_property must becompared against the desired names in serial order.

Dynamic casting¶

Godot provides dynamic casting between Object-derived classes, forexample:

voidsomefunc(Object*some_obj){Button*button=Object::cast_to<Button>(some_obj);}

If cast fails, NULL is returned. This system uses RTTI, but it alsoworks fine (although a bit slower) when RTTI is disabled. This is usefulon platforms where a small binary size is ideal, such as HTML5 orconsoles (with low memory footprint).

Signals¶

Objects can have a set of signals defined (similar to Delegates in otherlanguages). Connecting to them is rather easy:

obj->connect(<signal>,target_instance,target_method)// for example:obj->connect("enter_tree",this,"_node_entered_tree")

The method_node_entered_tree must be registered to the class usingClassDB::bind_method (explained before).

Adding signals to a class is done in_bind_methods, using theADD_SIGNAL macro, for example:

ADD_SIGNAL(MethodInfo("been_killed"))

Notifications¶

All objects in Godot have a_notificationmethod that allows it to respond to engine level callbacks that may relate to it.More information can be found on theGodot notifications page.

References¶

Reference inherits from Object and holds areference count. It is the base for reference counted object types.Declaring them must be done using Ref<> template. For example:

classMyReference:publicReference{GDCLASS(MyReference,Reference);};Ref<MyReference>myref(memnew(MyReference));

myref is reference counted. It will be freed when no more Ref<>templates point to it.

Resources:¶

Resource inherits from Reference, so all resourcesare reference counted. Resources can optionally contain a path, whichreference a file on disk. This can be set withresource.set_path(path).This is normally done by the resource loader though. No two differentresources can have the same path, attempt to do so will result in an error.

Resources without a path are fine too.

Resource loading¶

Resources can be loaded with the ResourceLoader API, like this:

Ref<Resource>res=ResourceLoader::load("res://someresource.res")

If a reference to that resource has been loaded previously and is inmemory, the resource loader will return that reference. This means thatthere can be only one resource loaded from a file referenced on disk atthe same time.

• resourceinteractiveloader (TODO)

Resource saving¶

Saving a resource can be done with the resource saver API:

ResourceSaver::save("res://someresource.res",instance)

Instance will be saved. Sub resources that have a path to a file will besaved as a reference to that resource. Sub resources without a path willbe bundled with the saved resource and assigned sub-IDs, likeres://someresource.res::1. This also helps to cache them when loaded.