API Documentation

Constructing

In py4godot, constructing Godot objects is straightforward and similar to what you're familiar with in Godot. You can create instances of various Godot classes like Node using their default constructors.

my_node = Node()

This doesn't work for classes in the core package. For example vector has to be instantiated using the static new method

my_vector = Vector3.new0()

However, in Godot, you're probably used to having access to multiple constructors for classes like Vector3, allowing you to initialize objects in different ways. Since Python does not natively support multiple constructors for a single class, py4godot provides an alternative through static methods. These methods follow a naming convention (new{number of parameters}) to simulate the behavior of different constructors.

For example, to create a Vector3 instance with specific x, y, and z values, you would use:

my_vector = Vector3.new3(1, 2, 3)  # Creating a Vector3 with x, y, z components

This approach allows you to choose the constructor that fits your needs while working within Python's constraints. Singletons

In Godot, singletons (often referred to as AutoLoad scripts) are globally accessible and provide essential services or data. In py4godot, you can access these singletons using the get_instance() method. This method ensures that you retrieve the singleton instance correctly.

For instance, to access the Input singleton, you would do the following:

input_instance: Input = Input.get_instance()

This gives you access to all the input-related methods and properties, just as you would expect in Godot.

Using signals

In certain programming frameworks (like Godot, for example), classes such as Node come with predefined signals. These signals are special events that the class can emit under specific conditions. For instance, a Node might have a signal that is triggered when it enters or exits the scene.

In Python, you can access these predefined signals through the members (attributes) of the class. This allows you to connect certain actions or responses to these signals when they are emitted.

If you'd like to define a custom signal (a signal that doesn't already exist in the class), you can do this using the signal function. This allows you to create events tailored to your needs, which other parts of your program can listen for and respond to.

Here’s an example of how to create a custom signal in Python using a framework that supports signals, like Godot:

# file: node3d.py
from py4godot.methods import private
from py4godot.signals import signal, SignalArg
from py4godot.classes import gdclass
from py4godot.classes.Node3D.Node3D import Node3D

@gdclass
class node3d(Node3D):
	custom_signal = signal([SignalArg("test_arg", int)])

	def _ready(self) -> None:
		self.custom_signal.connect(self.custom_method)
		self.visibility_changed.connect(self.visibility_changed_method)
	
	def custom_method(self, arg) -> None:
		pass 
	
	def visibility_changed_method(self) -> None:
		pass

Accessing python methods

You can access python classes directly by getting the script. In this case, we have a script attached to node2. To access its method more easily than calling the method call, we can use get_pyscript()

class node2(Node3D):
    ...
    def _process(self, delta):
        python_class = any_node.get_pyscript() # Returns the python class, if a script is attached, else None
        python_class.call_any_method() # We can now call the method of the script

API Differences

While most of the Godot API is directly accessible in py4godot, there are a few differences. Specifically, certain methods from the Node class, such as get_tree, get_window, and get_viewport, are not directly available. Instead, they are provided in a separate utility module. You can import these methods from py4godot.utils.utils.

Here's how you can do it:

from py4godot.utils.utils import get_window, get_tree, get_viewport

...

tree = get_tree(node)          # Retrieves the SceneTree from a Node
window = get_window(node)      # Retrieves the Window from a Node
viewport = get_viewport(node)  # Retrieves the Viewport from a Node