Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

オブジェクトクラス

参考

This page describes the C++ implementation of objects in Godot. Looking for the Object class reference? Have a look here.

一般的な定義

Object is the base class for almost everything. Most classes in Godot inherit directly or indirectly from it. Declaring them is a matter of using a single macro like this:

class CustomObject : public Object {
    GDCLASS(CustomObject, Object); // This is required to inherit from Object.
};

Objects come with a lot of built-in functionality, like reflection and editable properties:

CustomObject *obj = memnew(CustomObject);
print_line("Object class: ", obj->get_class()); // print object class

OtherClass *obj2 = Object::cast_to<OtherClass>(obj); // Converting between classes, similar to dynamic_cast

リファレンス:

• core/object/object.h

Registering Object classes

Most Object subclasses are registered by calling GDREGISTER_CLASS.

GDREGISTER_CLASS(MyCustomClass)

This will register it as a named, public class in the ClassDB, which will allow the class to be instantiated by scripts, code, or by deserialization. Note that classes registered as GDREGISTER_CLASS should expect to be instantiated or freed automatically, for example by the editor or the documentation system.

Besides GDREGISTER_CLASS, there are a few other modes of privateness:

// Registers the class publicly, but prevents automatic instantiation through ClassDB.
GDREGISTER_VIRTUAL_CLASS(MyCustomClass);

// Registers the class publicly, but prevents all instantiation through ClassDB.
GDREGISTER_ABSTRACT_CLASS(MyCustomClass);

// Registers the class in ClassDB, but marks it as private,
// such that it is not visible to scripts or extensions.
// This is the same as not registering the class explicitly at all
// - in this case, the class is registered as internal automatically
// when it is first constructed.
GDREGISTER_INTERNAL_CLASS(MyCustomClass);

// Registers the class such that it is only available at runtime (but not in the editor).
GDREGISTER_RUNTIME_CLASS(MyCustomClass);

It is also possible to use GDSOFTCLASS(MyCustomClass, SuperClass) instead of GDCLASS(MyCustomClass, SuperClass). Classes defined this way are not registered in the ClassDB at all. This is sometimes used for platform-specific subclasses.

Registering bindings

Object-derived classes can override the static function static void _bind_methods(). When the class is registered, this static function is called to register all the object methods, properties, constants, etc. It's only called once.

_bind_methods の内部には、実行できる事がいくつかあります。関数の登録は次の 1 つです:

ClassDB::bind_method(D_METHOD("methodname", "arg1name", "arg2name", "arg3name"), &MyCustomType::method);

Default values for arguments can be passed as parameters at the end:

ClassDB::bind_method(D_METHOD("methodname", "arg1name", "arg2name", "arg3name"), &MyCustomType::method, DEFVAL(-1), DEFVAL(-2)); // Default values for arg2name (-1) and arg3name (-2).

Default values must be provided in the same order as they are declared, skipping required arguments and then providing default values for the optional ones. This matches the syntax for declaring methods in C++.

D_METHOD は、効率を高めるために「メソッド名」をStringNameに変換するマクロです。引数名はイントロスペクションに使用されますが、リリース時にコンパイルするとマクロはそれらを無視するので、文字列は使用されず、最適化されます。

その他の例については、コントロールまたはオブジェクトの _bind_methods を確認してください。

十分に文書化されていないモジュールや機能を追加するだけなら、 D_METHOD() マクロは無視しても問題なく、簡潔にするために名前を渡す文字列を渡すことができます。

リファレンス:

• core/object/class_db.h

定数

クラスには、多くの場合、次のような列挙型があります:

enum SomeMode {
   MODE_FIRST,
   MODE_SECOND
};

For these to work when binding to methods, the enum must be declared convertible to int. A macro is provided to help with this:

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

定数は、次の方法を使用して _bind_methods 内でバインドすることもできます:

BIND_CONSTANT(MODE_FIRST);
BIND_CONSTANT(MODE_SECOND);

プロパティ (設定/取得)

オブジェクトはプロパティをエクスポートし、プロパティは次の場合に役立ちます:

• オブジェクトのシリアル化と逆シリアル化。

• オブジェクト派生クラスの編集可能な値のリストを作成します。

Properties are usually defined by the PropertyInfo() class and constructed as:

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

例:

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

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

別の例:

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

これは文字列プロパティであり、任意の文字列を受け取ることができますが、エディタは定義されたヒントのみを許可します。使用状況フラグが指定されていないため、既定のフラグは PROPERTY_USAGE_STORAGE および PROPERTY_USAGE_EDITOR です。

「object.h」には多くのヒントと使用フラグがあります。

プロパティはC#プロパティのように動作し、インデックス作成を使用してスクリプトからアクセスすることもできますが、読みやすさには関数の使用が推奨されるため、一般的にこの使用方法はお勧めできません。また、多くのプロパティは、演算子[]を使用しない限りインデックス作成を不可能にする「アニメーション/フレーム」などのカテゴリにバインドされています。

_bind_methods() から、set/get 関数が存在する限り、プロパティを作成してバインドできます。例:

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

これにより、セッターとゲッターを使用してプロパティが作成されます。

_set/_get/_get_property_list を使用してプロパティをバインドします

より柔軟な必要がある場合(つまり、コンテキスト上のプロパティの追加または削除)に、プロパティを作成する追加の方法が存在します。

次の関数はObject派生クラスでオーバーライドできます。これらの関数は仮想ではありません。仮想にしないでください。オーバーライドのたびに呼び出され、前の関数は無効になりません(多重レベル呼出し)。

protected:
     void _get_property_list(List<PropertyInfo> *r_props) const;      // return list of properties
     bool _get(const StringName &p_property, Variant &r_value) const; // return true if property was found
     bool _set(const StringName &p_property, const Variant &p_value); // return true if property was found

また、 p_property を必要な名前と順番に比較しなければならないため、これは少し効率が悪くなります。

シグナル

Objects can have a set of signals defined (similar to Delegates in other languages). This example shows how to connect to them:

// This is the function signature:
//
// Error connect(const StringName &p_signal, const Callable &p_callable, uint32_t p_flags = 0)
//
// For example:
obj->connect("signal_name_here", callable_mp(this, &MyCustomType::method), CONNECT_DEFERRED);

callable_mp is a macro to create a custom callable function pointer to member functions. For the values of p_flags, see ConnectFlags.

クラスへのシグナルの追加は _bind_methods で行われ、ADD_SIGNAL マクロを使用します。例:

ADD_SIGNAL(MethodInfo("been_killed"))

Object ownership and casting

Objects are allocated on the heap. There are two different ownership models:

• Objects derived from RefCounted are reference counted.

• All other objects are manually memory managed.

The ownership models are fundamentally different. Refer to the section for each respectively to learn how to create, store, and free the object.

When you do not know whether an object passed to you (via Object *) is RefCounted, and you need to store it, you should store its ObjectID rather than a pointer (as explained below, in the manual memory management section).

When an object is passed to you via Variant, especially when using deferred callbacks, it is possible that the contained Object * was already freed by the time your function runs. Instead of converting directly to Object *, you should use get_validated_object:

void do_something(Variant p_variant) {
    Object *object = p_variant.get_validated_object();
    ERR_FAIL_NULL(object);
}

Manual memory management

Manually memory managed objects are created using memnew and freed using memdelete:

Node *node = memnew(Node);
// ...
memdelete(node);
node = nullptr;

When you are not the sole owner of an object, storing a pointer to it is dangerous: The object may at any point be freed through other references to it, causing your pointer to become a dangling pointer, which will eventually result in a crash.

When storing objects you are not the only owner of, you should store its ObjectID rather than a pointer:

Node *node = memnew(Node);
ObjectID node_id = node.get_instance_id();
// ...
Object *maybe_node = ObjectDB::get_instance(node_id);
ERR_FAIL_NULL(maybe_node); // The node may have been freed between calls.

RefCounted memory management

RefCounted subclasses are memory managed with reference counting semantics.

They are constructed using memnew, and should be stored in Ref instances. When the last Ref instance is dropped, the object automatically self-destructs.

class MyRefCounted: public RefCounted {
    GDCLASS(MyReference, RefCounted);
};

Ref<MyRefCounted> my_ref = memnew(MyRefCounted);
// ...
// Ref holds shared ownership over the object, so the object
// will not be freed. As long as you have a valid, non-null
// Ref, it can be safely assumed the object is still valid.
my_ref->get_class_name();

You should never call memdelete for RefCounted subclasses, because there may be other owners of it.

You should also never store RefCounted subclasses using raw pointers, for example RefCounted *object = memnew(RefCounted). This is unsafe because other owners may destruct the object, leaving you with a dangling pointer, which will eventually result in a crash.

リファレンス:

• core/object/ref_counted.h

動的キャスト

Godotは、オブジェクト派生クラス間の動的キャストを提供します。例:

void some_func(Object *p_object) {
     Button *button = Object::cast_to<Button>(p_object);
}

If the cast fails, nullptr is returned. This works the same as dynamic_cast, but does not use C++ RTTI.

通知

All objects in Godot have a _notification method that allows them to respond to engine-level callbacks that may relate to it. More information can be found on the Godotの通知 page.

リソース

Resource inherits from RefCounted, so all resources are reference counted. Resources can optionally contain a path, which reference a file on disk. This can be set with resource.set_path(path), though this is normally done by the resource loader. No two different resources can have the same path; attempting to do so will result in an error.

パスのないリソースも問題ありません。

リファレンス:

• core/io/resource.h

リソースの読み込み

リソースは、次のようにResourceLoader APIを使用して読み込むことができます:

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

If a reference to that resource has been loaded previously and is in memory, the ResourceLoader will return that reference. This means that there can be only one resource loaded from a file referenced on disk at the same time.

リファレンス:

• core/io/resource_loader.h

リソースの保存

リソースの保存は、リソースセーバー API を使用して行うことができます:

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

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

リファレンス:

• core/io/resource_saver.h